Homologação e testes

Dois ambientes, duas bases

A integração de KYT tem um ambiente de testes e um de produção. Cada um é uma instalação própria, com banco próprio, e uma chave só funciona no ambiente em que foi emitida.

	Sandbox	Produção
Base da API	https://sandbox.api.crypto.sentinexrisk.com/api/v1	https://crypto-api.sentinexrisk.com/api/v1
Prefixo da chave	snxc_sand_	snxc_live_
Como a chave nasce	Emitida na hora, no painel	Pedida no painel e aprovada por outro Tenant Admin
Validade máxima da chave	30 dias	90 dias
Dados	Sintéticos	Reais
Cobrança e provedores pagos	Nenhum	Conforme o seu contrato
Consulta externa	Nenhuma: só o simulador	Sim

O painel é o mesmo nos dois casos (https://crypto.sentinexrisk.com). O ambiente em que você entra depende da conta: a conta de teste abre o sandbox, com uma faixa amarela fixa no topo (“Sandbox, dados sintéticos e efeitos externos desativados.”), e a conta real abre a produção. Os passos para criar cada chave estão no Guia de chaves de API.

Cuidado

A chave de um ambiente não vale no outro. Cada ambiente guarda só as próprias chaves, então uma snxc_live_ enviada ao host do sandbox, ou uma snxc_sand_ enviada à produção, não autentica. A resposta é 401 com error.code: "invalid_api_key" quando o ambiente não conhece a chave, e 403 com error.code: "api_key_environment_not_allowed" quando reconhece uma chave registrada para outro ambiente. Nos dois casos, confira se o prefixo da chave e a base da API são do mesmo ambiente. O prefixo snxc_test_ não é aceito por nenhum dos dois ambientes.

Como confirmar que você está no sandbox

A rota GET /health é pública. No sandbox, a resposta traz o header X-Sentinex-Environment: sandbox; na produção, o header não existe.

curl -i https://sandbox.api.crypto.sentinexrisk.com/api/v1/health

Se o header não aparecer, interrompa o teste e confira a base que você está usando.

O que o sandbox simula

O sandbox responde por um simulador determinístico. Ele não consulta provedor externo, não faz resolução de DNS e não cobra. Para a mesma entrada, devolve sempre o mesmo resultado.

• Contraparte só por fixture. Em POST /vasp/screenings, o counterparty_address precisa ser um dos endereços da tabela abaixo (com chain igual a ethereum). Qualquer outro endereço responde 422 com SANDBOX_FIXTURE_NOT_SUPPORTED, no mesmo envelope de erro das demais recusas da análise, sem consulta externa e sem cobrança. A produção nunca emite esse código
• Webhooks. Somente o evento webhook.test é entregue. Eventos de negócio, operacionais e regulatórios continuam bloqueados no sandbox
• E-mail. O sandbox não envia e-mail real
• Dados. Tudo o que você grava no sandbox fica no sandbox. Use apenas dados sintéticos: se enviar dado pessoal real, a LGPD continua valendo para ele

As demais operações do contrato (clientes, carteiras, alertas, decisão do cliente, laudo) têm o mesmo formato nos dois ambientes.

Fixtures do sandbox

O catálogo se chama sandbox-fixtures-v1. Cada identificador é derivado de forma pública: os 20 primeiros bytes do SHA-256 do texto sentinex:sandbox-fixture:v1: seguido do nome da fixture, em hexadecimal minúsculo, com o prefixo 0x. Todas usam a rede ethereum.

Fixture	Endereço da contraparte	Resultado em POST /vasp/screenings
fx-kyt-low-v1	0x7eae68ba864d7e60463ca6842c53f1b20ecfb1a2	ALLOW, risco LOW, score 5
fx-kyt-review-v1	0x50163eb876f2ae7ba62193d5138f50595976fb00	REVIEW, risco MEDIUM, score 55
fx-kyt-deny-sanctions-v1	0x4f6429a9dfcd41a13f20d5f96d0facd04847e691	DENY, risco CRITICAL, score 100, com sanção sintética
fx-provider-error-v1	0x1b5fb884c8a8cb051277a080d02a066dfb832480	HOLD com fail_closed verdadeiro: erro simulado, reprocesse
fx-provider-timeout-v1	0x8c06fec94e33882f76f03138ddff4a7018bb2656	HOLD com fail_closed verdadeiro: tempo esgotado simulado, sem espera real, reprocesse
fx-replay-v1	0x285621d51a93dda060d5e1a69ef98ccb72c90909	ALLOW, risco LOW, score 5
fx-webhook-retry-v1	0x4ec08a4923730faebea91fbb53e735f3e5bb7007	ALLOW, risco LOW, score 5
fx-concurrent-idempotency-v1	0x7137a9241c8c63df0c576d7ea66709e488c94073	ALLOW, risco LOW, score 5

Os três últimos têm o mesmo resultado da fixture de baixo risco. Eles servem de endereço para você exercitar a sua repetição com a mesma Idempotency-Key e as suas chamadas concorrentes (ver Idempotência).

A fixture fx-kyt-deny-sanctions-v1 é a única que produz DENY, porque a recomendação DENY só nasce de sanção ou de regra de bloqueio configurada pelo próprio tenant. A fixture fx-kyt-review-v1 mostra o caminho de revisão sem sanção. Na evidência de sanção dessa fixture, list vale SANDBOX_FIXTURE, list_version vale sandbox-fixtures-v1 e source vale SENTINEX_SANDBOX.

Os endereços 0x00000000000000000000000000000000000000a1 (baixo risco, ALLOW) e 0x00000000000000000000000000000000000000b2 (misturador sem sanção, REVIEW, risco CRITICAL) continuam respondendo no sandbox, com a mesma regra de rede. São fixtures antigas, mantidas por compatibilidade: em testes novos, use o catálogo acima.

O mesmo catálogo aparece no painel, em Desenvolvedores > Console da API, quando a sessão é do sandbox. O erro 422 aponta para GET /api/v1/sandbox/fixtures, que devolve o mesmo catálogo com um selo de integridade. Essa rota exige sessão de usuário do painel (token Bearer de um usuário do tenant) e não aceita chave de API.

Limites que valem no sandbox

Limite	Valor
Por chave	60 requisições por minuto, a menos que você tenha definido outro valor ao criar a chave (de 1 a 10.000)
Por tenant	2.000 requisições por minuto, somando chaves e usuários
Validade da chave	Até 30 dias. Sem data informada, a chave vale 29 dias e 23 horas

Ao estourar um limite, a resposta é 429 com Retry-After. Os detalhes dos cabeçalhos estão em Limites de requisição.

Em produção, uma chamada de teste é uma chamada real

O contrato não tem campo que marque uma requisição como teste. Na produção, tudo o que a página abaixo descreve acontece de verdade. Valide a integração no sandbox antes e chegue à produção só com o fluxo completo funcionando.

Chamada	Efeito em produção
POST /vasp/screenings	A análise é feita e gravada no tenant, com trilha de auditoria. É registrada como uso da API, e o efeito comercial segue o seu contrato. Análise sinalizada abre alerta na fila do tenant. Dispara kyt.screening.completed para as suas subscriptions. A repetição idempotente devolve a análise original e não repete nenhum desses efeitos
PATCH /vasp/screenings/{id}/client-decision	A decisão é gravada uma única vez e não pode ser alterada. Não registre decisão de teste numa análise real
POST /vasp/customers e POST /vasp/wallets	Criam registros reais no tenant. O external_id é único por tenant: use identificadores de teste que não colidam com os que você usará depois
POST /vasp/kyt-report	Gera o laudo e registra a emissão na auditoria. Conta no limite de 120 emissões por hora por IP
Webhooks	Os eventos de negócio só são entregues a tenant de cliente em produção: ativo, do tipo cliente, fora de demonstração e de dados sintéticos, no modo live, faturável e com efeitos externos liberados. O webhook.test é entregue em qualquer tenant

Roteiro sugerido

1. No sandbox: autenticação sem efeito. GET /vasp/alerts?limit=1 com o escopo vasp:read confere a chave, o ambiente e o acesso da conta sem gravar nada. Recusas da conta chegam como 402 ou 403 com o código no campo code (ver Autenticação)
2. No sandbox: uma análise por fixture. Rode fx-kyt-low-v1, fx-kyt-review-v1 e fx-kyt-deny-sanctions-v1 e confira que o seu sistema trata ALLOW, REVIEW e DENY. Rode as de erro e de tempo esgotado e confira que o seu sistema trata HOLD como pendente, nunca como aprovado
3. No sandbox: receptor de webhook. Crie a subscription com POST /vasp/webhooks e dispare POST /vasp/webhooks/{id}/test. Valide a assinatura como descrito em Webhooks
4. No sandbox: repetição. Repita uma análise com a mesma Idempotency-Key e os mesmos bytes e confirme idempotent_replay: true. Ver Idempotência
5. Na produção: autenticação sem efeito. Com a chave live aprovada, repita o passo 1 na base de produção
6. Na produção: poucas análises reais. Combine com a Sentinex Risk um volume pequeno, com client_transaction_id identificável e Idempotency-Key em todas, e registre a decisão do cliente só nas análises criadas para isso
7. Tratamento de erro sem efeito. Uma análise sem o campo obrigatório asset é recusada com 400 e KYT_ASSET_REQUIRED antes de qualquer gravação, nos dois ambientes