> ## 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.

# Monitoratge de transaccions: integració de l'API KYT

> Didit KYT: arquitectura i bones pràctiques del monitoratge de transaccions en temps real. 1,000 al mes inclosos, després $0.001 cada una.

Aquesta guia cobreix tota la superfície d'integració del monitoratge de transaccions. La [guia d'inici ràpid](https://docs.didit.me/ca/transaction-monitoring/quickstart.md) et posa en marxa; aquesta pàgina t'ajuda a passar a producció.

## Arquitectura

```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)
```

## Autenticació

Capçalera estàndard `x-api-key`. Es fan servir les mateixes claus per a sessions i entitats. Consulta [Autenticació de l'API](https://docs.didit.me/ca/getting-started/api-authentication.md).

## Enviament d'una transacció

Un únic endpoint: `POST /v3/transactions/`. Consulta [enviament de transaccions](https://docs.didit.me/ca/transaction-monitoring/transactions.md) per veure l'esquema complet.

**Payload mínim:**

```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 més complet, amb mètodes de pagament, context del dispositiu i propietats personalitzades:**

```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"
  }
}
```

Hi ha àlies en camelCase acceptats per a cada camp de primer nivell (`txnId`, `txnDate`, `type`, `info`, `applicant`, `props`, `travelRule`, `includeCryptoScreening`): el format de transmissió de l'SDK i el format snake\_case arriben al mateix lloc.

## Modelatge de les parts

Cada transacció té un `subject` obligatori (el teu client, la part que monitoritzes) i un `counterparty` opcional (l'altra part). Cadascun té el seu propi `payment_method` i un context `device` opcional.

A la resposta, arriben a l'array `parties` amb els rols `APPLICANT` i `COUNTERPARTY`. Una part sense `vendor_data` s'emmagatzema com a instantània externa (`kind: EXTERNAL`) sense cap entitat vinculada.

Consulta [payload de transaccions](https://docs.didit.me/ca/transaction-monitoring/transactions.md) per als camps de les parts.

## Idempotència

`txn_id` (el `transaction_id` que envies) és únic per aplicació.
Tornar a enviar un `transaction_id` que ja existeix retorna `400` amb `A transaction with this transaction_id already exists.` al camp `transaction_id`. Quan dues sol·licituds idèntiques competeixen entre si, la segona rep `409`.
Cap de les dues respostes retorna la transacció existent.
Davant d'un `400` o `409` per un `transaction_id` duplicat, consulta la transacció existent en lloc de tornar-la a enviar: llegeix-la amb [`GET /v3/transactions/{uuid}/`](https://docs.didit.me/ca/management-api/transactions/get) fent servir el `uuid` de la primera resposta, o fes servir el `transaction_id` (l'uuid de Didit) que el webhook `transaction.created` porta al costat del teu `txn_id`.

**Genera sempre el `txn_id` pel teu compte** abans d'enviar; no confiïs en un ID generat per Didit per a la idempotència. Fes servir l'ID de la teva base de dades, un UUID o un hash dels camps de la transacció.

## Temps real vs. lots

* **Temps real**: recomanat per a la majoria de casos d'ús. Envia la transacció en el moment que es produeix al teu sistema. Les regles s'avaluen de manera síncrona i retornen la decisió.
* **Lot / càrrega retroactiva**: per a la ingestió històrica, passa un `txn_date` en el passat. Les regles s'executen igualment i poden activar webhooks. Per evitar que les regles s'activin amb la càrrega, fes servir la importació CSV de la consola amb el marcador "dry ingest".

## Ingestió històrica

Quan migres des d'un altre sistema de monitoratge de transaccions:

1. Exporta les teves transaccions històriques a un CSV.
2. Fes servir *Transactions → Import history* a la consola (o envia-les per API en un bucle) amb `txn_date` en el passat.
3. Activa les regles només quan acabi la ingestió, o fes servir dry ingest per saltar-te l'avaluació de regles.

> [!WARNING]
>
> Sigues prudent amb l'avaluació històrica de regles. Passar 6 mesos d'historial per una regla de "20 transferències en 30 dies" generarà milers d'alertes de cop.

## Webhooks

Subscriu-te a:

* `transaction.created`: cada transacció enviada.
* `transaction.status.updated`: canvis d'estat (p. ex. l'analista passa de `IN_REVIEW` a `APPROVED`, o una comprovació AML asíncrona actualitza la puntuació).

Detalls complets: [webhooks de TM](https://docs.didit.me/ca/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();
});
```

## Gestió dels estats

| Estat | Què fer |
| - | - |
| `APPROVED` | Processa la transacció amb normalitat. |
| `IN_REVIEW` | Reté la transacció fins que la revisió de l'analista o la reverificació automàtica la resolgui. |
| `DECLINED` | Rebutja la transacció. Mostra a l'usuari un error genèric. |
| `AWAITING_USER` | L'usuari ha d'actuar perquè la transacció es pugui liquidar: llegeix el bloc `action_required` i envia-li la seva `url` a l'usuari (els SDK ho [poden gestionar automàticament](https://docs.didit.me/ca/transaction-monitoring/sdk-transaction-submission.md#accions-requerides-de-l’usuari)). |

Consulta [estats de TM](https://docs.didit.me/ca/transaction-monitoring/statuses.md).

## Vinculació de transaccions a entitats

Passa `vendor_data` a cada part. Beneficis:

* Cada transacció s'agrega al perfil de l'usuari o de l'empresa.
* Les regles de velocitat i de comportament tenen tot l'historial per avaluar-hi.
* Bloquejar una entitat es propaga automàticament a les transaccions futures.

No tenir `vendor_data` no és un error greu: la transacció s'emmagatzema com a instantània externa, però perds l'agregació a nivell d'entitat.

## Sessions de remediació

Quan una acció de regla mou una transacció a `AWAITING_USER`, Didit crea automàticament una **sessió de remediació**: una sessió de verificació allotjada estàndard per al mateix `vendor_data`.
Les regles personalitzades sempre indiquen el flux de treball a la mateixa acció; per a les regles de la biblioteca integrada, es recorre al [flux de treball de remediació de la configuració de transaccions](https://docs.didit.me/ca/transaction-monitoring/settings.md#flux-de-treball-de-remediació), després al flux de treball d'**Autenticació biomètrica** de la vostra aplicació (quan el subjecte té una cara de referència emmagatzemada) i, finalment, al flux de treball per defecte de la vostra aplicació.
Les transaccions Travel Rule queden excloses d'aquest recurs automàtic: la seva acció pendent és la prova de titularitat de la cartera.
La transacció (la resposta, cada lectura posterior i cada webhook) l'inclou al bloc canònic `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` es manté per compatibilitat amb versions anteriors; `action_required` és el bloc canònic (també inclou les accions `wallet_ownership` per a les transferències [Travel Rule](https://docs.didit.me/ca/transaction-monitoring/travel-rule.md)).
Una acció `wallet_ownership` no canvia per si sola l'estat de la transacció: la transacció conserva l'estat que li assignin les regles, sovint `APPROVED`, de manera que cal revisar `action_required` en cada resposta, i no només quan l'estat és `AWAITING_USER`.

L'usuari completa la verificació: per a un flux de treball d'**Autenticació biomètrica**, un selfie amb prova de vida comparat amb la cara capturada durant el seu alta KYC original, la verificació addicional més forta per a les [transaccions d'alt valor](https://docs.didit.me/ca/transaction-monitoring/sdk-transaction-submission.md#exemple-reverificació-biomètrica-per-a-una-retirada-d’alt-valor).
Quan la sessió arriba a una decisió, la transacció la segueix automàticament: `APPROVED` (`decision_reason_code: user_action_approved`), `DECLINED` (`user_action_declined`) o `IN_REVIEW` (`user_action_in_review`), i s'envia un webhook `transaction.status.updated`.

> [!NOTE]
>
> Es pot seleccionar qualsevol tipus de flux de treball excepte KYB.
> Els fluxos de treball d'Autenticació biomètrica (i els fluxos en què la coincidència facial s'executa abans de la verificació d'identitat) requereixen que el subjecte ja tingui una cara de referència emmagatzemada d'una verificació aprovada; els usuaris que no en tinguin són derivats al flux de treball per defecte de la vostra aplicació, i la transacció registra una nota que indica la substitució.

## Bones pràctiques

| Pràctica | Motiu |
| - | - |
| Passa sempre `vendor_data` | Permet l'agregació. |
| Utilitza el teu propi `txn_id` | Idempotència. |
| Subscriu-te tant a `transaction.created` com a `transaction.status.updated` | Detecta els canvis d'estat asíncrons (p. ex., els resultats de la revisió de l'analista). |
| Defineix els llindars de les regles amb criteri | Llindars baixos = més alertes; llindars alts = més riscos no detectats. Consulta [puntuació de risc](https://docs.didit.me/ca/transaction-monitoring/risk-scoring.md). |
| Supervisa el nombre d'execucions de les regles a la consola | Detecta regles que mai s'activen (mal configurades) o que s'activen per a tot (massa laxes). |
| Prova les regles en mode TEST abans de posar-les en producció | Consulta [regles](https://docs.didit.me/ca/transaction-monitoring/rules.md). |

## Límits de freqüència

Consulta [límit de freqüència](https://docs.didit.me/ca/integration/rate-limiting.md). La creació de transaccions és un dels endpoints amb més volum de trànsit; els límits habituals són de diversos centenars de sol·licituds per segon. Envia ràfegues amb cura.

## Següents passos

> [card] [Transaccions](https://docs.didit.me/ca/transaction-monitoring/transactions.md)
>
> Referència completa del payload.

> [card] [Regles](https://docs.didit.me/ca/transaction-monitoring/rules.md)
>
> Com s'avaluen les regles.

> [card] [Webhooks](https://docs.didit.me/ca/transaction-monitoring/webhooks.md)
>
> Catàleg d'esdeveniments.

> [card] [Resolució de problemes](https://docs.didit.me/ca/transaction-monitoring/troubleshooting.md)
>
> Problemes habituals d'integració.


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