Peráta SDK para Elixir

SDK oficial da API da Peráta para Elixir 1.18+, sem dependências: só :httpc, :crypto e o módulo JSON. É gerado a partir do contrato da API (openapi.json, na raiz de perata-sh/sdk) por generator/. Não edite os arquivos desta pasta: regenere.

# mix.exs
{:perata_sdk, "~> 0.3.0"}
client = Perata.new(System.fetch_env!("PERATA_API_KEY")) # prk_test_… ou prk_live_…

{:ok, product} = Perata.Products.create(client, %{name: "Curso"}, idempotency_key: "produto-curso")

client
|> Perata.Products.list_stream()
|> Enum.each(&IO.puts(&1.name))

Recursos

Módulo Funções
Perata.Benefits create, delete, get, list, list_stream, list_grants, list_grants_stream, update
Perata.CheckoutLinks create, delete, get, list, list_stream, update
Perata.Checkouts create, get, update
Perata.CustomerSessions create
Perata.Customers create, delete, get, get_external, get_state, list, list_stream, update, update_external
Perata.Discounts create, delete, get, list, list_stream, update
Perata.Disputes get, list, list_stream
Perata.Events list, list_stream
Perata.Meters get, list, list_stream
Perata.Orders get, get_invoice, get_receipt, list, list_stream
Perata.PaymentMethods detach, list, list_stream
Perata.Payments get, list, list_stream
Perata.Prices create, list, list_stream
Perata.Products archive, create, get, list, list_stream, update
Perata.Refunds create, list, list_stream
Perata.Subscriptions cancel, get, list, list_stream, update
Perata.Webhooks create_endpoint, delete_endpoint, get_endpoint, list_deliveries, list_deliveries_stream, list_endpoints, list_endpoints_stream, update_endpoint

Cada função recebe o cliente primeiro e devolve {:ok, valor} ou {:error, %Perata.Error{}}. Os modelos são structs com os nomes da API (payment.amount_cents). O corpo de uma escrita é a struct de parâmetros do método (%Perata.ProductsCreateParams{name: "Curso"}), uma keyword list ou um mapa com chaves atom; um campo opcional não informado fica fora do JSON. As funções _stream devolvem um Stream preguiçoso que percorre todas as páginas a partir de page: e levantam Perata.Error numa recusa.

As escritas aceitam idempotency_key:, e todas aceitam api_key: para usar a chave de outra organização numa chamada. Perata.new/2 aceita base_url:, timeout: (30 segundos, em milissegundos) e transport:. Um POST sem chave de idempotência é enviado com uma Idempotency-Key própria (UUID v4 aleatório, uma por chamada); passe a sua para poder repetir a mesma operação com segurança.

Erros

Uma recusa da API é um {:error, %Perata.Error{}}, com status, code (invalid_request, not_found…), message, fields (o problema de cada campo) e, num 429, retry_after em segundos.

Webhooks

{:ok, event} = Perata.verify_webhook(System.fetch_env!("PERATA_WEBHOOK_SECRET"), conn.req_headers, raw_body)

case event do
  %Perata.OrderWebhookEvent{type: "order.paid", data: order} -> IO.inspect(order.installments)
  %Perata.DisputeWebhookEvent{data: dispute} -> IO.inspect(dispute.provider_dispute_id)
  %Perata.UnknownWebhookEvent{} -> :ok
end

A assinatura é a do Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature), com tolerância de 5 minutos. Passe o corpo cru, antes de interpretar. Uma assinatura que não confere devolve {:error, %Perata.WebhookVerificationError{}}.

O evento é tipado: um tipo para cada dado que o webhook carrega (OrderWebhookEvent traz um Order, DisputeWebhookEvent a disputa, IdentifiersWebhookEvent os identificadores…), e o type diz o que aconteceu; um tipo que esta versão do SDK ainda não conhece chega como UnknownWebhookEvent, com os dados como vieram. Durante a rotação do segredo o cabeçalho traz mais de uma assinatura, e basta uma conferir. Perata.verify_webhook_signature/4 só confere a assinatura.

Versão do SDK: 0.3.0 · contrato da API: 0.1.0