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

# Modos teste e produção

> Uma conta, dois ambientes isolados — um sandbox de trabalho e produção.

Toda organização Caratuva tem dois modos: **teste** e **produção**. Eles
compartilham uma conta e um host de API, mas seus dados e seus trilhos de
pagamento são totalmente isolados. Essa é a divisão teste/produção no estilo
Stripe — desenvolva e demonstre no modo teste, movimente dinheiro real no modo
produção.

## O que cada modo faz

<CardGroup cols={2}>
  <Card title="Modo teste" icon="flask">
    Executa o pipeline completo — KYB, KYC do comprador, pagamento, liquidação,
    webhooks — contra uma **instância de pagamento sandbox**. KYB e KYC do
    comprador são aprovados automaticamente, e nenhum dinheiro real é
    movimentado. Utilizável no momento em que você se cadastra, sem espera de
    compliance.
  </Card>

  <Card title="Modo produção" icon="building-columns">
    Executa contra a **instância de pagamento de produção** em trilhos reais.
    Desbloqueado por uma **Solicitação de Acesso à Produção** aprovada pela
    Caratuva; em seguida você conclui o KYB de produção antes de poder
    transacionar. É aqui que o BRL real é liquidado para a sua conta PIX.
  </Card>
</CardGroup>

O modo teste é um sandbox fiel, não um conjunto de fixtures prontas: ele exercita
a instância de pagamento sandbox real, então as respostas, webhooks e transições
de estado que você vê no modo teste são as mesmas que verá no modo produção. A
diferença é que o sandbox aprova o compliance automaticamente e nunca toca em
fundos reais.

## As sessões começam no modo teste

Uma conta totalmente nova chega no **modo teste**. Você pode imediatamente
executar um fluxo completo de ponta a ponta — fazer o onboarding (aprovado
automaticamente), criar uma fatura e pagá-la pelo link do comprador — sem
esperar por nada. Recomendamos executar seu primeiro fluxo no modo teste antes de
mudar para o modo produção.

## Trocando de modo

**No painel**, um indicador de modo fica no topo de cada tela; a troca é um
único clique. Por trás dos panos, o painel chama `POST /v1/auth/switch-mode`,
que reemite seu token de sessão com o novo modo. O modo produção só fica
selecionável depois que a Caratuva aprova a **Solicitação de Acesso à Produção**
da sua organização (enviada pela página **Habilitar produção**) — uma aprovação
manual distinta do KYB. Depois de mudar para o modo produção, você conclui o KYB
de produção na página de **Repasses** antes de poder transacionar.

**Pela API**, você não troca — o modo é fixado pela chave que você apresenta.
Uma chave `pk_test_…` é sempre teste; uma chave `pk_live_…` é sempre produção.
(Chamar `switch-mode` com uma chave de API retorna `ModeSwitchNotAllowed` — emita
uma chave do modo que você precisa.)

## Isolamento de dados

Teste e produção mantêm conjuntos de dados totalmente separados:

* **Faturas** são marcadas com o modo em que foram criadas. As listas e
  relatórios do painel sempre mostram apenas as faturas do modo ativo.
* **Compradores** têm escopo por modo — um comprador que completou o KYC no modo
  teste não o fez no modo produção, e vice-versa. O mesmo e-mail pode existir de
  forma independente em cada modo.
* **Onboarding/ativação** é rastreado por modo. O modo teste é ativado assim que
  seu KYB de sandbox passa (aprovado automaticamente); o modo produção só é
  ativado quando o KYB real é aprovado.

Nada criado no modo teste é jamais visível no modo produção, e nada no modo
produção vaza para o modo teste.

## Indo para produção: dois portões

O modo produção tem dois portões distintos, em ordem:

1. **Acesso à produção** — uma Solicitação de Acesso à Produção aprovada pela
   Caratuva desbloqueia a capacidade de mudar para o modo produção (veja
   [Trocando de modo](#trocando-de-modo)).
2. **KYB de produção (+ destino PIX)** — exigido, após a troca, antes que você
   possa de fato transacionar no modo produção. O modo teste fica aberto desde o
   cadastro e não exige nenhum dos dois.

Para verificar onde uma organização se encontra no modo ativo, o painel lê:

```
GET /v1/onboarding/status
```

```json theme={null}
{
  "mode": "live",
  "needsOnboarding": true,
  "tosAccepted": false,
  "kybStatus": null
}
```

`kybStatus` é `null` até que um KYB seja enviado, e então passa a ser um de
`pending` | `submitted` | `verifying` | `approved` | `rejected`.
`needsOnboarding` é `true` até que o ambiente daquele modo esteja totalmente
ativado. Quando é `true`, o painel encaminha você para o fluxo de onboarding
(Termos → KYB → destino PIX). Veja [Onboarding](/pt-BR/onboarding).

## Mapeamento para chaves de API

As chaves de API carregam o modo em seu prefixo — `pk_test_` ou `pk_live_` — e o
modo da chave determina qual instância de pagamento e conjunto de dados cada
requisição acessa. Veja
[Autenticação](/pt-BR/api-reference/authentication) e
[Chaves de API](/pt-BR/api-reference/api-keys), e a página
[Ambientes](/pt-BR/api-reference/environments) da referência de API para os
detalhes no nível de requisição.

## Para onde ir agora

* [Cadastro](/pt-BR/signup) — crie sua conta e chegue no modo teste.
* [Onboarding](/pt-BR/onboarding) — acesso à produção + KYB para desbloquear e transacionar no modo produção.
* [Ambientes da API](/pt-BR/api-reference/environments) — como o modo é carregado na API.