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
Os fluxos que não têm superfície pública de API — o envio de KYB e o destino PIX da sua própria organização, o KYC do comprador na página de pagamento hospedada e a gestão de equipe — vivem no painel. São densos em documento e sensíveis em segurança demais para serem úteis via acesso programático.
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
Veja Autenticação para detalhes, incluindo idempotência e tenancy.
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/payments) 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.