Integração de Monitorização de Transações: API KYT

Monitorização de Transações: guia de integração Este guia cobre toda a superfície de integração da Monitorização de Transações. O início rápido põe-no a funcionar; esta página leva-o até à produção.

Arquitetura

Autenticação

Cabeçalho x-api-key padrão. As mesmas chaves de API são usadas para sessões e entidades. Consulte Autenticação da API.

Envio de uma transação

Endpoint único: POST /v3/transactions/. Consulte envio de transações para o esquema completo. Payload mínimo:

{
  "transaction_id": "tx-0001",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "500.00",
    "currency": "EUR"
  },
  "subject": { "entity_type": "person", "vendor_data": "user-42", "full_name": "John Doe" },
  "counterparty": { "entity_type": "company", "full_name": "Acme Corp" }
}

Payload mais completo, com métodos de pagamento, contexto do dispositivo e propriedades personalizadas:

{
  "transaction_id": "tx-0002",
  "transaction_at": "2026-04-16T10:00:00Z",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "12500.00",
    "currency": "USD",
    "action_type": "withdrawal"
  },
  "subject": {
    "entity_type": "person",
    "vendor_data": "user-42",
    "full_name": "John Doe",
    "country_code": "US",
    "device_context": {
      "fingerprint": "fp-9f2c...",
      "user_agent": "Mozilla/5.0 ...",
      "browser_family": "Chrome",
      "platform": "web",
      "network_context": { "ip_address": "203.0.113.5" }
    },
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US12345678901234567890",
      "issuing_country": "US"
    }
  },
  "counterparty": {
    "entity_type": "company",
    "vendor_data": "biz-acme",
    "full_name": "Acme Corp",
    "country_code": "US",
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US09876543210987654321",
      "issuing_country": "US"
    }
  },
  "custom_properties": {
    "invoice_id": "INV-2026-00042",
    "category": "b2b_goods"
  }
}

Os alias em camelCase são aceites para todos os campos de nível superior (txnId, txnDate, type, info, applicant, props, travelRule, includeCryptoScreening): o formato de transmissão do SDK e o formato snake_case são tratados da mesma forma.

Modelação das partes

Cada transação tem um subject obrigatório (o seu cliente, a parte que é monitorizada) e um counterparty opcional (a contraparte, o outro lado). Cada um tem o seu próprio payment_method e um contexto device opcional. Na resposta, são devolvidos no array parties com as funções APPLICANT e COUNTERPARTY; uma parte sem vendor_data é guardada como um instantâneo externo (kind: EXTERNAL) sem entidade associada. Consulte payload de transações para os campos das partes.

Idempotência

txn_id (o transaction_id que envia) é único por aplicação. Reenviar um transaction_id que já existe devolve 400 com A transaction with this transaction_id already exists. no campo transaction_id; quando dois pedidos idênticos entram em conflito em simultâneo, o segundo recebe 409. Nenhuma destas respostas devolve a transação existente. Perante um 400 ou 409 por transaction_id duplicado, consulte a transação existente em vez de a reenviar: leia-a com GET /v3/transactions/{uuid}/ usando o uuid da primeira resposta, ou use o transaction_id (o uuid da Didit) que o webhook transaction.created traz ao lado do seu txn_id. Gere sempre o txn_id do seu lado antes de submeter; não dependa de um ID gerado pela Didit para a idempotência. Use o ID da sua base de dados, um UUID ou um hash dos campos da transação.

Tempo real vs. lote

Tempo real: recomendado para a maioria dos casos. Envie a transação no momento em que acontece no seu sistema. As regras são avaliadas de forma síncrona e devolvem a decisão.
Lote / carregamento retroativo: para ingestão histórica, passe um txn_date no passado. As regras continuam a ser executadas e podem acionar webhooks. Para evitar acionar regras no carregamento retroativo, use a importação CSV da consola com a opção “dry ingest”.

Ingestão histórica

Quando estiver a migrar de outro sistema de monitorização de transações:

Exporte as suas transações históricas para um CSV.
Use Transactions → Import history na consola (ou envie através da API num ciclo) com txn_date no passado.
Ative as regras apenas depois de a ingestão terminar, ou use o dry ingest para ignorar a avaliação de regras.

Seja cuidadoso com a avaliação histórica de regras. Passar 6 meses de histórico por uma regra de “20 transferências em 30 dias” vai gerar milhares de alertas de uma só vez.

Webhooks

Subscreva:

transaction.created: todas as transações enviadas.
transaction.status.updated: alterações de estado (por exemplo, o analista passa de IN_REVIEW para APPROVED, ou uma verificação AML assíncrona atualiza a pontuação).

Detalhes completos: webhooks de Monitorização de Transações.

app.post('/webhooks/didit-tm', (req, res) => {
  if (!verifySignature(req)) return res.status(401).end();

  const { webhook_type, status, txn_id } = req.body;
  if (webhook_type === 'transaction.status.updated' && status === 'DECLINED') {
    suspendTransaction(txn_id);
  }
  res.status(200).end();
});

Gestão dos estados

Estado	O que fazer
`APPROVED`	Processe a transação normalmente.
`IN_REVIEW`	Retenha a transação até que a revisão do analista ou a reverificação automática a resolva.
`DECLINED`	Rejeite a transação. Apresente um erro genérico ao utilizador.
`AWAITING_USER`	O utilizador tem de agir antes de a transação poder ser liquidada: leia o bloco `action_required` e entregue o seu `url` ao utilizador (os SDK podem tratar isto automaticamente).

Consulte estados de Monitorização de Transações.

Associar transações a entidades

Passe vendor_data em todas as partes. Vantagens:

Cada transação é agregada ao perfil do utilizador ou da empresa.
As regras de velocidade e de comportamento têm o histórico completo para fazer a avaliação.
Bloquear uma entidade propaga-se automaticamente às transações futuras.

A ausência de vendor_data não é um erro impeditivo: a transação é guardada como instantâneo externo, mas perde a agregação ao nível da entidade.

Sessões de remediação

Quando uma ação de uma regra move uma transação para AWAITING_USER, a Didit cria automaticamente uma sessão de remediação - uma sessão de verificação alojada padrão para o mesmo vendor_data. As regras personalizadas indicam sempre o fluxo na própria ação; para as regras incluídas na biblioteca, o fluxo recai sobre o fluxo de remediação nas definições de transação, depois sobre o fluxo de Autenticação biométrica da sua aplicação (quando o titular tem um rosto de referência guardado) e, por fim, sobre o fluxo predefinido da sua aplicação. As transações Travel Rule são excluídas deste mecanismo de recurso automático - a ação pendente é a prova de propriedade da carteira. A transação (a resposta, todas as leituras seguintes e todos os webhooks) inclui a sessão no bloco canónico action_required:

{
  "status": "AWAITING_USER",
  "action_required": {
    "type": "verification_session",
    "url": "https://verify.didit.me/session/...",
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "status": "Not Started"
  },
  "remediation": {
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "url": "https://verify.didit.me/session/...",
    "status": "Not Started"
  }
}

remediation é mantido por compatibilidade com versões anteriores; action_required é o bloco canónico (inclui também as ações wallet_ownership das transferências Travel Rule). Uma ação wallet_ownership não altera, por si só, o estado da transação: a transação mantém o estado que as suas regras lhe atribuem, frequentemente APPROVED. Por isso, verifique action_required em todas as respostas, e não apenas quando o estado for AWAITING_USER. O utilizador conclui a verificação - num fluxo de Autenticação biométrica, uma selfie com prova de vida comparada com o rosto capturado no onboarding KYC inicial, o reforço de autenticação mais forte para transações de valor elevado. Quando a sessão atinge uma decisão, a transação segue-a automaticamente - APPROVED (decision_reason_code: user_action_approved), DECLINED (user_action_declined) ou IN_REVIEW (user_action_in_review) - e é disparado um webhook transaction.status.updated.

Pode ser selecionado qualquer tipo de fluxo, exceto KYB. Os fluxos de Autenticação biométrica (e os fluxos em que a correspondência facial é executada antes da verificação de identidade) exigem que o titular já tenha um rosto de referência guardado, proveniente de uma verificação aprovada. Os utilizadores que não tenham um são encaminhados para o fluxo predefinido da sua aplicação, com uma nota na transação a registar essa substituição.

Boas práticas

Prática	Porquê
Envie sempre `vendor_data`	Permite a agregação.
Utilize o seu próprio `txn_id`	Idempotência.
Subscreva tanto `transaction.created` como `transaction.status.updated`	Deteta alterações de estado assíncronas (por exemplo, resultados das revisões de analistas).
Defina criteriosamente os limiares das regras	Limiares baixos = mais alertas; elevados = mais riscos não detetados. Consulte a pontuação de risco.
Monitorize as contagens de execução das regras na consola	Deteta regras que nunca disparam (mal configuradas) ou que disparam em tudo (demasiado permissivas).
Teste as regras no modo TEST antes de entrar em produção	Consulte regras.

Limites de pedidos

Consulte a limitação de pedidos. A criação de transações é um dos endpoints com maior capacidade de processamento; os limites típicos situam-se nas centenas de pedidos por segundo. Envie rajadas de pedidos com cuidado.

Próximos passos

Transações

Referência completa do payload.

Regras

Como as regras são avaliadas.

Webhooks

Catálogo de eventos.

Resolução de problemas

Problemas comuns de integração.

Primeiros passos

Funcionalidades

Referência

Consola

Integração de Monitorização de Transações: API KYT

Arquitetura

Autenticação

Envio de uma transação

Modelação das partes

Idempotência

Tempo real vs. lote

Ingestão histórica

Webhooks

Gestão dos estados

Associar transações a entidades

Sessões de remediação

Boas práticas

Limites de pedidos

Próximos passos

Transações

Regras

Webhooks

Resolução de problemas

​Arquitetura

​Autenticação

​Envio de uma transação

​Modelação das partes

​Idempotência

​Tempo real vs. lote

​Ingestão histórica

​Webhooks

​Gestão dos estados

​Associar transações a entidades

​Sessões de remediação

​Boas práticas

​Limites de pedidos

​Próximos passos

Transações

Regras

Webhooks

Resolução de problemas

Arquitetura

Autenticação

Envio de uma transação

Modelação das partes

Idempotência

Tempo real vs. lote

Ingestão histórica

Webhooks

Gestão dos estados

Associar transações a entidades

Sessões de remediação

Boas práticas

Limites de pedidos

Próximos passos