perata_sdk

# 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](https://github.com/perata-sh/sdk)) por `generator/`. Não edite os arquivos desta pasta: regenere.

```elixir
# mix.exs
{:perata_sdk, "~> 0.3.0"}
```

```elixir
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

```elixir
{: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