Inttegro Elixir SDK

The official typed Elixir client for server-side Inttegro integrations.

API documentation · Integration guides · Source

Install

Add inttegro to your dependencies:

def deps do
  [
    {:inttegro, "~> 0.2"}
  ]
end

Fetch the package:

mix deps.get

Store your Inttegro secret key in the server environment:

export INTTEGRO_API_KEY="your_secret_key"

Never put this key in browser code, a mobile application, source control, or logs. The client uses https://api.inttegro.com unless you explicitly configure another origin.

Make your first request

Create one client and pass it to the resource module you need:

client = Inttegro.Client.new!(System.fetch_env!("INTTEGRO_API_KEY"))
request = Inttegro.Orders.LookupRequest.new!(order_id: "or_...")

case Inttegro.Orders.lookup(client, request) do
  {:ok, order} ->
    IO.inspect(order.status, label: "order status")

  {:error, %Inttegro.Errors.APIError{} = error} ->
    IO.warn("Inttegro rejected the request: #{error.code}")

  {:error, %Inttegro.Errors.TransportError{} = error} ->
    IO.warn("Inttegro could not be reached: #{Exception.message(error)}")
end

The client is a plain immutable struct. It does not start a process and can be safely shared between requests, tasks, and supervised application components.

API organization

The package follows Elixir module conventions instead of placing hundreds of unrelated schemas in the root namespace:

Resource functions return {:ok, domain_value} or {:error, exception}. HTTP envelopes and JSON codec helpers are private implementation details.

Safe retries

Supply an idempotency key for every logical mutation:

Inttegro.Customers.create(client, request,
  idempotency_key: "create-customer-account-8342"
)

Reuse that key only when retrying the same operation with the same intent. A transport error does not prove that the server rejected the request, so mutations without stable idempotency cannot be retried safely.

Errors

Pattern match on the failure class:

case Inttegro.Refunds.lookup(client, request) do
  {:ok, refund} ->
    refund

  {:error, %Inttegro.Errors.APIError{status: 404}} ->
    :not_found

  {:error, %Inttegro.Errors.APIError{} = error} ->
    {:rejected, error.code, error.fix_code}

  {:error, %Inttegro.Errors.TransportError{}} ->
    :outcome_unknown

  {:error, %Inttegro.Errors.DecodingError{}} ->
    :contract_mismatch
end

API errors include the HTTP status and safe structured codes when available. They never expose the secret key or raw request body.

Observability

The SDK can send privacy-safe lifecycle events to a callback owned by your application:

client =
  Inttegro.Client.new!(System.fetch_env!("INTTEGRO_API_KEY"),
    telemetry: fn event -> MyApp.Telemetry.record(event) end,
    error_reporter: fn report -> MyApp.ErrorReporter.enqueue(report) end
  )

No exporter is installed and no error report is constructed unless you configure these callbacks. Events exclude API keys, headers, bodies, resource IDs, dynamic URLs, error messages, and stack traces. See the Observability guide for the event names and policy controls.

Learn the workflows

HexDocs includes guides for:

• getting started and configuring the client;
• creating orders and reconciling asynchronous payments;
• API errors, transport uncertainty, and idempotent retries;
• file uploads, delivery, links, and upload requests; and
• telemetry and application-owned error reporting.

The Studio API reference remains authoritative for HTTP contracts and business rules. The HexDocs reference explains the Elixir types and how they work together.