> ## 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 para Submeter Transações: Payload e Modelo de Dados

> Submeta transações com partes e dispositivo na Didit para monitorização em tempo real. 1,000 por mês incluídas, depois $0.001 cada.

Envie transações para a Didit através da API [Criar transação](https://docs.didit.me/pt/management-api/transactions/create.md). Cada transação inclui dados estruturados sobre as partes, o pagamento e o contexto, que o motor de regras avalia em tempo real.

> [!TIP]
>
> Quando a transação tem origem no dispositivo de um utilizador final, por exemplo um levantamento de criptoativos ou um pagamento na aplicação, considere a [submissão de transações pelo SDK](https://docs.didit.me/pt/transaction-monitoring/sdk-transaction-submission.md). Um token com âmbito limitado substitui a chave de API, a inteligência de dispositivo é recolhida automaticamente e as ações obrigatórias do utilizador (prova de titularidade da carteira, verificação adicional) são iniciadas no momento.

## Categorias de transação

Cada transação tem um `transaction_category` que determina a forma como as regras e as análises a tratam:

| Categoria | Descrição |
| - | - |
| `finance` | Transação financeira padrão (depósito, levantamento, transferência) |
| `kyc` | Evento relacionado com a verificação de identidade |
| `travel_rule` | Transferência de ativos virtuais que exige conformidade com a Travel Rule |
| `user_event` | Evento personalizado da plataforma (início de sessão, alteração de perfil, etc.) |
| `gambling_bet` | Aposta ou colocação de uma aposta em jogos de azar |
| `gambling_limit_change` | Alteração do limite de depósito, perda ou aposta de um jogador |
| `gambling_bonus_change` | Atribuição, resgate ou perda de um bónus |
| `audit_trail_event` | Evento de auditoria do sistema ou de conformidade |

## Detalhes da transação

O objeto `transaction_details` contém os dados financeiros:

| Campo | Tipo | Descrição |
| - | - | - |
| `direction` | string | `inbound` ou `outbound` |
| `amount` | string | Valor da transação como string decimal (por exemplo, `"1500.50"`) |
| `currency` | string | Código de moeda ISO (por exemplo, `USD`, `EUR`, `BTC`) |
| `currency_kind` | string | `fiat` ou `crypto` (alias `currencyType`); determina se a triagem de criptoativos é acionada |
| `action_type` | string | Rótulo da ação definido pelo fornecedor (por exemplo, `deposit`, `withdrawal`, `purchase`) |
| `payment_details` | string | Descrição em texto livre do pagamento (por exemplo, `"Bank transfer from ABC Corp"`) |
| `payment_reference_id` | string | Identificador de referência do pagamento externo. Para a triagem de criptoativos após a transferência, utilize o hash da transação na blockchain. |

## Sujeito e contraparte

Cada transação tem um **sujeito** (obrigatório) e uma **contraparte** (opcional). Ambos utilizam o mesmo modelo de parte:

| Campo | Tipo | Descrição |
| - | - | - |
| `entity_type` | string | `person` ou `company` |
| `vendor_data` | string | O seu identificador para esta parte. Liga a transação a um [utilizador](https://docs.didit.me/pt/management-api/users/list.md) ou a um [perfil de empresa](https://docs.didit.me/pt/business-verification/business-profiles.md) |
| `full_name` | string | Nome completo da parte |
| `first_name` | string | Nome próprio |
| `last_name` | string | Apelido |
| `date_of_birth` | string | Data no formato ISO (por exemplo, `1990-01-15`) |
| `country_code` | string | Código de país ISO 3166-1 alpha-2 |
| `address` | object ou string | Morada estruturada com `street`, `city`, `state`, `country`, `postal_code`. Aceita também uma string simples, como um endereço de carteira para uma contraparte de criptoativos. A Didit guarda-a sem alterações na parte. |

A Didit deriva o `country_code` da parte a partir de `address.country` quando `address` é um objeto. Quando `address` é uma string, o `country_code` dessa parte é devolvido como `null`.

Quando o `vendor_data` corresponde a um utilizador ou a uma empresa existente, a Didit liga automaticamente a transação ao perfil dessa entidade, o que permite a avaliação de regras entre sessões e as verificações de frequência e volume.
Na resposta, ambas as partes são devolvidas no array `parties`, com as funções `APPLICANT` e `COUNTERPARTY`.

## Métodos de pagamento

Associe um `payment_method` a cada parte para descrever o instrumento utilizado por essa parte:

| Campo | Tipo | Descrição |
| - | - | - |
| `method_type` | string | `bank_card`, `bank_account`, `e_wallet`, `crypto_wallet`, `unhosted_wallet` ou `other` (alias `type`); `ewallet`, `card` e `crypto` são aceites como aliases, e um valor não reconhecido é guardado como `other` |
| `account_id` | string | Número de conta, endereço ou token do cartão |
| `issuing_country` | string | País que emitiu o instrumento de pagamento |

Nas transações `travelRule`, um método de pagamento da contraparte com `method_type: "unhosted_wallet"` (alias `type`) declara a carteira da contraparte como autocustodiada.
Quando a Travel Rule está ativada e o montante, na moeda predefinida da sua aplicação, não é inferior a `threshold_amount`, a transferência passa diretamente para `UNCONFIRMED_OWNERSHIP` e para o fluxo de prova de titularidade. Consulte [Carteiras autocustodiadas declaradas](https://docs.didit.me/pt/transaction-monitoring/travel-rule.md#carteiras-autocustodiadas-declaradas).

Nas transações de criptoativos, inclua os endereços em `account_id` e defina `currency_kind` como `crypto`, para que a triagem na blockchain seja executada automaticamente. A direção determina a carteira que é analisada: a triagem pré-transferência de entrada utiliza a carteira do remetente em `counterparty.payment_method.account_id`; a triagem de saída utiliza a carteira de destino em `counterparty.payment_method.account_id`. Se enviar um hash da blockchain em `transaction_details.payment_reference_id`, a triagem de transações de entrada exige o endereço de depósito do seu serviço em `subject.payment_method.account_id`, enquanto a triagem de transações de saída exige a carteira de destino em `counterparty.payment_method.account_id`.

## Substituição da predefinição da triagem de criptoativos

Utilize `include_crypto_screening` no nível superior do pedido para substituir a predefinição configurada em **Transações** > **Definições** na Consola:

| Valor | Descrição |
| - | - |
| `true` | Força a triagem de criptoativos para esta transação |
| `false` | Ignora a triagem de criptoativos para esta transação |
| omitido ou `null` | Utiliza a predefinição ao nível da aplicação |

## Contexto do dispositivo

Inclua informações do dispositivo na parte sujeita (e, opcionalmente, na contraparte) para alimentar as regras de inteligência de dispositivo. O campo do pedido é `device_context` em cada parte; o alias em camelCase `device` também é aceite e é o que o formato de transmissão do SDK utiliza. A resposta devolve-o como `device` em cada parte no array `parties`.

| Campo | Tipo | Descrição |
| - | - | - |
| `device_context.fingerprint` | string | Impressão digital única do dispositivo |
| `device_context.persistent_device_id` | string | Identificador estável do dispositivo entre sessões (esquema de impressão digital v2) |
| `device_context.user_agent` | string | Cadeia de caracteres do user agent do browser ou da aplicação |
| `device_context.browser_family` | string | Família do browser (ex.: `Chrome`, `Firefox`, `Safari`). **Deve ser enviada explicitamente**; não é derivada de `user_agent`. Alimenta regras como `subject_browser_family`. |
| `device_context.browser_version` | string | Cadeia de caracteres da versão do browser (ex.: `131.0`). Deve ser enviada explicitamente. |
| `device_context.platform` | string | Identificador da plataforma (`web`, `ios`, `android`, `macos`, `windows`, `linux`). **Deve ser enviado explicitamente**; não é derivado de `user_agent`. Alimenta regras como `subject_platform`. |
| `device_context.os_family` | string | Família do sistema operativo (ex.: `iOS`, `Android`, `Windows`) |
| `device_context.os_version` | string | Cadeia de caracteres da versão do sistema operativo |
| `device_context.accept_language` | string | Valor do cabeçalho Accept-Language (ex.: `en-US,en;q=0.9`). No caminho do SDK, este valor é recolhido automaticamente. |
| `device_context.session_id` | string | Identificador da sessão atual do utilizador. Armazenado nos metadados. Alias em camelCase: `sessionId`. |
| `device_context.session_age_ms` | number | Idade da sessão do utilizador, em milissegundos, no momento da transação. Alimenta regras como `subject_session_age_ms`. |
| `device_context.network_context.ip_address` | string | Endereço IP do cliente |
| `device_context.network_context.ip_country_code` | string | País do IP resolvido por geolocalização (ISO 3166-1 alpha-3) |
| `device_context.network_context.latitude` | number | Latitude geográfica do IP |
| `device_context.network_context.longitude` | number | Longitude geográfica do IP |

> [!NOTE]
>
> `browser_family` e `platform` **não** são derivados de `user_agent`. Têm de ser enviados como chaves explícitas de primeiro nível dentro de `device_context` para que as regras de inteligência de dispositivo sejam acionadas. Se utilizar o SDK da Didit, estes campos são recolhidos automaticamente.

São aceites aliases em camelCase para todos os campos: `userAgent`, `browserFamily`, `browserVersion`, `osFamily`, `osVersion`, `acceptLang`, `sessionId`, `sessionAgeMs`. O subobjeto `network_context` aceita os aliases `ip` / `countryCode3` / `lat` / `lon`, e um bloco `ipInfo` de primeiro nível também é integrado em `network_context`.

O contexto do dispositivo permite regras como a deteção de multicontas (mesma impressão digital em sujeitos diferentes), a deteção da combinação de novo browser com novo IP, transferências de valor elevado com idade de sessão baixa e a pontuação de risco baseada na localização.

## Propriedades personalizadas

Adicione quaisquer pares chave-valor adicionais no objeto `custom_properties`. As regras podem referenciar estes campos nas respetivas condições, o que é útil para transmitir contexto específico do negócio, como a categoria do produto, o ID do comerciante ou o canal.

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

Nas condições das regras, referencie cada chave com o caminho do campo `custom_values.<key>`. Por exemplo, o payload acima corresponde a `custom_values.product_category eq "electronics"`. No criador de regras da Consola, as chaves vistas em transações recentemente recebidas aparecem no seletor de campos de condição em **Propriedades personalizadas**, e **Introduzir propriedade personalizada** no mesmo grupo permite introduzir manualmente qualquer chave (sensível a maiúsculas e minúsculas). Consulte [Regras e pontuação](https://docs.didit.me/pt/transaction-monitoring/rules.md#referenciar-propriedades-personalizadas) para mais detalhes.

## Exemplo de pedido

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

A API devolve a transação criada com os resultados da avaliação inicial:

| Campo | Tipo | Descrição |
| - | - | - |
| `uuid` | string | Identificador único da transação na Didit |
| `txn_id` | string | O ID da transação que forneceu |
| `status` | string | `APPROVED`, `IN_REVIEW`, `DECLINED` ou `AWAITING_USER` |
| `score` | number | Pontuação de risco cumulativa de todas as regras correspondidas |
| `severity` | string | Gravidade mais alta das regras correspondidas (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`) |
| `decision_reason_code` | string | Motivo legível por máquina da decisão relativa ao estado |
| `decision_reason_label` | string | Descrição legível para humanos da decisão |

Consulte a [Referência da API](https://docs.didit.me/pt/management-api/transactions/create.md) para o esquema completo do pedido e da resposta, e a [referência do esquema de resposta](https://docs.didit.me/pt/transaction-monitoring/response-schema.md) para uma explicação anotada de um payload.

## Atribuir uma transação a um revisor

Atribua uma transação retida a um membro da sua aplicação, ou desatribua-a, com uma chave de API que tenha o privilégio `write:transactions`.
Cada alteração é registada na linha temporal da transação como `TRANSACTION_ASSIGNED`.

| Chamada | Utilização |
| - | - |
| `POST /v3/transactions/{transaction_uuid}/assign/` | Atribui uma transação. |
| `POST /v3/transactions/assign/` | Atribui até 500 transações a um membro. |

Ambas as chamadas recebem `assignee_email`, o e-mail de um membro da aplicação que tenha iniciado sessão no Didit.
Envie `null` ou uma cadeia de caracteres vazia para desatribuir.
A chamada em massa recebe também `transaction_ids`, uma lista de 1 a 500 UUIDs de transações.

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

A chamada individual devolve `uuid`, `transaction_number`, `assignee` e `changed` (`false` quando a transação já tinha este responsável atribuído), ou `404` quando a transação não existe na aplicação.
A chamada em massa devolve `transactions` (uma entrada como a acima), `updated_count` e `not_found_transaction_ids`.

Filtre a [lista de transações](https://docs.didit.me/pt/management-api/transactions/list.md) com `assignee`, uma lista separada por vírgulas em que qualquer valor corresponde a um destes valores: `me`, `unassigned`, `rules` (decidida apenas pelas regras, sem intervenção de revisor) ou o e-mail de um membro.

## Idempotência

O `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`, e dois pedidos idênticos enviados em simultâneo devolvem `409` ao segundo.
Nenhuma das respostas devolve a transação existente.
Para repetir o envio com segurança, trate um `400` ou `409` para um `transaction_id` duplicado como "já criada" e 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 junto do seu `txn_id`.
Gere sempre o `txn_id` do seu lado (por exemplo, o ID da sua base de dados de transações, um UUID ou um hash determinístico).

## Carregamento histórico

Envie um `txn_date` anterior à data atual para importar transações históricas. Por predefinição, as regras continuam a ser avaliadas. Se quiser ignorar a avaliação de regras durante carregamentos históricos em massa, use a importação CSV da consola com o modo dry-ingest. Consulte o [guia de integração](https://docs.didit.me/pt/transaction-monitoring/integration-guide.md#ingestão-histórica).

## Próximos passos

> [card] [Regras e pontuação](https://docs.didit.me/pt/transaction-monitoring/rules.md)
>
> Como as transações enviadas são avaliadas em função das regras.

> [card] [Esquema da resposta](https://docs.didit.me/pt/transaction-monitoring/response-schema.md)
>
> Payload completo da resposta, com anotações.

> [card] [Triagem de criptoativos](https://docs.didit.me/pt/transaction-monitoring/aml-screening.md)
>
> Triagem automática de carteiras e transações para transações cripto.

> [card] [Travel Rule](https://docs.didit.me/pt/transaction-monitoring/travel-rule.md)
>
> Anexar dados de conformidade da Travel Rule às transferências de ativos virtuais.

> [card] [Enriquecimento de IP](https://docs.didit.me/pt/transaction-monitoring/ip-enrichment.md)
>
> Contexto derivado do IP disponível para as regras.

> [card] [Referência da API](https://docs.didit.me/pt/management-api/transactions/create.md)
>
> Esquema completo do pedido para o endpoint de criação de transação.


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