API Reference: Visão Geral

A API REST do Sentinex Risk Crypto segue convenções consistentes em todos os endpoints. Aprenda essas convenções uma vez e qualquer endpoint passa a ser previsível.

Base URLs

Ambiente	URL	Uso
Produção	`https://api.crypto.sentinexrisk.com/api/v1`	Tráfego real, dados reais, billing ativo
Produção (host do dashboard)	`https://crypto.sentinexrisk.com/api/v1`	Mesmo backend
Dashboard	`https://crypto.sentinexrisk.com`	Console humano (JWT + MFA), UI Pages

Convenções universais

Tópico	Convenção
Encoding	UTF-8, sempre
Casing	`snake_case` em campos JSON e query params
IDs	UUID v4 string (ex: `9c2a1b3e-1d0a-4b7f-8e2c-7a1b3c5d7e9f`)
Data/hora	ISO 8601 UTC com sufixo `Z` (ex: `2026-05-18T14:32:11Z`)
Valores monetários	string decimal de unidades-base (ex: `"1500.00"` BRL) ou raw integer (ex: `"50000000"` satoshis), sempre string para precisão
Enums	`UPPER_SNAKE_CASE` (ex: `KYC_TIER_STANDARD`, `RISK_RED`)
Booleanos	prefixos `is_`, `has_`, `requires_`
Paginação	cursor-based via `?cursor=…&limit=…` (ver Paginação)
Versionamento	URL versioning: `/api/v1/...` é estável; `/api/v2/...` (futuro) é breaking

Headers obrigatórios

Superfície de integração (/vasp/*), autenticada por API key:

X-API-Key: snxc_live_<sua_chave_aqui>
Content-Type: application/json
Accept: application/json

A API key carrega o tenant e os escopos: não existe header X-Tenant-ID. Rotas de dashboard usam Authorization: Bearer <JWT> (ver Authentication).

Headers opcionais úteis:

Header	Para que serve
`Idempotency-Key`	Retry-safe para POST/PATCH (ver Idempotência)
`X-Request-ID`	Correlation id que volta no `X-Request-ID` da resposta. Útil para suporte
`Accept-Language`	`pt-BR` (default) ou `en-US`. Afeta mensagens de erro

Estrutura padrão de resposta

Sucesso

{
  "success": true,
  "data": { /* recurso ou collection */ }
}

Listas vêm com paginação:

{
  "success": true,
  "data": [ /* items */ ],
  "pagination": {
    "next_cursor": "eyJpZCI6IjlhYjJjLi4uIn0=",
    "has_more": true,
    "page_size": 20
  }
}

Erro

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "O campo external_id é obrigatório.",
    "details": { "field": "external_id" },
    "request_id": "req_01HVZX9YQB7M3J2K5N8P1R4T6W"
  }
}

Ver Tabela de erros para o catálogo completo de códigos.

Grupos de endpoints

Grupo	Prefixo	Resumo
Identidade	`/customers`, `/clients`	KYC PF/PJ, screening, ciclo de vida
Carteiras	`/wallets`, `/vasp/wallets`	Screening on-chain, blocklist, attribution
Transações	`/transactions`, `/vasp/transactions`	KYT scoring real-time, histórico
Operações	`/alerts`, `/cases`, `/queue`	Mesa de trabalho compliance
Compliance	`/compliance/coaf`, `/compliance/decripto`, `/compliance/travelrule`	Reportes regulatórios
LGPD	`/lgpd/dsar`, `/lgpd/erasure`	Direitos do titular (Art. 18)
Webhooks	`/admin/webhooks/*`	Subscrições outbound + DLQ
Plataforma	`/auth/`, `/billing/`, `/admin/*`	Autenticação, billing, admin

Próximos passos

Quickstart: primeira chamada em 5 minutos
Authentication: JWT vs API Key, escopos
Webhooks: receber eventos em tempo real
Integration Guide: onboarding VASP ponta-a-ponta