Pular para o conteúdo principal
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 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:
PrefixoModoTrilhos
pk_test_…testeInstância de pagamento sandbox — KYB/KYC com aprovação automática, sem dinheiro real.
pk_live_…produçãoInstâ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). O recurso de chave de API reporta seu modo via o booleano testMode, derivado do prefixo: 
{
  "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: 
curl -X POST https://api.caratuva.com/v1/auth/switch-mode \
  -H "Authorization: Bearer <dashboard-jwt>" \
  -H "content-type: application/json" \
  -d '{ "mode": "live" }'

{ "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: 
{
  "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) 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: 
curl https://api.caratuva.com/v1/onboarding/status \
  -H "Authorization: Bearer <dashboard-jwt>"

{
  "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.