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

# Ambientes

> Como os modos teste e produção são transmitidos na API.

A Caratuva tem um único host de API. Não existe uma URL de sandbox separada. Em vez
disso, toda requisição roda em modo **teste** ou **produção**, e o modo é
determinado inteiramente pela credencial que você apresenta.

Veja a página [Modos teste e produção](/pt-BR/environments) no lado dos guias para
a visão conceitual; esta página cobre os detalhes em nível de requisição.

## O modo é transmitido pela chave

As chaves de API codificam seu modo no prefixo:

| Prefixo     | Modo     | Trilhos                                                                               |
| ----------- | -------- | ------------------------------------------------------------------------------------- |
| `pk_test_…` | teste    | Instância de pagamento sandbox — KYB/KYC com aprovação automática, sem dinheiro real. |
| `pk_live_…` | produção | Instância de pagamento de produção — trilhos reais, liquidação real.                  |

Uma chave de teste só pode ler e gravar dados de teste; uma chave de produção,
apenas dados de produção. Você não passa um parâmetro de modo e não pode
sobrescrevê-lo com um header — a chave é o modo. Emita uma chave por modo (veja
[Chaves de API](/pt-BR/api-reference/api-keys)).

O recurso de chave de API reporta seu modo via o booleano `testMode`, derivado do
prefixo:

```json theme={null}
{
  "keyPrefix": "pk_test_KEY_ID",
  "testMode": true
}
```

## Sessões do dashboard alternam; chaves não

Os JWTs Bearer do dashboard também carregam um modo, e começam em **teste**. O
dashboard re-emite o token para alternar:

```bash theme={null}
curl -X POST https://api.caratuva.com/v1/auth/switch-mode \
  -H "Authorization: Bearer <dashboard-jwt>" \
  -H "content-type: application/json" \
  -d '{ "mode": "live" }'
```

```json theme={null}
{ "token": "<new-jwt-bound-to-live>", "mode": "live" }
```

O novo token é vinculado ao modo escolhido; o dashboard o armazena e o usa para as
requisições subsequentes. Alternar para produção exige que a **Solicitação de Acesso
à Produção** da organização tenha sido aprovada pela Caratuva (uma aprovação manual,
distinta do KYB); caso contrário, a chamada retorna `400 ProductionAccessNotApproved`.
O KYB de produção é concluído depois, na página de "Repasses", antes de a organização
poder transacionar.

Quem chama via chave de API **não pode** usar este endpoint — já carrega seu modo
no prefixo da chave. Chamá-lo com uma chave de API retorna:

```json theme={null}
{
  "statusCode": 400,
  "error": "ModeSwitchNotAllowed",
  "message": "API-key callers select mode via their key prefix, not switch-mode."
}
```

## Isolamento de dados

Teste e produção são conjuntos de dados separados. O mesmo escopo que isola uma
organização de outra (veja [Autenticação → Tenancy](/pt-BR/api-reference/authentication#tenancy))
também isola teste de produção dentro da sua organização:

* Faturas e payment intents são marcados com o modo em que foram criados; os
  endpoints de listagem e leitura só retornam os registros do modo ativo.
* Compradores têm escopo por modo — o mesmo e-mail de comprador é um registro
  distinto em teste e em produção, e o KYC concluído em um não é transferido para o
  outro.
* As entregas de webhook refletem apenas o modo da fatura que as gerou.

## Status de onboarding

Para verificar se o modo ativo de quem chama está pronto para transacionar:

```bash theme={null}
curl https://api.caratuva.com/v1/onboarding/status \
  -H "Authorization: Bearer <dashboard-jwt>"
```

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

* `mode` — o modo ativo da credencial.
* `needsOnboarding` — `true` até que o ambiente deste modo seja ativado. O teste é
  ativado assim que seu KYB de sandbox é liberado (aprovação automática); a produção
  só é ativada com a aprovação real do KYB (após o acesso à produção ter sido
  concedido).
* `tosAccepted` — se os Termos do provedor de pagamento foram aceitos para este modo.
* `kybStatus` — o status da submissão de KYB mais recente para este modo, ou `null`
  se nenhuma foi iniciada.

## Paridade de comportamento

O modo teste roda o mesmo caminho de código que o de produção contra uma instância
de pagamento sandbox — as mesmas transições de intent, os mesmos tipos de evento de
webhook, os mesmos formatos de resposta. As únicas diferenças são que o sandbox
aprova a conformidade automaticamente e nunca movimenta fundos reais. Desenvolva e
teste com `pk_test_`, depois mude para `pk_live_` em produção.