> ## 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 plataforma

> Como as três superfícies da Caratuva se conectam.

A Caratuva expõe três superfícies. A maioria dos clientes usa uma combinação: o painel para operação, o link de pagamento para coletar do comprador e a API para integração com o ERP.

## O painel

`dashboard.caratuva.com` é a cabine de operação da sua empresa. Vendedores, financeiro e operações usam o painel para:

* Fazer onboarding da empresa (KYB).
* Criar, aprovar e cancelar faturas.
* Configurar o destino do repasse PIX.
* Emitir e revogar chaves de API.
* Cadastrar e inspecionar inscrições de webhook de saída.
* Acompanhar a linha do tempo de cada pagamento até a liquidação.
* Baixar relatórios de preços de transferência para contabilidade e fisco (hoje via API).

Login é por magic link via e-mail — sem senhas. As sessões duram 12 horas.

Veja [Painel](/pt-BR/dashboard) para um tour guiado.

## O link de pagamento

`pay.caratuva.com` é o que seus compradores veem. É um checkout hospedado que leva o comprador de "devo USD 12.500" até "pago" sem sair da página. O comprador:

1. Chega numa página com o nome da sua empresa e os detalhes da fatura que você criou.
2. Faz login por magic link no e-mail — o mesmo para o qual você endereçou a fatura.
3. Faz KYC se ainda não tiver feito (obrigatório, sem caminho para pular).
4. Vê uma cotação de câmbio travada com o valor exato que pagará na própria moeda.
5. Paga por transferência bancária (ACH, wire ou SEPA, conforme o país), seguindo as instruções de transferência exibidas.
6. É redirecionado para sua `returnUrl` quando o pagamento é coletado, ou vê uma página de confirmação da Caratuva caso contrário.

O comprador nunca instala app, cria carteira ou abre conta na Caratuva. O KYC é reutilizado entre faturas e entre vendedores — um comprador já verificado paga as faturas seguintes em segundos.

Veja [Links de pagamento](/pt-BR/payment-links) para o fluxo completo do comprador.

## A API REST

`api.caratuva.com/v1` é uma única superfície de API com tudo o que um integrador precisa:

* Emitir e revogar chaves de API.
* Criar payment intents (seu ERP mantém a fatura como fonte única da verdade).
* Ler estado de faturas e pagamentos.
* Inscrever-se em eventos do ciclo de vida como webhooks de saída.

É REST + OpenAPI 3.x. Endpoints que criam recursos aceitam um `Idempotency-Key` para retentativas seguras. Todo webhook é assinado com HMAC-SHA256 e reentregue com backoff exponencial.

Veja [Visão geral da API](/pt-BR/api-reference/introduction) e o [Início rápido de integração B2B](/pt-BR/api-reference/b2b-quickstart).

## Como elas se relacionam

```
+--------------------+        +---------------------+
|  Seu ERP / CMS     |        |   Caratuva          |
|                    |  API   |   Painel            |
|  - emite fatura    +<------>+   (sua equipe)      |
|  - acompanha       |        |                     |
|    pedidos         |        |                     |
+--------+-----------+        +----------+----------+
         |                               |
         | link de pagamento hospedado   | convida o comprador
         v                               v
              +------------------------+
              |   pay.caratuva.com     |
              |   (seu comprador)      |
              +-----------+------------+
                          |
                          v
                    +-----+------+
                    | Liquidação |
                    +-----+------+
                          |
                          v
                    BRL via PIX
                    para sua conta
```

Sua equipe pode tocar todo o fluxo pelo painel. Ou seu ERP pode tocar pela API. Ou os dois — API e painel operam sobre os mesmos dados, então uma fatura criada via API aparece na linha do tempo do painel, e uma fatura criada no painel dispara os mesmos eventos de webhook.

## Modos

Toda organização tem um modo **teste** e um modo **produção**. Eles são isolados: dados de teste nunca vazam para produção, e vice-versa. Novas sessões começam em teste.

* **Modo teste** roda cada etapa do fluxo de ponta a ponta — KYC, pagamento, liquidação, webhooks — usando uma instância de pagamento sandbox. KYB e KYC do comprador são aprovados automaticamente e nenhum dinheiro real se move. Use para desenvolvimento, CI, staging e demonstrações.
* **Modo produção** movimenta dinheiro real e roda contra trilhos reais. Entrar em produção exige uma Solicitação de Acesso à Produção aprovada pela Caratuva e, em seguida, o KYB de produção. Use somente em produção.

Chaves de API carregam o modo no prefixo: `pk_test_*` ou `pk_live_*`. Sessões do painel mostram um indicador de modo claro o tempo todo e alternam com um único clique. Veja [Modos teste e produção](/pt-BR/environments).

## Regiões

Os fundos liquidam em contas bancárias brasileiras via PIX. A plataforma é hospedada em São Paulo para residência de dados e baixa latência com o PIX. A coleta do lado do comprador funciona globalmente — onde quer que ele possa ter uma conta bancária.