API HTTP

O SDK é um cliente fino sobre uma API REST. Se você não está em Node — ou está depurando com curl — é isto que você precisa.

Base

O prefixo da chave decide o ambiente. Uma sk_test_ enviada pra produção não falha com "chave errada" — o recurso simplesmente não existe lá (404).

Autenticação

curl https://api-sandbox.beinfi.com/metering/products \
  -H "Authorization: Bearer sk_test_…"

Só Authorization: Bearer. Não existe X-Api-Key.

As rotas públicas de checkout (/public/v1/* e /pay/{slug}/*) não levam chave: são abertas por definição, porque rodam no navegador do pagador.

Provisionamento pelo agente

POST /public/v1/claimables é público. Aceita ref, accountName e email opcionais. Retorna apiKeySecret, publishableKey, tenantSlug, productId, claimUrl e expiresAt. O nome prepara a conta; o email é contato não verificado. Com a atualização de email de claim, o endereço recebe um aviso assíncrono com link e prazo, limitado a um enfileiramento por endereço a cada 24 horas. Um 201 confirma a criação, não a entrega. Sempre guarde a claimUrl.

Veja cadastro pelo agente para perguntas, chaves e finalização. Se a resposta desse POST se perder, não repita automaticamente: ele pode já ter criado a conta.

Idempotency-Key

Mutações autenticadas exigem o header. O provisionamento público de claim acima é uma exceção:

-H "Idempotency-Key: $(uuidgen)"

Sem ele: 400 idempotency_key_required. Reusar a mesma chave com corpo diferente: 409 idempotency_key_reused.

Envelopes de resposta

Algumas rotas devolvem o recurso embrulhado. Criar produto devolve dois:

{ "product": { "id": "0d83d66e-…", "key": "x1", … },
  "version": { "id": "…", "version": 1, "status": "draft" } }

Listagens vêm sob a chave do plural ({"products":[…]}, {"links":[…]}). Confira o corpo antes de assumir que o objeto está na raiz — é o erro mais comum de quem sai do SDK.

Envelopes de erro

São dois, e a diferença importa se você faz parsing:

// handlers — a maioria esmagadora
{ "message": "…", "error_code": "validation_failed", "tracer_id": "befee651…",
  "errors": [ { "field": "eventId", "description": "is required" } ] }
 
// middleware (idempotência, rate limit)
{ "error": { "code": "rate_limited", "message": "…", "request_id": "e0484f60…" } }

errors[] é onde mora o motivo de um 422 — é o campo que diz o que corrigir. Guarde o tracer_id/request_id: é o que o suporte procura.

Rotas

{id} são UUIDs, exceto onde indicado. Esta seção é gerada do contrato OpenAPI, então acompanha a API.

Catálogo e clientes

Cobrança

Conta

Público — sem chave

Operação — sessão e webhooks de entrada

Uma venda inteira, só com curl

API=https://api-sandbox.beinfi.com
C=$(curl -s -X POST $API/public/v1/claimables \
     -H 'Content-Type: application/json' -d '{}')
K=$(echo $C | jq -r .apiKeySecret); SLUG=$(echo $C | jq -r .tenantSlug)
IDEM() { echo "Idempotency-Key: $(uuidgen)"; }
 
P=$(curl -s -X POST $API/metering/products -H "Authorization: Bearer $K" \
  -H 'Content-Type: application/json' -H "$(IDEM)" \
  -d '{"key":"guia","name":"Guia","type":"item","pricingModel":"one_time",
       "currency":"BRL","basePrice":"49.90"}')
PID=$(echo $P | jq -r .product.id); VID=$(echo $P | jq -r .version.id)
 
curl -s -X POST $API/metering/products/$PID/versions/$VID/publish \
  -H "Authorization: Bearer $K" -H "$(IDEM)"
 
INV=$(curl -s -X POST $API/billing/products/$PID/invoices \
  -H "Authorization: Bearer $K" -H 'Content-Type: application/json' -H "$(IDEM)" \
  -d '{"customer":{"externalId":"u1","email":"[email protected]","taxId":"52998224725"}}' | jq -r .id)
 
curl -s -X POST $API/pay/$SLUG/invoices/$INV/charge \
  -H 'Content-Type: application/json' -H "$(IDEM)" -d '{"method":"pix"}' | jq .pixPayload