API Reference: Visão Geral

Esta referência é o contrato do cliente KYT: as operações que a API de produção serve a uma integração autenticada por chave de API. Cada operação tem página própria, gerada a partir do contrato, com parâmetros, corpos, respostas e códigos de erro declarados. A lista completa, com a versão do contrato e as convenções publicadas nele, está em Todas as operações. O arquivo do contrato está em openapi.yaml e openapi.json, e o histórico de versões em Versionamento e changelog.

Base URL

Uso	URL
API de produção	https://crypto-api.sentinexrisk.com/api/v1
API do sandbox	https://sandbox.api.crypto.sentinexrisk.com/api/v1
Painel, para pessoas	https://crypto.sentinexrisk.com

Os caminhos do contrato são relativos à base. O prefixo /v1 sozinho responde 404. O endereço do painel serve a interface: uma chamada de API feita para ele recebe o HTML do painel, e não a resposta da API. O contrato publicado descreve a base de produção; o sandbox usa os mesmos caminhos na base própria, com chave snxc_sand_ e contraparte restrita às fixtures. Veja Homologação e testes.

Headers

X-API-Key: snxc_live_<sua_chave>   # snxc_sand_<sua_chave> no sandbox
Content-Type: application/json
Accept: application/json

A chave carrega o tenant e os escopos: não existe header X-Tenant-ID. Ver Autenticação.

Header opcional	Para que serve
Idempotency-Key	Retentativa segura em POST /vasp/screenings, POST /vasp/customers e POST /vasp/wallets (ver Idempotência)
X-Request-ID	Identificador de correlação, que volta na resposta. Guarde-o para o suporte

Envelope de sucesso

As respostas de screening trazem success: true e o recurso em data. A criação e o teste de subscription de webhook devolvem seus campos na raiz, sem data. Algumas operações acrescentam campos ao lado de data, como idempotent_replay no replay idempotente e next_cursor nas listagens de clientes. As páginas de cada operação mostram o schema declarado.

Envelope de erro

O formato de erro não é único na superfície /vasp. Os mais comuns:

Origem	Forma
Chave, escopo, ambiente e limite por chave; cadastro de clientes e carteiras	{"success": false, "error": {"code": "...", "message": "..."}}
Análise, decisão do cliente e laudo	{"success": false, "error": {"code", "http_status", "message", "action", "retriable", "retry_after_seconds", "request_id"}}
Acesso da conta e módulo do tenant	{"success": false, "error": "texto", "code": "...", "details": {...}}
Outras recusas de validação	{"success": false, "error": "texto"}

Trate primeiro o status HTTP e só depois o corpo, checando se error é objeto ou texto. Ver Erros e códigos.

Cuidado

Quando receber 5xx numa análise, a transação não foi triada. Não substitua a resposta por uma aprovação local: repita com a mesma Idempotency-Key ou trate a transação como pendente de análise.

Rota inexistente e evidência de decisão

Caminho ou método inexistente sob /vasp, com chave válida e gates anteriores atendidos, responde 404 route_not_found. Sem chave válida, continua valendo o erro de autenticação. HTTP 200 com data.fail_closed: true e HOLD registra evidência incompleta: retenha e reprocesse após recuperar a fonte. Consulte Como as regras decidem.

O que fica fora desta referência

As rotas do painel, usadas por pessoas com sessão de usuário, não fazem parte do contrato do cliente e não aceitam chave de API. Entre elas estão a lista de bloqueio do tenant, a resolução de alertas pela mesa de análise, a aprovação de KYC e a gestão de chaves e de entregas de webhook. Referências antigas a POST /wallets/screen, GET /alerts ou PUT /clients/{id}/kyc/approve neste site descreviam essas rotas.