> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caratuva.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Visão geral da API

> REST + OpenAPI. Uma única superfície para tudo o que um integrador precisa.

A API da Caratuva é uma única superfície REST servida em `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 dev` no 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).                                                                                                                             |

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](/pt-BR/api-reference/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-config` de 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.                                |

Veja [Autenticação](/pt-BR/api-reference/authentication) 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 resposta `X-RateLimit-*`. Quando você excede um limite, a API retorna `429 RateLimitExceeded` com um campo `retryAfter` (segundos) no corpo JSON:

```json theme={null}
{
  "statusCode": 429,
  "error": "RateLimitExceeded",
  "message": "Rate limit exceeded. Retry after 30s.",
  "retryAfter": 30
}
```

Espere `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](/pt-BR/api-reference/authentication#idempotency).

## Para onde ir

* [Autenticação](/pt-BR/api-reference/authentication) — credenciais e tenancy.
* [Início rápido de integração B2B](/pt-BR/api-reference/b2b-quickstart) — seu primeiro intent pago em cinco passos.
* [Erros](/pt-BR/api-reference/errors) — envelope de erro e os códigos que você verá de fato.