api.caratuva.com/v1. Ela é projetada para ERPs, marketplaces e plataformas de trade finance que querem adicionar cobrança internacional sem construir tesouraria, mesa de câmbio e stack de compliance próprios.
- URL base —
https://api.caratuva.com/v1 - Formato — JSON. Corpos de requisição e respostas são JSON UTF-8.
- Spec — OpenAPI 3.x, servida pelo host da API em
/docs-json, com um Swagger UI navegável em/docs. Eles ficam acessíveis assim que o host da API (api.caratuva.com) estiver publicamente disponível. Enquanto isso,pnpm devno repositório de docs gera um snapshot local da spec a partir de uma API em execução.
Versionamento
A versão major atual év1, fixada no path. Mudanças quebradoras vão para v2 em vez de mutar v1. Adições não-quebradoras chegam em v1 continuamente.
Capacidades
| Superfície | O que faz |
|---|---|
| Chaves de API | Emitir, listar e revogar credenciais servidor-a-servidor por organização. |
| Payment intents | Criar pedidos de pagamento com links de pagamento hospedados. A superfície primária do integrador. |
| Invoices | Ler estado de faturas, tanto as criadas via API quanto via painel. |
| Payments | Ler a visão canônica do pagamento (coleta, câmbio, liquidação). |
| Webhook subscriptions | Cadastrar e inspecionar endpoints de webhook de saída; girar segredos de assinatura. |
| Connected accounts | Faça o onboarding dos seus próprios clientes finais (vendedores/compradores) ao KYB/KYC servidor-a-servidor e cadastre o destino de repasse PIX de um cliente final vendedor. |
| Health | Probes /healthz e /readyz (sem autenticação). |
O que NÃO está na API
Deliberadamente deixamos algumas coisas de fora da v1:- Sem KYC do comprador na página de pagamento hospedada via API. O KYC do comprador acontece na página de pagamento hospedada, onde a captura de documento, a selfie de verificação e os fluxos de consentimento são de primeira classe. Você não pode enviar o passaporte de um comprador para o fluxo hospedado via API. (O onboarding dos seus próprios clientes finais ao KYB/KYC está disponível via Connected accounts.)
- Sem configuração do destino PIX da sua própria organização. A chave PIX de repasse da sua organização é só pelo painel e restrita por propriedade (ownership). (O destino PIX de um cliente final vendedor é definido via
payout-configde connected-accounts.) - Sem autenticação de comprador. O login do comprador vive na página de pagamento hospedada.
- Sem flag “skip KYC”. Todo comprador passa pela verificação de identidade no primeiro pagamento, independente de como a fatura foi criada.
Esquemas de autenticação
| Esquema | Header | Usado por |
|---|---|---|
| Chave de API | X-API-Key: pk_<mode>_<id>.<secret> | Clientes servidor-a-servidor do lado do vendedor. |
| Bearer JWT | Authorization: Bearer <jwt> | Sessões do painel. |
Limites de taxa
Limites de taxa por chave de API se aplicam em rotas específicas de alto custo (por exemplo, criação de payment intent e de invoice), não em todos os endpoints. Não há headers de respostaX-RateLimit-*. Quando você excede um limite, a API retorna 429 RateLimitExceeded com um campo retryAfter (segundos) no corpo JSON:
retryAfter segundos e então tente novamente. Não martele a API.
Idempotência
Endpoints que criam recursos (POST /v1/invoices, POST /v1/payment-intents) aceitam um header Idempotency-Key (qualquer string tipo UUID). Um replay com a mesma chave retorna o recurso existente (reserializado a partir do armazenamento, refletindo seu estado atual) sem reexecutar efeitos colaterais — não há expiração. Sempre defina uma em retentativas. Veja Autenticação → Idempotência.
Para onde ir
- Autenticação — credenciais e tenancy.
- Início rápido de integração B2B — seu primeiro intent pago em cinco passos.
- Erros — envelope de erro e os códigos que você verá de fato.