Guia de Integração: VASP onboarding ponta-a-ponta

Este guia leva uma VASP do zero ao primeiro fluxo produtivo em 4 horas de engineering. Cobre KYC de cliente, registro de wallet, scoring de transação, recepção de alerta via webhook, e escalonamento na mesa.

Pré-requisitos:

CNPJ ativo e cadastro aprovado em crypto.sentinexrisk.com/signup
API key gerada com escopos customers:write, wallets:write, transactions:write, alerts:read
Endpoint HTTPS público para receber webhooks (ou ngrok em dev)

Configure variáveis de ambiente

export SENTINEX_API_KEY="snxc_live_<SUA_API_KEY_AQUI>"
export SENTINEX_BASE_URL="https://api.crypto.sentinexrisk.com/api/v1"
export SENTINEX_WEBHOOK_SECRET="<secret retornado na criação do webhook>"

Health check: confirme conectividade
Terminal window
```
curl $SENTINEX_BASE_URL/health
```
Esperado: 200 {"postgres":"ok","redis":"ok","service":"crypto-sentinexrisk","status":"ok","version":"..."}. O health é público; as demais chamadas usam o header X-API-Key (a key carrega o tenant e os escopos; não existe header de tenant).

Crie um cliente (KYC PF)

A API recebe somente identificadores pseudonimizados (LGPD): envie o SHA-256 do CPF/CNPJ em document_hash, nunca o documento em claro. Payloads com CPF/CNPJ/email/telefone em claro são rejeitados com 400.

curl -X POST $SENTINEX_BASE_URL/vasp/customers \
  -H "X-API-Key: $SENTINEX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "external_id": "DEMO-VASP-001",
    "type": "PF",
    "document_hash": "'$(printf %s "00000000000" | shasum -a 256 | cut -d" " -f1)'",
    "kyc_tier": "STANDARD",
    "risk_classification": "MEDIUM",
    "consent_data_share": true
  }'

Resposta 201 inclui id (prefixo cust_), kyc_tier, risk_classification e screening_status: "PENDING". Requer o escopo vasp:customers:write.

Vincule uma wallet ao cliente

curl -X POST $SENTINEX_BASE_URL/vasp/wallets \
  -H "X-API-Key: $SENTINEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "<id retornado no passo 3>",
    "external_id": "WALLET-DEMO-001",
    "address": "bc1qexample0demoaddress0000000000000000",
    "blockchain": "btc",
    "asset_symbol": "BTC",
    "wallet_label": "Hot wallet principal"
  }'

Resposta 201 com screening_status, decision e risk_tier (carteira desconhecida cai em REVIEW fail-closed até o screening completar). Requer o escopo vasp:wallets:write.

Analise uma transação (KYT scoring)

curl -X POST $SENTINEX_BASE_URL/vasp/screenings \
  -H "X-API-Key: $SENTINEX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: txn-demo-001" \
  -d '{
    "client_transaction_id": "txn-demo-001",
    "customer_ref": "DEMO-VASP-001",
    "direction": "DEPOSIT",
    "asset": "BTC",
    "chain": "btc",
    "counterparty_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "amount": 0.05
  }'

Resposta síncrona (escopo vasp:transactions:screen):

{
  "success": true,
  "data": {
    "screening_id": "uuid",
    "screen_status": "completed",
    "decision": "REVIEW",
    "risk_score": 67,
    "risk_level": "HIGH",
    "sanctions": { "hit": false },
    "rule_hits": [
      { "rule_id": "R-CRYPTO-04", "name": "Counterparty exposure to known mixer", "severity": "HIGH", "weight": 25 }
    ],
    "obligations": { "travel_rule": "NOT_REQUIRED", "coaf_sar": "MONITOR", "decripto": "REPORTABLE" },
    "amount_brl": 17300.5,
    "fail_closed": false,
    "latency_ms": 41,
    "api_version": "2026-06-01"
  }
}

decision: REVIEW ou pior gera alerta, vai para a mesa de compliance e dispara o webhook alert.created.

Receba o webhook

Sua aplicação recebe POST em <seu_url>/sentinex:

{
  "event": "alert.created",
  "delivery_id": "dlv_01HVZ…",
  "timestamp": "2026-05-18T14:32:11Z",
  "data": {
    "id": "alt_01HVZ…",
    "severity": "HIGH",
    "customer_id": "…",
    "transaction_id": "txn_01HVZ…",
    "score": 67,
    "rules_triggered": [{ "id": "R-CRYPTO-04", "name": "..." }]
  }
}

Verifique a assinatura HMAC antes de processar. Ver Webhooks.

Trabalhe o alerta
- Por API key: acompanhe com GET /vasp/alerts (escopo vasp:read) e feche o ciclo com o feedback set-once PATCH /vasp/screenings/{id}/decision { "resolution": "FALSE_POSITIVE", "reason": "Mixer exposure < 0.1%" }.
- Pela mesa do console (JWT + RBAC): atribuir (POST /alerts/{id}/assign), escalar (POST /alerts/{id}/escalate) e resolver (POST /alerts/{id}/resolve).
Cada ação grava no audit trail imutável e dispara webhook alert.escalated / alert.resolved.
Próximos passos
- Configure mais subscriptions de webhook por área (ops, compliance, fraude)
- Integre com seu CRM via outbound events
- Configure SAR COAF automático no console Compliance → COAF
- Habilite Travel Rule no console Compliance → Travel Rule (obrigatório fev/2027)

Checklist go-live

API key de produção gerada (não reusar a de ambiente de teste)
Webhook secret armazenado em vault, rotação programada (90d)
Retry exponencial implementado para 429/5xx
Idempotency-Key em todos os POST de mutação
Validação de assinatura HMAC em todos os webhooks recebidos
Logs estruturados com request_id para correlação com suporte
Monitoring de quota (X-RateLimit-Remaining) com alerta em 80%
Plano de contingência se Sentinex retornar 503 SERVICE_DEGRADED

Tempo estimado por etapa

Etapa	Engenharia
Setup + health check	30 min
KYC + wallet linking	1h
KYT + recepção webhook	1h30
Mesa de trabalho automation	1h
Total	~4h