> ## 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 Monitorização de Transações: API KYT

> Guia do KYT na Didit: tempo real vs. lote, partes, idempotência, histórico e webhooks. 1,000 por mês incluídas, depois $0.001 cada.

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](https://docs.didit.me/pt/transaction-monitoring/quickstart.md) põe-no a funcionar; esta página leva-o até à 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 `x-api-key` padrão. As mesmas chaves de API são usadas para sessões e entidades. Consulte [Autenticação da API](https://docs.didit.me/pt/getting-started/api-authentication.md).

## Envio de uma transação

Endpoint único: `POST /v3/transactions/`. Consulte [envio de transações](https://docs.didit.me/pt/transaction-monitoring/transactions.md) para 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 do 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"
  }
}
```

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](https://docs.didit.me/pt/transaction-monitoring/transactions.md) 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}/`](https://docs.didit.me/pt/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 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:

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

> [!WARNING]
>
> 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](https://docs.didit.me/pt/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();
});
```

## 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](https://docs.didit.me/pt/transaction-monitoring/sdk-transaction-submission.md#ações-necessárias-do-utilizador)). |

Consulte [estados de Monitorização de Transações](https://docs.didit.me/pt/transaction-monitoring/statuses.md).

## 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](https://docs.didit.me/pt/transaction-monitoring/settings.md#fluxo-de-remediaçã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`:

```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 (inclui também as ações `wallet_ownership` das transferências [Travel Rule](https://docs.didit.me/pt/transaction-monitoring/travel-rule.md)).
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](https://docs.didit.me/pt/transaction-monitoring/sdk-transaction-submission.md#exemplo-verificação-biométrica-reforçada-para-um-levantamento-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`.

> [!NOTE]
>
> 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](https://docs.didit.me/pt/transaction-monitoring/risk-scoring.md). |
| 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](https://docs.didit.me/pt/transaction-monitoring/rules.md). |

## Limites de pedidos

Consulte a [limitação de pedidos](https://docs.didit.me/pt/integration/rate-limiting.md). 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

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

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

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

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


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