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

# API per enviar transaccions: payload i model de dades

> Envia transaccions a Didit per al monitoratge en temps real amb parts i mètodes de pagament. 1,000 al mes inclosos; després, $0.001 cadascuna.

Envia transaccions a Didit mitjançant l'API [Crear transacció](https://docs.didit.me/ca/management-api/transactions/create.md). Cada transacció inclou dades estructurades de les parts, del pagament i del context, que el motor de regles avalua en temps real.

> [!TIP]
>
> Quan la transacció s'origina al dispositiu de l'usuari final (una retirada de criptoactius, un pagament dins de l'aplicació), considera [l'enviament de transaccions amb el SDK](https://docs.didit.me/ca/transaction-monitoring/sdk-transaction-submission.md): un token amb abast limitat substitueix la clau d'API, la intel·ligència del dispositiu es recull automàticament i les accions que l'usuari ha de fer (prova de titularitat de la cartera, verificació addicional) s'activen en el moment.

## Categories de transacció

Cada transacció té un `transaction_category` que determina com la tracten les regles i les analítiques:

| Categoria | Descripció |
| - | - |
| `finance` | Transacció financera estàndard (dipòsit, retirada, transferència) |
| `kyc` | Esdeveniment relacionat amb la verificació d'identitat |
| `travel_rule` | Transferència d'actius virtuals que requereix compliment de la Travel Rule |
| `user_event` | Esdeveniment personalitzat de la plataforma (inici de sessió, canvi de perfil, etc.) |
| `gambling_bet` | Aposta o realització d'una aposta |
| `gambling_limit_change` | Canvi en el límit de dipòsit, de pèrdues o d'apostes d'un jugador |
| `gambling_bonus_change` | Concessió, bescanvi o pèrdua d'un bonus |
| `audit_trail_event` | Esdeveniment d'auditoria del sistema o de compliment |

## Detalls de la transacció

L'objecte `transaction_details` conté les dades financeres:

| Camp | Tipus | Descripció |
| - | - | - |
| `direction` | string | `inbound` o `outbound` |
| `amount` | string | Valor de la transacció com a cadena decimal (p. ex., `"1500.50"`) |
| `currency` | string | Codi de moneda ISO (p. ex., `USD`, `EUR`, `BTC`) |
| `currency_kind` | string | `fiat` o `crypto` (àlies `currencyType`); determina si s'activa el cribratge de criptoactius |
| `action_type` | string | Etiqueta d'acció definida pel proveïdor (p. ex., `deposit`, `withdrawal`, `purchase`) |
| `payment_details` | string | Descripció en text lliure del pagament (p. ex., `"Bank transfer from ABC Corp"`) |
| `payment_reference_id` | string | Identificador extern de referència del pagament. Per al cribratge de criptoactius posterior a la transferència, utilitza el hash de la transacció a la blockchain. |

## Subjecte i contrapart

Cada transacció té un **subjecte** (obligatori) i una **contrapart** (opcional). Tots dos fan servir el mateix model de part:

| Camp | Tipus | Descripció |
| - | - | - |
| `entity_type` | string | `person` o `company` |
| `vendor_data` | string | El teu identificador d'aquesta part: vincula la transacció a un [usuari](https://docs.didit.me/ca/management-api/users/list.md) o a un [perfil d'empresa](https://docs.didit.me/ca/business-verification/business-profiles.md) |
| `full_name` | string | Nom complet de la part |
| `first_name` | string | Nom de pila |
| `last_name` | string | Cognoms |
| `date_of_birth` | string | Data ISO (p. ex., `1990-01-15`) |
| `country_code` | string | Codi de país ISO 3166-1 alpha-2 |
| `address` | object o string | Adreça estructurada amb `street`, `city`, `state`, `country`, `postal_code`. També accepta una cadena de text simple, com una adreça per a una contrapart de criptoactius: Didit l'emmagatzema sense canvis a la part. |

Didit deriva el `country_code` de la part a partir de `address.country` quan `address` és un objecte. Quan `address` és una cadena, `country_code` es retorna com a `null` per a aquesta part.

Quan `vendor_data` coincideix amb un usuari o una empresa existents, Didit vincula automàticament la transacció al perfil d'aquesta entitat, cosa que permet avaluar regles entre sessions i fer comprovacions de freqüència de les transaccions.
A la resposta, totes dues parts es retornen a la matriu `parties` amb els rols `APPLICANT` i `COUNTERPARTY`.

## Mètodes de pagament

Adjunta un `payment_method` a cada part per descriure l'instrument d'aquesta part:

| Camp | Tipus | Descripció |
| - | - | - |
| `method_type` | string | `bank_card`, `bank_account`, `e_wallet`, `crypto_wallet`, `unhosted_wallet` o `other` (àlies `type`); `ewallet`, `card` i `crypto` s'accepten com a àlies, i un valor no reconegut s'emmagatzema com a `other` |
| `account_id` | string | Número de compte, adreça o token de targeta |
| `issuing_country` | string | País emissor de l'instrument de pagament |

En les transaccions `travelRule`, un mètode de pagament de la contrapart amb `method_type: "unhosted_wallet"` (àlies `type`) declara la cartera de la contrapart com a autoallotjada.
Quan la Travel Rule està activada i l'import, en la moneda per defecte de la teva aplicació, no és inferior a `threshold_amount`, la transferència passa directament a `UNCONFIRMED_OWNERSHIP` i al flux de prova de titularitat: consulta [Carteres autoallotjades declarades](https://docs.didit.me/ca/transaction-monitoring/travel-rule.md#carteres-autoallotjades-declarades).

Per a les transaccions de criptoactius, inclou les adreces de cartera a `account_id` i defineix `currency_kind` com a `crypto` perquè el cribratge de blockchain s'executi automàticament. La direcció controla quina cartera es cribra: el cribratge previ a la transferència d'entrada fa servir la cartera de l'emissor a `counterparty.payment_method.account_id`; el cribratge de sortida fa servir la cartera de destinació a `counterparty.payment_method.account_id`. Si envies un hash de blockchain a `transaction_details.payment_reference_id`, el cribratge de transaccions d'entrada requereix l'adreça de dipòsit del teu servei a `subject.payment_method.account_id`, mentre que el cribratge de transaccions de sortida requereix la cartera de destinació a `counterparty.payment_method.account_id`.

## Sobreescriptura del cribratge de criptoactius

Fes servir `include_crypto_screening` al nivell superior de la sol·licitud per sobreescriure el valor per defecte configurat a **Transaccions** > **Configuració** de la consola:

| Valor | Descripció |
| - | - |
| `true` | Força el cribratge de criptoactius per a aquesta transacció |
| `false` | Omet el cribratge de criptoactius per a aquesta transacció |
| omès o `null` | Utilitza el valor per defecte de l'aplicació |

## Context del dispositiu

Inclou la informació del dispositiu del subjecte (i, opcionalment, de la contrapart) per activar les regles d'intel·ligència de dispositius. El camp de la sol·licitud és `device_context` a cada part. L'àlies en camelCase `device` també s'accepta, i és el que utilitza el format de transmissió de l'SDK. La resposta el retorna com a `device` a cada part de la matriu `parties`.

| Camp | Tipus | Descripció |
| - | - | - |
| `device_context.fingerprint` | string | Empremta digital única del dispositiu |
| `device_context.persistent_device_id` | string | Identificador estable del dispositiu entre sessions (esquema d'empremta v2) |
| `device_context.user_agent` | string | Cadena d'agent d'usuari del navegador o de l'aplicació |
| `device_context.browser_family` | string | Família del navegador (p. ex. `Chrome`, `Firefox`, `Safari`). **Cal enviar-la explícitament**: no es deriva de `user_agent`. Fa funcionar regles com `subject_browser_family`. |
| `device_context.browser_version` | string | Versió del navegador (p. ex. `131.0`). Cal enviar-la explícitament. |
| `device_context.platform` | string | Identificador de la plataforma (`web`, `ios`, `android`, `macos`, `windows`, `linux`). **Cal enviar-lo explícitament**: no es deriva de `user_agent`. Fa funcionar regles com `subject_platform`. |
| `device_context.os_family` | string | Família del sistema operatiu (p. ex. `iOS`, `Android`, `Windows`) |
| `device_context.os_version` | string | Versió del sistema operatiu |
| `device_context.accept_language` | string | Valor de la capçalera Accept-Language (p. ex. `en-US,en;q=0.9`). En el camí de l'SDK, es recull automàticament. |
| `device_context.session_id` | string | Identificador de la sessió actual de l'usuari. S'emmagatzema a les metadades. Àlies en CamelCase: `sessionId`. |
| `device_context.session_age_ms` | number | Antiguitat de la sessió de l'usuari, en mil·lisegons, en el moment de la transacció. Fa funcionar regles com `subject_session_age_ms`. |
| `device_context.network_context.ip_address` | string | Adreça IP del client |
| `device_context.network_context.ip_country_code` | string | País de la IP resolt geogràficament (ISO 3166-1 alpha-3) |
| `device_context.network_context.latitude` | number | Latitud geogràfica de la IP |
| `device_context.network_context.longitude` | number | Longitud geogràfica de la IP |

> [!NOTE]
>
> `browser_family` i `platform` **no** es deriven de `user_agent`. Cal enviar-los com a claus de primer nivell dins de `device_context` perquè les regles d'intel·ligència de dispositius s'activin. Si fas servir l'SDK de Didit, aquests camps es recullen automàticament.

Tots els camps accepten àlies en CamelCase: `userAgent`, `browserFamily`, `browserVersion`, `osFamily`, `osVersion`, `acceptLang`, `sessionId`, `sessionAgeMs`. L'objecte `network_context` accepta els àlies `ip` / `countryCode3` / `lat` / `lon`, i un bloc `ipInfo` de primer nivell també es fusiona dins de `network_context`.

El context del dispositiu permet regles com la detecció de multicomptes (la mateixa empremta entre subjectes diferents), la combinació de navegador nou i IP nova, una transferència d'alt valor amb una sessió de poca antiguitat, i la puntuació de risc basada en la ubicació.

## Propietats personalitzades

Afegeix qualsevol parell clau-valor addicional a l'objecte `custom_properties`. Les regles poden fer referència a aquests camps a les seves condicions. Això és útil per passar context específic del negoci, com ara la categoria del producte, l'identificador del comerciant o el canal.

```json theme={null}
"custom_properties": {
  "product_category": "electronics",
  "merchant_id": "MER456",
  "channel": "mobile_app"
}
```

A les condicions de les regles, fes referència a cada clau amb la ruta de camp `custom_values.<key>`. Per exemple, el payload anterior coincideix amb `custom_values.product_category eq "electronics"`. Al constructor de regles de la Console, les claus que han aparegut en transaccions rebudes recentment apareixen al selector de camps de condició, sota **Propietats personalitzades**. Dins del mateix grup, **Introdueix una propietat personalitzada** permet escriure manualment qualsevol clau (distingeix entre majúscules i minúscules). Consulta [Regles i puntuació](https://docs.didit.me/ca/transaction-monitoring/rules.md#referència-a-propietats-personalitzades) per a més detalls.

## Exemple de sol·licitud

```bash theme={null}
curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "TXN-20260410-001",
    "transaction_at": "2026-04-10T15:30:00Z",
    "transaction_category": "finance",
    "transaction_details": {
      "direction": "outbound",
      "amount": "1500.50",
      "currency": "EUR",
      "currency_kind": "fiat",
      "action_type": "withdrawal"
    },
    "subject": {
      "entity_type": "person",
      "vendor_data": "user-123",
      "full_name": "John Doe",
      "country_code": "US",
      "payment_method": {
        "method_type": "bank_account",
        "account_id": "DE89370400440532013000",
        "issuing_country": "DE"
      }
    },
    "counterparty": {
      "entity_type": "company",
      "full_name": "John Doe",
      "country_code": "GB"
    },
    "custom_properties": {
      "order_id": "ORD-7891"
    }
  }'
```

## Resposta

L'API retorna la transacció creada amb els resultats de l'avaluació inicial:

| Camp | Tipus | Descripció |
| - | - | - |
| `uuid` | string | Identificador únic de la transacció de Didit |
| `txn_id` | string | L'identificador de transacció que has proporcionat |
| `status` | string | `APPROVED`, `IN_REVIEW`, `DECLINED` o `AWAITING_USER` |
| `score` | number | Puntuació de risc acumulada de totes les regles coincidents |
| `severity` | string | Severitat més alta de les regles coincidents (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`) |
| `decision_reason_code` | string | Codi llegible per una màquina del motiu de la decisió d'estat |
| `decision_reason_label` | string | Descripció de la decisió comprensible per a les persones |

Consulta la [referència de l'API](https://docs.didit.me/ca/management-api/transactions/create.md) per a l'esquema complet de la sol·licitud i la resposta, i la [referència de l'esquema de resposta](https://docs.didit.me/ca/transaction-monitoring/response-schema.md) per a un recorregut anotat de la resposta.

## Assignar una transacció a un revisor

Assigna una transacció retinguda a un membre de la teva aplicació, o desassigna-la, amb una clau d'API que tingui el privilegi `write:transactions`.
Cada canvi queda registrat a la línia de temps de la transacció com a `TRANSACTION_ASSIGNED`.

| Crida | Ús |
| - | - |
| `POST /v3/transactions/{transaction_uuid}/assign/` | Assigna una transacció. |
| `POST /v3/transactions/assign/` | Assigna fins a 500 transaccions a un membre. |

Totes dues crides reben `assignee_email`, el correu electrònic d'un membre de l'aplicació que hagi iniciat sessió a Didit.
Envia `null` o una cadena buida per desassignar.
La crida massiva també rep `transaction_ids`, una llista d'entre 1 i 500 UUID de transaccions.

```bash theme={null}
curl -X POST "https://verification.didit.me/v3/transactions/assign/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transaction_ids": ["<transaction-uuid>"], "assignee_email": "analyst@example.com"}'
```

La crida individual retorna `uuid`, `transaction_number`, `assignee` i `changed` (`false` quan la transacció ja tenia aquesta persona assignada), o `404` quan la transacció no existeix a l'aplicació.
La crida massiva retorna `transactions` (una entrada com l'anterior), `updated_count` i `not_found_transaction_ids`.

Filtra la [llista de transaccions](https://docs.didit.me/ca/management-api/transactions/list.md) amb `assignee`, una llista separada per comes en què qualsevol valor coincideix: `me`, `unassigned`, `rules` (decidida només per les regles, sense intervenció d'un revisor) o un correu electrònic de membre.

## Idempotència

`txn_id` (el `transaction_id` que envies) és únic per aplicació.
En tornar a enviar un `transaction_id` que ja existeix, es retorna `400` amb `A transaction with this transaction_id already exists.` al camp `transaction_id`, i si dues sol·licituds idèntiques arriben alhora, la segona rep `409`.
Cap de les dues respostes retorna la transacció existent.
Per reintentar amb seguretat, tracta un `400` o un `409` per un `transaction_id` duplicat com a "ja creada" i 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 utilitza el `transaction_id` (l'uuid de Didit) que el webhook `transaction.created` porta juntament amb el teu `txn_id`.
Genera sempre el `txn_id` pel teu compte (per exemple, l'ID de la teva base de dades de transaccions, un UUID o un hash determinista).

## Càrrega històrica

Passa un `txn_date` anterior per ingerir transaccions històriques. Les regles s'avaluen per defecte: si vols saltar l'avaluació de regles durant les càrregues massives històriques, utilitza la importació de CSV de la consola amb el mode d'ingesta en sec. Consulta la [guia d'integració](https://docs.didit.me/ca/transaction-monitoring/integration-guide.md#ingestió-històrica).

## Següents passos

> [card] [Regles i puntuació](https://docs.didit.me/ca/transaction-monitoring/rules.md)
>
> Com s'avaluen les transaccions enviades en funció de les regles.

> [card] [Esquema de resposta](https://docs.didit.me/ca/transaction-monitoring/response-schema.md)
>
> Payload de resposta complet i anotat.

> [card] [Cribratge de criptomonedes](https://docs.didit.me/ca/transaction-monitoring/aml-screening.md)
>
> Cribratge automàtic de carteres i transaccions per a transaccions amb criptomonedes.

> [card] [Travel Rule](https://docs.didit.me/ca/transaction-monitoring/travel-rule.md)
>
> Adjunta les dades de compliment de la Travel Rule a les transferències d'actius virtuals.

> [card] [Enriquiment d'IP](https://docs.didit.me/ca/transaction-monitoring/ip-enrichment.md)
>
> Context derivat de la IP disponible per a les regles.

> [card] [Referència de l'API](https://docs.didit.me/ca/management-api/transactions/create.md)
>
> Esquema complet de la sol·licitud de l'endpoint Create Transaction.


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