> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Integração de monitoramento de transações: API KYT

> Integre o KYT da Didit: tempo real vs lote, partes, idempotência, ingestão histórica e webhooks. 1,000 por mês inclusos, depois $0.001 cada.

Este guia cobre todos os aspectos da integração do Monitoramento de transações. O [guia de início rápido](https://docs.didit.me/pt-br/transaction-monitoring/quickstart.md) permite que você comece a usar; esta página prepara você para produção.

## Arquitetura

```mermaid theme={null}
sequenceDiagram
    participant You as Your platform
    participant Didit as Didit API
    participant Rules as Rule engine
    participant AML as AML providers
    participant Webhook as Your webhook

    You->>Didit: POST /v3/transactions/ (txn_id, parties, amount)
    Didit->>Didit: IP enrichment (inline)
    Didit->>AML: Screen wallet or transaction hash + address
    AML-->>Didit: Hits / clean
    Didit->>Rules: Evaluate all active rules
    Rules-->>Didit: Score + matched rules + actions
    Didit-->>You: Transaction record with status
    Didit->>Webhook: transaction.created
    Didit->>Webhook: transaction.status.updated (if async rules)
```

## Autenticação

Cabeçalho padrão `x-api-key`. São as mesmas chaves usadas para sessões e entidades. Consulte [autenticação da API](https://docs.didit.me/pt-br/getting-started/api-authentication.md).

## Envio de uma transação

Um único endpoint: `POST /v3/transactions/`. Consulte [envio de transações](https://docs.didit.me/pt-br/transaction-monitoring/transactions.md) para ver o esquema completo.

**Payload mínimo:**

```json theme={null}
{
  "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 de dispositivo e propriedades personalizadas:**

```json theme={null}
{
  "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"
  }
}
```

Aliases em camelCase são aceitos 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 processados da mesma forma.

## Modelagem das partes

Toda transação tem um `subject` obrigatório (seu cliente, a parte que você monitora) e uma `counterparty` opcional (o outro lado). Cada uma tem seu próprio `payment_method` e um contexto de `device` opcional.

Na resposta, elas voltam no array `parties` com as funções `APPLICANT` e `COUNTERPARTY`. Uma parte sem `vendor_data` é armazenada como um snapshot externo (`kind: EXTERNAL`), sem entidade vinculada.

Consulte [payload de transações](https://docs.didit.me/pt-br/transaction-monitoring/transactions.md) para ver os campos das partes.

## Idempotência

`txn_id` (o `transaction_id` que você envia) é único por aplicação.
Reenviar um `transaction_id` que já existe retorna `400` com `A transaction with this transaction_id already exists.` no campo `transaction_id`. Quando duas requisições idênticas concorrem entre si, a segunda recebe `409`.
Nenhuma das duas respostas retorna a transação existente.
Diante de um `400` ou `409` por `transaction_id` duplicado, consulte a transação existente em vez de reenviá-la: leia-a com [`GET /v3/transactions/{uuid}/`](https://docs.didit.me/pt-br/management-api/transactions/get) usando o `uuid` da primeira resposta, ou use o `transaction_id` (o uuid da Didit) que o webhook `transaction.created` traz junto com o seu `txn_id`.

**Sempre gere o `txn_id` do seu lado** antes de enviar; não dependa de um ID gerado pela Didit para a idempotência. Use o ID do seu próprio banco de dados, um UUID ou um hash dos campos da transação.

## Tempo real vs. lote

* **Tempo real**: recomendado para a maioria dos casos de uso. Envie a transação no momento em que ela acontece no seu sistema. As regras são avaliadas de forma síncrona e retornam a decisão.
* **Lote / carga retroativa**: para ingestão de histórico, informe um `txn_date` no passado. As regras continuam sendo executadas e podem disparar webhooks. Para evitar que as regras sejam acionadas na carga retroativa, use a importação de CSV do console com a opção "dry ingest".

## Ingestão de histórico

Quando você estiver migrando de outro sistema de monitoramento de transações:

1. Exporte suas transações históricas para um CSV.
2. Use *Transactions → Import history* na console (ou envie pela API em um loop) com `txn_date` no passado.
3. Ative as regras somente depois que a ingestão terminar, ou use o dry ingest para pular a avaliação de regras.

> [!WARNING]
>
> Pense bem antes de avaliar regras sobre o histórico. 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

Inscreva-se em:

* `transaction.created`: toda transação enviada.
* `transaction.status.updated`: mudanças de status (por exemplo, um analista muda de `IN_REVIEW` para `APPROVED`, ou uma verificação AML assíncrona atualiza a pontuação).

Detalhes completos: [webhooks de TM](https://docs.didit.me/pt-br/transaction-monitoring/webhooks.md).

```typescript theme={null}
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();
});
```

## Tratamento dos status

| Status | O que fazer |
| - | - |
| `APPROVED` | Processe a transação normalmente. |
| `IN_REVIEW` | Retenha a transação até que a revisão do analista ou uma nova verificação automática seja concluída. |
| `DECLINED` | Rejeite a transação. Mostre um erro genérico ao usuário. |
| `AWAITING_USER` | O usuário precisa agir antes que a transação possa ser liquidada: leia o bloco `action_required` e forneça a `url` ao usuário (os SDKs podem [cuidar disso automaticamente](https://docs.didit.me/pt-br/transaction-monitoring/sdk-transaction-submission.md#ações-exigidas-do-usuário)). |

Consulte [status de TM](https://docs.didit.me/pt-br/transaction-monitoring/statuses.md).

## Vinculação de transações a entidades

Informe `vendor_data` para cada parte. Benefícios:

* Todas as transações são agregadas ao perfil do usuário ou da empresa.
* As regras de velocidade e de comportamento têm acesso ao histórico completo para avaliação.
* O bloqueio de uma entidade se propaga automaticamente para as transações futuras.

A ausência de `vendor_data` não é um erro bloqueante (a transação é armazenada como um snapshot externo), mas você perde a agregação no nível da entidade.

## Sessões de remediação

Quando a 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 hospedada padrão para o mesmo `vendor_data`.
Regras personalizadas sempre indicam o fluxo de verificação (workflow) na própria ação. Para regras da biblioteca integrada, o fluxo usado é, primeiro, o [fluxo de remediação nas configurações de transações](https://docs.didit.me/pt-br/transaction-monitoring/settings.md#fluxo-de-remediação), depois o fluxo de Autenticação biométrica da sua aplicação (quando o titular tem um rosto de referência armazenado) e, por fim, o fluxo padrão da sua aplicação.
Transações de Travel Rule ficam fora dessa fallback automático, pois a ação pendente delas é a comprovação de propriedade da carteira.
A transação (na resposta, em toda leitura posterior e em todo webhook) traz essa sessão no bloco canônico `action_required`:

```json theme={null}
{
  "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 (ele também traz ações `wallet_ownership` para transferências de [Travel Rule](https://docs.didit.me/pt-br/transaction-monitoring/travel-rule.md)).
Uma ação `wallet_ownership` não altera o status da transação por si só: a transação mantém o status que suas regras atribuírem, muitas vezes `APPROVED`. Por isso, verifique `action_required` em toda resposta, e não apenas em `AWAITING_USER`.

O usuário conclui a verificação. Em um fluxo de **Autenticação biométrica**, isso é uma selfie com prova de vida comparada ao rosto capturado no onboarding de KYC original, a verificação adicional mais forte para [transações de alto valor](https://docs.didit.me/pt-br/transaction-monitoring/sdk-transaction-submission.md#exemplo-biometria-adicional-para-um-saque-de-alto-valor).
Quando a sessão chega a uma decisão, a transação a segue automaticamente: `APPROVED` (`decision_reason_code: user_action_approved`), `DECLINED` (`user_action_declined`) ou `IN_REVIEW` (`user_action_in_review`), e um webhook `transaction.status.updated` é disparado.

> [!NOTE]
>
> É possível selecionar qualquer tipo de fluxo, exceto KYB.
> Fluxos de Autenticação biométrica (e 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 armazenado obtido em uma verificação aprovada. Usuários sem esse rosto são enviados para o fluxo padrão da sua aplicação, e uma nota na transação registra a substituição.

## Boas práticas

| Prática | Motivo |
| - | - |
| Sempre envie `vendor_data` | Permite a agregação. |
| Use seu próprio `txn_id` | Idempotência. |
| Assine `transaction.created` e `transaction.status.updated` | Captura mudanças de estado assíncronas (por exemplo, resultados da revisão de analistas). |
| Defina os limiares das regras de forma deliberada | Limiares baixos = mais alertas; altos = mais riscos não detectados. Veja [pontuação de risco](https://docs.didit.me/pt-br/transaction-monitoring/risk-scoring.md). |
| Acompanhe no console quantas vezes cada regra é executada | Identifica regras que nunca disparam (mal configuradas) ou que disparam em tudo (permissivas demais). |
| Teste as regras no modo TEST antes de ir para produção | Veja [regras](https://docs.didit.me/pt-br/transaction-monitoring/rules.md). |

## Limites de requisições

Veja [limite de requisições](https://docs.didit.me/pt-br/integration/rate-limiting.md). A criação de transações é um dos endpoints de maior vazão; os limites típicos ficam na casa das centenas de requisições por segundo. Envie rajadas de requisições com cautela.

## Próximos passos

> [card] [Transações](https://docs.didit.me/pt-br/transaction-monitoring/transactions.md)
>
> Referência completa do payload.

> [card] [Regras](https://docs.didit.me/pt-br/transaction-monitoring/rules.md)
>
> Como as regras são avaliadas.

> [card] [Webhooks](https://docs.didit.me/pt-br/transaction-monitoring/webhooks.md)
>
> Catálogo de eventos.

> [card] [Solução de problemas](https://docs.didit.me/pt-br/transaction-monitoring/troubleshooting.md)
>
> Problemas comuns de integração.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.