Pular para o conteúdo principal
A API da Caratuva suporta dois esquemas de autenticação:
EsquemaHeaderUsado por
Chave de APIX-API-Key: pk_<mode>_<id>.<secret>Clientes servidor-a-servidor do lado do vendedor.
Bearer JWTAuthorization: Bearer <jwt>Sessões do painel.
Para integradores B2B, a chave de API é a credencial que você usará em toda parte. JWTs são emitidos para o frontend do painel e não são diretamente relevantes para integrações servidor-a-servidor.

​
Chaves de API

Uma chave de API tem o formato: 
pk_<mode>_<id>.<secret>
  • <mode> é test ou live.
  • <id> é a metade pública de lookup — seguro para logar.
  • <secret> aparece exatamente uma vez na criação. A Caratuva guarda só um hash; o texto plano não é recuperável. Se perder, revogue a chave e crie uma nova.
Veja Chaves de API para emissão, listagem, revogação, escopos e rotação.

​
Tenancy

Toda requisição autenticada resolve para uma organização derivada da credencial — a claim orgId do JWT ou a organização dona da chave de API. Não há override por header; tenancy é sempre carregada pela credencial. Isso significa:
  • Uma chave de API nunca pode agir em nome de outra organização, independente dos headers.
  • Uma chave vazada afeta exatamente uma organização, e você pode revogá-la sem mexer em nenhuma outra.
  • Todos os endpoints de leitura escopam automaticamente para sua organização. Você nunca lista nem busca dados de outra.

​
Idempotência

Endpoints que criam recursos (POST /v1/invoices e POST /v1/payment-intents) aceitam um header Idempotency-Key. O valor recomendado é um UUID novo por operação lógica. 
Idempotency-Key: <um UUID novo por operação lógica>
Comportamento:
  • A primeira criação com uma determinada chave cria o recurso.
  • Um replay com a mesma chave retorna o recurso existente, re-serializado a partir do armazenamento — então o payload reflete o estado atual do recurso (não uma cópia byte a byte da resposta original), e nenhum efeito colateral roda duas vezes.
  • A correspondência é feita apenas pela chave — o corpo da requisição não é comparado. Um replay com a mesma chave mas um corpo diferente ainda retorna o recurso original; o novo corpo é ignorado. Use uma chave nova sempre que pretender criar um recurso diferente.
  • A idempotência é chaveada por (organização, chave) no recurso criado e não tem expiração — replays permanecem idempotentes durante toda a vida daquele recurso.
  • Se uma chave já estiver vinculada a um recurso criado por um caminho diferente (por exemplo, uma invoice do dashboard quando você faz POST /v1/payment-intents), a API retorna 409 IdempotencyKeyConflict — use uma chave nova.
Sempre envie uma chave de idempotência em retentativas — erros de rede e 5xx transitórios acontecem, e o padrão seguro é “envie de novo com a mesma chave”.

​
Modo teste vs. produção

Chaves com prefixo pk_test_ são reconhecidas como credenciais de modo teste. O modo teste roda o fluxo inteiro de ponta a ponta — KYC, coleta de pagamento, câmbio, liquidação, webhooks — contra uma instância de pagamento sandbox. KYB e KYC do comprador são aprovados automaticamente, e nenhum dinheiro real se move. Veja Ambientes para saber como o modo é carregado em cada requisição. Use o modo teste para:
  • Desenvolvimento local.
  • Testes de CI / integração.
  • Ambientes de staging.
  • Demonstrações.
Modos teste e produção são totalmente isolados. Faturas de teste, compradores de teste e entregas de webhook de teste ficam em um dataset separado; nunca aparecem no painel de modo produção e vice-versa. Chaves pk_live_* batem nos trilhos reais. Nunca use fora de produção.

​
CORS

A API aceita requisições cross-origin via navegador apenas das origens web próprias da Caratuva que estão na allowlist (o painel, o portal hospedado do comprador e o site de marketing); ela não é aberta a origens de navegador arbitrárias. Sua integração B2B deve chamar a API servidor-a-servidor — nunca embuta uma chave de API em código de navegador. Fluxos do lado do comprador passam pela página de pagamento hospedada em pay.caratuva.com, não pelo seu próprio código de browser.

​
Tempo

A API retorna timestamps em RFC 3339 / ISO 8601 com timezone explícita (2026-05-02T14:00:00.000Z). Sempre envie timestamps com timezone; horários locais sem timezone são rejeitados.

​
Content type

Requisições e respostas são application/json. A API rejeita requisições sem Content-Type: application/json em endpoints de escrita.

​
Dicas de log

  • A metade <id> da chave de API é segura para logar; a metade <secret> não.
  • O header Idempotency-Key é seguro para logar e útil para tracing.
  • Não logue headers Authorization: Bearer <jwt> — JWTs são curto-prazo, mas ainda secretos.