> ## 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 da Travel Rule da FATF: Conformidade para VASPs

> Mensagens da Travel Rule com a Didit para VASPs e PSPs: troca de dados de ordenante e beneficiário e monitorização de protocolos a $0.02 por troca.

A Didit executa a troca entre ordenante e beneficiário prevista pelo FATF/EU Transfer of Funds Regulation (TFR) para transferências de ativos virtuais: procura um canal que alcance a VASP contraparte, negocia os dados necessários através do mesmo, acompanha a troca ao longo de um ciclo de vida de 13 estados e informa-o quando a troca tiver sido concluída para que possa libertar fundos on-chain.

## Visão geral

A Travel Rule do GAFI (Recomendação 16), implementada na UE como o Regulamento relativo às Transferências de Fundos (TFR), exige que um Prestador de Serviços de Ativos Virtuais remetente (o **VASP ordenante**) recolha e transmita informações do ordenante e do beneficiário ao VASP destinatário (o **VASP beneficiário**) antes da liquidação de uma transferência de ativos virtuais.

Ao contrário da maioria das jurisdições, o TFR da UE aplica-se **sem montante mínimo** - todas as transferências de criptoativos estão abrangidas, e não apenas as transferências acima de um limiar de comunicação.

O produto Travel Rule da Didit é uma troca gerida, não apenas um campo de dados:

* Submete uma transferência com `transaction_category: "travelRule"`.
* A Didit tenta as vias por ordem de prioridade para contactar o VASP da contraparte, executa a troca através da primeira que a alcance e, caso o outro lado devolva um nome de beneficiário, compara-o com o que enviou.
* Só quando a troca atinge o estado `COMPLETED` é que deve difundir a transferência on-chain.
* Em seguida, comunica o hash da transação on-chain à Didit para fechar a troca como `FINISHED`.

Sete vias são disponibilizadas nesta versão, tentadas por estrita ordem de prioridade - a primeira que conseguir contactar a contraparte é a utilizada:

| Prioridade | Via | Como funciona |
| - | - | - |
| 1 | `INTERNAL` | Utilizada quando outro cliente da Didit comprovou o controlo da carteira do beneficiário com uma mensagem assinada ou um depósito de teste. A Didit cria uma transferência de entrada correspondente na aplicação desse cliente e negoceia a troca inteiramente dentro da plataforma - sem qualquer chamada de rede externa. Instantânea. |
| 2 | `TRP` | Integração nativa com o protocolo aberto Travel Rule Protocol (TRP / OpenVASP). Utilizada quando a transferência inclui um [Travel Address](#travel-addresses), o registo da carteira de destino no livro de endereços armazena um, ou o VASP da contraparte é identificado no [diretório](#diretório) com um endpoint TRP. Suporta os ativos listados em [identificadores de ativos TRP](#identificadores-de-ativos-trp). A Didit troca dados do ordenante e do beneficiário máquina a máquina, sem necessidade de troca de e-mails. |
| 3 | `GTR` | Rede Global Travel Rule (GTR). A contraparte é resolvida através de um `counterparty_gtr_vasp_code` explícito ou de uma entrada de diretório que contenha um. A Didit lê a resposta da contraparte a partir da resposta da GTR ou através da consulta periódica do estado do pedido a cada 5 minutos enquanto a transferência aguarda. |
| 4 | `TRUST` | Rede TRUST. A contraparte é resolvida através de `counterparty_trust_membership_id` ou de uma entrada de diretório que contenha um. Apenas envio: a TRUST não devolve nada que a Didit possa ler, pelo que a transferência aguarda em `AWAITING_COUNTERPARTY` até expirar. |
| 5 | `VERIFYVASP` | Rede VerifyVASP. A contraparte é resolvida através de `counterparty_verifyvasp_id` ou de uma entrada de diretório que contenha um. A Didit lê a resposta da contraparte através da consulta periódica do estado da verificação a cada 5 minutos. |
| 6 | `SYGNA` | Rede Sygna Bridge (adquirida pela VerifyVASP em 2026, ainda em funcionamento para membros existentes). Implementação nativa do protocolo Sygna - IVMS101 encriptado com ECIES e pedidos de permissão assinados. A contraparte é resolvida através de `counterparty_sygna_vasp_code` ou de uma entrada de diretório que contenha um. A resposta de aceitação ou recusa da contraparte conclui ou recusa a transferência: a Didit consulta periodicamente o estado da transferência a cada 5 minutos e também recebe a resposta no seu callback Sygna assim que o servidor TRP público da Didit estiver ativo. |
| 7 | `EMAIL` | Solução de recurso utilizada quando nenhuma via de protocolo ou rede consegue contactar a contraparte e o utilizador indica o respetivo contacto de conformidade em `counterparty_vasp_email`, ou a entrada da contraparte no diretório tiver um [contacto de conformidade](#contactos). A Didit envia por e-mail a esse contacto uma ligação de recolha de utilização única para que possa confirmar ou recusar a troca sem ter uma conta Didit. Esta é a solução principal para o problema do período de transição - contrapartes que ainda não são contactáveis em nenhuma rede. |

As vias de rede (`GTR`, `TRUST`, `VERIFYVASP`, `SYGNA`) requerem uma adesão à rede do lado emissor e, atualmente, essa adesão tem de ser a **sua própria**.
Associe as credenciais da sua adesão no **Marketplace** da consola (categoria Redes da Travel Rule), e as suas transferências serão processadas sob a sua própria identidade de rede.

**A Didit não detém atualmente qualquer adesão de plataforma para nenhuma das quatro redes e está a fazer onboarding como fornecedor nessas redes.**
Até que esse onboarding esteja concluído, `platform_available` é `false` para as quatro, o modo `didit` das definições (encaminhamento através da adesão de plataforma da Didit) não está disponível para nenhuma rede, e `disabled_networks` não tem nada para desativar.
Uma adesão que o próprio utilizador ligue tem sempre precedência sobre uma adesão de plataforma.
Nenhuma adesão a redes está incluída por defeito, incluindo a GTR.
Ativar a Travel Rule não ativa a GTR, a TRUST, a VerifyVASP nem a Sygna.
Consulte [Obter definições da Travel Rule](https://docs.didit.me/pt/management-api/travel-rule/get-settings.md) para ver os modos de `networks` em vigor da sua aplicação e [Redes da Travel Rule](https://docs.didit.me/pt/transaction-monitoring/travel-rule-networks.md) para saber o que cada rede alcança atualmente.
Se as quatro indicarem `unavailable`, nenhuma conseguirá encaminhar uma troca: associe a sua própria adesão no **Marketplace** ou utilize uma contraparte contactável por `INTERNAL`, `TRP` ou `EMAIL`.

Ao guardar uma adesão, o código de participante tem de ser o seu: guardar a adesão resulta numa resposta `400` se o código for o código da própria Didit nessa rede, ou um código que a adesão de outra aplicação já detenha.
Uma adesão à GTR necessita da sua chave privada ed25519 (base64), cuja chave pública está registada no portal da GTR: esta encripta os dados pessoais que envia e desencripta os dados que recebe.
Uma adesão à VerifyVASP aponta para o seu próprio VerifyVASP Enclave: o URL é o do seu Enclave e o token é aquele que o seu Enclave apresenta à Didit.

Mesmo com a sua própria adesão, uma via de rede só encaminha uma transferência se os respetivos `beneficiary_data` contiverem o ID da contraparte nessa rede (`counterparty_gtr_vasp_code`, `counterparty_trust_membership_id`, `counterparty_verifyvasp_id` ou `counterparty_sygna_vasp_code`), ou se a entrada da contraparte no diretório a listar nessa rede (consulte [Rotas](#rotas)).

O campo `platform_available` indica se a adesão da plataforma está configurada, não sendo uma verificação em tempo real do estado da rede. Da mesma forma, `connected` significa que as credenciais da sua adesão foram guardadas e passaram na validação local; a primeira troca em tempo real verifica-as junto da rede. Um modo `didit` ou `own` não garante que a contraparte seja contactável nem assegura uma entrega bem-sucedida.

Com a sua própria adesão, a Didit lê a resposta da contraparte através de `GTR`, `VERIFYVASP` e `SYGNA` a partir da resposta da rede ou consultando a rede a cada 5 minutos, o que conclui ou recusa a transferência.
O `TRUST` apenas envia: uma transferência enviada através deste permanece em `AWAITING_COUNTERPARTY` até decorrer `confirmation_timeout_hours`, passando depois para `EXPIRED` e aplicando-se o seu `timeout_outcome`.
A receção de uma transferência que outro VASP lhe envie através de uma rede ainda não está ativa e nenhuma troca através de uma rede foi ainda concluída numa rede de produção: consulte [Redes da Travel Rule](https://docs.didit.me/pt/transaction-monitoring/travel-rule-networks.md).

Outras redes - CODE (a aliança coreana), TRISA, Notabene e Veriscope - estão listadas no **Marketplace** da consola como blocos para solicitar acesso.
A Didit ainda não tem integração com as mesmas, pelo que nenhuma transferência pode ser encaminhada através delas atualmente.

Quando nenhuma das sete vias consegue resolver uma contraparte, a Didit executa mais um passo de resolução antes de desistir: atribuição por análise de blockchain.
A carteira de destino é pesquisada em dados de análise de blockchain; quando a carteira pertence a uma exchange ou custodiante conhecido, a Didit regista o VASP atribuído na transferência, adiciona-o ao [diretório](#diretório) e volta a executar as vias uma vez com o novo nome.
Consulte [Atribuição por análise de blockchain](#atribuição-por-análise-de-blockchain) para obter informações sobre o comportamento completo e os preços.

Uma transferência cujo destino seja [declarado como uma carteira autocustodiada](#carteiras-autocustodiadas-declaradas) ignora todas as sete vias - não existe um VASP de contraparte com o qual trocar informações - e avança diretamente para a prova de propriedade da carteira pelo utilizador final.

> [!NOTE]
>
> A Didit também opera a vertente da troca direcionada para a contraparte: endpoints públicos de identidade e consulta TRP que outros VASP chamam para entrar em contacto consigo, endpoints de callback e o fluxo de recolha por e-mail.
> Nunca os chama diretamente - são infraestrutura gerida -, mas a página [Interoperabilidade da Travel Rule](https://docs.didit.me/pt/transaction-monitoring/travel-rule-interoperability.md) documenta cada um deles para que os VASP de contraparte se possam ligar a si.
> Interage com a Travel Rule apenas através dos endpoints `/v3/` descritos nesta página.

## O que é executado ao submeter uma transferência

As verificações são executadas dentro da única chamada `POST /v3/transactions/` - no momento em que recebe a resposta, a triagem já foi executada, a transferência está armazenada e as regras foram avaliadas.
A troca em si tem início após a resposta: a Didit escolhe o rail e contacta a contraparte fora do seu pedido, para que nenhuma rede ou contraparte possa tornar a criação mais lenta ou fazê-la falhar.
Cada alteração de estado posterior chega como um webhook [`travel_rule.status.updated`](#webhooks) que indica o rail, e o objeto de transferência devolvido pelos endpoints de transferência da Travel Rule contém um campo [`delivery`](#entrega-e-tentativas) que mostra se a mensagem foi entregue com sucesso.
Não existe nenhum pipeline para consultar ciclicamente (polling); as partes assíncronas são a troca, a resposta da contraparte e qualquer ação do utilizador final.

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant You as Your platform
    participant Didit as Didit API
    participant CP as Counterparty VASP
    participant User as Your customer

    You->>Didit: POST /v3/transactions/ (travelRule)
    Note over Didit: Validate + bind subject + blocklist check
    Note over Didit: Device & IP enrichment
    Note over Didit: Crypto screening (when crypto + monitoring on)
    Note over Didit: Threshold check -> transfer stored (AWAITING_COUNTERPARTY)
    Note over Didit: Rules engine (EU TFR bundle + your rules)
    Didit--)You: transaction.created webhook
    Didit-->>You: Transaction + travel_rule.status + action_required
    Note over Didit: After the response: rails in priority order -> analytics attribution
    Didit->>CP: Exchange over the first reachable rail
    Didit--)You: travel_rule.status.updated (each status change)
    User->>Didit: Proves wallet control (when action_required)
    CP-->>Didit: Confirms beneficiary data
    Didit--)You: travel_rule.status.updated (COMPLETED)
    You->>You: Broadcast on-chain
    You->>Didit: PATCH .../travel-rule/ { payment_txn_id }
    Didit--)You: travel_rule.status.updated (FINISHED)
```

Passo a passo:

1. **Validação e vinculação do sujeito.** O payload é validado.
   Um `transaction_id` já utilizado na sua aplicação é rejeitado com `400`, e quando dois pedidos concorrem com o mesmo ID, um deles recebe `409`.
   O `subject` é associado ao perfil de utilizador ou empresa através de `vendor_data`, para que a transferência apareça nesse perfil para monitorização.
   Um `vendor_data` do sujeito ou da contraparte presente na lista de bloqueio é rejeitado com `400`, e nenhuma transação é criada.
   Carteiras, contas bancárias, IPs e dispositivos na lista de bloqueio são verificados no passo 6 e fazem com que a transação seja recusada nesse passo, após a execução do encaminhamento.
2. **Enriquecimento de dispositivo e rede.** Os IPs das partes são geo-enriquecidos e qualquer contexto de dispositivo (automático no [envio via SDK](https://docs.didit.me/pt/transaction-monitoring/sdk-transaction-submission.md)) é normalizado no grafo de dispositivos - o mesmo grafo alimentado pelas sessões de KYC, para que a associação "relacionado por dispositivo" funcione transversalmente no onboarding e nas transações.
3. **Triagem cripto.** Para transferências cripto com monitorização ativada, a carteira relevante (ou o hash on-chain) é submetida a triagem em ferramentas de análise de blockchain antes de qualquer troca - exposição a sanções, proximidade a mixers, fundos roubados. Consulte [Triagem de cripto e carteiras](https://docs.didit.me/pt/transaction-monitoring/aml-screening.md).
4. **Transferência Travel Rule.** O motor de troca verifica o limiar e respeita uma [declaração de carteira autocustodiada](#carteiras-autocustodiadas-declaradas), armazenando depois a transferência: `NOT_APPLICABLE` abaixo do seu limiar, `UNCONFIRMED_OWNERSHIP` para uma carteira autocustodiada declarada, `COMPLETED` quando a outra carteira é a sua própria carteira verificada e `AWAITING_COUNTERPARTY` caso contrário, com o respetivo rail ainda vazio.
   Cada alteração de estado coloca em fila um evento `travel_rule.status.updated`, e a Didit envia-o após o `transaction.created` da transação (passo 7).
5. **Emissão da sessão de comprovação de propriedade da carteira.** Se a transferência exigir comprovação de controlo por parte do utilizador final e `auto_wallet_verification` estiver ativado, é gerada uma sessão de [widget de propriedade de carteira](https://docs.didit.me/pt/transaction-monitoring/wallet-ownership-widget.md) devolvida em `action_required`.
6. **Avaliação de regras.** Todas as regras ativas são executadas - o [pacote de regras TFR da UE](#pacote-de-regras-tfr-da-ue) reage ao estado da transferência definido no passo 4, as suas regras personalizadas consultam o resultado da triagem do passo 3, e uma regra pode reter a transação (`IN_REVIEW`), recusá-la ou exigir [verificação reforçada (step-up)](https://docs.didit.me/pt/transaction-monitoring/sdk-transaction-submission.md#ações-necessárias-do-utilizador) (`AWAITING_USER`).
7. **Faturação e notificação.** Uma transação de **saída** é faturada numa única linha: a [linha da Travel Rule](#preços) quando iniciou uma troca, e a Triagem de Transações caso contrário. Uma transferência recebida não acarreta nenhuma das tarifas, e uma aplicação em sandbox nunca é cobrada.
   A resposta é devolvida e `transaction.created` é disparado para os seus destinos de webhook, seguido pelos eventos `travel_rule.status.updated` do passo 4.
8. **Encaminhamento, após a resposta.** A Didit percorre os [sete rails](#visão-geral) por ordem de prioridade; se nenhum resolver, a [atribuição por análise de blockchain](#atribuição-por-análise-de-blockchain) identifica a contraparte e os rails são executados novamente uma vez. O primeiro rail acessível processa a troca: a transferência permanece em `AWAITING_COUNTERPARTY` nesse rail enquanto a contraparte responde, liquida de imediato quando uma contraparte `INTERNAL` é correspondida (`COMPLETED` ou `COUNTERPARTY_MISMATCHED_DATA`), ou passa para `COUNTERPARTY_VASP_NOT_FOUND` quando nenhum rail alcança a contraparte. Cada alteração dispara `travel_rule.status.updated`, e as suas regras são executadas novamente sempre que o estado ou o rail mudarem. Uma transferência que o encaminhamento deixe em `COUNTERPARTY_VASP_NOT_FOUND` obtém a sua sessão do widget de propriedade de carteira nesse momento (quando `auto_wallet_verification` estiver ativado); consulte-a a partir de `action_required` da transação com [Get transaction](https://docs.didit.me/pt/management-api/transactions/get.md).

### Como cada passo corresponde às suas obrigações

| Passo do pipeline | Obrigação cumprida |
| - | - |
| Dados do ordenante fornecidos em `originator_data` | Informações precisas do ordenante (GAFI/FATF R.16; Regulamento TFR da UE Art.º 14). Nos rails que transmitem dados de pessoas (`INTERNAL`, `TRP` e os rails de rede), a Didit transmite a identidade verificada quando o sujeito é um utilizador com uma verificação KYC da Didit aprovada (consulte [Dados verificados e proveniência](#dados-verificados-e-proveniência)) e, caso contrário, exatamente os `originator_data` que enviar. |
| Troca pelos rails antes da liquidação | Informações do ordenante e do beneficiário transmitidas ao VASP da contraparte **antes** da liquidação da transferência (GAFI/FATF R.16; Regulamento TFR da UE Art.º 14-16) |
| Correspondência do nome do beneficiário | Verificação de que os dados do beneficiário correspondem ao destino (obrigações do CASP beneficiário segundo o Art.º 16 do Regulamento TFR da UE) |
| Comprovação de propriedade de carteira autocustodiada | A obrigação do Regulamento TFR da UE relativa a carteiras autocustodiadas - verificar a propriedade de um endereço não alojado em vez de realizar a troca com um VASP |
| Triagem cripto + pacote de regras TFR da UE | Procedimentos baseados no risco para transferências com informações em falta ou incompletas e controlos de exposição a sanções |
| Exigência de `COMPLETED` antes da transmissão | Os fundos não são libertados até que a troca esteja concluída - a essência da regra |
| Encerramento `FINISHED` com o hash on-chain + cronologia | Conservação de registos: cada transferência inclui a sua cronologia completa de negociação para auditoria |

> [!NOTE]
>
> **Nota sobre testes.** As aplicações em sandbox ignoram a avaliação de regras e a faturação, e não enviam webhooks `transaction.created` ou `transaction.status.updated`. As transações em sandbox permanecem `APPROVED`, a menos que uma transferência Travel Rule prestes a expirar aplique o seu `timeout_outcome`, e nada é cobrado.
> O motor de troca da Travel Rule é executado em aplicações em sandbox quando a Travel Rule está ativada, contra uma única contraparte: cada troca de **saída** segue para o [Didit Test VASP](https://docs.didit.me/pt/transaction-monitoring/travel-rule-sandbox.md) no rail `TEST_VASP`, que responde dentro da Didit com o cenário que escolher, para que a transferência fique concluída, seja recusada, apresente divergência de dados, fique inacessível, expire ou aguarde pela comprovação de propriedade da carteira.
> Nenhuma mensagem de conformidade chega a um VASP de contraparte real, e os webhooks `travel_rule.status.updated` são entregues com `environment: sandbox`.
> **Numa transferência recebida**, o VASP de teste pode enviar-lhe uma transferência ([Trigger Test VASP Inbound Transfer](https://docs.didit.me/pt/management-api/travel-rule/trigger-test-vasp-inbound.md)), e o registo (`POST /v3/travel-rule/inbound/`) é liquidado com base no livro de endereços da sua carteira tal como numa aplicação em produção - `ON_HOLD`, `UNCONFIRMED_OWNERSHIP`, `COUNTERPARTY_MISMATCHED_DATA` ou `COMPLETED` seguido de `FINISHED`.
> Consulte [Testar a Travel Rule em sandbox](https://docs.didit.me/pt/transaction-monitoring/travel-rule-sandbox.md).

## Ciclo de vida

Cada transferência tem um `status` selecionado a partir de 13 valores.
A troca começa em `AWAITING_COUNTERPARTY` no caso normal, em `NOT_APPLICABLE` quando o montante está abaixo do seu `threshold_amount` ou um pedido de pagamento Lightning não indica nenhum beneficiário (consulte [Lightning](#lightning)), ou em `UNCONFIRMED_OWNERSHIP` quando o destino foi [declarado como uma carteira autocustodiada](#carteiras-autocustodiadas-declaradas), e termina num dos estados terminais: `FINISHED`, `CANCELLED` ou `EXPIRED`.

A transferência executa a sua própria máquina de estados, **separada do** estado de análise da transação subjacente.
O estado de uma troca nunca altera o estado da transação por si só, com uma exceção: uma expiração aplica o seu `timeout_outcome` configurado (ou uma [política de sunrise ou de não resposta](#políticas-de-sunrise-e-de-não-resposta) quando aplicável).
Em vez disso, as suas regras voltam a ser executadas em cada transição, pelo que as [regras do TFR da UE](#pacote-de-regras-tfr-da-ue) ou qualquer regra baseada em `travel_rule_status` podem mover a transação, por exemplo para `IN_REVIEW`.
Uma transferência que necessite de comprovativo de controlo da carteira por parte do utilizador final adiciona um bloco `action_required` à transação, mas o seu `status` permanece tal como as suas regras o deixaram.
Leia o estado da troca a partir de `travel_rule.status`; leia o veredito de permissão / suspensão / recusa a partir do próprio `status` da transação.

Cada transição (e cada estado reportado passivamente) é também refletida nos valores personalizados da transação para que as [regras](https://docs.didit.me/pt/transaction-monitoring/rules.md) possam basear-se nela: `custom_values.travel_rule_status` (estado canónico), `custom_values.travel_rule_rail` (o canal que transportou a troca, vazio até que um seja selecionado) e `custom_values.travel_rule_regime` (derivado da `jurisdiction` das suas [definições](#configuração): `SG` → `singapore`, `GB` → `uk`, e qualquer código de membro da UE ou do EEE como `DE` ou `FR` → `eu`; códigos não mapeados são gravados em minúsculas, por exemplo `US` → `us`. Um `props.travel_rule_regime` submetido por si prevalece sempre sobre o valor derivado).

| Estado | Significado |
| - | - |
| `AWAITING_COUNTERPARTY` | A transferência aguarda a sua contraparte: primeiro enquanto a Didit escolhe a rede e envia a troca, logo após a criação, e depois enquanto a contraparte responde. A [`delivery`](#entrega-e-tentativas) da transferência indica se a mensagem foi entregue com sucesso. O `TRUST` apenas envia, pelo que uma transferência através dele permanece aqui até expirar. |
| `UNCONFIRMED_OWNERSHIP` | A transferência está a aguardar o comprovativo de controlo da carteira. É alcançado quando a carteira da contraparte foi [declarada como autocustodiada](#carteiras-autocustodiadas-declaradas) na submissão (de saída ou de entrada), ou quando uma transferência de entrada corresponde a uma [entrada do livro de endereços](#livro-de-endereços-de-carteiras) cuja propriedade ainda não foi verificada. Avança através do [widget de propriedade da carteira](https://docs.didit.me/pt/transaction-monitoring/wallet-ownership-widget.md) ou de [`POST .../travel-rule/ownership/`](#confirmar-a-propriedade-da-carteira). |
| `ON_HOLD` | A Didit define-o apenas em transferências de entrada: a carteira de destino de um [registo pós-depósito](#registo-sunrise-posterior-ao-depósito) ou de uma consulta `TRP` de entrada não está no seu [livro de endereços](#livro-de-endereços-de-carteiras), ou uma consulta `TRP` de entrada aguarda a sua decisão (a aceitação automática está desativada ou a resposta automática não pôde ser entregue). Resolva-o com [`POST .../travel-rule/ownership/`](#confirmar-a-propriedade-da-carteira). Não altera o estado da transação por si só; a [regra de biblioteca](https://docs.didit.me/pt/transaction-monitoring/rules-library.md) opcional `travel-rule-pending-action` move essas transações para `AWAITING_USER`. |
| `COMPLETED` | A troca foi concluída com sucesso: a contraparte (ou, numa transferência de entrada, você) aprovou-a, ou as verificações que a Didit executa nesse percurso foram aprovadas (correspondência do nome do beneficiário, comprovativo de propriedade da carteira). É seguro transmitir a transferência on-chain. |
| `FINISHED` | A troca é finalizada com o hash da transação on-chain. Numa transferência de saída, reporta o hash através de [`PATCH .../travel-rule/`](#enviar-uma-transferência). Numa transferência de entrada, a Didit define-o quando o depósito já foi liquidado ([registo pós-depósito](#registo-sunrise-posterior-ao-depósito)), quando o ordenante confirma uma transferência `TRP`, ou quando o lado de saída `INTERNAL` termina. |
| `CANCELLED` | Cancelada manualmente com `action: "cancel"` a partir de qualquer estado não terminal, ou cancelada pelo ordenante de uma transferência `TRP` de entrada. |
| `EXPIRED` | Decorreu o período de `confirmation_timeout_hours` enquanto estava em `AWAITING_COUNTERPARTY`. Um processo de limpeza periódico (a cada 15 minutos) expira a transferência e aplica o seu `timeout_outcome` configurado à transação subjacente: `REJECT` recusa-a, `HOLD` move-a para análise, `PROCEED` deixa-a inalterada. A sua [política de sunrise ou de não resposta](#políticas-de-sunrise-e-de-não-resposta) substitui o `timeout_outcome` quando aplicável. |
| `COUNTERPARTY_MISMATCHED_DATA` | O nome do beneficiário não cumpriu a `name_matching_strictness` configurada em relação ao outro lado: o nome devolvido pela contraparte ou o `holder_name` da entrada correspondente no livro de endereços. |
| `COUNTERPARTY_VASP_NOT_FOUND` | Nenhum dos sete canais - nem a alternativa de [atribuição por análise de blockchain](#atribuição-por-análise-de-blockchain) - conseguiu resolver um VASP de contraparte acessível para esta transferência. Qualquer entidade atribuída continua registada na transferência e no diretório. Nas transferências de saída, a Didit cria automaticamente uma sessão do [widget de propriedade da carteira](https://docs.didit.me/pt/transaction-monitoring/wallet-ownership-widget.md) (quando `auto_wallet_verification` está ativo) para que a transferência ainda possa ser concluída como uma transferência de carteira autocustodiada. `reason` e `next_actions` explicam o motivo e o que permite avançar: consulte [Por que motivo uma transferência está bloqueada](#por-que-motivo-uma-transferência-está-bloqueada). |
| `COUNTERPARTY_VASP_NOT_REACHABLE` | Foi identificado um VASP de contraparte, mas o canal selecionado não conseguiu efetuar a entrega: não foi possível contactar o seu endpoint de identidade ou de consulta `TRP`, a identidade reportada não correspondeu a `counterparty_vasp_lei` ou `counterparty_vasp_name`, uma rede recusou a mensagem ou não a aceitou após seis tentativas (consulte [Entrega e novas tentativas](#entrega-e-tentativas)), ou o fornecedor de correio eletrónico recusou o e-mail de conformidade. `reason` distingue estes casos e `next_actions` indica o que permite avançar a transferência: consulte [Por que motivo uma transferência está bloqueada](#por-que-motivo-uma-transferência-está-bloqueada). Tente novamente com `action: "resend"` assim que estiver novamente acessível. |
| `COUNTERPARTY_VASP_GENERAL_DECLINE` | A contraparte recusou a troca: propriedade negada, recolha por e-mail recusada ou uma rejeição `TRP` ou Sygna. |
| `NOT_ENOUGH_COUNTERPARTY_DATA` | Uma consulta `TRP` de entrada não identificou o beneficiário nem pelo nome nem pelo endereço da carteira, pelo que a Didit não conseguiu associá-lo ao seu livro de endereços. Nem o endpoint de propriedade nem `resend` aceitam tal transferência de entrada: só é possível cancelá-la, e cancelar não responde à consulta da contraparte. A Didit nunca define este estado numa transferência de saída; se o registar manualmente numa, `action: "resend"` executa novamente o encaminhamento. |
| `NOT_APPLICABLE` | O montante da transferência ficou abaixo do `threshold_amount` configurado, um pedido de pagamento de saída por [Lightning](#lightning) não indica nenhum beneficiário (`chain_details.not_applicable_reason` explica o motivo), ou registou este estado manualmente com a Travel Rule desativada (incluindo os valores legados `UNKNOWN` e `EXEMPT`, consulte abaixo). |

> [!WARNING]
>
> **Nunca transmita para a rede antes de `COMPLETED`.**
> Libertar fundos on-chain enquanto uma transferência está em `AWAITING_COUNTERPARTY`, `UNCONFIRMED_OWNERSHIP`, ou em qualquer estado de discrepância/recusa anula o propósito da troca de informações.
> Condicione o seu passo de transmissão a `status == "COMPLETED"`, e depois chame `PATCH .../travel-rule/` com o `payment_txn_id` resultante para transitar para `FINISHED`.

As transições, de relance (`CANCELLED` é adicionalmente acessível a partir de qualquer estado não terminal com `action: "cancel"`):

```mermaid theme={null}
stateDiagram-v2
    [*] --> NOT_APPLICABLE: below threshold
    [*] --> UNCONFIRMED_OWNERSHIP: self-hosted wallet declared
    [*] --> AWAITING_COUNTERPARTY: transfer stored, routing queued
    [*] --> COMPLETED: your own verified wallet
    [*] --> ON_HOLD: inbound with no matching wallet entry
    [*] --> NOT_ENOUGH_COUNTERPARTY_DATA: inbound TRP inquiry names no beneficiary
    AWAITING_COUNTERPARTY --> COUNTERPARTY_MISMATCHED_DATA: INTERNAL rail, verified entry, name mismatch
    AWAITING_COUNTERPARTY --> COUNTERPARTY_VASP_NOT_FOUND: no rail resolved
    AWAITING_COUNTERPARTY --> COUNTERPARTY_VASP_NOT_REACHABLE: delivery failed
    AWAITING_COUNTERPARTY --> COMPLETED: counterparty confirmed, names match where checked
    AWAITING_COUNTERPARTY --> COUNTERPARTY_MISMATCHED_DATA: name match failed
    AWAITING_COUNTERPARTY --> COUNTERPARTY_VASP_GENERAL_DECLINE: counterparty declined
    AWAITING_COUNTERPARTY --> EXPIRED: confirmation timeout
    AWAITING_COUNTERPARTY --> COUNTERPARTY_VASP_NOT_REACHABLE: TRP inquiry not delivered
    UNCONFIRMED_OWNERSHIP --> COMPLETED: ownership proven, names match
    UNCONFIRMED_OWNERSHIP --> COUNTERPARTY_MISMATCHED_DATA: name match failed
    UNCONFIRMED_OWNERSHIP --> COUNTERPARTY_VASP_GENERAL_DECLINE: ownership denied
    ON_HOLD --> COMPLETED: you confirm the wallet, names match
    ON_HOLD --> COUNTERPARTY_MISMATCHED_DATA: you confirm the wallet, name mismatch
    ON_HOLD --> COUNTERPARTY_VASP_GENERAL_DECLINE: you deny the wallet
    COUNTERPARTY_MISMATCHED_DATA --> COMPLETED: you approve an inbound TRP inquiry
    COUNTERPARTY_MISMATCHED_DATA --> COUNTERPARTY_VASP_GENERAL_DECLINE: you decline an inbound TRP inquiry
    COUNTERPARTY_VASP_NOT_FOUND --> COMPLETED: wallet ownership proven in the widget
    COUNTERPARTY_VASP_NOT_FOUND --> AWAITING_COUNTERPARTY: action resend
    COUNTERPARTY_VASP_NOT_REACHABLE --> AWAITING_COUNTERPARTY: action resend
    COMPLETED --> FINISHED: payment_txn_id reported or deposit already settled
    FINISHED --> [*]
    EXPIRED --> [*]
```

### Entrega e tentativas

A Didit envia, fora do pedido que a originou, todas as mensagens que uma transferência tem de enviar, e tenta novamente até que a outra parte a receba.
O objeto de transferência devolvido por [Concluir, cancelar ou reenviar](https://docs.didit.me/pt/management-api/travel-rule/update-transfer.md), [Confirmar propriedade](https://docs.didit.me/pt/management-api/travel-rule/confirm-ownership.md) e [registo de sunrise](#registo-sunrise-posterior-ao-depósito) inclui a mais recente em `delivery`, tal como o objeto `travel_rule` embutido da transação; fica a `null` quando a transferência nunca exigiu uma mensagem.

| Campo | Significado |
| - | - |
| `kind` | `SEND` (a primeira mensagem para a contraparte), `ANSWER` (a sua aceitação ou recusa, devida à rede que solicitou), `TXID` (o hash on-chain, após concluir a transferência), `CANCEL` (após a cancelar), ou `POLL` (uma consulta de estado a uma rede que o disponibilize, a cada 5 minutos enquanto a transferência aguarda a contraparte). |
| `status` | `QUEUED`, `SENDING`, `RETRYING`, `DELIVERED`, ou `FAILED`. |
| `rail` | O canal que transporta a mensagem; vazio até que a Didit tenha escolhido um para a primeira mensagem. |
| `attempts` | Tentativas realizadas até ao momento. |
| `last_error` | O motivo da falha da última tentativa, vazio se nenhuma falhou. Um motivo breve que indica o passo e o tipo de falha, por exemplo `sygna permission request failed: HTTP 503` ou `sygna status query failed: no answer in time`; quando a GTR responde com um erro, o seu próprio código de estado e mensagem são incluídos. Os corpos de resposta nunca são incluídos. |
| `next_attempt_at` | Quando a próxima tentativa é executada, enquanto a mensagem está em `QUEUED` ou `RETRYING`. |
| `delivered_at` | Quando a outra parte recebeu a mensagem. |

Uma falha da qual a rede ainda possa recuperar (falta de resposta atempada, falha de ligação, HTTP `408`, `429` ou `5xx`) é tentada novamente após 30 segundos, 2 minutos, 10 minutos, 30 minutos e 1 hora.
Quando uma primeira mensagem falha definitivamente - a rede recusou-a, ou a sexta tentativa falhou também - a transferência transita para `COUNTERPARTY_VASP_NOT_REACHABLE` com `last_error` na sua `timeline`, e pode tentar novamente com `action: "resend"`.
Qualquer outra mensagem que falhe definitivamente é registada na `timeline`.
`delivery` nunca substitui o `status` da transferência: leia a troca de informações a partir de `status`, e utilize `delivery` para verificar por que motivo uma transferência ainda está em espera.

### Valores de estado legados

Se já enviava `travel_rule_details.status` antes desta versão, esses valores continuam a funcionar e são mapeados automaticamente.
As grafias em camelCase de qualquer estado (por exemplo `counterpartyVaspNotFound`) também são aceites, tanto no envio como em valores de condição de [regra](https://docs.didit.me/pt/transaction-monitoring/rules.md), e são normalizadas para a forma canónica:

| Valor legado | Mapeado para |
| - | - |
| `UNKNOWN` | `NOT_APPLICABLE` |
| `COMPLIANT` | `COMPLETED` |
| `PENDING_ACTION` | `ON_HOLD` |
| `PENDING_COUNTERPARTY` | `AWAITING_COUNTERPARTY` |
| `FAILED` | `CANCELLED` |
| `EXEMPT` | `NOT_APPLICABLE` |

## Configuração

Configure o seu perfil de VASP e a política de negociação uma vez por aplicação com `GET`/`PUT /v3/travel-rule/settings/`.

```bash theme={null}
curl -X GET https://verification.didit.me/v3/travel-rule/settings/ \
  -H "x-api-key: YOUR_API_KEY"
```

```json theme={null}
{
  "is_enabled": false,
  "jurisdiction": "EU",
  "name_matching_strictness": "DEFAULT",
  "confirmation_timeout_hours": 48,
  "timeout_outcome": "HOLD",
  "threshold_amount": "0.00",
  "inbound_auto_accept": true,
  "allow_self_declaration": true,
  "allow_screenshot_proof": true,
  "auto_wallet_verification": true,
  "vasp_attribution_enabled": true,
  "counterparty_screening_enabled": false,
  "sunrise_policy": "",
  "sunrise_jurisdictions": ["CO", "KH", "VN"],
  "non_responsive_policy": "",
  "legal_name": "",
  "lei": "",
  "compliance_email": "",
  "is_discoverable": true,
  "travel_address": "",
  "disabled_networks": [],
  "networks": {
    "gtr": { "rail": "GTR", "mode": "unavailable", "platform_available": false, "connected": false },
    "trust": { "rail": "TRUST", "mode": "unavailable", "platform_available": false, "connected": false },
    "verifyvasp": { "rail": "VERIFYVASP", "mode": "unavailable", "platform_available": false, "connected": false },
    "sygna": { "rail": "SYGNA", "mode": "unavailable", "platform_available": false, "connected": false }
  }
}
```

```bash theme={null}
curl -X PUT https://verification.didit.me/v3/travel-rule/settings/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "is_enabled": true,
    "legal_name": "Origin CASP SL",
    "jurisdiction": "EU",
    "name_matching_strictness": "DEFAULT",
    "confirmation_timeout_hours": 48,
    "timeout_outcome": "HOLD",
    "is_discoverable": true
  }'
```

O `PUT` é uma atualização parcial - envie apenas os campos que pretende alterar.

| Campo | Tipo | Descrição |
| - | - | - |
| `is_enabled` | boolean | Ativa o fluxo gerido de negociação para transações `travelRule` de saída desta aplicação. Requer um `legal_name` não vazio (já armazenado ou incluído no mesmo pedido) - caso contrário, o pedido devolve `400`. |
| `legal_name` | string | A denominação social do seu VASP. Mostrada à contraparte na página de recolha por e-mail e devolvida no [diretório de VASP](#diretório). |
| `lei` | string | O seu identificador de entidade jurídica, devolvido no diretório de VASP. |
| `jurisdiction` | string | O código de jurisdição operacional do seu VASP, até 8 carateres (predefinição `"EU"`). |
| `name_matching_strictness` | string | `NONE`, `STRICT`, `CONTAINS`, `DEFAULT` ou `FUZZY` - consulte abaixo. |
| `confirmation_timeout_hours` | integer | Horas que uma transferência `AWAITING_COUNTERPARTY` pode aguardar antes de expirar automaticamente. Mínimo `1`, predefinição `48`. |
| `timeout_outcome` | string | O que acontece à transação subjacente quando uma transferência expira: `HOLD` coloca-a em análise, `REJECT` recusa-a, `PROCEED` mantém o seu estado inalterado. Predefinição `HOLD`. `sunrise_policy` e `non_responsive_policy` têm precedência quando uma delas se aplica. |
| `sunrise_policy` | string | `HOLD`, `REJECT`, `PROCEED` ou `""` (predefinição) para seguir `timeout_outcome`: o que faz uma transferência expirada quando a sua contraparte é uma entrada do diretório numa jurisdição listada em `sunrise_jurisdictions`. Consulte [Políticas de adaptação e de não resposta](#políticas-de-sunrise-e-de-não-resposta). |
| `non_responsive_policy` | string | `HOLD`, `REJECT`, `PROCEED` ou `""` (predefinição) para seguir `timeout_outcome`: o que faz uma transferência expirada quando a sua contraparte é uma entrada do diretório cuja [capacidade de resposta](#capacidade-de-resposta) é `UNRESPONSIVE`. `sunrise_policy` aplica-se primeiro quando ambas forem aplicáveis. |
| `sunrise_jurisdictions` | string\[] | Apenas de leitura. Os países que a Didit trata como estando num período de adaptação da Travel Rule, atualmente `["CO", "KH", "VN"]`. Qualquer outra jurisdição segue `timeout_outcome`. |
| `compliance_email` | string | E-mail de contacto de conformidade para o seu perfil de VASP. A [rede Didit](#a-rede-didit) lista o seu perfil apenas após este endereço ser confirmado através de uma ligação enviada por e-mail; alterá-lo requer uma nova confirmação. |
| `is_discoverable` | boolean | Indica se o seu perfil de VASP pode ser listado na [rede Didit](#a-rede-didit): encontrado em `GET /v3/travel-rule/vasps/` por outros clientes da Didit e contactado através do canal INTERNAL. A listagem tem condições adicionais; `didit_network` nas definições indica quais estão em falta. Predefinição `true`. |
| `inbound_auto_accept` | boolean | Quando for `true`, um pedido `TRP` de entrada cuja carteira do beneficiário seja uma entrada verificada no seu livro de endereços e cujo nome coincida é aprovado automaticamente. Quando for `false`, aguarda em `ON_HOLD` pela sua decisão. Outros caminhos de entrada não leem esta definição. Predefinição `true`. |
| `allow_self_declaration` | boolean | Quando for `true`, o [widget de propriedade da carteira](https://docs.didit.me/pt/transaction-monitoring/wallet-ownership-widget.md) oferece a autodeclaração como método de prova, e você pode criar entradas no [livro de endereços de carteiras](#livro-de-endereços-de-carteiras) com `self_declared: true`. Predefinição `true`. |
| `allow_screenshot_proof` | boolean | Quando for `true`, o [widget de propriedade da carteira](https://docs.didit.me/pt/transaction-monitoring/wallet-ownership-widget.md) oferece o carregamento de capturas de ecrã como método de prova de propriedade. Uma captura de ecrã nunca verifica a carteira por si só: a sua equipa de conformidade analisa-a e confirma a transferência. Mais fraca do que a assinatura criptográfica - desative-a onde a sua política exigir prova ao nível de uma assinatura. Predefinição `true`. |
| `auto_wallet_verification` | boolean | Quando for `true`, uma transferência de saída que necessite de prova de controlo da carteira pelo utilizador final gera automaticamente uma sessão do [widget de propriedade da carteira](https://docs.didit.me/pt/transaction-monitoring/wallet-ownership-widget.md) vinculada à transação e apresenta-a no bloco `action_required` da transação - os SDKs da Didit iniciam-na automaticamente na [submissão do lado do cliente](https://docs.didit.me/pt/transaction-monitoring/sdk-transaction-submission.md). Predefinição `true`. |
| `counterparty_screening_enabled` | boolean | [Triagem de VASPs de contraparte](#triagem-de-contrapartes) opcional para sanções e notícias adversas, faturada por triagem ao preço da Triagem AML para empresas. Quando for `true`, a Didit faz a triagem da contraparte que uma troca de saída alcança quando a troca é iniciada, reutilizando uma triagem com menos de 30 dias. Predefinição `false`: nada é analisado ou faturado. |
| `vasp_attribution_enabled` | boolean | Quando for `true`, uma transferência de saída que nenhum canal consiga encaminhar é atribuída através de [análise de blockchain](#atribuição-por-análise-de-blockchain) - a carteira de destino é resolvida para o respetivo VASP proprietário, a entidade é adicionada ao diretório e os canais são executados novamente uma vez com o nome atribuído. Predefinição `true`. |
| `threshold_amount` | string (decimal) | Montante mínimo de transferência que aciona uma troca gerida, na moeda predefinida da sua aplicação: a Didit compara-o com o montante da transferência convertido para essa moeda (ou com o `amount_in_default_currency` que enviar), e não com o montante na moeda da própria transferência. As transferências abaixo deste valor passam diretamente para `NOT_APPLICABLE` e nunca são negociadas. Se a Didit não conseguir converter o montante, o limiar não é aplicado e a transferência é trocada. As aplicações em sandbox não convertem montantes, pelo que aí o limiar só se aplica quando envia `amount_in_default_currency`. Predefinição `0.00` - correspondendo ao modelo sem montante mínimo do TFR da UE, pelo que todas as transferências são verificadas, independentemente do valor. |
| `ownership_validation_mode` | string | `FULL`, `SIMPLIFIED` ou `AUTOMATED` - quanto comprovativo é necessário para validar a propriedade de uma carteira. Consulte [Modos de validação de propriedade](#modos-de-validação-de-propriedade). Predefinição `AUTOMATED`. |
| `simplified_validation_threshold` | string (decimal) | No modo `SIMPLIFIED`, uma transferência abaixo deste montante aceita uma autodeclaração. Predefinição `0.00`. |
| `data_sharing_fields` | object | Os campos que envia sobre os seus próprios utilizadores, por tipo de entidade. Consulte [Partilha de dados](#partilha-de-dados). |
| `matching_rules` | object | Com que rigor cada campo dos dados da contraparte é comparado, por tipo de entidade. Consulte [Correspondência por campo](#correspondência-por-campo). |
| `disabled_networks` | string\[] | Redes (`GTR`, `TRUST`, `VERIFYVASP`, `SYGNA`) pelas quais as suas transferências NÃO devem ser encaminhadas através da adesão da plataforma Didit. Uma rede à qual tenha associado a sua própria adesão (Marketplace da consola) nunca é afetada por esta lista. A Didit ainda não possui nenhuma adesão de plataforma, pelo que a lista não tem qualquer efeito no encaminhamento atualmente (uma rede listada reporta `mode: off`). Predefinição `[]`. |
| `networks` | object | Só de leitura. Estado por rede indexado por `gtr` / `trust` / `verifyvasp` / `sygna`: `{rail, mode, platform_available, connected}` onde `mode` é `own` (a sua adesão associada), `didit` (adesão da plataforma Didit, ainda não disponível em nenhuma rede), `off` (desativada por si) ou `unavailable`. |
| `travel_address` | string | Só de leitura. O Travel Address próprio do seu VASP - o endpoint de consulta `TRP` de entrada codificado que outros VASP utilizam para o contactar. Preenchido assim que a Travel Rule for ativada, por exemplo `ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeS5uNDp3dGW3bweBWLKws442chRsyNxmmJnyWc7frxjjSeABVsYR11UuBePkw6E`. |

### Rigor da correspondência de nomes

| Valor | Comportamento |
| - | - |
| `NONE` | Qualquer nome de beneficiário é aceite - nenhuma comparação é efetuada. |
| `STRICT` | Os conjuntos de tokens normalizados de ambos os nomes têm de ser exatamente iguais. |
| `CONTAINS` | As palavras de um dos nomes aparecem todas no outro, independentemente de serem poucas. |
| `DEFAULT` | Cada token do nome mais curto tem de aparecer no nome mais longo (correspondência por subconjunto), e o nome mais curto necessita de pelo menos dois tokens, exceto se ambos os nomes forem idênticos. |
| `FUZZY` | O rácio de semelhança entre as strings normalizadas completas tem de ser de pelo menos `0.85`. |

### Modos de validação de propriedade

`ownership_validation_mode` determina o nível de comprovação da propriedade de uma carteira necessário antes de uma transferência poder basear-se nela:

| Modo | Comportamento |
| - | - |
| `FULL` | É sempre exigido um comprovativo: uma mensagem assinada, um depósito de teste ou uma captura de ecrã revista. A declaração do utilizador final nunca é considerada. O widget não disponibiliza `SELF_DECLARATION`; iniciá-la resulta em `403`, e uma entrada no livro de endereços criada com `self_declared: true` responde com `400`. |
| `SIMPLIFIED` | Uma autodeclaração é aceite enquanto a transferência estiver abaixo de `simplified_validation_threshold`; acima deste valor, é exigido um comprovativo. Uma transferência de entrada (uma consulta TRP, uma mensagem de rede ou um depósito reportado por si) é avaliada pelo seu montante convertido para a moeda predefinida da sua aplicação à taxa atual. Um ativo sem taxa de câmbio, bem como qualquer transferência de uma aplicação em sandbox, é considerado como estando acima do limiar. |
| `AUTOMATED` | O livro de endereços e os comprovativos anteriores do utilizador final são suficientes por si só, autodeclarações incluídas enquanto `allow_self_declaration` for `true`. Esta é a predefinição e o comportamento de todas as aplicações antes de estes modos existirem. |

Uma carteira fica associada a cada utilizador final assim que for verificada.
Em `FULL` e `SIMPLIFIED`, uma transferência posterior apenas reutiliza a carteira quando for suportada por um comprovativo que o modo aceite para essa transferência.
Quando `inbound_auto_accept` não encontra nenhuma carteira no livro de endereços para corresponder, uma carteira de criptomoeda registada por si nas transações de exatamente um utilizador final identifica o titular.
A Didit adiciona essa carteira ao livro de endereços do utilizador final como a sua autodeclaração, verificada exceto se o modo for `FULL`. Nunca adiciona uma carteira que o livro de endereços já liste sob outro nome da mesma cadeia (`eth` e `ethereum`), incluindo uma registada como pertencente a outro VASP.
As verificações de endereço que outros VASP efetuam antes do envio (através de `GTR`, `Sygna` e `VerifyVASP`) também seguem o modo: sob `FULL`, uma carteira que o utilizador final apenas tenha declarado não é reportada como sendo sua.

### Partilha de dados

`data_sharing_fields` escolhe quais os campos que a Didit envia à contraparte sobre os seus próprios utilizadores, separadamente para particulares e empresas:

```json theme={null}
{
  "data_sharing_fields": {
    "individual": ["name", "wallet_address", "address", "date_of_birth"],
    "company": ["name", "wallet_address", "address"]
  }
}
```

* Os particulares podem partilhar `name`, `wallet_address`, `address`, `national_id`, `customer_identification`, `date_of_birth` e `place_of_birth`. As empresas utilizam os primeiros cinco.
* `name` e `wallet_address` são sempre enviados.
* Um tipo de entidade que nunca tenha configurado partilha todos os campos. Uma lista vazia é também uma escolha: partilha apenas o nome e a carteira.
* Um `PUT` faz a intercalação por tipo de entidade, pelo que enviar `individual` não altera a escolha armazenada para `company`.
* Uma escolha que não consiga satisfazer as obrigações do ordenante do regime da sua `jurisdiction` (EU TFR ou Recomendação 16 do GAFI/FATF), incluindo uma lista vazia, é recusada com `400`. Os erros surgem sob `data_sharing_fields`, indexados pelo tipo de entidade.

### Correspondência por campo

`matching_rules` define o nível de rigor com que cada campo dos dados da contraparte é comparado com os dados que possui:

```json theme={null}
{
  "matching_rules": {
    "individual": { "name": "DEFAULT", "date_of_birth": "STRICT", "address": "NONE", "account": "STRICT" },
    "company": { "name": "FUZZY", "address": "NONE", "account": "STRICT" }
  }
}
```

Cada valor é `NONE`, `STRICT`, `CONTAINS`, `DEFAULT` ou `FUZZY`.
Predefinições: `name` segue `name_matching_strictness`, `date_of_birth` e `address` são `NONE`, e `account` é `STRICT`.
Um campo omitido mantém a respetiva predefinição, e um campo que o tipo de entidade não compara (uma empresa não tem `date_of_birth`) é recusado com `400`.

### Limiares por jurisdição

`threshold_amount` existe porque o âmbito de aplicação da Travel Rule varia consoante o regulador.
A Didit tem como predefinição `0.00` - a posição da UE - pelo que é trocada informação relativamente a todas as transferências, a menos que aumente este valor deliberadamente:

| Regime | Limiar | Notas |
| - | - | - |
| **UE** - Regulamento das Transferências de Fundos (UE) 2023/1113 | **Sem mínimo** | Todas as transferências de criptoativos entre CASP estão abrangidas. A propriedade de uma carteira autocustodiada tem de ser verificada para transferências superiores a 1000 EUR. |
| **Recomendação 16 do GAFI/FATF** (referencial global) | 1000 USD/EUR | Abaixo deste valor, o GAFI permite um conjunto reduzido de dados (nomes e endereços, sem verificação). |
| **Estados Unidos** - BSA Travel Rule | 3000 USD | O limiar histórico da FinCEN para transferências de fundos, aplicado a moedas virtuais convertíveis. |
| **Reino Unido** | Equivalente a 1000 EUR | Informação completa acima deste valor; conjunto reduzido de dados abaixo (MLRs Part 7A). |
| **Singapura** - MAS PSN02 | 1500 SGD | Requisitos reduzidos abaixo do limiar. |
| **Suíça** - FINMA | Sem mínimo | Informação obrigatória para todas as transferências; espera-se uma prova de propriedade para carteiras autocustodiadas. |

Defina `threshold_amount` com o valor indicado pelo seu regulador; as transferências abaixo deste limiar resultam em `NOT_APPLICABLE` sem partilhar quaisquer dados de identidade.
Os limiares evoluem - confirme o valor em vigor junto do seu consultor jurídico de conformidade em vez de tratar esta tabela como aconselhamento jurídico.

### Modelo de dados IVMS 101

O padrão da indústria para os dados trocados ao abrigo da Travel Rule é o **IVMS 101** (interVASP Messaging Standard).
`travel_rule_details.originator_data` e `travel_rule_details.beneficiary_data` são payloads de pessoas no estilo IVMS 101: o Didit envolve-os no envelope nativo de cada rail - o rail TRP troca blocos `IVMS101` (`ivms101.2023`, reportado no campo `ivms_version` da transferência), o rail Sygna a sua variante IVMS encriptada com ECIES, e os rails `GTR`, `TRUST` e `VERIFYVASP` os seus próprios envelopes encriptados - para que um único formato de payload chegue a cada contraparte no formato esperado pelo respetivo protocolo.

O Didit lê estas chaves de cada payload de pessoa ao construir a mensagem IVMS 101: `first_name` e `last_name` (ou um único `name` ou `full_name`), `date_of_birth`, `place_of_birth`, `residence_country` (ou `country`), `vendor_data` (ou `customer_identification`) e `wallet_address`.

Duas regras práticas:

* **Sistema de escrita latino.** O IVMS 101 exige valores no sistema de escrita latino; translitere nomes que estejam originalmente escritos noutro sistema de escrita. A [correspondência de nomes](#rigor-da-correspondência-de-nomes) do Didit compara conjuntos de tokens normalizados, pelo que diferenças de ordenação e de maiúsculas/minúsculas não inviabilizam uma troca - mas sistemas de escrita diferentes entre ambas as partes irão inviabilizá-la.
* **Envie dados que verificou.** Quando a pessoa por trás de `vendor_data` for um utilizador com uma verificação KYC aprovada no Didit, o Didit transmite a identidade verificada, e não os valores que introduziu: consulte [Dados verificados e proveniência](#dados-verificados-e-proveniência).
  Para qualquer outra pessoa, o Didit transmite exatamente o `originator_data` que enviar, pelo que deve construí-lo a partir da identidade que verificou no onboarding, e não a partir de um campo de formulário não verificado.
  É isso que a redação de "informações obrigatórias e **exatas** sobre o ordenante" do GAFI/FATF exige.
  No rail `INTERNAL`, a aplicação do beneficiário também recebe o `subject` que enviou (nome, `vendor_data`, data de nascimento, país e morada) como a contraparte da sua transação recebida.

#### Dados verificados e proveniência

Quando a parte de uma transferência for um dos seus utilizadores, uma pessoa singular com uma verificação KYC aprovada, o Didit constrói esse lado da troca a partir dos dados verificados:

* o ordenante de uma transferência enviada que criar com `POST /v3/transactions/`;
* o beneficiário de uma transferência recebida que reportar com `POST /v3/transactions/`, ou com `POST /v3/travel-rule/inbound/` quando o `holder_vendor_data` da carteira correspondente indicar esse utilizador.

No `POST /v3/transactions/`, ambos aplicam-se a uma transação cujo `transaction_category` seja `travel_rule` enquanto a Travel Rule estiver ativada.

Os nomes verificados, a data e o local de nascimento, o número e o tipo de documento, a morada e o país de residência (a partir dessa morada) têm precedência sobre os valores que enviou. Um campo que a verificação não contenha mantém o seu valor, assim como uma morada completa que tenha enviado quando a verificada não for suficientemente completa para transmissão.

Os `metadata` da transferência, no objeto incorporado `travel_rule` da transação, registam a origem de cada campo e onde os seus valores divergiram:

```json theme={null}
{
  "metadata": {
    "originator_provenance": { "name": "verified", "date_of_birth": "verified", "customer_identification": "caller" },
    "originator_verified_differences": {
      "name": { "caller": "Jane Doe", "verified": "Jane Elizabeth Doe" }
    }
  }
}
```

`*_provenance` mapeia cada campo para `verified` ou `caller`, e `*_verified_differences` lista todos os campos onde enviou um valor diferente do verificado, ignorando maiúsculas/minúsculas, espaçamento e códigos de país de duas ou três letras. Enquanto os dados de uma transferência recebida estiverem [mascarados](#dados-da-contraparte-mascarados), as diferenças são omitidas. O Didit calcula ambos, pelo que cópias destas chaves, ou de `name_match`, que enviar em `travel_rule_details.metadata` são descartadas.

#### Envio direto de IVMS 101

Além dos objetos planos `originator_data` e `beneficiary_data`, o campo `travel_rule_details` (em `POST /v3/transactions/`) e o endpoint `POST /v3/travel-rule/inbound/` aceitam IVMS 101 autêntico:

* um bloco `originator` e um bloco `beneficiary`, com `originatorPersons` ou `beneficiaryPersons` contendo uma `naturalPerson` ou uma `legalPerson`, e `accountNumber`;
* os mesmos blocos dentro de um objeto `ivms101` (ou `IVMS101`);
* uma pessoa IVMS 101, ou um bloco completo, como `originator_data` ou `beneficiary_data`.

Cada lado aceita uma pessoa: uma `naturalPerson`, ou uma `legalPerson`, o que torna a parte uma empresa. Um `originator_data` ou `beneficiary_data` plano não vazio tem precedência sobre um bloco para o mesmo lado.

```json theme={null}
{
  "travel_rule_details": {
    "status": "AWAITING_COUNTERPARTY",
    "beneficiary": {
      "beneficiaryPersons": [
        {
          "naturalPerson": {
            "name": { "nameIdentifier": [{ "primaryIdentifier": "Ruiz", "secondaryIdentifier": "Carlos", "nameIdentifierType": "LEGL" }] }
          }
        }
      ],
      "accountNumber": ["0xBeneficiaryWallet01"]
    }
  }
}
```

Um bloco malformado devolve uma resposta `400` identificada pelo seu caminho, por exemplo `{"travel_rule_details": {"originator.originatorPersons": ["must be a non-empty list of originator persons."]}}`. No `POST /v3/travel-rule/inbound/`, as mesmas chaves situam-se no nível raiz, sob `ivms101.` quando utilizou o invólucro.

#### Dados obrigatórios por regime

Enquanto a Travel Rule estiver ativada, uma transferência enviada de valor igual ou superior ao seu limiar deve incluir o que o respetivo regime exige, caso contrário responderá com `400`. Apenas os lados enviados são verificados, os dados verificados contam para o ordenante e os erros situam-se sob `travel_rule_details.originator_data` ou `travel_rule_details.beneficiary_data`, por exemplo `"EU TFR requires the originator name."` ou `"FATF Recommendation 16 requires the beneficiary wallet address."`:

| Regime | Ordenante | Beneficiário |
| - | - | - |
| EU TFR (a sua `jurisdiction` é um Estado-Membro da UE, Islândia, Listenstaine, Noruega, `EU` ou `EEA`; `EU` é a predefinição) | O nome, mais a morada, o número do documento oficial e o número de identificação do cliente em conjunto, ou a data e o local de nascimento. Uma empresa não dispõe da alternativa de nascimento. | Nome e endereço |
| FATF Recommendation 16 (todas as outras jurisdições, incluindo uma em branco) | O nome, mais um entre a morada, o número do documento oficial ou o número de identificação do cliente, ou a data e o local de nascimento em conjunto. Uma empresa não dispõe da alternativa de nascimento. | Nome e endereço |

Para o ordenante, a validação lê os campos que a sua aplicação partilha em [`data_sharing_fields`](#partilha-de-dados), pois são apenas esses que um rail envia; o beneficiário é verificado tal como o enviou. Quando a transferência cumpre o regime apenas através de um campo que não partilha, o erro `400` indica o requisito do regime seguido dos campos que as suas definições partilham.

O número do documento oficial é `national_id` (ou `document_number`), o número de identificação do cliente é `customer_identification` (ou `vendor_data`), e a data de nascimento é `date_of_birth`. Um `beneficiary_data.wallet_address` vazio é preenchido a partir de `counterparty.payment_method.account_id` antes da validação, e um levantamento UTXO cujo output do beneficiário o Didit inferiu a partir de `travel_rule_details.utxo` conta como incluindo esse dado. Uma transferência Lightning à qual a Travel Rule não se aplica não é verificada.

### Travel addresses

Um **Travel Address** é uma cadeia compacta e codificada que aponta para o endpoint de consulta `TRP` de entrada de um VASP - nunca expõe um URL em bruto nem qualquer endereço de carteira.
Assim que a Travel Rule estiver ativada, a Didit deriva o seu próprio `travel_address` (devolvido em modo só de leitura nas definições) para que o possa partilhar com outros VASP que o contactem através do carril `TRP`.
Cada uma das suas próprias carteiras do livro de endereços também recebe um `receiving_travel_address` por carteira: uma consulta enviada para o mesmo identifica essa carteira, pelo que a Didit não precisa de a procurar pelo número de conta ou nome do titular.
O host TRP público da Didit ainda não responde a outros VASP, pelo que a receção através do `TRP` não está disponível até que o faça: consulte [Redes da Travel Rule](https://docs.didit.me/pt/transaction-monitoring/travel-rule-networks.md).
Quando souber o Travel Address de uma contraparte, guarde-o na [entrada do livro de endereços de carteiras](#livro-de-endereços-de-carteiras) de destino para que a Didit encaminhe diretamente através de `TRP` as transferências desse beneficiário em vez de recorrer ao e-mail.
A Didit valida os Travel Addresses que guarda numa entrada do livro de endereços de carteiras ou que envia em `originating_vasp`: cada um deve começar por `ta` e descodificar-se num URL de consulta com `t=i`, pelo que um marcador de posição como `ta...` devolve `400`.
O campo `beneficiary_data.travel_address` numa transação não é validado: se não puder ser descodificado, o carril `TRP` é ignorado.

A codificação é Base58Check com um prefixo `ta`: o host e caminho do endpoint (que inclui sempre o par de consulta `t=i`) mais uma soma de verificação double-SHA-256 de quatro bytes, codificada em base58.
Um endereço real tem, portanto, o seguinte aspeto e tem cerca de 100 carateres:

```text theme={null}
ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx
```

Nos casos em que a Didit valida um Travel Address, um valor que não seja um endereço bem formatado e com soma de verificação válida devolve `400` com `"Invalid travel address."`.
Obtenha um endereço real a partir da resposta às suas próprias definições ou diretamente da contraparte.

## Testar sem credenciais de rede

Não precisa de uma adesão à GTR, TRUST, VerifyVASP ou Sygna para testar os caminhos sem adesão. Continua a necessitar de uma chave de API da Didit para a aplicação em teste.

* **Saída em sandbox:** envie uma transação `travelRule` a partir de uma aplicação de sandbox. Após as verificações de limiar e de carteira autocustodiada, o [Didit Test VASP](https://docs.didit.me/pt/transaction-monitoring/travel-rule-sandbox.md) responde dentro da Didit com o cenário que escolher com base na carteira ou no nome do beneficiário: aceitar, recusar, divergência de nome, inacessível, tempo limite excedido ou autocustodiada. Nenhuma rede, e-mail ou outro cliente da Didit recebe o que quer que seja.
* **Entrada em sandbox:** faça com que o VASP de teste lhe envie uma transferência com [Trigger Test VASP Inbound Transfer](https://docs.didit.me/pt/management-api/travel-rule/trigger-test-vasp-inbound.md), ou registe uma por conta própria com [Register Inbound Travel Rule Transfer](https://docs.didit.me/pt/management-api/travel-rule/register-inbound.md). Teste uma carteira desconhecida, uma carteira não verificada, uma divergência no nome do beneficiário e uma carteira correspondente verificada. Isto permite testar decisões de entrada reais sem contactar uma rede.
* **Duas aplicações de produção controladas:** utilize o carril `INTERNAL` entre duas das suas próprias aplicações de produção (a recetora é detetável e comprova o controlo da carteira de destino com uma mensagem assinada ou um depósito de teste), ou uma contraparte TRP controlada, para testar uma troca entre duas partes sem credenciais de redes comerciais. As aplicações de produção podem incorrer em cobranças e notificações normais; utilize identidades de teste e contrapartes que controle.

Consulte [Testar a Travel Rule em sandbox](https://docs.didit.me/pt/transaction-monitoring/travel-rule-sandbox.md) para conhecer todos os cenários e o respetivo resultado exato. Os testes bem-sucedidos em sandbox ou de protocolo local não validam as credenciais, a adesão ou a interoperabilidade em produção de uma rede comercial. Estes requerem uma sandbox de rede autorizada ou uma troca controlada em produção com credenciais de adesão válidas.

## Enviar uma transferência

Inclua a transferência em [`POST /v3/transactions/`](https://docs.didit.me/pt/transaction-monitoring/transactions) definindo `transaction_category` como `travelRule` (ou `travel_rule`) e anexando um objeto `travel_rule_details` (alias: `travelRule`).

O bloco `travel_rule_details` em si é opcional, mas depois de o anexar, `travel_rule_details.status` é obrigatório: um bloco sem este campo devolve `400`.
Quando a Travel Rule está **ativada** para a sua aplicação, a Didit ignora o valor de `status` que enviar e gere a troca por si própria:

1. Se o montante for inferior ao seu `threshold_amount` configurado, a transferência resolve-se imediatamente para `NOT_APPLICABLE` e nada é negociado.
2. Se o método de pagamento da contraparte declarar o destino como uma carteira autocustodiada (`payment_method.method_type: "unhosted_wallet"`), nenhum canal é tentado - a transferência avança diretamente para `UNCONFIRMED_OWNERSHIP` e o widget de propriedade da carteira é gerado automaticamente (consulte [Carteiras autocustodiadas declaradas](#carteiras-autocustodiadas-declaradas)).
3. Caso contrário, os canais são executados por ordem de prioridade, e o primeiro que conseguir alcançar a contraparte processa a troca:
   * `INTERNAL` - exatamente um outro cliente da Didit possui uma prova por mensagem assinada ou depósito de teste para `beneficiary_data.wallet_address`, realizada após a carteira ter mudado de titular pela última vez. A sua própria aplicação nunca conta e, quando o seu utilizador final tiver selecionado um membro da rede Didit no [widget de propriedade da carteira](https://docs.didit.me/pt/transaction-monitoring/wallet-ownership-widget.md), apenas a prova desse membro é considerada. A aplicação desse cliente está em produção (não sandbox), tem a Travel Rule ativada e `is_discoverable` definido, e é o VASP que indicou ao enviar `counterparty_vasp_lei` ou `counterparty_vasp_name`. Uma carteira que seja apenas autodeclarada, comprovada por captura de ecrã, não verificada ou apenas listada num livro de endereços nunca recebe nada através de `INTERNAL`.
   * `TRP` - o ativo da transferência tem um mapeamento de identificador de token digital para a rede da transferência (consulte [Identificadores de ativos TRP](#identificadores-de-ativos-trp)), e o payload contém `beneficiary_data.travel_address`, a própria entrada de livro de endereços do destino armazena um, ou a contraparte é resolvida no [diretório](#diretório) (por `counterparty_vasp_lei` ou `counterparty_vasp_name`) com um endpoint TRP.
   * `GTR`, `TRUST`, `VERIFYVASP`, `SYGNA` - ligou a sua própria adesão a essa rede no **Marketplace**, e a contraparte resolve-se para um ID de rede (campo explícito ou entrada no diretório - consulte [Campos de resolução da contraparte](#campos-de-resolução-da-contraparte)).
     A Didit ainda não possui adesão de plataforma nestas redes (está em onboarding como fornecedor), pelo que `disabled_networks` não altera este passo atualmente.
   * `EMAIL` - `beneficiary_data.counterparty_vasp_email` foi fornecido, ou `counterparty_vasp_name` é resolvido para uma entrada no diretório com um e-mail de conformidade.
4. Se nenhum canal conseguir resolver uma contraparte, a Didit executa a cadeia de [descoberta de contrapartes](#descoberta-de-contrapartes). Com `vasp_attribution_enabled` ativado, isso inclui a [atribuição por análise de blockchain](#atribuição-por-análise-de-blockchain): a carteira de destino é resolvida para o respetivo VASP proprietário, o nome atribuído é gravado em `beneficiary_data.counterparty_vasp_name` (quando vazio) e no [diretório](#diretório), e os canais são executados novamente uma vez - assim, uma carteira atribuída a um VASP cuja entrada no diretório contenha um endpoint TRP, ID de rede ou e-mail de conformidade é encaminhada nesta segunda passagem.
5. Se a contraparte continuar por resolver, a transferência passa para `COUNTERPARTY_VASP_NOT_FOUND`. Em transferências de saída, a Didit gera automaticamente o [widget de propriedade da carteira](https://docs.didit.me/pt/transaction-monitoring/wallet-ownership-widget.md) (quando `auto_wallet_verification` estiver ativado) para que a transferência ainda possa ser concluída como uma transferência para carteira autocustodiada, e pode voltar a executar o encaminhamento mais tarde com `action: "resend"` assim que tiver melhores dados da contraparte.

Os passos 1 e 2 ocorrem dentro do pedido. Os passos 3 a 5 são executados logo após a resposta: a transferência regressa com `AWAITING_COUNTERPARTY` e `protocol: null`, e cada resultado chega como um webhook [`travel_rule.status.updated`](#webhooks).

### Identificadores de ativos TRP

O `TRP` identifica o ativo transferido pelo seu Identificador de token digital (DTI) ISO 24165.
Um DTI identifica um token numa blockchain, pelo que um token multicadeia possui um DTI por rede.

A Didit envia transferências através de `TRP` para estes ativos:

| Ativo | Rede | DTI |
| - | - | - |
| `BTC` | Bitcoin | `4H95J0R2X` |
| `ETH` | Ethereum | `X9J9K872S` |
| `USDC` | Ethereum | `CK9PW1MFH` |
| `USDC` | Celo | `2ZTG3NNVB` |
| `USDC` | Base | `CP6817N4B` |
| `USDC` | Optimism | `898NNTPZJ` |
| `USDC` | Arbitrum One | `4ZSZS1F4F` |
| `USDC` | Polygon PoS | `LS71LQK3L` |
| `USDC` | Avalanche C-Chain | `45J6XJX7H` |
| `USDC` | Solana | `5R3XFPZSM` |
| `USDC` | Plume | `N064ZKXDM` |

Os identificadores do `USDC` são os que o emissor do token publica no seu livro branco do MiCA.

Para um token multicadeia, a transferência tem de indicar a sua rede em `transaction_details.crypto_params.crypto_chain` (por exemplo `CELO`, `BASE`, `OP`, `ARB` ou `POL`).
Sem uma rede, ou numa rede sem mapeamento, a transferência não é enviada através de `TRP` e a Didit tenta os canais restantes: primeiro as redes de interoperabilidade e, em seguida, o e-mail.

O `USDT` ainda não está mapeado.
Um token sem mapeamento de DTI, tal como a stablecoin de uma própria empresa, requer que o seu emissor registe um DTI junto da autoridade de registo ISO 24165, um por token por blockchain.
Assim que os DTI existirem, contacte o suporte da Didit com cada DTI, a respetiva blockchain e as casas decimais do token, e a Didit adicionará o mapeamento.

Os pedidos de informação de `TRP` recebidos que incluam um DTI mapeado por cadeia são registados com a moeda do token, o montante nas casas decimais do token e a rede.

### Descoberta de contrapartes

Uma transferência que contenha apenas um endereço de carteira continua a alcançar a sua contraparte sempre que alguém conseguir identificar esse endereço.
Antes de uma transferência de saída ser declarada não encaminhável, a Didit consulta, por esta ordem, e interrompe no primeiro passo que indique um VASP com uma rota:

| Passo | O que faz |
| - | - |
| `internal_address_book` | Outro cliente da Didit comprovou o controlo da carteira (uma assinatura ou um depósito de teste), pelo que o canal `INTERNAL` entrega a transferência a esse cliente. Uma entrada no livro de endereços não comprovada nunca é contabilizada. |
| `wallet_attribution` | A atribuição por análise de blockchain da carteira, associada a um VASP do diretório com uma rota. Um resultado armazenado é reutilizado e a cobrança é feita apenas uma vez. Requer `vasp_attribution_enabled`. |
| `network_lookup` | Uma rede de Travel Rule que responde a "a quem pertence este endereço", quando a sua aplicação tem acesso a ela. Apenas a GTR oferece isto hoje, e é executada quando a via GTR efetua o envio. Caso contrário, o passo é registado como `skipped` com o respetivo motivo. |
| `customer_hint` | O nome da VASP, LEI ou jurisdição que indicou em `beneficiary_data`, associado a uma VASP do diretório com uma rota. Um `travel_address` ou e-mail de conformidade é contactado através da sua própria via. |
| `end_user` | Ninguém indicou a contraparte, pelo que é perguntado ao utilizador final. Consulte abaixo. |

O campo `discovery` da transferência lista cada passo executado com o respetivo `outcome` (`match`, `miss` ou `skipped`), um `reason` legível por máquina, a `vasp` e a `rail` encontradas, e um carimbo de data/hora.
Uma VASP selecionada por si ou pelo utilizador final tem prioridade sobre qualquer passo automático: a descoberta nunca a substitui pela sua própria estimativa.

Quando nenhum passo identifica uma contraparte, a transferência passa para `COUNTERPARTY_VASP_NOT_FOUND`, ou `COUNTERPARTY_VASP_NOT_REACHABLE` quando uma VASP foi identificada mas nenhuma das suas rotas está disponível para a sua aplicação.
A transferência inclui então um `reason` (`awaiting_end_user`, `no_directory_match`, `directory_match_no_route`, ou `picked_member_without_proven_wallet` quando o membro selecionado pelo utilizador final não comprovou a carteira) e uma lista de `next_actions`:

| `action` | Significado |
| - | - |
| `select_counterparty_vasp` | O utilizador final seleciona a VASP de destino no [widget de carteira](https://docs.didit.me/pt/transaction-monitoring/wallet-ownership-widget.md), ou você mesmo indica-a com `{"action": "beneficiary_vasp", "beneficiary_vasp": "<directory VASP id>"}` no [endpoint de transferência](#enviar-uma-transferência). A transferência é encaminhada para essa VASP e enviada novamente. |
| `declare_self_hosted` | O utilizador final declara a carteira como autocustodiada no mesmo widget. |
| `add_vasp_hint` | Envie o nome de uma VASP, LEI ou `travel_address` em `beneficiary_data`, e depois reenvie. |
| `update_compliance_email` | Indique novamente o e-mail de conformidade da contraparte quando o primeiro foi recusado; consulte [Porque é que uma transferência está bloqueada](#por-que-motivo-uma-transferência-está-bloqueada). |
| `resend` | Execute a descoberta novamente com as alterações efetuadas. |

A ligação do widget é o `url` nas ações que o utilizador final executa.
Quando uma ação de propriedade da carteira está pendente, o bloco `action_required` da transação (do tipo `wallet_ownership`) contém o mesmo `reason` e `next_actions`, para que um cliente que já processe `action_required` mostre o seletor sem trabalho adicional.

### Campos de resolução da contraparte

Tudo o que a Didit sabe sobre a contraparte provém de `travel_rule_details.beneficiary_data`.
Estes campos determinam a resolução da via; todos são opcionais:

| Campo | Determina |
| - | - |
| `wallet_address` | Correspondência no livro de endereços `INTERNAL`, pesquisa no livro de endereços `TRP` e os fluxos de propriedade da carteira. Quando omitido, a Didit utiliza `counterparty.payment_method.account_id`. |
| `chain` | Delimita ambas as pesquisas no livro de endereços: uma entrada corresponde apenas quando o seu `chain` for igual a este valor (insensível a maiúsculas/minúsculas) ou a entrada não tiver `chain`. Quando omitido, a Didit preenche-o a partir de `transaction_details.crypto_params.crypto_chain`, `custom_properties.crypto_chain` ou da moeda da transferência, em maiúsculas, mas apenas quando esse valor for uma blockchain reconhecida pela Didit (por exemplo `ETH`, `BTC`, `SOL`, `TRX`); caso contrário, a transferência não tem blockchain associada e corresponde a entradas em qualquer blockchain. Para uma transferência de `USDT` ou `USDC` sem blockchain explícita, a Didit infere-a a partir do hash da transação em `transaction_details.payment_reference_id` (um hash `0x` resulta em `ETH`). |
| `memo` | A tag de destino ou memo de `wallet_address` numa rede com memo. Faz parte da carteira sempre que `wallet_address` seja correspondido (consulte [Redes de memo e tag](#redes-com-memo-e-tag)). Alias: `destinationTag`. |
| `travel_address` | Encaminha diretamente através de `TRP` - o sinal mais forte que pode passar. |
| `counterparty_vasp_lei` | Pesquisa no diretório por LEI para `TRP`, `GTR`, `TRUST`, `VERIFYVASP` e `SYGNA`. Também verificado contra a identidade reportada pelo endpoint TRP - uma divergência, ou uma identidade sem LEI, aborta a troca como `COUNTERPARTY_VASP_NOT_REACHABLE`. |
| `counterparty_vasp_name` | Pesquisa no diretório para `TRP`, `GTR`, `TRUST`, `VERIFYVASP`, `SYGNA` e `EMAIL`: o nome exato, o mesmo nome escrito de outra forma (`B.V.` em vez de `BV`, um acento), e depois um alias de uma entrada. Comparação aproximada com a identidade TRP quando ambas estiverem presentes. |
| `counterparty_vasp_jurisdiction` | Código de país ISO 3166 da entidade recetora quando a VASP indicada for uma marca com várias entidades reguladas, ou quando várias entradas do diretório partilharem o nome - consulte [Marcas e as respetivas entidades](#marcas-e-as-respetivas-entidades). |
| `counterparty_gtr_vasp_code` | ID de rede `GTR` explícito - ignora o diretório. |
| `counterparty_trust_membership_id` | ID de rede `TRUST` explícito - ignora o diretório. |
| `counterparty_verifyvasp_id` | ID de rede `VerifyVASP` explícito - ignora o diretório. |
| `counterparty_sygna_vasp_code` | Código de VASP `Sygna Bridge` explícito - ignora o diretório. |
| `counterparty_vasp_email` | Contacto de conformidade explícito para a via `EMAIL` - ignora o diretório. |

### Estruturas de blockchain

Numa blockchain baseada em contas (blockchains EVM, Solana, Tron), uma transferência move fundos de um endereço para outro, e a Didit lê ambas as carteiras diretamente da transação.
Três outras estruturas exigem mais detalhes, e o que a Didit determinou para elas está na transferência como `chain_details` (vazio, `{}`, numa blockchain baseada em contas).
`chain_details.originator` e `chain_details.beneficiary` contêm, cada um, o `address`, o respetivo `memo` e a `source` de onde veio, e a correspondência e o encaminhamento leem as carteiras a partir daí em primeiro lugar.

#### Transferências UTXO

Uma transação de Bitcoin, Litecoin, Bitcoin Cash ou Dogecoin gasta inputs de qualquer número de endereços e paga qualquer número de outputs, sendo alguns deles o troco devolvido ao remetente.
Envie os inputs e outputs como `travel_rule_details.utxo` (valores na própria unidade da moeda, como cadeias de caracteres decimais), e a Didit deduz o que não declarar:

* **Ordenante**: `originator_data.wallet_address` quando o envia, caso contrário o endereço de input que mais contribuiu (`source: largest_input`).
* **Beneficiário**: a carteira declarada, caso contrário o único output que não devolve troco a um endereço de input (`only_non_change_output`), caso contrário o output que paga o valor da transferência (`amount_match`).

```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": "btc-withdrawal-0042",
    "transaction_category": "travelRule",
    "transaction_details": {
      "direction": "outbound",
      "amount": "0.25",
      "currency": "BTC",
      "currency_kind": "crypto"
    },
    "subject": { "vendor_data": "user-042", "full_name": "Ana Diaz" },
    "counterparty": { "full_name": "Luis Perez" },
    "travel_rule_details": {
      "status": "AWAITING_COUNTERPARTY",
      "beneficiary_data": { "name": "Luis Perez", "counterparty_vasp_name": "Destination Exchange" },
      "utxo": {
        "inputs": [
          { "address": "bc1qsenderhotwallet01", "amount": "0.30" },
          { "address": "bc1qsendercoldwallet02", "amount": "0.05" }
        ],
        "outputs": [
          { "address": "bc1qbeneficiarydeposit01", "amount": "0.25" },
          { "address": "bc1qsenderhotwallet01", "amount": "0.0999" }
        ]
      }
    }
  }'
```

A transferência passa então a incluir:

```json theme={null}
{
  "chain_details": {
    "chain": "BTC",
    "shape": "utxo",
    "originator": { "address": "bc1qsenderhotwallet01", "memo": "", "source": "largest_input" },
    "beneficiary": { "address": "bc1qbeneficiarydeposit01", "memo": "", "source": "only_non_change_output" },
    "utxo": {
      "inputs": [
        { "address": "bc1qsenderhotwallet01", "amount": "0.300000000000000000" },
        { "address": "bc1qsendercoldwallet02", "amount": "0.050000000000000000" }
      ],
      "outputs": [
        { "address": "bc1qbeneficiarydeposit01", "amount": "0.250000000000000000" },
        { "address": "bc1qsenderhotwallet01", "amount": "0.099900000000000000" }
      ],
      "change_output_indexes": [1],
      "beneficiary_output_index": 0
    }
  }
}
```

`chain_details.warnings` sinaliza o que não coincide: `declared_originator_not_an_input`, `declared_beneficiary_not_an_output`, `beneficiary_output_ambiguous` (não foi possível distinguir uma saída única) e `beneficiary_output_amount_differs`.
`utxo` em qualquer outra blockchain devolve um `400`, e cada lista contém no máximo 1,000 entradas.
Um depósito comunicado aceita o mesmo objeto `utxo` (consulte [Registo sunrise após depósito](#registo-sunrise-posterior-ao-depósito)).

#### Redes com memo e tag

No XRP, Stellar (XLM), EOS, Cosmos (ATOM) e Hedera (HBAR), uma exchange recebe todos os clientes num único endereço partilhado e distingue-os através da tag de destino ou memo.
O memo faz, por isso, parte da carteira: envie-o como `payment_method.memo` no participante, ou como `memo` em `originator_data` / `beneficiary_data` (alias `destinationTag`), e a Didit compara o endereço e o memo em conjunto.

* Uma entrada do livro de endereços com um memo corresponde apenas a transferências que indiquem esse memo. Uma entrada sem memo corresponde a todo o endereço. Uma transferência que não indique qualquer memo nunca chega a uma entrada que tenha um: num endereço partilhado, um depósito sem a sua tag não pertence a ninguém.
* Um X-address do XRP inclui a sua tag no próprio endereço: a Didit divide-o no endereço clássico e na tag (`source: x_address`), pelo que uma carteira registada em qualquer um dos formatos corresponde a uma transferência no outro.
* Cada memo num endereço partilhado é o seu próprio método de pagamento na transação.
* O que cada rede aceita: uma tag de destino do XRP é um número inteiro de 0 a 4294967295 (um número em formato JSON é aceite); um memo da Stellar tem até 28 bytes de texto, um id de 64 bits ou um hash de 32 bytes em hexadecimal; a EOS aceita até 256 bytes, a Cosmos até 256 carateres e a Hedera até 100 bytes. Um memo numa blockchain que não os suporte (Bitcoin, blockchains EVM, Solana, Tron, Litecoin, Bitcoin Cash, Dogecoin, Lightning) devolve um `400`.

#### Lightning

Um pagamento Lightning não possui um endereço de beneficiário on-chain: o pagador detém um pedido de pagamento.
Numa transferência cripto de bitcoin ou Lightning, `payment_method.account_id` pode ser esse pedido, e a Didit identifica o beneficiário a partir dele sem contactar nenhuma rede:

| O que envia | Beneficiário |
| - | - |
| Fatura BOLT11 (`lnbc...`) | O nó do destinatário, indicado na fatura ou recuperado a partir da sua assinatura. |
| Oferta ou fatura BOLT12 (`lno1...`, `lni1...`) | O nó emissor, exceto se estiver oculto por caminhos cegos. |
| Endereço Lightning (`name@domain`) | O próprio endereço. |
| ID do nó | O próprio nó. |
| LNURL (`lnurl1...`, `lnurlp://`) | Nenhum: indica um serviço, não um destinatário. |

O destinatário é armazenado como a conta e como `chain_details.beneficiary` (`source: invoice_payee`), na blockchain `LIGHTNING`, e o que o pedido indica é colocado em `chain_details.lightning`.
Quando o pedido não indica nenhum destinatário, uma transferência de saída fica como `NOT_APPLICABLE` com o motivo indicado em `chain_details.not_applicable_reason` e na sua `timeline`: `LIGHTNING_NO_PAYEE_IDENTIFIER`, `LIGHTNING_BOLT12_BLINDED_PAYEE` ou `LIGHTNING_LNURL_NAMES_NO_PAYEE`.
Um valor só é interpretado como Lightning em bitcoin, em `LIGHTNING` ou quando nenhuma blockchain é indicada (um endereço Lightning apenas em bitcoin ou `LIGHTNING`): em qualquer outra blockchain, é interpretado como o próprio endereço dessa blockchain.

> [!NOTE]
>
> O canal `INTERNAL` só alcança outro cliente da Didit através de uma carteira que esse cliente tenha provado que controla com uma mensagem assinada ou um depósito de teste, e essas provas existem atualmente para Bitcoin, blockchains EVM, Solana e Tron.
> Em redes com memo, Lightning, Litecoin, Bitcoin Cash e Dogecoin, uma transferência, por conseguinte, nunca alcança outro cliente da Didit através de `INTERNAL`.
> A correspondência de memo, tag e Lightning continua a aplicar-se ao seu próprio livro de endereços: transferências recebidas, depósitos comunicados e consultas `TRP` às suas carteiras.

### Atualizar a carteira do ordenante

Um levantamento é frequentemente declarado a partir da carteira principal do seu cliente e transmitido a partir dos endereços que continham as moedas.
Registe a carteira de onde os fundos efetivamente saíram com `PATCH /v3/transactions/{transaction_id}/travel-rule/`:

```bash theme={null}
curl -X PATCH "https://verification.didit.me/v3/transactions/$TRANSACTION_ID/travel-rule/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "update_originator_wallet", "wallet_address": "bc1qsendercoldwallet02" }'
```

* Apenas transferências de saída, e nunca transferências `CANCELLED` ou `EXPIRED` (`409`).
* Quando as entradas UTXO da transferência são conhecidas, a carteira tem de ser uma delas (caso contrário, `400`). Numa rede com memo, envie também `memo`.
* Altera apenas o registo: nada é reenviado para a contraparte e o estado mantém-se. `chain_details.originator` passa a ser a nova carteira com `source: updated`, a `timeline` regista a carteira anterior e a nova carteira, e a contraparte `INTERNAL` da transferência é atualizada da mesma forma.

### Atribuição por análise de blockchain

Quando fornece apenas um endereço de carteira, a Didit consegue, ainda assim, descobrir quem está do outro lado.
Se nenhum canal conseguir encaminhar a transferência, a Didit resolve a carteira de destino consultando os dados de atribuição de análise de blockchain - a mesma análise que suporta a [triagem de transações de cripto](https://docs.didit.me/pt/transaction-monitoring/aml-screening.md) sabe quais carteiras pertencem a que exchanges e custodiantes.
A atribuição é executada apenas em transferências de saída que incluam tanto uma carteira de destino como uma `chain` (consulte [Campos de resolução da contraparte](#campos-de-resolução-da-contraparte)); sem uma blockchain indicada, a atribuição é ignorada.

Quando a carteira é atribuída a uma entidade conhecida, a Didit:

1. Regista a atribuição na transferência: `beneficiary_data.counterparty_vasp_name` é preenchido (caso não tenha fornecido um), e os metadados da transferência passam a incluir um bloco `vasp_attribution` com o nome da entidade, o tipo de entidade, o país e `source: "blockchain_analytics"`.
2. Adiciona a entidade ao [diretório de VASPs](#diretório) (ou faz a correspondência com a entrada existente), para que a atribuição seja estável entre transferências.
3. Executa novamente os canais com o nome atribuído - uma entrada no diretório que já contenha um endpoint TRP faz com que a transferência seja imediatamente encaminhada em vez de terminar em `COUNTERPARTY_VASP_NOT_FOUND`.

A chamada de atribuição funciona também como uma triagem completa de cripto: a transação recebe o resultado completo da triagem - pontuação de risco, categoria de risco da carteira, instantâneo da rede - exatamente como se a monitorização de cripto tivesse sido executada, e `custom_values.aml_screening_trigger` da transação é definido como `travel_rule_attribution` para que possa verificar que a triagem foi executada porque o encaminhamento da Travel Rule a exigiu.
Quando a monitorização de cripto já tiver analisado a mesma carteira nesta transação, o resultado armazenado é reutilizado - sem uma segunda chamada à análise e sem uma segunda cobrança.
A atribuição nunca bloqueia a criação da transação: se a consulta analítica falhar ou o seu saldo não a puder cobrir, a transferência simplesmente avança para `COUNTERPARTY_VASP_NOT_FOUND` e nada é cobrado pela tentativa.
Em `action: "resend"`, uma atribuição registada anteriormente é reutilizada em vez de ser consultada de novo.

Desative todo o passo com `vasp_attribution_enabled: false` nas [definições](#configuração).
Consulte [Preços](#preços) para saber como a chamada de atribuição é faturada.

Quando a Travel Rule está **desativada**, o objeto `travel_rule_details` (incluindo um `status` fornecido pelo autor da chamada, legado ou atual) continua a ser registado na transação, mas passivamente - nenhuma via (rail) é acionada.
Utilize isto para preencher retroativamente dados de conformidade que já monitorizou através do seu próprio processo.
Uma transferência passiva de saída não inicia qualquer troca, pelo que é faturada como Triagem de Transações, e não na [linha da Travel Rule](#preços).

Com a Travel Rule ativada, este pedido é encaminhado através da via `EMAIL`, porque indica o e-mail de conformidade da contraparte e nenhuma via anterior consegue alcançar o beneficiário:

```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": "trv-2026-07-05-001",
    "transaction_category": "travelRule",
    "transaction_details": {
      "direction": "outbound",
      "action_type": "transfer",
      "amount": "0.25",
      "currency": "ETH",
      "currency_kind": "crypto"
    },
    "subject": {
      "entity_type": "individual",
      "vendor_data": "user-042",
      "full_name": "Jane Doe"
    },
    "travel_rule_details": {
      "status": "AWAITING_COUNTERPARTY",
      "originator_data": {
        "first_name": "Jane",
        "last_name": "Doe",
        "date_of_birth": "1990-04-12",
        "residence_country": "ES",
        "customer_identification": "user-042",
        "wallet_address": "0x135908330861442a814796ae99feac507925782a"
      },
      "beneficiary_data": {
        "wallet_address": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb",
        "name": "Ana Diaz",
        "counterparty_vasp_email": "compliance@bene-casp.example"
      }
    }
  }'
```

A resposta, abreviada para os campos relevantes aqui:

```json theme={null}
{
  "uuid": "22222222-3333-4444-5555-666666666666",
  "txn_id": "trv-2026-07-05-001",
  "transaction_type": "travelRule",
  "direction": "OUTBOUND",
  "status": "APPROVED",
  "amount": "0.25",
  "currency": "ETH",
  "currency_type": "crypto",
  "travel_rule": {
    "uuid": "33333333-4444-5555-6666-777777777777",
    "status": "AWAITING_COUNTERPARTY",
    "protocol": null,
    "required": true,
    "obligations_count": 0,
    "originator_data": {
      "first_name": "Jane",
      "last_name": "Doe",
      "date_of_birth": "1990-04-12",
      "residence_country": "ES",
      "customer_identification": "user-042",
      "wallet_address": "0x135908330861442a814796ae99feac507925782a"
    },
    "beneficiary_data": {
      "wallet_address": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb",
      "name": "Ana Diaz",
      "counterparty_vasp_email": "compliance@bene-casp.example",
      "chain": "ETH"
    },
    "metadata": {
      "compliance_email_source": "caller_supplied"
    }
  },
  "action_required": null
}
```

* `originator_data` corresponde ao que enviou, porque o utilizador do exemplo não tem uma verificação KYC aprovada; para um utilizador verificado, o Didit constrói-o a partir dos dados verificados (consulte [Dados verificados e proveniência](#dados-verificados-e-proveniência)).
  A via `EMAIL` mostra ao destinatário apenas os campos do ordenante que partilhar em [`data_sharing_fields`](#partilha-de-dados).
* `beneficiary_data.chain` é `ETH` porque o pedido não especificou nenhuma cadeia, pelo que o Didit a deduziu a partir da moeda.
* `status` é `APPROVED` porque nenhuma regra atuou sobre a transação; as suas próprias regras podem definir outro estado.
* O contacto de conformidade recebe a ligação de recolha, e a transferência fica concluída, falha na correspondência do nome ou é recusada quando respondem, ou expira se não o fizerem (consulte [Recolha por e-mail](#recolha-por-e-mail-para-contrapartes-inacessíveis)).

O campo `protocol` ainda é `null` porque a via é escolhida após a resposta (por exemplo, `EMAIL` quando indicou `counterparty_vasp_email`): [Obter transação](https://docs.didit.me/pt/management-api/transactions/get.md) mostra-o assim que for escolhido, e cada webhook `travel_rule.status.updated` posterior transporta-o em `rail`.
Se a carteira do beneficiário pertencer a outro cliente Didit que tenha comprovado o controlo da mesma, a via `INTERNAL` liquida toda a troca logo após a resposta, e esse webhook já reporta `COMPLETED` (ou `COUNTERPARTY_MISMATCHED_DATA`). Quando o nome não coincide, a sua transferência fica como `COUNTERPARTY_MISMATCHED_DATA` e o outro cliente não recebe nada.
Sem `counterparty_vasp_email`, e quando nem as vias nem a [atribuição](#atribuição-por-análise-de-blockchain) conseguem alcançar o beneficiário, a transferência termina mais tarde em `COUNTERPARTY_VASP_NOT_FOUND` com uma ação `wallet_ownership` na transação.

> [!NOTE]
>
> O objeto `travel_rule` embutido na transação transporta os campos próprios da transferência (`uuid`, `status`, `protocol`, `required`, `obligations_count`, `originator_data`, `beneficiary_data`, `metadata`), o que o Didit determinou e comparou (`chain_details`, `name_match`, `data_match`, `mismatched_fields`, e os campos de [mascaramento](#dados-da-contraparte-mascarados) `data_masked` e `data_unmasked`), bem como os campos que indicam a sua situação atual: `direction`, `rail`, `counterparty_vasp`, `delivery`, `discovery`, `reason` e `next_actions` (consulte [Por que motivo uma transferência está bloqueada](#por-que-motivo-uma-transferência-está-bloqueada)).
> Cada linha de [`GET /v3/transactions/`](https://docs.didit.me/pt/management-api/transactions/list) transporta o mesmo bloco, ou `null` no caso de uma transação sem transferência.
> Os endpoints dedicados de transferência abaixo também devolvem esses campos, além de `ivms_version`, `ownership_confirmed`, `deadline_at`, `timeline` e `created_at`, mas sem `obligations_count` ou `metadata`.

Para encerrar uma transferência de saída `COMPLETED` após a ter transmitido on-chain:

```bash theme={null}
curl -X PATCH https://verification.didit.me/v3/transactions/22222222-3333-4444-5555-666666666666/travel-rule/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payment_txn_id": "0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060"}'
```

Isto exige que a transferência seja uma transferência de **saída** no estado `COMPLETED` - caso contrário, a API devolve `409`.
Em caso de sucesso, tanto a transferência de saída como a sua contraparte da via `INTERNAL` transitam para `FINISHED`, e o campo `payment_txn_id` da transação é definido com o hash que forneceu.
Na via `TRP`, o Didit também envia o hash para o callback de confirmação da contraparte.

Para cancelar uma transferência que ainda não atingiu um estado terminal, envie, em vez disso, `{"action": "cancel"}` para o mesmo endpoint.
A contraparte da via `INTERNAL` também é cancelada e, na via `TRP`, assim que a contraparte tiver aprovado o pedido de informação, o Didit envia o cancelamento para o respetivo callback de confirmação.
Uma transferência que já esteja em `FINISHED`, `CANCELLED` ou `EXPIRED` devolve `409`.
Um pedido sem `payment_txn_id` nem uma `action` suportada devolve `400`.

Numa transferência efetuada através de `GTR`, `VERIFYVASP` ou `SYGNA`, o Didit comunica o hash on-chain (ou o cancelamento) à rede após a resposta, com as [mesmas tentativas de repetição](#entrega-e-tentativas); o campo `delivery` da resposta mostra essa mensagem.

Para tentar novamente uma transferência de saída que não conseguiu alcançar a respetiva contraparte - uma que esteja atualmente em `COUNTERPARTY_VASP_NOT_FOUND`, `COUNTERPARTY_VASP_NOT_REACHABLE` ou `NOT_ENOUGH_COUNTERPARTY_DATA` - melhore primeiro os dados da contraparte, por exemplo, adicionando um `travel_address` ao registo da carteira de destino, um [contacto](#contactos) ao registo da contraparte no diretório, ou catalogando o VASP no [diretório](#diretório).
Em seguida, envie `{"action": "resend"}` para o mesmo endpoint.
O Didit reinicia o prazo limite de confirmação e coloca novamente a sequência de encaminhamento na fila desde o início, utilizando os dados armazenados na transferência: a resposta mostra a transferência novamente em `AWAITING_COUNTERPARTY` (com `resend queued` na sua `timeline`), e o resultado chega através de um webhook `travel_rule.status.updated`.
Um reenvio submetido enquanto uma tentativa anterior ainda está em execução é enviado assim que essa tentativa for concluída.
Qualquer outro estado, ou uma transferência de entrada, devolve `409`.

```bash theme={null}
curl -X PATCH https://verification.didit.me/v3/transactions/22222222-3333-4444-5555-666666666666/travel-rule/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "resend"}'
```

Para indicar a contraparte manualmente quando a [descoberta](#descoberta-de-contrapartes) não o conseguiu fazer, envie `{"action": "beneficiary_vasp", "beneficiary_vasp": "<directory VASP id>"}` (o `id` obtido a partir de `GET /v3/travel-rule/vasps/`).
A transferência é encaminhada para esse VASP e enviada novamente.
Apenas uma transferência de saída em `COUNTERPARTY_VASP_NOT_FOUND`, `COUNTERPARTY_VASP_NOT_REACHABLE` ou `NOT_ENOUGH_COUNTERPARTY_DATA` a aceita; qualquer outro estado devolve `409`, e um id desconhecido devolve `404`.

### Por que motivo uma transferência está bloqueada

Uma transferência em `COUNTERPARTY_VASP_NOT_FOUND` ou `COUNTERPARTY_VASP_NOT_REACHABLE` indica por que motivo está bloqueada e o que permite desbloqueá-la, em cada consulta da respetiva transação.
O bloco `travel_rule` de [`GET /v3/transactions/{transaction_id}/`](https://docs.didit.me/pt/management-api/transactions/get), da resposta `201` de [`POST /v3/transactions/`](https://docs.didit.me/pt/management-api/transactions/create), e de cada linha de [`GET /v3/transactions/`](https://docs.didit.me/pt/management-api/transactions/list) inclui essa informação, assim como o objeto de transferência devolvido pelo [endpoint de transferência](https://docs.didit.me/pt/management-api/travel-rule/update-transfer.md):

* `reason` é a causa legível por máquina, `""` para qualquer outro estado.
* `next_actions` lista o que faz a transferência avançar, `[]` para qualquer outro estado.
* `delivery` é a mensagem mais recente que a transferência deve ao outro lado: `kind`, `status` (`QUEUED`, `SENDING`, `RETRYING`, `DELIVERED` ou `FAILED`), `rail`, `attempts`, `last_error`, `next_attempt_at` e `delivered_at`, ou `null` quando não tiver nenhuma mensagem pendente.
* `discovery` indica onde a Didit procurou a contraparte, uma entrada por passo executado: `step`, `outcome` (`match`, `miss` ou `skipped`), `reason`, `vasp`, `rail` e `at`.

`email_undeliverable` e `delivery_failed` resultam de uma falha de entrega e aparecem apenas em `COUNTERPARTY_VASP_NOT_REACHABLE`.
Uma falha de entrega define `reason` primeiro, pelo que uma contraparte que a Didit tenha encontrado nunca é reportada como uma que não conseguiu encontrar.
Os outros quatro resultam do rastreio de descoberta, em qualquer um dos estados.

| `reason` | O que aconteceu | `next_actions` |
| - | - | - |
| `email_undeliverable` | O fornecedor de e-mail recusou o e-mail de conformidade e já não restam endereços por tentar: quando foi enviado, num lembrete ou como devolução permanente reportada posteriormente. | `update_compliance_email`, depois `resend` |
| `delivery_failed` | O rail que estava a entregar falhou em definitivo: um rail de rede recusou a mensagem ou esgotou as tentativas, um anfitrião de identidade `TRP` não respondeu ou o anfitrião `TRP` da contraparte não aceitou a consulta. | `resend` |
| `awaiting_end_user` | Nenhum passo de descoberta identificou uma contraparte que a Didit consiga contactar, pelo que é pedido ao utilizador final que a indique. | `select_counterparty_vasp`, `declare_self_hosted`, `add_vasp_hint`, `resend` |
| `directory_match_no_route` | Um passo identificou uma entrada do [diretório](#diretório), mas essa entrada não tem nenhuma rota que a Didit possa utilizar em seu nome. | Igual a `awaiting_end_user` |
| `picked_member_without_proven_wallet` | O utilizador final selecionou outro cliente da Didit como contraparte, mas esse cliente não comprovou o controlo da carteira. | Igual a `awaiting_end_user` |
| `no_directory_match` | O rastreio de descoberta não fornece nenhum outro motivo. | Igual a `awaiting_end_user` |

| Ação seguinte | O que fazer |
| - | - |
| `update_compliance_email` | Forneça novamente o e-mail de conformidade da contraparte, com `{"action": "update_compliance_email", "compliance_email": "..."}` no endpoint de transferência. |
| `resend` | Execute novamente o encaminhamento com `{"action": "resend"}` assim que algo tiver mudado. |
| `select_counterparty_vasp` | O utilizador final escolhe o VASP de destino no [widget de propriedade da carteira](https://docs.didit.me/pt/transaction-monitoring/wallet-ownership-widget.md). `url` é a ligação do widget enquanto a transferência tiver uma sessão de widget aberta. |
| `declare_self_hosted` | O utilizador final declara a carteira como autocustodiada no widget, no mesmo `url`. |
| `add_vasp_hint` | Indique à Didit quem é a contraparte, com um nome de VASP, LEI ou Travel Address (por exemplo, um `travel_address` na [entrada do livro de endereços](#livro-de-endereços-de-carteiras) da carteira de destino) e, em seguida, reenvie. |

Um reenvio faz a transferência avançar, pelo que o respetivo `reason` deixa de estar definido.
A entrada na cronologia de uma transição causada por uma falha de entrega apresenta o mesmo valor em `reason`.

Se o fornecedor de e-mail recusar o e-mail de conformidade da [transferência de exemplo acima](#enviar-uma-transferência), o bloco `travel_rule` da respetiva transação apresentará, de forma abreviada:

```json theme={null}
{
  "uuid": "33333333-4444-5555-6666-777777777777",
  "status": "COUNTERPARTY_VASP_NOT_REACHABLE",
  "protocol": "EMAIL",
  "direction": "OUTBOUND",
  "rail": "EMAIL",
  "counterparty_vasp": null,
  "delivery": {
    "kind": "SEND",
    "status": "FAILED",
    "rail": "EMAIL",
    "attempts": 1,
    "last_error": "email undeliverable",
    "next_attempt_at": null,
    "delivered_at": null
  },
  "reason": "email_undeliverable",
  "next_actions": [
    { "action": "update_compliance_email" },
    { "action": "resend" }
  ]
}
```

Aqui `delivery` coincide com `reason`, porque o próprio envio foi recusado.
Uma recusa num lembrete, ou uma devolução reportada posteriormente, mantém `delivery.status` como `DELIVERED`: o primeiro e-mail chegou a sair.
Consulte `reason`, e não `delivery`, para saber por que razão uma transferência está bloqueada.

Para corrigir, forneça novamente o e-mail de conformidade da contraparte e, em seguida, reenvie:

```bash theme={null}
curl -X PATCH https://verification.didit.me/v3/transactions/22222222-3333-4444-5555-666666666666/travel-rule/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "update_compliance_email", "compliance_email": "desk@bene-casp.example"}'

curl -X PATCH https://verification.didit.me/v3/transactions/22222222-3333-4444-5555-666666666666/travel-rule/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "resend"}'
```

O `update_compliance_email` mantém o endereço como o `beneficiary_data.counterparty_vasp_email` desta transferência: pertence apenas a esta transferência e não é adicionado a nenhuma entrada do diretório nem a nenhuma lista de contactos.
O estado não é alterado, a cronologia ganha `compliance email updated` e a transferência mantém `reason: email_undeliverable` até que o reenvio envie o pedido para o novo endereço.
Apenas uma transferência de saída em `COUNTERPARTY_VASP_NOT_FOUND`, `COUNTERPARTY_VASP_NOT_REACHABLE` ou `NOT_ENOUGH_COUNTERPARTY_DATA` o aceita; qualquer outra transferência responde com `409`, e um `compliance_email` em falta ou mal formatado responde com `400`.

### Carteiras autocustodiadas declaradas

Quando o seu cliente lhe informar que o destino é a sua própria carteira autocustodiada (não alojada), declare-o na transação em vez de permitir que o encaminhamento descubra que não existe nenhum VASP por trás dela: defina o tipo do método de pagamento da contraparte como `unhosted_wallet`.

```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": "trv-2026-07-07-002",
    "transaction_category": "travelRule",
    "transaction_details": {
      "direction": "outbound",
      "action_type": "transfer",
      "amount": "0.25",
      "currency": "ETH",
      "currency_kind": "crypto"
    },
    "subject": {
      "entity_type": "individual",
      "vendor_data": "user-042",
      "full_name": "Jane Doe"
    },
    "counterparty": {
      "entity_type": "external",
      "full_name": "Jane Doe",
      "payment_method": {
        "method_type": "unhosted_wallet",
        "account_id": "0xd3b62acb76fb27a7f8961ec40fa11746b113aca9"
      }
    },
    "travel_rule_details": {
      "status": "AWAITING_COUNTERPARTY",
      "beneficiary_data": {
        "wallet_address": "0xd3b62acb76fb27a7f8961ec40fa11746b113aca9",
        "name": "Jane Doe"
      }
    }
  }'
```

A declaração contorna totalmente o encaminhamento:

* Nenhum rail é tentado - não existe um VASP de contraparte com quem trocar dados - e a transferência é criada diretamente em `UNCONFIRMED_OWNERSHIP`.
* Quando `auto_wallet_verification` está ativado (o valor predefinido), a Didit cria automaticamente uma sessão do [widget de propriedade da carteira](https://docs.didit.me/pt/transaction-monitoring/wallet-ownership-widget.md) vinculada à transação e devolve-a no bloco `action_required` da transação; os SDKs iniciam-na automaticamente no [envio do lado do cliente](https://docs.didit.me/pt/transaction-monitoring/sdk-transaction-submission.md).
* Assim que o cliente comprovar o controlo da carteira, a transferência executa a correspondência de nome do beneficiário e avança para `COMPLETED` (ou `COUNTERPARTY_MISMATCHED_DATA` se a correspondência falhar).

Esta é a obrigação da TFR da UE relativa a carteiras autocustodiadas em formato de API: verificar a propriedade da carteira não alojada em vez de trocar dados com um VASP de contraparte.
A declaração é lida a partir do método de pagamento no lado de **destino** de uma transferência de saída e no lado de **origem** de uma de entrada - em ambos os casos, o participante da contraparte.
Uma transferência declarada como não alojada já se encontra no seu caminho final sem rails, pelo que `UNCONFIRMED_OWNERSHIP` não é um estado passível de reenvio - conclua a comprovação de propriedade (ou cancele) em vez de chamar `action: "resend"`.

## Receber

### Confirmar a propriedade da carteira

Uma transferência aguarda em `UNCONFIRMED_OWNERSHIP` em dois casos:

* Uma transferência recebida corresponde a uma entrada do [livro de endereços](#livro-de-endereços-de-carteiras) cuja propriedade ainda não foi verificada.
* A carteira da contraparte foi declarada como autocustodiada (`counterparty.payment_method.method_type: "unhosted_wallet"`), num levantamento de saída ou num depósito recebido. Consulte [Carteiras autocustodiadas declaradas](#carteiras-autocustodiadas-declaradas).

A sua aplicação confirma ou rejeita a transferência:

```bash theme={null}
curl -X POST https://verification.didit.me/v3/transactions/{transaction_uuid}/travel-rule/ownership/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirmed": true}'
```

O corpo aceita `confirmed` (obrigatório, booleano) e um `wallet_address` opcional.

O endpoint aceita uma transferência em qualquer um destes estados e devolve `409` com `{"detail": "Transfer is not awaiting ownership confirmation."}` para qualquer outro:

* `UNCONFIRMED_OWNERSHIP`, em qualquer uma das direções.
* `ON_HOLD` numa transferência recebida.
* `UNCONFIRMED_OWNERSHIP`, `ON_HOLD` ou `COUNTERPARTY_MISMATCHED_DATA` numa transferência `TRP` recebida, para que um responsável pela conformidade possa resolver uma consulta da contraparte manualmente.

Numa transferência que a própria Didit criou (via `INTERNAL`, registo sunrise ou uma carteira autocustodiada declarada):

* `confirmed: true` marca a entrada correspondente no livro de endereços como tendo a propriedade verificada e, em seguida, faz a correspondência do nome com o `holder_name` dessa entrada - `COMPLETED` se passar, `COUNTERPARTY_MISMATCHED_DATA` se não passar.
  A contraparte da via `INTERNAL`, quando existir, obtém o mesmo resultado.
  Para uma carteira autocustodiada declarada, `confirmed: true` regista que o seu cliente verificou quem controla a carteira da contraparte e conclui a transferência (`COMPLETED`), enviada ou recebida.
  Uma transferência recebida cujo depósito já tenha sido liquidado avança então diretamente para `FINISHED`.
* `confirmed: false` move ambos os lados da transferência para `COUNTERPARTY_VASP_GENERAL_DECLINE`.
* A entrada correspondente é pesquisada no seu próprio livro de endereços apenas pelo endereço, sem a blockchain.
  Resolver um `ON_HOLD` recebido sem nenhuma entrada correspondente cria a entrada a partir do `beneficiary_data.wallet_address` da transferência e marca-a como verificada.
  Uma carteira autocustodiada declarada é a exceção: a carteira é registada no seu livro de endereços com a propriedade verificada, conforme descrito abaixo.
  Em todos os outros casos, uma entrada em falta devolve `409` com `{"detail": "wallet address entry no longer available"}`, que é também o que uma entrada eliminada devolve.

Numa transferência `TRP` recebida, a mesma chamada responde à consulta da contraparte:

* `confirmed: true` necessita de um endereço de pagamento para devolver, obtido primeiro a partir de `wallet_address` do pedido, depois da entrada correspondente e, por fim, de `beneficiary_data.wallet_address`.
  Se nenhum dos três estiver presente, o pedido devolve `400` com `{"wallet_address": ["wallet_address is required to approve."]}`.
  A Didit cria ou verifica a entrada, envia o callback de resolução da consulta para a contraparte, define `ownership_confirmed` e move a transferência para `COMPLETED`.
* `confirmed: false` envia uma resolução recusada e move a transferência para `COUNTERPARTY_VASP_GENERAL_DECLINE`.
* Se o endpoint de callback da contraparte não puder ser alcançado, o pedido devolve `502` e a transferência mantém o seu estado atual.
  Numa aprovação, a entrada no livro de endereços continua a ser criada ou marcada como verificada.

Para uma carteira autocustodiada declarada, a carteira que você verifica é a da contraparte: o destino de um levantamento enviado ou a origem (a carteira do ordenante) de um depósito recebido.
A Didit adiciona-a ao livro de endereços com a propriedade verificada sob o nome da contraparte, para que a carteira seja comparada com o nome da contraparte (o ordenante, no caso de um depósito).
Se o livro de endereços já contiver essa carteira com um nome de titular diferente, a transferência move-se para `COUNTERPARTY_MISMATCHED_DATA`.

Se a transferência não indicar nenhuma carteira da contraparte, transmita `wallet_address` no corpo do pedido.
Quando nem a transferência nem o pedido fornecerem um endereço, o pedido é rejeitado com `400`.

```json theme={null}
{"confirmed": true, "wallet_address": "0xCounterpartyWallet01"}
```

* Uma transferência de rede já respondida através da respetiva rede (uma transferência VerifyVASP, ou uma transferência GTR ou Sygna Bridge já decidida) devolve `409` (consulte [Transferências a partir de uma rede](#transferências-a-partir-de-uma-rede)).

A resposta é o objeto de transferência mais completo descrito acima.
Uma nova transferência `INTERNAL` nunca aguarda aqui: só chega a um cliente que já tenha comprovado a carteira. Uma transferência `INTERNAL` mais antiga que ainda esteja a aguardar desde antes dessa regra mantém os dados do remetente ocultos até que comprove o controlo da carteira (uma mensagem assinada ou um depósito de teste), e confirmá-la responde com `409` até que o faça. Recusá-la continua a funcionar.
Quando a contraparte responder que a carteira é autocustodiada (atualmente, o [Didit Test VASP](https://docs.didit.me/pt/transaction-monitoring/travel-rule-sandbox.md) dá essa resposta na sandbox), a confirmação adiciona a carteira ao seu livro de endereços sob o nome do beneficiário e executa a correspondência de nomes: uma correspondência conclui a transferência e marca a carteira como verificada.

### Transferências a partir de uma rede

A Didit também pode receber transferências Travel Rule que uma contraparte envie através de `GTR`, `VERIFYVASP` ou `SYGNA`.
A receção é ativada pela Didit para cada rede separadamente, e **nenhuma está ativada hoje**: também necessita do registo dos endpoints da Didit em cada rede, e a Didit ainda não é membro dessas redes.
As transferências `TRUST` não podem ser recebidas.

Assim que uma rede for ativada, uma mensagem entregue por ela é processada da seguinte forma:

* **Encaminhamento.** A mensagem chega à sua aplicação quando identifica o código de participante da sua própria adesão ligada a essa rede. Uma mensagem endereçada à adesão da própria Didit só chega até si quando for o único cliente Didit em produção que comprovou o controlo da carteira do beneficiário. Qualquer outra mensagem é recusada, para que nenhum cliente receba a transferência de outro cliente.
* **Decisão.** A Didit cria a transferência recebida na sua aplicação e decide-a como uma [consulta TRP](https://docs.didit.me/pt/transaction-monitoring/travel-rule-interoperability.md#endpoints-trp): correspondência da carteira, propriedade, correspondência de nomes e `inbound_auto_accept`.
* **Uma única vez.** As redes reenviam uma mensagem até que seja respondida. Uma repetição obtém a resposta que a primeira cópia obteve, e nada é criado ou decidido duas vezes.
* **A sua revisão, através de `GTR` e `SYGNA`.** Uma transferência que aguarde por si (`UNCONFIRMED_OWNERSHIP`, `ON_HOLD` ou `COUNTERPARTY_MISMATCHED_DATA`) é decidida com [`POST .../travel-rule/ownership/`](#confirmar-a-propriedade-da-carteira): `confirmed: true` aprova-a (transmita `wallet_address` quando a transferência não indicar nenhum) e `confirmed: false` recusa-a. A Didit responde à rede após a resposta, com as [mesmas tentativas](#entrega-e-tentativas). Uma transferência que já tenha sido respondida devolve `409`.
* **Sem resposta posterior através de `VERIFYVASP`.** A VerifyVASP obtém a sua resposta no momento em que efetua o pedido, pelo que uma transferência que necessite da sua revisão é recusada de imediato e não pode ser decidida posteriormente (`409`).

### Dados da contraparte mascarados

Até que a propriedade da carteira seja confirmada, os dados pessoais da contraparte numa transferência de entrada são devolvidos mascarados em vez de serem omitidos.
A primeira letra de cada palavra é mantida, e o encaminhamento da carteira, da blockchain e do VASP permanece legível.
`data_masked` é `true`, e a contraparte nos detalhes da transação, na lista e na exportação CSV é mascarada da mesma forma.

Assim que a propriedade é confirmada, os valores reais aparecem e `data_unmasked` regista a entrada de auditoria:

```json theme={null}
{
  "data_masked": false,
  "data_unmasked": { "at": "2026-10-17T10:00:00Z", "reason": "wallet_proof", "actor": "" }
}
```

`reason` é `ownership_confirmed`, `wallet_proof`, `address_book_match`, `own_verified_wallet`, `inquiry_approved` (aprovou uma consulta `TRP` ou uma mensagem `GTR` ou `Sygna`), `known_payment_method` (a carteira do utilizador final nos seus próprios registos respondeu) ou `travel_address` (o Travel Address de cada carteira identificou a carteira).
Uma transferência de entrada `INTERNAL` inclui `data_unmasked` com `reason: wallet_proof` desde o momento em que é criada, porque apenas um destinatário que comprovou a carteira recebe uma.
`actor` é o e-mail do utilizador da consola ou a etiqueta da chave de API, ficando em branco para uma decisão automática.
O relatório do **Registo de transferências da Travel Rule** (CSV e PDF) mascara os nomes de uma transferência de entrada da mesma forma até que a propriedade seja confirmada. Os relatórios que submete a um regulador, como o XML goAML e o PDF do relatório regulamentar, contêm os dados reais da contraparte.

### Feedback de divergências

Uma transferência com `COUNTERPARTY_MISMATCHED_DATA` indica agora os campos que diferem.
`data_match` contém a comparação e `mismatched_fields` lista os campos.
Ambos contêm apenas os nomes dos campos e os resultados, nunca os valores, pelo que permanecem legíveis enquanto os dados estiverem mascarados:

```json theme={null}
{
  "status": "COUNTERPARTY_MISMATCHED_DATA",
  "mismatched_fields": ["date_of_birth"],
  "data_match": {
    "matched": false,
    "mismatched_fields": ["date_of_birth"],
    "fields": {
      "name": { "result": "matched", "strictness": "DEFAULT" },
      "date_of_birth": { "result": "mismatched", "strictness": "STRICT" },
      "address": { "result": "not_compared", "strictness": "NONE" },
      "account": { "result": "matched", "strictness": "STRICT" }
    }
  }
}
```

A entrada na cronologia indica os campos, por exemplo "a data de nascimento do beneficiário não corresponde ao titular da carteira".
Uma rejeição `TRP` após uma divergência informa o VASP de origem sobre quais os campos que diferem, por exemplo "Os dados do beneficiário não correspondem ao titular da carteira: nome".
O que o outro VASP fica a saber é deliberadamente limitado: enquanto o nome estiver incorreto, o nome é o único campo comunicado (`mismatched_fields: ["name"]`, todos os outros campos `not_compared`), e assim que o nome coincidir, todos os campos que diferem são indicados. Isto aplica-se ao lado do remetente de um intercâmbio `INTERNAL` e a uma rejeição `TRP`.
Um nome em falta em ambos os lados é apresentado como `not_compared` e não constitui uma divergência, e um país coincide com base no código que o identifica, pelo que `ES` e `ESP` coincidem.

#### Pontuação de correspondência do nome

Cada transferência cujo nome foi comparado contém `name_match`, e a entrada na cronologia que a decidiu contém o mesmo objeto junto ao seu `detail`:

```json theme={null}
{
  "name_match": {
    "score": 90,
    "matched": false,
    "method": "sequence_ratio",
    "strictness": "FUZZY",
    "compared_with": "wallet_holder",
    "transfer_name": "Ana Diaz",
    "compared_name": "Ana Diaz Garcia",
    "matched_names": ["Ana", "Diaz"],
    "mismatched_names": ["Garcia"]
  }
}
```

* `score` é a semelhança dos dois nomes completos, de 0 a 100, e `0` quando qualquer um estiver em branco. `matched` é o resultado ao nível de rigor (`strictness`), pelo que os dois podem divergir: `FUZZY` decide com base no seu próprio rácio de semelhança de `0.85`.
* `matched_names` são as palavras do nome da transferência encontradas no outro nome; `mismatched_names` são as palavras que um dos lados tem e o outro não.
* `method` é `none`, `exact_token`, `token_subset`, `token_containment` ou `sequence_ratio`, para `NONE`, `STRICT`, `DEFAULT`, `CONTAINS` e `FUZZY`.
* `compared_with` é `wallet_holder` (o titular registado para a carteira) ou `counterparty_vasp` (o nome que a contraparte indicou na resposta através da página de resposta por e-mail, ou a resposta do Didit Test VASP).
* O resultado da transferência depende de `data_match`, que compara todos os campos, pelo que uma transferência pode ter `COUNTERPARTY_MISMATCHED_DATA` enquanto `name_match.matched` é `true`.
* `name_match` encontra-se no objeto de transferência devolvido pelos endpoints da Travel Rule e no `travel_rule` incorporado da transação, e é `null` até que um nome tenha sido comparado. A lista de transferências e os webhooks não o incluem.
* Os nomes ficam ocultos enquanto as partes estiverem [mascaradas](#dados-da-contraparte-mascarados), e na cópia do outro cliente de um intercâmbio `INTERNAL`.

### Mensagens e pedidos de documentos

Dois VASPs podem resolver uma transferência contestada na Didit em vez de o fazerem por e-mail.
`GET` e `POST /v3/transactions/{transaction_id}/travel-rule/messages/` listam e enviam mensagens numa transferência:

```bash theme={null}
curl -X POST https://verification.didit.me/v3/transactions/{transaction_uuid}/travel-rule/messages/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "DOCUMENT_REQUEST", "body": "Please confirm the beneficiary date of birth.", "requested_documents": ["Proof of address"]}'
```

* `kind` é `MESSAGE` (predefinição) ou `DOCUMENT_REQUEST`. Um pedido de documentos necessita de pelo menos uma entrada em `requested_documents` (até 10); uma mensagem necessita de um `body` (até 5000 carateres) ou de um ficheiro.
* `reply_to` faz referência a uma mensagem anterior da mesma transferência. Uma resposta do outro lado que inclua um documento cumpre o pedido de documentos a que responde, sendo definido `fulfilled_at` na mesma. A sua própria resposta nunca cumpre o seu próprio pedido.
* Envie em formato multipart com `files` para anexar até 5 ficheiros de 10 MB cada, em PDF, PNG, JPEG ou WebP. A Didit verifica o conteúdo de cada ficheiro, não apenas o tipo declarado, e qualquer outro ficheiro faz com que o pedido responda com `400` no campo `files` ("Anexe apenas ficheiros PDF, PNG, JPEG ou WebP.").
* Uma transferência suporta até 100 mensagens, das quais até 20 podem conter anexos (cada uma com até 5 ficheiros), contabilizando ambos os lados; ultrapassar qualquer um dos limites faz com que o pedido responda com `400`. Os anexos das mensagens não contam para os documentos da própria transação.
* As mensagens funcionam através dos canais `INTERNAL` e `EMAIL`. Em `INTERNAL`, o outro cliente Didit vê a mensagem no seu lado do par. Em `EMAIL`, a contraparte recebe um e-mail e responde no portal de recolha. Se esse e-mail de notificação não puder ser enviado, a mensagem é guardada na mesma e o pedido responde com `201`.
* O pedido responde com `409` com um motivo em `detail` para uma transferência através de `TRP`, `GTR`, `TRUST`, `VerifyVASP` ou `Sygna` (esses protocolos não transmitem mensagens), uma transferência ainda sem contraparte, uma transferência `INTERNAL` cujos dados não coincidiram com o titular da carteira (nada chegou ao destinatário), uma transferência `INTERNAL` cujo destinatário ainda não comprovou o controlo da carteira (em ambos os lados, até que o faça), uma transferência `EMAIL` cuja contraparte já não possui um endereço de e-mail de conformidade e uma transferência `EMAIL` cuja ligação de recolha expirou ou cuja transferência se encontra encerrada.
* Nenhum webhook é acionado quando a contraparte responde por escrito. Consulte o endpoint de mensagens.
* O e-mail que informa a contraparte sobre uma nova mensagem é enviado em inglês.

### Livro de endereços de carteiras

Registe as carteiras que controla para que as transferências de entrada (canal `INTERNAL`, consultas `TRP` de entrada e [registos após depósito](#registo-sunrise-posterior-ao-depósito)) possam ser associadas a essas carteiras, com `POST`/`GET /v3/travel-rule/wallet-addresses/` e `PATCH`/`DELETE /v3/travel-rule/wallet-addresses/{entry_uuid}/`.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/travel-rule/wallet-addresses/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb",
    "chain": "ETH",
    "holder_name": "Ana Diaz",
    "holder_vendor_data": "user-042",
    "self_declared": true
  }'
```

| Campo | Tipo | Descrição |
| - | - | - |
| `address` | string | O endereço da carteira. Único por aplicação, `chain` e `memo` (o endereço é comparado sem distinção entre maiúsculas e minúsculas) - um duplicado devolve `400`. Um endereço X de XRP é armazenado como o seu endereço clássico e a sua tag. Vazio numa entrada [importada pelo seu hash](#importar-carteiras-em-lote). |
| `address_hash` | string | Apenas de leitura. SHA-256 do endereço em minúsculas, em hexadecimal em minúsculas. |
| `memo` | string | Opcional. A tag de destino ou memo que faz parte da carteira numa [rede com memo](#redes-com-memo-e-tag); vazio para o endereço completo. Alias: `destinationTag`. |
| `chain` | string | Identificador opcional da chain, até 32 carateres. Utilize o mesmo token que as suas transferências contêm (por exemplo `ETH` ou `BTC`), ou deixe em branco para fazer corresponder transferências em qualquer chain - consulte a nota abaixo. Um destinatário Lightning (ID do nó ou Lightning Address) registado em bitcoin é armazenado em minúsculas em `LIGHTNING`, onde as transferências [Lightning](#lightning) são correspondidas. |
| `holder_name` | string | Nome do titular da carteira, utilizado para a correspondência do nome do beneficiário. |
| `holder_vendor_data` | string | O seu identificador interno para o titular. |
| `entity_type` | string | Texto livre até 16 carateres, por omissão `"individual"`. |
| `travel_address` | string | Opcional. O Travel Address do VASP da contraparte para esta carteira, se o souber. Permite à Didit encaminhar transferências para este beneficiário através da via `TRP` em vez de e-mail. |
| `receiving_travel_address` | string | Apenas de leitura. O seu próprio Travel Address específico desta carteira. Forneça-o a um VASP que envie para esta carteira: a sua consulta TRP nomeia então a carteira diretamente. Vazio para uma carteira registada como pertencendo a outro VASP, enquanto a Travel Rule estiver desativada e antes de o seu perfil de VASP ser guardado. Deixa de responder assim que a carteira for eliminada. |
| `is_ownership_verified` | boolean | Apenas de leitura. Se a propriedade deste endereço foi comprovada (através do [widget de propriedade de carteira](https://docs.didit.me/pt/transaction-monitoring/wallet-ownership-widget.md) ou autodeclaração). |
| `self_declared` | boolean | Apenas de escrita, apenas `POST`. Quando `true`, a entrada é criada já verificada através de uma prova `SELF_DECLARATION` - as transferências recebidas para este endereço ignoram `UNCONFIRMED_OWNERSHIP` por completo e avançam diretamente para a correspondência de nomes. Devolve `400` quando `allow_self_declaration` estiver desativado nas suas definições. |

`PATCH` aceita `holder_name`, `holder_vendor_data`, `entity_type` e `travel_address`, e devolve apenas esses quatro campos.
`DELETE` elimina a entrada (`204`) - o seu endereço fica disponível para novo registo e deixa imediatamente de corresponder a novas transferências.

> [!NOTE]
>
> A correspondência é insensível a maiúsculas e minúsculas no endereço, inclui o seu `memo` numa rede com memo e é limitada por `chain`.
> Quando uma transferência tem uma chain associada, uma entrada só corresponde se a sua `chain` tiver o mesmo valor (sem sensibilidade a maiúsculas e minúsculas) ou estiver vazia.
> Os nomes das chains são comparados como texto, não são traduzidos, pelo que uma entrada guardada como `ethereum` não corresponde a uma transferência cuja chain seja `ETH`.
> As transferências de saída obtêm a sua chain a partir de `beneficiary_data.chain`, depois de `transaction_details.crypto_params.crypto_chain`, depois de `custom_properties.crypto_chain` e, em seguida, da moeda (por exemplo `ETH`, ou para `USDT` e `USDC` a chain inferida de `payment_reference_id`), definida apenas quando for uma chain que a Didit reconhece, e os registos pós-depósito a partir do respetivo campo `chain`, em minúsculas.
> As consultas `TRP` de entrada ignoram a chain: correspondem por endereço ou, quando a consulta não indica nenhuma carteira, comparando o nome do beneficiário com as suas entradas verificadas.
> [`POST .../travel-rule/ownership/`](#confirmar-a-propriedade-da-carteira) também faz a correspondência apenas pelo endereço.
> Quando várias entradas correspondem, a via `INTERNAL` e os registos pós-depósito dão preferência a uma entrada cuja propriedade foi verificada e, de seguida, à mais antiga; e a pesquisa `TRP` de saída escolhe a entrada mais antiga que armazena um Travel Address.
> As consultas `TRP` de entrada e o endpoint de propriedade aceitam qualquer uma das entradas correspondentes, pelo que deve manter uma entrada por endereço sempre que possível.
> A via `INTERNAL` não faz corresponder nenhuma entrada se existirem entradas verificadas para o endereço em mais do que uma outra aplicação.

#### Importar carteiras em lote

Importe até 10,000 carteiras numa única chamada com [`POST /v3/travel-rule/wallet-addresses/import/`](https://docs.didit.me/pt/management-api/travel-rule/import-wallet-addresses), como JSON (`{"entries": [...]}` ou um array simples) ou como um ficheiro CSV em UTF-8 com um máximo de 5 MB com uma linha de cabeçalho.
Uma linha identifica uma carteira pelo seu `address`, por `address_hash` (o SHA-256 do endereço em minúsculas, 64 carateres hexadecimais ou 44 carateres base64), ou ambos, além de qualquer um dos campos de entrada acima.
Envie apenas o hash para registar uma carteira sem divulgar o seu endereço: corresponde a transferências para esse endereço como qualquer outra entrada e pode ser comprovada com o [widget de propriedade de carteira](https://docs.didit.me/pt/transaction-monitoring/wallet-ownership-widget.md).

```bash theme={null}
curl -X POST https://verification.didit.me/v3/travel-rule/wallet-addresses/import/ \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@wallets.csv;type=text/csv"
```

```text theme={null}
address,address_hash,chain,memo,holder_name,holder_vendor_data
0xBeneficiaryWallet01,,ethereum,,Ana Diaz,user-042
,4f7d2e1c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e,bitcoin,,,user-043
rExchangeSharedAddress01,,XRP,104729,Ana Diaz,user-042
```

A importação é idempotente e reporta cada linha na ordem enviada: `created`, `existing` (a mesma carteira, chain e memo já estão registados e não foram alterados), `duplicate` (repete uma linha anterior, indicada em `duplicate_of_row`) ou `failed` com os seus `errors`.
Uma linha inválida nunca faz falhar as restantes: a resposta é `200` quando nenhuma linha falhou e `207` quando alguma falhou, com as contagens em `total`, `created`, `existing`, `duplicate` e `failed`.
Uma célula vazia no CSV conta como não enviada e as colunas que a importação não lê são ignoradas, pelo que uma exportação de outra ferramenta é importada tal como está.

Em `GET /v3/travel-rule/transfers/`, cada linha inclui `originator_memo` e `beneficiary_memo` junto às duas carteiras.

### Recolha por e-mail para contrapartes inacessíveis

Quando nenhuma via de protocolo consegue alcançar a contraparte, a Didit recorre a `EMAIL`: envia uma ligação de recolha de utilização única para `beneficiary_data.counterparty_vasp_email` (ou um e-mail resolvido a partir de `beneficiary_data.counterparty_vasp_name` face ao registo do diretório de VASPs).
O destinatário não necessita de uma conta Didit nem de uma chave de API - o token da ligação é a autenticação.
Como o pedido é enviado:

* **Para os endereços certos.** Um `counterparty_vasp_email` que forneça é o único destinatário. Caso contrário, a Didit envia mensagens para até três endereços: os [contactos](#contactos) da contraparte que não tenham sofrido bounce (primeiro os seus, depois os contactos da plataforma, dando prioridade aos que responderam anteriormente) e, se restar uma vaga, o e-mail de conformidade da entrada do diretório. Cada endereço recebe o seu próprio e-mail.
* **Em seu nome.** O e-mail provém do endereço da Didit como "*a sua denominação social* via Didit", no idioma da jurisdição da contraparte (inglês quando não for conhecida nenhuma), e a ligação abre a página de resposta nesse idioma. Não recebe nenhuma cópia: acompanhe a linha temporal da transferência.
* **Com lembretes.** Até a contraparte responder, a Didit envia-lhe lembretes 72, 24 e 6 horas antes do prazo limite, pelo menos 12 horas após o pedido ou o último lembrete, e nunca após o prazo limite.
* **Com gestão de bounces.** Um bounce ou uma denúncia de spam marca o contacto alcançado como inválido com o respetivo motivo, sendo registado na linha temporal da transferência. Um contacto da plataforma fica então inválido para todos os clientes da Didit; o contacto da sua própria aplicação apenas para a sua aplicação. Quando a entrega de e-mail da Didit deixa de enviar para um endereço (após um bounce permanente, uma denúncia de spam ou um cancelamento de subscrição), todos os contactos nesse endereço são marcados como inválidos (`suppressed`), voltando a ser válidos assim que o envio para o endereço for retomado. Quando já não resta nenhum endereço para o qual escrever, a transferência passa para `COUNTERPARTY_VASP_NOT_REACHABLE` com o motivo do servidor de correio recetor na respetiva linha temporal. Um bounce permanente ou uma denúncia de spam no `counterparty_vasp_email` que forneceu provoca isso de imediato, por ser o único destinatário; um bounce temporário (`soft_bounce`) no mesmo, ou no e-mail de conformidade da própria entrada do diretório, mantém o pedido aberto para os lembretes.

A ligação abre uma página alojada que mostra a troca pendente e chama estes dois endpoints públicos para o destinatário.
Para a [transferência de exemplo acima](#enviar-uma-transferência), os detalhes de recolha são:

```bash theme={null}
curl https://verification.didit.me/v3/travel-rule/pickup/{token}/
```

```json theme={null}
{
  "reference": "33333333-4444-5555-6666-777777777777",
  "requested_at": "2026-07-05T10:00:00Z",
  "originator_vasp_name": "Origin CASP SL",
  "originator_vasp_lei": "529900EXAMPLEORIG001",
  "recipient_vasp_name": "Example Counterparty VASP",
  "language": "es",
  "amount": "0.250000000000000000",
  "currency": "ETH",
  "fiat_amount": "",
  "fiat_currency": "",
  "chain": "ETH",
  "beneficiary_wallet": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb",
  "status": "AWAITING_COUNTERPARTY",
  "ivms_version": "ivms101.2023",
  "deadline_at": "2026-07-07T10:00:00Z",
  "reminders_sent": 0,
  "contact": "",
  "decline_reasons": ["data_mismatch", "not_our_customer", "wallet_not_hosted", "sanctions", "risk_appetite", "jurisdiction", "insufficient_data", "other"],
  "join_invitation": { "eligible": false, "url": "" },
  "originator_data": { "name": "Jane Doe", "wallet_address": "0x77ccff0cc624a53cd8b8d8703ced826710211ec7" },
  "beneficiary_data": { "name": "Ana Diaz", "wallet_address": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb" },
  "ivms_request": {
    "originator": {
      "originatorPersons": [{ "naturalPerson": { "name": { "nameIdentifier": [{ "primaryIdentifier": "Doe", "secondaryIdentifier": "Jane", "nameIdentifierType": "LEGL" }] } } }],
      "accountNumber": ["0x77ccff0cc624a53cd8b8d8703ced826710211ec7"]
    },
    "beneficiary": {
      "beneficiaryPersons": [{ "naturalPerson": { "name": { "nameIdentifier": [{ "primaryIdentifier": "Diaz", "secondaryIdentifier": "Ana", "nameIdentifierType": "LEGL" }] } } }],
      "accountNumber": ["0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb"]
    }
  },
  "data_masked": false
}
```

`reference` é o `uuid` da transferência. `originator_data` e o `ivms_request` IVMS 101 construído a partir dele contêm apenas os campos do ordenante que partilhar em [`data_sharing_fields`](#partilha-de-dados); o nome e a carteira estão sempre incluídos. `fiat_amount` e `fiat_currency` ficam vazios quando não enviou qualquer valor convertido, `contact` reflete o valor `?contact=` da ligação e `decline_reasons` lista os valores que `decline_reason` aceita. `join_invitation.eligible` é `true` enquanto a contraparte tiver um convite ativo para aderir à Didit; a própria ligação de convite viaja apenas no e-mail.

Este endpoint devolve o montante armazenado na íntegra, pelo que contém as 18 casas decimais completas em vez do formato truncado utilizado pelo objeto de detalhes da transação.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/travel-rule/pickup/{token}/respond/ \
  -H "Content-Type: application/json" \
  -d '{"decision": "accept", "beneficiary_name": "Ana Diaz"}'
```

`decision` é `accept` ou `decline`.
Em `accept`, o `beneficiary_name` fornecido é comparado com o `beneficiary_data.name` da transferência ao abrigo da sua regra de nomes - `COMPLETED` em caso de correspondência, `COUNTERPARTY_MISMATCHED_DATA` caso contrário. A contraparte pode, em alternativa, enviar uma resposta IVMS 101 completa como `ivms_response`; o seu nome de beneficiário prevalece então sobre `beneficiary_name`.
Em `decline`, a transferência passa para `COUNTERPARTY_VASP_GENERAL_DECLINE`. A contraparte pode indicar um `decline_reason` a partir de `decline_reasons`, com um `decline_detail` (até 512 carateres, obrigatório para `other`), e a linha temporal da sua transferência regista-o, por exemplo, `counterparty declined: The beneficiary is not our customer`.
A resposta é o `{"status": "..."}` resultante, mais `decline_reason` após uma recusa. Assim que a contraparte responder, ambos os endpoints devolvem `410`.
Ambos os endpoints devolvem `404` para um token desconhecido e `410` assim que a janela fecha - quer porque a transferência saiu de `AWAITING_COUNTERPARTY`, quer porque o respetivo prazo de confirmação (`confirmation_timeout_hours` após a criação ou o último reenvio) expirou.

A contraparte consulta e responde através da ligação de recolha com `GET` e `POST /v3/travel-rule/pickup/{token}/messages/`.
Não necessita de chave de API, aceita apenas anexos em PDF, PNG, JPEG ou WebP, e responde com `410` assim que a ligação expira ou a transferência é encerrada.
Uma mensagem enviada por si apresenta o nome do seu VASP como `author` e como `uploaded_by` do anexo, nunca a pessoa ou a chave de API por trás da mesma.

### Depósitos sem correspondência

Um depósito de entrada pode chegar antes dos dados de Travel Rule do VASP de origem.
Esse depósito permanece em `AWAITING_COUNTERPARTY` ou `NOT_ENOUGH_COUNTERPARTY_DATA` até que os dados cheguem.
Liste os depósitos que ainda estão a aguardar com uma chave de API que tenha o privilégio de transações:

```bash theme={null}
curl "https://verification.didit.me/v3/travel-rule/unmatched/" \
  -H "x-api-key: YOUR_API_KEY"
```

A resposta utiliza as mesmas linhas que `GET /v3/travel-rule/transfers/`, limitada a depósitos de entrada que aguardam os dados do VASP de origem.

Quando os dados tiverem chegado como uma mensagem recebida separada, emparelhe os dois manualmente:

```bash theme={null}
curl -X POST "https://verification.didit.me/v3/travel-rule/unmatched/{transaction_uuid}/match/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transaction_id": "<uuid of the received message transaction>"}'
```

`{transaction_uuid}` é o depósito.
`transaction_id` é a transação da mensagem de Travel Rule recebida.
A chamada devolve `{ "deposit": ..., "message": ... }`.
Responde com `404` quando qualquer uma das transações já não existir, e com `409` com `travel_rule_match_conflict` ("This deposit can no longer be matched.") quando qualquer um dos lados já tiver avançado.

### Registo sunrise posterior ao depósito

Quando um depósito de cripto é liquidado on-chain **antes** de qualquer troca de Travel Rule ter ocorrido - o VASP remetente estava inalcançável ou está a registar retroativamente depósitos históricos - registe-o posteriormente com `POST /v3/travel-rule/inbound/`.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/travel-rule/inbound/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "eth",
    "txid": "0xf103cfc37f6d390b61827987b9dc631b5e1d2bfeb008a780c1e38047ae5d557b",
    "wallet_address": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb",
    "amount": "500.00",
    "currency": "USDC",
    "originator_data": { "name": "Carlos Ruiz", "wallet_address": "0x77ccff0cc624a53cd8b8d8703ced826710211ec7" },
    "beneficiary_data": { "name": "Ana Diaz" },
    "originating_vasp": {
      "name": "Northwind Digital Assets Ltd",
      "lei": "5493001KJTIIGC8Y1R12",
      "travel_address": "tareGfwAzkySLkFzcqr7AKno3K4VsT3jayMwPvj3ovbFZHzpayHLmgCrAMoLqjfCYRPpvLqr9dSr2VVTFAncwChcMjL4AheNuHCJM8NRcUg"
    }
  }'
```

`originating_vasp.travel_address` tem de ser um [Travel Address](#travel-addresses) real e com soma de verificação válida: um marcador de posição devolve `400` com `"Invalid travel address."`.
`originating_vasp.lei` tem de estar vazio ou conter 20 carateres no formato LEI (18 letras ou dígitos, seguidos de 2 dígitos); qualquer outra coisa devolve `400` com `"Invalid LEI: expected 20 alphanumeric characters (ISO 17442)."`.
A Didit valida apenas este formato, e não os dígitos de controlo da ISO 17442.

| Campo | Tipo | Descrição |
| - | - | - |
| `chain` | string | blockchain onde o depósito foi liquidado, até 32 carateres. A Didit converte-a para minúsculas e utiliza-a para fazer a correspondência com as entradas do seu [livro de endereços](#livro-de-endereços-de-carteiras); por isso, utilize o mesmo token das suas entradas (`eth` corresponde a uma entrada armazenada como `ETH`). Também determina se o depósito pode ser analisado: `bitcoin`/`btc`, `ethereum`/`eth`, `solana`/`sol`, `tron`/`trx`, `polygon`/`matic`, `bsc`/`bnb`, `litecoin`/`ltc`, `ripple`/`xrp`, `bitcoin-cash`/`bch` e `dogecoin`/`doge`. |
| `txid` | string | O hash da transação on-chain. Utilizado para desduplicação - a combinação do mesmo `txid` + `wallet_address` devolve a transferência existente em vez de criar um duplicado. |
| `wallet_address` | string | A carteira de destino onde recebeu o depósito. Um X-address de XRP é dividido no respetivo endereço clássico e na tag. |
| `memo` | string | Opcional. A tag de destino ou o memo do depósito numa [rede com memo](#redes-com-memo-e-tag): num endereço de depósito partilhado, identifica o cliente ao qual o depósito pertence. |
| `amount` | string (decimal) | Montante do depósito. |
| `currency` | string | Ativo do depósito. |
| `originator_data` | object | Detalhes do ordenante do VASP remetente, se conhecidos, como um objeto simples: a Didit lê `name` (ou `full_name`), `first_name`, `last_name` e `vendor_data`. |
| `beneficiary_data` | object | Detalhes do beneficiário (o seu cliente), como um objeto simples: a Didit compara o respetivo `name` com o `holder_name` da entrada correspondente no livro de endereços e adiciona-lhe `wallet_address` e `chain`. |
| `utxo` | object | Opcional, apenas para [blockchains UTXO](#transferências-utxo). Os `inputs` e `outputs` da transação de depósito: a carteira do remetente é `originator_data.wallet_address` quando a declara, caso contrário é a entrada de maior valor. |
| `originating_vasp` | object | `{ name, lei, travel_address }` opcional que descreve o remetente. `lei` tem de corresponder ao formato LEI acima e `travel_address` tem de ser um Travel Address válido, sob pena de o pedido devolver `400`. Mantido nesta transferência como `metadata.originating_vasp`; nunca cria nem altera uma entrada partilhada no [diretório](#como-as-entradas-entram-no-diretório). |

A Didit cria uma transação de entrada `travelRule` (ou reutiliza um depósito de entrada que já tenha submetido com o mesmo hash e carteira, se este ainda não tiver uma transferência da Travel Rule) e resolve a transferência em relação ao seu [livro de endereços de carteiras](#livro-de-endereços-de-carteiras), pelo endereço e respetivo memo:

* Nenhuma entrada correspondente -> `ON_HOLD`.
  Resolva com [`POST .../travel-rule/ownership/`](#confirmar-a-propriedade-da-carteira): `confirmed: true` adiciona a carteira ao seu livro de endereços como verificada e executa a correspondência de nomes; havendo correspondência, a transferência avança para `COMPLETED` e depois para `FINISHED`.
* A entrada existe, mas a propriedade não está comprovada -> `UNCONFIRMED_OWNERSHIP`.
* O nome do beneficiário não corresponde ao `holder_name` da entrada -> `COUNTERPARTY_MISMATCHED_DATA`.
* Entrada verificada e o nome corresponde -> `COMPLETED` e logo de seguida `FINISHED` (o depósito já foi liquidado).

Com a entrada verificada do livro de endereços registada no [exemplo acima](#livro-de-endereços-de-carteiras), a resposta é:

```json theme={null}
{
  "transaction_id": "44444444-5555-6666-7777-888888888888",
  "txn_id": "tr-in-0xf103cfc37f6d390b61827987b9dc631b5e1d2bfeb008a780c1e38047ae5d557b-6151d81b366e",
  "created": true,
  "travel_rule": {
    "uuid": "55555555-6666-7777-8888-999999999999",
    "status": "FINISHED",
    "direction": "INBOUND",
    "rail": null,
    "protocol": null,
    "ivms_version": "ivms101.2023",
    "required": true,
    "ownership_confirmed": true,
    "deadline_at": null,
    "timeline": [
      { "status": "COMPLETED", "at": "2026-07-06T10:15:02.114208+00:00", "detail": "matched verified wallet address book entry" },
      { "status": "FINISHED", "at": "2026-07-06T10:15:02.131544+00:00", "detail": "on-chain deposit already settled" }
    ],
    "counterparty_vasp": null,
    "originator_data": { "name": "Carlos Ruiz", "wallet_address": "0x77ccff0cc624a53cd8b8d8703ced826710211ec7" },
    "beneficiary_data": { "name": "Ana Diaz", "wallet_address": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb", "chain": "eth" },
    "created_at": "2026-07-06T10:15:02.087412Z"
  }
}
```

O `txn_id` da nova transação é `tr-in-`, os primeiros 80 carateres do `txid` e um hash de 12 carateres do `txid` e da carteira.
`created` é `true` (HTTP `201`) quando esta chamada registou o depósito, e `false` (HTTP `200`) quando os mesmos `txid` e `wallet_address` já estavam registados, caso em que a transferência existente é devolvida sem alterações.
No caminho de entrada verificada, ambas as transições ocorrem antes de o endpoint responder, pelo que a resposta síncrona já apresenta o estado terminal `FINISHED` - o passo intermédio `COMPLETED` continua registado na `timeline` da transferência.
Cada transição aciona um webhook `travel_rule.status.updated` (`COMPLETED` e `FINISHED` acionam, cada um, um webhook).
Quando a Didit cria uma nova transação, envia primeiro [`transaction.created`](https://docs.didit.me/pt/integration/webhooks#tipos-de-eventos) e estes eventos a seguir.
O registo não tem qualquer taxa de Travel Rule ou de monitorização.
Quando a monitorização de criptoativos está ativada e a `chain` é uma das que a Didit consegue analisar, o depósito recém-criado também é analisado e faturado uma vez à tarifa de Verificação e Triagem de Carteiras.

### Widget de propriedade da carteira

Para retirar uma transferência de `UNCONFIRMED_OWNERSHIP` - ou para pré-verificar uma carteira antes da chegada de qualquer transferência -, crie um widget alojado de propriedade da carteira com `POST /v3/travel-rule/widget-session/` e encaminhe o seu cliente para o `url` retornado. O widget comprova o controlo da carteira através de assinatura de mensagens (incluindo contas de contratos inteligentes EVM, através de ERC-1271 e ERC-6492), um teste de Satoshi, uma captura de ecrã ou autodeclaração, e de seguida marca a entrada correspondente no livro de endereços como verificada para que a plataforma de câmbio possa prosseguir.
A captura de ecrã é a exceção: nunca verifica a carteira por si só, pelo que a sua equipa de conformidade a revê e confirma uma transferência em `UNCONFIRMED_OWNERSHIP` com [`POST .../travel-rule/ownership/`](#confirmar-a-propriedade-da-carteira).

Consulte [Widget de propriedade da carteira](https://docs.didit.me/pt/transaction-monitoring/wallet-ownership-widget.md) para conhecer o fluxo completo, os métodos de comprovação e a nota importante de que o widget tem de ser aberto num navegador real - nunca dentro de uma webview de SDK móvel.

## Diretório

`GET /v3/travel-rule/vasps/` pesquisa o diretório de VASPs: as entradas partilhadas do diretório mais os membros da [rede Didit](#a-rede-didit). Cada linha indica como a sua aplicação pode contactar esse VASP hoje.

```bash theme={null}
curl "https://verification.didit.me/v3/travel-rule/vasps/?search=counterparty" \
  -H "x-api-key: YOUR_API_KEY"
```

```json theme={null}
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91",
      "kind": "directory",
      "name": "Example Counterparty VASP",
      "lei": "529900EXAMPLECPTY001",
      "jurisdiction": "DE",
      "domains": ["counterparty.example"],
      "reachable": true,
      "aliases": [{ "name": "Example Counterparty", "kind": "trading_name" }],
      "networks": [
        {
          "network": "GTR",
          "code": "EXAMPLE01",
          "listed_name": "Example Counterparty VASP",
          "country": "DE",
          "verified_at": "2026-10-12T09:30:00Z",
          "last_seen_at": "2026-10-12T09:30:00Z",
          "source": "staff"
        }
      ],
      "routes": [
        { "rail": "GTR", "status": "unavailable", "reason": "no_membership", "via": "" },
        { "rail": "EMAIL", "status": "available", "reason": "", "via": "contact" }
      ],
      "umbrella": null,
      "entities": [],
      "contacts": [
        {
          "id": "6c1f9b8e-2d4a-4f7e-8b3c-5a9d0e1f2a3b",
          "email": "travelrule@counterparty.example",
          "name": "Travel Rule desk",
          "source": "staff",
          "scope": "platform",
          "verified_at": null
        }
      ],
      "dd_status": "NOT_STARTED",
      "dd_score": 62,
      "dd_score_breakdown": {
        "jurisdiction": { "points": 25.0, "max": 25, "reason": "jurisdiction_not_high_risk", "detail": "DEU is not on the high-risk jurisdiction list" },
        "verification": { "points": 3.8, "max": 15, "reason": "dd_status_not_started", "detail": "due diligence status NOT_STARTED" },
        "protocol": { "points": 6.0, "max": 15, "reason": "email_only", "detail": "reachable over the email fallback only" },
        "lei": { "points": 10.0, "max": 10, "reason": "lei_valid", "detail": "valid LEI on record" },
        "history": { "points": 5.0, "max": 10, "reason": "no_history", "detail": "no exchange history" },
        "essentials": { "points": 7.5, "max": 15, "reason": "no_essential_checks", "detail": "no decided essential check yet" },
        "responsiveness": { "points": 5.0, "max": 10, "reason": "responsiveness_unknown", "detail": "0 decided recent requests, too few to judge" }
      },
      "dd_assessed_at": "2026-10-12T09:30:00Z",
      "dd_score_semantic": "higher_is_safer",
      "risk_level": "MEDIUM",
      "responsiveness": { "status": "UNKNOWN", "answered": 0, "total": 0, "computed_at": "2026-10-12T09:30:00Z" },
      "essential_checks": {},
      "reachable_rails": ["GTR", "EMAIL"],
      "is_didit_customer": false,
      "decision": {
        "decision": "APPROVED",
        "reason": "Licensed in DE",
        "decided_by": "",
        "updated_at": "2026-10-14T10:05:00Z",
        "inherited_from": null
      },
      "entity_screening": {
        "id": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
        "status": "Approved",
        "total_hits": 0,
        "score": null,
        "screened_at": "2026-10-14T09:58:00Z",
        "fresh": true,
        "flagged": false
      },
      "questionnaires": []
    }
  ]
}
```

`search` faz corresponder um fragmento de nome ou alias, um LEI exato ou um domínio (`counterparty.example` ou um URL nesse domínio). Filtre os resultados com:

| Parâmetro | Efeito |
| - | - |
| `network` | `GTR`, `TRUST`, `VERIFYVASP`, `SYGNA` ou `TRISA`: apenas entradas que o diretório de membros dessa rede lista atualmente. |
| `jurisdiction` | Código de país ISO 3166 alpha-2 ou alpha-3. |
| `reachable` | `true`: apenas VASPs para os quais a sua aplicação tem uma rota disponível. `false`: apenas entradas que não consegue alcançar hoje. |
| `kind` | `directory` para entradas partilhadas, `didit` para membros da rede Didit. |
| `risk` | `LOW`, `MEDIUM` ou `HIGH`: apenas entradas do diretório cujo `risk_level` esteja nessa faixa. Consulte [Pontuação e nível de risco](#pontuação-e-nível-de-risco). |
| `responsiveness` | `RESPONSIVE`, `UNRESPONSIVE` ou `UNKNOWN`: apenas entradas do diretório com esse `responsiveness.status`. Consulte [Capacidade de resposta](#capacidade-de-resposta). |

Os membros da rede Didit não são pontuados, pelo que `risk` e `responsiveness` devolvem apenas entradas do diretório. Os resultados são ordenados por nome e paginados com `limit` (predefinição `50`) e `offset`. Uma rede, código de país, faixa de risco ou estado de capacidade de resposta desconhecido responde com `400` indicando o campo. `GET /v3/travel-rule/vasps/{vasp_id}/` devolve uma linha pelo respetivo `id`. O perfil do seu próprio VASP nunca aparece nos seus próprios resultados.

`dd_status`, `dd_score`, `dd_score_breakdown`, `dd_assessed_at`, `dd_score_semantic`, `risk_level`, `responsiveness` e `essential_checks` contêm a avaliação partilhada de due diligence de uma entrada do diretório. `decision`, `entity_screening` e `questionnaires` são registos da própria aplicação sobre o VASP, e nenhum outro cliente os vê. Consulte [Due diligence da contraparte](#diligência-devida-da-contraparte) para saber o que cada um significa, e aplique restrições com os [campos de regras da contraparte](#campos-e-predefinições-de-regras) em vez de criar ramificações em linha. Os membros da rede Didit não são pontuados: `dd_status` é `COMPLETED`, `dd_score` é `null`, `risk_level` está vazio e o detalhamento está vazio.

### Rotas

`routes` lista as formas como a sua aplicação pode entregar ao VASP, pela ordem em que são tentadas pela hierarquia de encaminhamento, e `reachable` é `true` quando pelo menos uma está `available`:

* `TRP` quando a entrada inclui um endpoint TRP verificado pelo diretório.
* `GTR`, `TRUST`, `VERIFYVASP`, `SYGNA` quando uma rede lista o VASP sob um código. A rota está `available` apenas quando a sua aplicação pode enviar através dessa rede hoje (`via: own_membership` para a sua própria adesão ligada, `via: didit_membership` para a da Didit). Caso contrário, está `unavailable` com `reason: no_membership` ou `reason: network_switched_off`, nunca sendo apresentada como uma forma de alcançar o VASP. As adesões a redes da própria Didit ainda não estão ativas, pelo que hoje uma rota de rede está disponível apenas através de uma adesão que a sua aplicação associou no Marketplace.
* `EMAIL` quando existe um contacto de conformidade para a entrada.
* `INTERNAL` para um membro da rede Didit.

Uma listagem `TRISA` aparece em `networks` e indica quem é o VASP na TRISA, mas a Didit não tem um canal TRISA, pelo que nunca é uma rota.

Uma aplicação de sandbox envia apenas para o [Didit Test VASP](https://docs.didit.me/pt/transaction-monitoring/travel-rule-sandbox.md), pelo que nenhuma rota do diretório está disponível para ela: todas as rotas estão `unavailable` com `reason: sandbox_application`, todas as linhas têm `reachable: false`, e `reachable=true` não devolve linhas.

### Marcas e as respetivas entidades

Uma marca que opera através de várias entidades reguladas constitui uma linha cujas `entities` são as entidades legais que recebem as suas transferências; uma linha de entidade aponta de volta para a sua marca em `umbrella`. Uma transferência que indique a marca vai para uma das suas entidades, escolhida de entre todas elas: aquela na jurisdição indicada em `beneficiary_data.counterparty_vasp_jurisdiction`, caso contrário a entidade que a [atribuição de análise de blockchain](#atribuição-por-análise-de-blockchain) associou à carteira de destino, caso contrário a única entidade da marca quando nenhuma jurisdição for indicada. Só então essa entidade deve estar alcançável; se não estiver, a transferência nunca vai para outra entidade nem para a marca em substituição. Quando nenhuma entidade se adequa (duas adequam-se igualmente, ou uma jurisdição indicada na qual nenhuma delas se encontra), é utilizada a rota da própria marca e, sem ela, a transferência fica como `COUNTERPARTY_VASP_NOT_FOUND`. A escolha da entidade legal que recebe os dados do ordenante nunca é feita por suposição, e nunca é decidida com base em que entidade tem por acaso um contacto.

Várias entradas com o mesmo nome, como empresas do grupo que partilham um nome comercial, são diferenciadas pela mesma regra: a que estiver na jurisdição indicada, caso contrário a que a atribuição de análise de blockchain tiver associado. Quando nenhuma das opções seleciona uma, nenhuma é utilizada, e os detalhes contam como não indicando qualquer entrada do diretório.

### Contactos

`contacts` são os endereços para os quais o canal `EMAIL` escreve. Os contactos com `scope: platform` servem todos os clientes Didit: a Didit faz a sua curadoria (`source: staff`), ou um endereço num dos domínios do próprio VASP respondeu a um pedido através da sua ligação de resposta (`source: learned`). Os contactos com `scope: application` são privados para a sua aplicação: os que adiciona (`source: application`), e um endereço fora dos domínios do próprio VASP que respondeu a um dos seus pedidos (`source: learned`). Uma transferência envia um e-mail primeiro para o contacto da sua própria aplicação, depois para um contacto da plataforma que já tenha respondido anteriormente (`verified_at` definido) e, em seguida, para os restantes.

Faça a gestão dos contactos da sua própria aplicação com a API de contactos de contrapartes:

```bash theme={null}
curl -X POST https://verification.didit.me/v3/travel-rule/counterparty-contacts/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"counterparty": "0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91", "email": "compliance@counterparty.example", "name": "Compliance desk"}'
```

* `GET /v3/travel-rule/counterparty-contacts/` lista todos os contactos para os quais a sua aplicação pode enviar, incluindo contactos da plataforma e contactos com mensagens devolvidas, os mais recentes primeiro, paginados com `limit` e `offset`. Filtre com `?counterparty=` e um `id` de entrada do diretório; um valor que não seja um UUID responde com `400`.
* `POST` adiciona um contacto privado (`counterparty`, `email`, opcional `name`) e responde com `201`. Adicionar um endereço que a entrada já tenha entre os seus próprios contactos devolve esse contacto. Uma entrada desconhecida responde com `400` (`"No directory entry with this id."`).
* `DELETE /v3/travel-rule/counterparty-contacts/{contact_uuid}/` elimina um dos seus próprios contactos (`204`). Os contactos da plataforma não podem ser eliminados e respondem com `404`.

Um contacto cuja mensagem foi devolvida ou que apresentou uma reclamação tem `is_invalid: true`, com `invalid_reason` (`hard_bounce`, `soft_bounce`, `spam_complaint` ou `suppressed`), `invalid_detail` e `invalid_at`, e o canal `EMAIL` ignora-o. `created_by` está vazio em contactos da plataforma e em contactos adicionados por uma chave de API.

### Como as entradas entram no diretório

* O registo provisório MiCA da ESMA de prestadores de serviços de criptoativos, consultado semanalmente: o nome de cada prestador, LEI e Estado-Membro de origem.
* O diretório público da TRISA, consultado semanalmente: a identidade de cada membro, o seu país e a sua listagem TRISA. Uma listagem que o diretório deixe de apresentar durante três semanas é removida.
* O registo global de LEI preenche o LEI, outras denominações sociais e o país de uma entrada, e localiza o LEI de uma entrada pela sua denominação social exata no respetivo país.
* A [atribuição por análise de blockchain](#atribuição-por-análise-de-blockchain) adiciona ou faz corresponder o VASP detentor de uma carteira de destino, mantendo o nome atribuído como um alias.
* A equipa da Didit faz a curadoria das entradas: identificadores de encaminhamento e listagens de rede verificados por esta, contactos de conformidade, aliases, marcas e as respetivas entidades, duplicados fundidos e entradas ocultadas.

Os dados comunicados por um cliente sobre uma contraparte, tais como um `originating_vasp` recebido ou um Travel Address, permanecem na transferência desse cliente e nunca alteram uma entrada partilhada. As entradas são correspondidas primeiro pelo LEI, depois pelo nome exato ou alias, e são enriquecidas em vez de duplicadas.

### A rede Didit

O perfil do seu VASP faz parte da rede Didit, pelo que outros clientes da Didit conseguem encontrá-lo no diretório e no seletor de VASP do utilizador final, apenas se todas as seguintes condições se verificarem:

* a sua aplicação está em produção (não na sandbox) e a Travel Rule está ativa;
* `is_discoverable` está a `true` e `legal_name` está definido;
* `compliance_email` está definido e confirmado: envie a confirmação com `POST /v3/travel-rule/settings/compliance-email/confirmation/` e abra a ligação enviada por e-mail. Alterar o endereço exige uma nova confirmação;
* a Didit não marcou a aplicação como teste, demonstração ou aplicação interna.

O canal `INTERNAL` em si realiza a entrega numa carteira cuja posse comprovou, conforme descrito em [Enviar uma transferência](#enviar-uma-transferência): apenas necessita que a sua aplicação esteja em produção, com a Travel Rule ativa e `is_discoverable`, dispensando o resto da lista.

`GET /v3/travel-rule/settings/` devolve `didit_network`: `listed`, `compliance_email_confirmed`, e em `missing` cada condição ainda não cumprida (`travel_rule_off`, `sandbox_application`, `not_discoverable`, `legal_name_missing`, `compliance_email_missing`, `compliance_email_unconfirmed`, `excluded_by_staff`, `internal_organization`).

### Identificadores de encaminhamento

O encaminhamento de saída consulta uma entrada do diretório sempre que a sua transferência identifica a contraparte por `counterparty_vasp_lei` ou `counterparty_vasp_name` (um alias também funciona). Uma entrada inclui um identificador por rede na qual pode ser contactada, um endpoint TRP verificado e os seus contactos de conformidade, e `routes` mostra quais deles a sua aplicação pode utilizar. Pode sempre ignorar o diretório numa única transferência transmitindo os campos explícitos em [Campos de resolução da contraparte](#campos-de-resolução-da-contraparte).

## Diligência devida da contraparte

Antes de os fundos dos seus clientes chegarem a outro VASP, precisa de saber quem é esse VASP e se o aceita. A diligência devida sobre uma contraparte tem duas camadas:

* **A avaliação partilhada.** Cada entrada do diretório inclui uma pontuação de diligência devida, o respetivo nível de risco, um estado de capacidade de resposta e um relatório de verificações essenciais. A Didit calcula-os a partir dos dados da própria plataforma, para que todos os clientes vejam os mesmos valores.
* **Os seus próprios registos.** A sua decisão sobre o VASP, a sua triagem de sanções e de notícias adversas do mesmo, e os questionários de diligência devida que trocou com ele pertencem unicamente à sua aplicação. Outro cliente nunca os vê e nunca alteram a entrada partilhada.

Os seus próprios registos funcionam de igual forma para uma entrada do diretório e para um membro da [rede Didit](#a-rede-didit): identifique ambos através do `id` que o [diretório](#diretório) apresenta.

| Endpoint | O que faz |
| - | - |
| `GET` / `PUT` / `DELETE /v3/travel-rule/vasps/{vasp_id}/decision/` | Consultar, definir ou limpar [a sua decisão](#a-sua-decisão-sobre-uma-contraparte) sobre a contraparte. |
| `GET` / `POST /v3/travel-rule/vasps/{vasp_id}/screening/` | Consultar a sua [triagem da contraparte](#triagem-de-contrapartes) mais recente ou executar uma. |
| `GET` / `POST /v3/travel-rule/vasps/{vasp_id}/questionnaires/` | Listar os seus [questionários de diligência devida](#questionário-de-diligência-devida) com a contraparte ou enviar um. |
| `GET /v3/travel-rule/transfers/?counterparty={vasp_id}` | As suas [transferências com essa contraparte](#transferências-com-uma-contraparte). |

### Pontuação e nível de risco

O `dd_score` varia de 0 a 100 e **quanto mais elevado, mais seguro**. Todos os resultados indicam-no em `dd_score_semantic`, que é sempre `higher_is_safer`. O `risk_level` é o intervalo em que a pontuação se enquadra:

| `risk_level` | `dd_score` |
| - | - |
| `LOW` | 70 ou mais |
| `MEDIUM` | 40 a 69 |
| `HIGH` | Inferior a 40 |

A pontuação é a soma de sete componentes. O `dd_score_breakdown` apresenta cada um como `{points, max, reason, detail}`: `max` é o peso do componente, `reason` um código legível por máquina que pode traduzir e `detail` uma explicação de uma linha em inglês.

| Componente | Peso | Como pontua | Códigos de `reason` |
| - | - | - | - |
| `jurisdiction` | 25 | Total quando o país da entrada não consta da lista predefinida de jurisdições de alto risco (`IRN`, `PRK`, `SYR`, `AFG`, `RUS`, `MMR`), zero quando consta, metade quando o país é desconhecido. | `jurisdiction_not_high_risk`, `jurisdiction_high_risk`, `jurisdiction_unknown` |
| `verification` | 15 | Estado de verificação da Didit para a entrada (`dd_status`): total para `COMPLETED`, metade para `IN_PROGRESS`, um quarto para `NOT_STARTED`, zero para `REJECTED`. | `dd_status_completed`, `dd_status_in_progress`, `dd_status_not_started`, `dd_status_rejected` |
| `protocol` | 15 | Total quando uma via de protocolo nativa alcança a entrada (um endpoint TRP ou a via `INTERNAL`), 40 por cento quando apenas o recurso alternativo por e-mail o faz, zero sem uma via alcançável. | `native_rail`, `email_only`, `no_rail` |
| `lei` | 10 | Total com um LEI válido registado, zero sem ele. | `lei_valid`, `lei_missing` |
| `history` | 10 | A percentagem das trocas decididas da entrada que foram bem-sucedidas, metade caso não exista nenhuma. | `history`, `no_history` |
| `essentials` | 15 | A percentagem de [verificações essenciais](#verificações-essenciais) decididas que são aprovadas, metade enquanto nenhuma estiver decidida. | `essential_checks`, `no_essential_checks` |
| `responsiveness` | 10 | Total para `RESPONSIVE`, zero para `UNRESPONSIVE`, metade para `UNKNOWN`. Consulte [Capacidade de resposta](#capacidade-de-resposta). | `responsive`, `unresponsive`, `responsiveness_unknown` |

Os pontos são arredondados a uma casa decimal e o total a um número inteiro. O `history` avalia os mesmos pedidos que a [capacidade de resposta](#capacidade-de-resposta), sem janela temporal: uma troca com o estado `COMPLETED` ou `FINISHED` é um sucesso, e uma troca com o estado `EXPIRED`, `COUNTERPARTY_MISMATCHED_DATA` ou `COUNTERPARTY_VASP_GENERAL_DECLINE` é uma falha. Um cancelamento é um ato do próprio remetente e nunca é contabilizado.

A Didit recalcula a avaliação quando uma troca com a entrada é concluída, finalizada, expira, apresenta discrepâncias ou é recusada, quando atualiza ou faz a curadoria da entrada, e para cada entrada na atualização semanal do diretório. O `dd_assessed_at` indica quando foi executada pela última vez; uma entrada que ainda não tenha sido avaliada não tem `dd_assessed_at`, tem um `dd_score` de `0` e um `risk_level` vazio, pelo que deve ler o `risk_level` em vez da pontuação em bruto. Os membros da rede Didit não são pontuados: o respetivo `dd_score` é `null`, o respetivo `risk_level` está vazio e o respetivo `dd_score_breakdown` está vazio.

### Verificações essenciais

O `essential_checks` é um breve relatório sobre quatro verificações que a Didit executa em cada entrada do diretório, apenas a partir de fontes verificadas da plataforma, nunca a partir de dados reportados por um cliente:

| `id` da verificação | É aprovada quando |
| - | - |
| `registration` | Um registo oficial lista o VASP: o registo provisório do MiCA da UE de prestadores de serviços de criptoativos, o diretório público do TRISA ou o registo global de LEI com um LEI emitido. |
| `licence` | O registo do MiCA regista uma autorização para o VASP que não tenha terminado. |
| `domain` | O domínio da entrada corresponde ao respetivo endpoint TRP ou ao site indicado pelo seu registo. |
| `lei` | O registo LEI da entrada está ativo e emitido, e a respetiva denominação social e país correspondem à entrada. |

Cada verificação em `checks` reporta o seu `status` (`pass`, `fail`, ou `unknown` quando nenhuma fonte registada o consegue decidir), um `reason` legível por máquina e um `detail` de uma linha em inglês. `passed`, `failed`, `unknown` e `total` contabilizam-nas, `level` é `essential` e `checked_at` indica quando o relatório foi gerado. O componente `essentials` pontua a percentagem de verificações decididas que são aprovadas, pelo que uma verificação com `unknown` não conta nem a favor nem contra a entrada. O relatório está vazio até que a atualização semanal do diretório verifique uma entrada pela primeira vez, e está sempre vazio para um membro da rede Didit.

### Capacidade de resposta

O `responsiveness` indica se o VASP responde a pedidos de Travel Rule:

```json theme={null}
{ "status": "UNRESPONSIVE", "answered": 0, "total": 6, "computed_at": "2026-10-12T09:30:00Z" }
```

O `total` contabiliza os pedidos iniciados pelos clientes da Didit destinados ao VASP nos últimos 90 dias cujo resultado foi decidido, e o `answered` os pedidos aos quais este respondeu:

* **Contabilizados:** pedidos enviados através de uma rede ou via de protocolo, e pedidos enviados por e-mail para um endereço partilhado, que seja o endereço de conformidade da entrada ou um contacto da plataforma.
* **Nunca contabilizados:** um pedido enviado por e-mail para um endereço introduzido por um cliente ou para um contacto privado de um cliente. Essa troca permanece no histórico de transferências do próprio cliente e nunca rotula o VASP para todos os outros.
* **Respondidos:** `COMPLETED`, `FINISHED`, `COUNTERPARTY_VASP_GENERAL_DECLINE` ou `COUNTERPARTY_MISMATCHED_DATA`. Uma recusa ou uma discrepância é uma resposta: o VASP interagiu.
* **Não respondidos:** `EXPIRED`.
* **Nenhum dos dois:** todos os restantes estados. Um pedido `CANCELLED` é um ato do próprio remetente, `COUNTERPARTY_VASP_NOT_REACHABLE` pode ser uma falha do lado do remetente e um pedido que ainda esteja em curso ainda não foi decidido.

| `status` | Quando |
| - | - |
| `UNKNOWN` | Menos de 5 pedidos decididos na janela, pelo que um único pedido expirado nunca rotula um VASP. |
| `UNRESPONSIVE` | O VASP respondeu a menos de 10 por cento dos seus pedidos decididos. |
| `RESPONSIVE` | Caso contrário. |

Os membros da rede Didit respondem dentro da Didit e mostram sempre `UNKNOWN` com contagens a zero. Atue sobre uma contraparte que não responde com a [política de não resposta](#políticas-de-sunrise-e-de-não-resposta) ou com a [predefinição](#campos-e-predefinições-de-regras) `travel-rule-counterparty-unresponsive`.

### A sua decisão sobre uma contraparte

Registe o veredito da sua equipa de conformidade sobre uma contraparte com `PUT /v3/travel-rule/vasps/{vasp_id}/decision/`:

```bash theme={null}
curl -X PUT https://verification.didit.me/v3/travel-rule/vasps/0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91/decision/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decision": "BLOCKED", "reason": "Unlicensed in its home jurisdiction"}'
```

```json theme={null}
{
  "decision": {
    "decision": "BLOCKED",
    "reason": "Unlicensed in its home jurisdiction",
    "decided_by": "",
    "updated_at": "2026-10-14T10:05:00Z",
    "inherited_from": null
  }
}
```

| `decision` | Significado | Predefinição que atua sobre ela |
| - | - | - |
| `APPROVED` | A sua equipa aprovou a contraparte. | Nenhuma |
| `RESTRICTED` | As transferências para a mesma podem avançar após revisão. | `travel-rule-counterparty-restricted` retém-nas para revisão. |
| `BLOCKED` | A sua equipa recusou a contraparte. | `travel-rule-counterparty-blocked` recusa-as. |

* A decisão é privada para a sua aplicação: outro cliente nunca a vê e nunca altera a entrada partilhada.
* Uma decisão não altera nada por si só e nunca altera a forma como uma transferência é encaminhada. Chega às suas transações através do [campo de regra](#campos-e-predefinições-de-regras) `counterparty_dd_status`: instale as predefinições ou escreva a sua própria regra sobre o mesmo.
* Uma decisão sobre uma marca abrange cada uma das suas [entidades](#marcas-e-as-respetivas-entidades) que não tenha uma decisão própria, e a entidade mostra a marca em `inherited_from`. Uma decisão sobre a entidade sobrepõe-se à da marca para essa entidade.
* `GET` devolve a decisão aplicável ou `{"decision": null}`. `DELETE` limpa a sua própria decisão e devolve o que se aplica a seguir: a decisão da marca para uma entidade; caso contrário, `null`. Responde com `404` quando a sua aplicação não tem uma decisão própria sobre a contraparte.
* `reason` é opcional, tem até 255 carateres e cada `PUT` substitui-o. `decided_by` é o utilizador da consola que tomou ou alterou pela última vez a decisão e fica vazio quando foi uma chave de API a fazê-lo.

### Triagem de contrapartes

A triagem de contrapartes verifica o próprio VASP da contraparte, enquanto empresa, contra sanções e notícias adversas. É **opcional e faturada**: ative-a com `counterparty_screening_enabled` nas suas [definições](#configuração). Enquanto estiver desativada, nada é analisado ou faturado.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/travel-rule/vasps/0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91/screening/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"refresh": false}'
```

```json theme={null}
{
  "outcome": "screened",
  "screening": {
    "id": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "status": "In Review",
    "total_hits": 2,
    "score": 85.0,
    "screened_at": "2026-10-14T09:58:00Z",
    "fresh": true,
    "flagged": true
  }
}
```

* **Faturação.** Cada nova triagem custa o [preço](https://docs.didit.me/pt/getting-started/pricing.md) de Triagem AML de empresas da sua organização. O `GET /v3/travel-rule/vasps/{vasp_id}/screening/` devolve esse `price`, `fresh_days` e se a triagem está `enabled`, sem custos. Uma triagem com menos de 30 dias é recente: o `POST` devolve-a novamente com `200` e `outcome: reused` e não fatura nada, a menos que envie `refresh: true`. Uma nova triagem devolve `201` com `outcome: screened`. As aplicações em sandbox nunca são analisadas nem faturadas.
* **Triagem automática.** Com a triagem ativada, a Didit também analisa a contraparte que uma exchange de saída contacta quando a exchange se inicia, antes de as suas regras avaliarem a transação, com a mesma reutilização e faturação. Uma recusa ou falha nesse ponto nunca faz falhar a transferência.
* **Resultado.** O `status` é `Approved` quando nenhuma correspondência potencial necessita de atenção, e `In Review` ou `Declined` para uma possível correspondência em sanções ou notícias adversas. `flagged` é `true` enquanto uma triagem recente estiver em `In Review` ou `Declined`.
* **Efeito.** Enquanto a sua triagem mais recente de uma contraparte estiver sinalizada e a triagem permanecer ativada, `counterparty_risk_level` é `HIGH` nas suas regras, pelo que a predefinição `travel-rule-counterparty-high-risk`, depois de instalada, retém as suas transferências. O `risk_level` partilhado no diretório não muda.
* **Privacidade.** A triagem é privada para a sua aplicação: outro cliente nunca a vê e nunca altera a entrada partilhada. O diretório mostra a sua mais recente como `entity_screening`.
* **Recusas.** `409` quando a triagem está desativada, para uma aplicação sandbox, ou enquanto uma triagem da mesma contraparte já estiver em execução. `403` com `code: insufficient_credits` quando o seu saldo não cobrir o preço. `502` quando a triagem não pôde ser concluída. Nenhuma delas fatura nada.

### Questionário de diligência devida

Peça a uma contraparte as suas respostas de diligência devida com o questionário padrão da Didit. O `POST /v3/travel-rule/vasps/{vasp_id}/questionnaires/` envia-o por e-mail para um endereço de conformidade registado para a contraparte, com uma ligação de utilização única para uma página de resposta:

```bash theme={null}
curl -X POST https://verification.didit.me/v3/travel-rule/vasps/0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91/questionnaires/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sent_to": "travelrule@counterparty.example"}'
```

```json theme={null}
{
  "id": "3f9e8d7c-6b5a-4c3d-9e2f-1a0b9c8d7e6f",
  "status": "SENT",
  "form_version": "1",
  "sent_to": "travelrule@counterparty.example",
  "sent_at": "2026-10-14T10:00:00Z",
  "expires_at": "2026-11-13T10:00:00Z",
  "answered_at": null,
  "valid_until": null,
  "current": false,
  "answers": {}
}
```

* **Para onde vai.** `sent_to` deve ser um endereço de conformidade registado: para uma entrada de diretório, o seu endereço de conformidade ou um contacto que a sua aplicação veja em `contacts`; para um membro da rede Didit, o seu e-mail de conformidade confirmado. Omita-o para utilizar o endereço para o qual vai um e-mail de Travel Rule para a contraparte: primeiro o seu próprio contacto, depois um contacto da plataforma e, a seguir, o endereço de conformidade da entrada. A Didit nunca envia o questionário para nenhum outro local e responde com `400` quando a contraparte não tiver um endereço de conformidade registado.
* **Responder.** A ligação abre `/v3/travel-rule/questionnaires/{token}/`, uma página para uma pessoa da contraparte que não necessita de conta nem de chave de API. Responde a cada pergunta, com até 2000 carateres cada (`N/A` onde não se aplique), e submete uma vez. Uma contraparte também pode enviar um pedido POST com `{"answers": {"<question id>": "<answer>"}}` para a mesma ligação. Uma ligação que tenha sido utilizada, substituída ou cujo prazo tenha expirado mostra, em vez disso, uma página de expiração. O e-mail e a página são traduzidos; as perguntas em si estão sempre em inglês, para que o seu significado nunca mude entre idiomas.
* **Prazos.** A contraparte tem 30 dias para responder (`expires_at`). As respostas permanecem válidas durante 365 dias (`valid_until`), e `current` é `true` até então. Um questionário sem resposta após o prazo, e respostas fora da sua validade, tornam-se `EXPIRED`.
* **Um questionário aberto por contraparte.** Um novo envio substitui o seu questionário anterior sem resposta para a mesma contraparte: torna-se `EXPIRED` e a sua ligação deixa de funcionar. Pode ser enviado um e-mail por minuto para um endereço; um envio mais rápido responde com `429`.
* **Ler as respostas.** O `GET /v3/travel-rule/vasps/{vasp_id}/questionnaires/` lista os seus questionários com a contraparte, dos mais recentes para os mais antigos, com `answers` organizadas por id de pergunta assim que respondidas. O diretório mostra-os como `questionnaires`. São privados para a sua aplicação.

A versão `1` do formulário faz estas doze perguntas:

| ID da pergunta | Pergunta |
| - | - |
| `legal_name` | Nome da entidade jurídica e jurisdição de constituição. |
| `licensing` | Licenças ou registos detidos para serviços de ativos virtuais: regulador, número da licença e estado em cada jurisdição. |
| `jurisdictions` | Jurisdições onde opera e quaisquer jurisdições onde esteja excluído ou restringido. |
| `aml_program` | Resumo do seu programa AML/CFT: políticas, procedimentos e data da última auditoria ou revisão independente. |
| `compliance_officer` | Nome e função do seu responsável pela conformidade, e como pode ser contactado. |
| `sanctions_screening` | Como faz a triagem de clientes e contrapartes contra sanções e notícias adversas: fornecedor ou listas, frequência e escalamento. |
| `transaction_monitoring` | Como monitoriza transações para identificar atividades suspeitas: ferramentas, limiares e práticas de apresentação de relatórios. |
| `travel_rule` | Como cumpre a Travel Rule: protocolos e redes utilizados, e o seu tempo de resposta típico a um pedido. |
| `custody` | Disposições de custódia para ativos de clientes: custodiante qualificado, seguro e segregação. |
| `ownership` | Beneficiários efetivos com 25 por cento ou mais, e qualquer entidade-mãe ou agregadora. |
| `record_keeping` | Práticas de manutenção de registos e período de conservação para dados da Travel Rule e de transações. |
| `data_protection` | Como protege os dados pessoais partilhados para conformidade e onde são armazenados. |

### Transferências com uma contraparte

O endpoint [`GET /v3/travel-rule/transfers/?counterparty={vasp_id}`](https://docs.didit.me/pt/management-api/travel-rule/list-transfers) lista as transferências da Travel Rule da sua aplicação com uma contraparte, da mais recente para a mais antiga, pelo `id` que o diretório apresenta: as suas transferências cuja contraparte é essa entrada do diretório, ou os seus intercâmbios `INTERNAL` com esse membro da rede Didit. Um valor que não seja um ID válido devolve `400`.
Cada linha inclui `reason` logo após `status`: o próprio [`reason`](#por-que-motivo-uma-transferência-está-bloqueada) da transferência, para que a lista distinga um e-mail de conformidade devolvido de uma contraparte sem rota sem abrir cada transferência.

### Políticas de sunrise e de não resposta

Quando uma transferência expira (`confirmation_timeout_hours` decorreu enquanto estava em `AWAITING_COUNTERPARTY`), o `timeout_outcome` decide o que acontece à sua transação. Duas definições permitem-lhe tratar duas causas comuns para um tempo limite excedido de forma diferente:

| Definição | Aplica-se quando a contraparte é uma entrada de diretório que |
| - | - |
| `sunrise_policy` | Está numa jurisdição listada em `sunrise_jurisdictions`: um país que ainda não aplica a Travel Rule, pelo que o VASP não é obrigado a responder. |
| `non_responsive_policy` | Tem `responsiveness.status` como `UNRESPONSIVE`. |

Ambas aceitam `HOLD`, `REJECT` ou `PROCEED`, com o mesmo significado que para `timeout_outcome`, ou uma string vazia para seguir o `timeout_outcome`. Ambas estão vazias por predefinição, pelo que nada se altera até definir uma:

```bash theme={null}
curl -X PUT https://verification.didit.me/v3/travel-rule/settings/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sunrise_policy": "PROCEED", "non_responsive_policy": "HOLD"}'
```

A primeira destas que se aplicar decide o resultado:

1. `sunrise_policy`, quando estiver definida e a jurisdição da contraparte constar de `sunrise_jurisdictions`.
2. `non_responsive_policy`, quando estiver definida e a contraparte for `UNRESPONSIVE`.
3. `timeout_outcome` em todos os outros casos, incluindo uma transferência para um membro da rede Didit ou para uma contraparte sem entrada no diretório.

`sunrise_jurisdictions` é apenas de leitura e atualmente contém `["CO", "KH", "VN"]`. Apenas estes países contam como estando num período de sunrise: qualquer outra jurisdição, bem como uma vazia ou desconhecida, segue o `timeout_outcome`, para que uma contraparte nunca receba a sua política de sunrise por acidente. A cronologia da transferência expirada indica o resultado aplicado, por exemplo `sunrise_policy=PROCEED (counterparty jurisdiction CO does not enforce the Travel Rule yet)`. As suas regras continuam a ser executadas após a expiração, pelo que uma regra como a do TFR da UE `tr_eu_expired_review` ainda pode mover a transação para análise sob `PROCEED`.

### Campos e predefinições de regras

Quatro campos de [regra](https://docs.didit.me/pt/transaction-monitoring/rules.md) contêm o que a sua aplicação sabe sobre a contraparte que o intercâmbio de Travel Rule de uma transação alcançou: a sua entrada de diretório ou, no caso de um intercâmbio `INTERNAL`, o cliente da Didit que a recebeu. Cada campo fica vazio quando o intercâmbio não alcançou nenhuma contraparte conhecida.

| Campo | Valor |
| - | - |
| `counterparty_dd_status` | A sua [decisão](#a-sua-decisão-sobre-uma-contraparte): `APPROVED`, `RESTRICTED` ou `BLOCKED`, ou o de uma entidade que segue o da sua marca. Vazio quando não tomou nenhuma. Nunca a decisão de outro cliente. |
| `counterparty_risk_level` | O `risk_level` da entrada (`LOW`, `MEDIUM` ou `HIGH`), ou `HIGH` enquanto a sua própria [triagem](#triagem-de-contrapartes) da contraparte estiver sinalizada. Vazio para uma entrada ainda não avaliada e para um membro da rede Didit, a menos que a sua triagem do mesmo esteja sinalizada. |
| `counterparty_jurisdiction` | O país da contraparte, a partir da entrada de diretório ou do perfil do membro da rede Didit. Os códigos ISO-2 e ISO-3 são ambos comparados, tal como os outros campos de país. |
| `counterparty_responsiveness` | O `responsiveness.status` da entrada: `RESPONSIVE`, `UNRESPONSIVE` ou `UNKNOWN`. Vazio para um membro da rede Didit. |

Cinco predefinições no pacote `travel_rule` atuam sobre eles. Instale-as a partir de **Transactions → Rules → Library** na Business Console ou com a [API da biblioteca de regras](https://docs.didit.me/pt/management-api/transactions/rules-install.md):

| `library_key` | Acionador | Ação predefinida |
| - | - | - |
| `travel-rule-counterparty-blocked` | `counterparty_dd_status` é `BLOCKED` | +90 à pontuação, `DECLINED` |
| `travel-rule-counterparty-restricted` | `counterparty_dd_status` é `RESTRICTED` | +50 à pontuação, `IN_REVIEW` |
| `travel-rule-counterparty-high-risk` | `counterparty_risk_level` é `HIGH` | +40 à pontuação, `IN_REVIEW` |
| `travel-rule-counterparty-high-risk-jurisdiction` | `counterparty_jurisdiction` está na lista predefinida de alto risco (`IRN`, `PRK`, `SYR`, `AFG`, `RUS`, `MMR`) | +60 à pontuação, `IN_REVIEW` |
| `travel-rule-counterparty-unresponsive` | `counterparty_responsiveness` é `UNRESPONSIVE` | +30 à pontuação, `IN_REVIEW` |

Todas as cinco aplicam-se apenas a transações da Travel Rule.

## Webhooks

Subscreva um destino a `travel_rule.status.updated` para receber notificações em cada transição de estado de todas as transferências na sua aplicação, de saída e de entrada, incluindo os segmentos do rail `INTERNAL`.
O encaminhamento é executado após o retorno da criação da transação, pelo que resultados como `COUNTERPARTY_VASP_NOT_FOUND`, `COUNTERPARTY_VASP_NOT_REACHABLE`, ou uma troca `INTERNAL` liquidada de imediato chegam até si através deste evento em vez de serem incluídos na resposta de criação.

```json theme={null}
{
  "event_id": "9c0c8b8a-1111-4222-9333-666666666666",
  "webhook_type": "travel_rule.status.updated",
  "timestamp": 1774970000,
  "created_at": 1774970000,
  "application_id": "11111111-2222-3333-4444-555555555555",
  "environment": "live",
  "transaction_id": "22222222-3333-4444-5555-666666666666",
  "txn_id": "trv-2026-07-05-001",
  "travel_rule_status": "COMPLETED",
  "rail": "INTERNAL",
  "direction": "OUTBOUND"
}
```

O campo `rail` fica vazio até que um rail seja selecionado.
Para uma transação, o Didit envia `travel_rule.status.updated` após `transaction.created`: quando o Didit cria a transação (o seu `POST /v3/transactions/`, um registo sunrise, um pedido `TRP` de entrada ou o segmento de entrada do rail `INTERNAL`), envia primeiro `transaction.created`.
Cada evento é entregue e é feita uma nova tentativa de forma independente, pelo que um `transaction.created` que tenha necessitado de nova tentativa pode ainda chegar após um evento de estado: utilize `transaction_id` como chave no seu processador e leia a transação quando um evento de estado referenciar uma que ainda não tenha visto.
Uma transferência enviada através da `TRUST` não recebe nenhum evento `COMPLETED`: a TRUST não devolve nada que o Didit possa ler, pelo que, a menos que o envio falhe ou que o cancele, o seu último evento é `EXPIRED`. Na `GTR`, `VERIFYVASP` e `SYGNA`, o evento segue a resposta que o Didit lê da rede.
As aplicações sandbox também enviam este evento, com `"environment": "sandbox"`; uma transferência respondida pelo [Didit Test VASP](https://docs.didit.me/pt/transaction-monitoring/travel-rule-sandbox.md) inclui `rail: "TEST_VASP"`, `test_vasp: true` e `test_vasp_scenario`.

Consulte o [guia de webhooks](https://docs.didit.me/pt/integration/webhooks.md#tipos-de-eventos) para ver o catálogo completo de eventos, a verificação da assinatura e a política de novas tentativas.

## Preços

A taxa da Travel Rule é de **\$0.02 por troca de saída iniciada**, cobrada uma vez aquando da criação da transação, independentemente de quantas transições de estado a troca atravesse posteriormente. Um `resend` nunca a cobra novamente.

* Aplica-se a uma transação `travelRule` de saída numa aplicação com a Travel Rule ativada, cujo montante seja igual ou superior ao seu `threshold_amount`, para que o Didit inicie uma troca gerida para essa transação. Uma transferência para uma carteira autocustodiada, ou para a própria carteira verificada do seu utilizador, também conta: a prova de propriedade é a respetiva troca.
* Todas as outras transações de saída que transportem dados da Travel Rule são faturadas como Triagem de transações padrão, que o seu plano inclui até ao respetivo [limite mensal de transações](https://docs.didit.me/pt/getting-started/pricing.md#monitorização-de-transações-kyt) e tem o preço de \$0.001 para além desse limite: uma transferência abaixo do seu limiar, um pagamento Lightning ao qual a Travel Rule não se aplica e uma transferência registada passivamente enquanto a Travel Rule está desativada. Uma transação é faturada numa das duas linhas, nunca em ambas.
* As transações `travelRule` de entrada não têm taxa da Travel Rule ou de monitorização: o segmento de entrada que o Didit cria na aplicação do beneficiário através do rail `INTERNAL`, pedidos `TRP` de entrada e [registos após depósito](#registo-sunrise-posterior-ao-depósito).
* Uma aplicação que tenha aderido gratuitamente à Travel Rule não paga nenhuma das taxas em transações `travelRule` de saída até ativar a faturação de saída com `POST /v3/travel-rule/workspace/billing/`; a receção permanece gratuita.
* As aplicações sandbox nunca são cobradas.
* A taxa da Travel Rule é de $0.02 e a Triagem de transações é de $0.001 para além do seu limite incluído. Cada transação é cobrada pelo preço da linha em que é faturada.
* Se a triagem AML de cripto/carteiras também for executada na mesma transação (por exemplo, um depósito de entrada com `currency_kind: "crypto"` e monitorização ativada), isso é faturado separadamente à taxa padrão de Verificação e Triagem de Carteiras - não está incluído na taxa da Travel Rule.
* A [triagem de contrapartes](#triagem-de-contrapartes) é opcional e faturada separadamente, ao preço de Triagem AML de empresas por triagem; uma triagem com menos de 30 dias é reutilizada sem custos. Decisões, questionários e a avaliação de diligência devida do diretório não têm custos.

### Preços de atribuição

A [atribuição por análise de blockchain](#atribuição-por-análise-de-blockchain) necessita de uma consulta de carteira junto do fornecedor de análise, e você obtém sempre o valor total dessa consulta:

* **A monitorização de cripto já fez a triagem da carteira nesta transação** - o resultado armazenado é reutilizado. Uma chamada de análise, uma cobrança de Verificação e Triagem de Carteiras (aquela que a monitorização de cripto já efetuou). A atribuição não acrescenta custos.
* **A monitorização de cripto não foi executada** - o Didit faz a chamada de análise necessária uma única vez e transmite o seu valor total: a transação é cobrada à taxa padrão de Verificação e Triagem de Carteiras (\$0.15 com análise gerida pelo Didit) e recebe em troca o resultado completo da triagem de cripto - pontuação de risco, categoria de risco da carteira, instantâneo da rede - e não apenas o nome do VASP. O item de utilização é marcado com o acionador `travel_rule_attribution` para que a cobrança seja explicável.
* **Chave de análise própria** - a mesma taxa de plataforma que se aplica à monitorização de cripto com a sua própria chave aplica-se aqui (\$0.02 por chamada). O seu fornecedor fatura-lhe diretamente a consulta subjacente.
* **As consultas falhadas nunca são cobradas**, os reenvios reutilizam a atribuição registada sem uma nova chamada ou cobrança, e as aplicações sandbox nunca são cobradas.

Portanto, uma transferência de saída que necessitou de atribuição custa \$0.02 (Travel Rule) + uma cobrança de Verificação e Triagem de Carteiras - e quando ambos os produtos estão ativados, a chamada de análise e a respetiva cobrança ocorrem apenas uma vez.

## Pacote de regras TFR da UE

Quatro regras pré-definidas são fornecidas no pacote `travel_rule_eu_tfr`, concebidas especificamente para as obrigações do TFR da UE.
Tal como qualquer outro [pacote pré-definido](https://docs.didit.me/pt/transaction-monitoring/rules-library.md), ative-o a partir da Business Console em **Transactions → Rules → Library**.

| Regra (`library_key`) | Acionador | Ação |
| - | - | - |
| `tr_eu_mismatch_hold` | O estado da transferência é `COUNTERPARTY_MISMATCHED_DATA` | Adicionar `+50` à pontuação, transação colocada em `IN_REVIEW` |
| `tr_eu_unverified_selfhosted_review` | O estado da transferência é `UNCONFIRMED_OWNERSHIP` e o montante na moeda predefinida é de pelo menos `1000` | Transação colocada em `IN_REVIEW` |
| `tr_eu_vasp_not_found_score` | O estado da transferência é `COUNTERPARTY_VASP_NOT_FOUND` | Adicionar `+25` à pontuação, etiquetada com `travel-rule-sunrise` |
| `tr_eu_expired_review` | O estado da transferência é `EXPIRED` | Transação colocada em `IN_REVIEW` |

Estas regras são acionadas em todas as transições relevantes - na criação da transferência, na confirmação de propriedade, na resposta à recolha por e-mail e através do processo de limpeza de transferências expiradas - para que uma transferência que nunca seja concluída continue a surgir para revisão de conformidade em vez de ser liquidada silenciosamente.

## Por que motivo funciona melhor numa única plataforma

A conformidade com a Travel Rule é um problema de identidade disfarçado de pagamentos - e a Didit já detém a identidade:

* **Dados verificados disponíveis.** A pessoa associada a cada transferência está associada através de `vendor_data` ao perfil de KYC que a Didit verificou no onboarding (OCR de documentos, prova de vida, correspondência facial), para que possa construir `originator_data` a partir de campos verificados na mesma plataforma.
  Para um utilizador com uma verificação de KYC aprovada, a Didit transmite a identidade verificada em vez dos valores que introduziu (consulte [Dados verificados e proveniência](#dados-verificados-e-proveniência)).
* **Biometria adicional para transferências de risco.** Uma [regra](https://docs.didit.me/pt/transaction-monitoring/rules.md) pode reter qualquer transferência de valor elevado até que o utilizador passe por uma nova verificação biométrica contra o rosto capturado no onboarding - a resposta mais forte possível à tomada de controlo de conta no momento do levantamento. Consulte o [exemplo prático](https://docs.didit.me/pt/transaction-monitoring/sdk-transaction-submission.md#exemplo-verificação-biométrica-reforçada-para-um-levantamento-de-valor-elevado).
* **Um único grafo de dispositivos.** As transferências submetidas através do SDK contêm os mesmos dados de inteligência sobre o dispositivo que as sessões de KYC, pelo que "novo dispositivo + montante elevado + beneficiário pela primeira vez" é uma única regra, e não uma junção no armazém de dados.
* **Triagem, regras, casos e a troca num único local.** A triagem de carteiras que atribui o VASP da contraparte é a mesma triagem que as suas regras e analistas veem - uma cobrança, uma consola, um registo de auditoria.
* **Preços públicos.** [\$0.02 por troca de saída](#preços), sem níveis de volume, sem chamadas de vendas.

## FAQ

### Como funciona a troca

> [accordion] A Didit executa a troca VASP a VASP diretamente ou apenas regista os dados da Travel Rule após outra rede concluir o handshake?
>
> A Didit executa a troca diretamente.
> Quando submete uma transferência `travelRule`, a Didit realiza a descoberta de contrapartes em tempo real, envia os dados do ordenante e do beneficiário para o VASP recetor nos canais que os transportam e marca a transferência como `COMPLETED` apenas quando a contraparte a confirmar - trata-se de um handshake gerido, não de um registo pós-liquidação.
> A resposta de uma contraparte é processada em todos os canais, exceto no `TRUST`, que apenas envia, pelo que uma transferência através dele expira em vez de ser concluída. No `GTR`, `VERIFYVASP` e `SYGNA`, a Didit lê a resposta a partir da resposta da rede ou consultando-a a cada 5 minutos, e nenhuma troca através destes foi ainda concluída contra uma rede em produção; no `TRP`, uma resposta que a contraparte não forneça de imediato requer o anfitrião público TRP da Didit, que ainda não está ativo (consulte [Redes da Travel Rule](https://docs.didit.me/pt/transaction-monitoring/travel-rule-networks.md)).
> A Didit também mantém o registo completo e o estado de conformidade de cada troca (um [ciclo de vida](#ciclo-de-vida) de 13 estados, [webhooks](#webhooks) e um registo de auditoria).
> Se preferir executar a Travel Rule através do seu próprio processo, a Didit pode, em alternativa, registar os dados passivamente como o seu sistema único de registo (consulte a pergunta sobre registo passivo abaixo).
> Ambos os modos estão disponíveis: a troca ativa é executada assim que definir `is_enabled: true` nas [definições](#configuração) (está como `false` por predefinição) e, até lá, a Didit regista os dados de forma passiva.

> [accordion] A troca é nativa da Didit ou depende de um fornecedor externo de interoperabilidade (Notabene, Sygna, VerifyVASP, TRP)?
>
> É nativa. A Didit executa a sua própria implementação do Travel Rule Protocol (TRP), disponibilizada em `trp.didit.me` assim que esse anfitrião público estiver ativo (ainda não responde, pelo que as contrapartes não conseguem contactá-lo por TRP hoje), e implementa diretamente os protocolos de rede da indústria - `GTR` (Global Travel Rule), `TRUST`, `VerifyVASP` e `Sygna Bridge` (falado nativamente, incluindo o IVMS 101 encriptado com ECIES da Sygna e pedidos de permissão assinados). A Didit não é um revendedor de uma única camada de interoperabilidade de terceiros. Contactar uma contraparte que pertença a uma rede de adesão específica ocorre necessariamente através dessa rede - não existe um canal universal único na Travel Rule - mas a descoberta, o handshake, a verificação e a conservação de registos são todos executados pela Didit.
> Atualmente, cada canal de rede requer a sua própria adesão, e o `TRUST` apenas envia: consulte [Visão geral](#visão-geral).

> [accordion] Que redes e protocolos da Travel Rule são suportados pela Didit?
>
> Implementados nativamente, tentados por ordem estrita de prioridade: `INTERNAL` (ambos os VASP na Didit), `TRP` (OpenVASP Travel Rule Protocol), `GTR`, `TRUST`, `VerifyVASP`, `Sygna Bridge` e um recurso de contingência por `EMAIL` para contrapartes sem ferramentas.
> Os canais de rede requerem a sua própria adesão atualmente, o `TRUST` apenas envia e a receção através de uma rede ainda não está ativada: consulte [Redes da Travel Rule](https://docs.didit.me/pt/transaction-monitoring/travel-rule-networks.md).
> CODE, TRISA, Notabene e Veriscope surgem no Marketplace da Didit como mosaicos para solicitar acesso, ainda sem integração.
> Consulte [Como a Didit encaminha uma troca](https://docs.didit.me/pt/transaction-monitoring/travel-rule-interoperability.md#como-a-didit-encaminha-uma-transferência) para a tabela de encaminhamento completa e [Redes da Travel Rule](https://docs.didit.me/pt/transaction-monitoring/travel-rule-networks.md) para saber o alcance atual de cada uma.

> [accordion] Que rede devo utilizar e preciso das minhas próprias adesões?
>
> O `TRP` é a base que recomendamos: não requer qualquer adesão partilhada - partilhar o seu [Travel Address](#travel-addresses) permite que qualquer VASP compatível com TRP o contacte - e quando uma contraparte é conhecida apenas pelo endereço da carteira, a [atribuição por análise de blockchain](#atribuição-por-análise-de-blockchain) encaminha-a através de TRP apenas se a entrada correspondente no diretório já tiver um endpoint TRP.
> No envio, a Didit envia os ativos listados em [Identificadores de ativos TRP](#identificadores-de-ativos-trp) através dele, e uma contraparte que não responda de imediato requer o anfitrião público TRP da Didit, que ainda não está ativo.
> Para redes de adesão, escolha em função do local onde as suas contrapartes operam: a GTR oferece uma cobertura global alargada, a TRUST está orientada para VASP dos EUA e a VerifyVASP (que agora também opera a Sygna Bridge) tem uma forte cobertura na Ásia.
> Sim, atualmente necessita da sua própria adesão: a Didit ainda não detém uma adesão de plataforma nestas redes e está em processo de integração como fornecedor.
> Ligue a sua adesão no **Marketplace**; não está limitado a uma única rede.
> Lembre-se de que o `TRUST` apenas envia, pelo que uma transferência através dele não fica concluída, e que nenhuma troca através de uma rede foi ainda concluída contra uma rede em produção.

> [accordion] Como é que a Didit encontra o VASP da contraparte quando tenho apenas o endereço de uma carteira?
>
> Através de uma cadeia de resolução: outro cliente Didit que tenha comprovado o controlo da carteira (o canal `INTERNAL`), o seu próprio [livro de endereços de carteiras](#livro-de-endereços-de-carteiras) para um Travel Address guardado, depois os canais de protocolo e de rede e, por fim, a [atribuição por análise de blockchain](#atribuição-por-análise-de-blockchain).
> Se a transferência incluir apenas uma carteira de destino, a Didit resolve-a através de dados de análise de blockchain para atribuir a exchange ou serviço de custódia da contraparte e cataloga-a no [diretório de VASP](#diretório).
> A transferência é depois encaminhada automaticamente apenas se essa entrada do diretório já tiver uma rota, como um endpoint `TRP`; caso contrário, termina em `COUNTERPARTY_VASP_NOT_FOUND` com o nome da contraparte registado, e pode reenviar assim que existir uma rota, por exemplo após guardar o `travel_address` da contraparte na entrada do seu livro de endereços para essa carteira (para os ativos listados em [Identificadores de ativos TRP](#identificadores-de-ativos-trp)).

### Preços e licenciamento

> [accordion] Quanto custa a Travel Rule e está incluída no meu plano de KYC ou verificação?
>
> A Travel Rule é um produto separado, baseado na utilização.
> Não está incluída na verificação de identidade.
> Custa \*\*$0.02 por troca de saída iniciada** ([tabela de preços publicada](#preços), sem escalões de volume, sem chamadas comerciais).
>         Quando o encaminhamento necessita de uma consulta de análise de blockchain para identificar o VASP da contraparte, essa consulta é cobrada uma vez à [taxa de atribuição](#preços-de-atribuição): a partir de $0.15 com gestão, ou \$0.02 com uma chave de fornecedor existente.
> Não é faturada novamente se a monitorização de cripto já tiver analisado a mesma carteira.
> Uma transferência abaixo do seu limiar, ou uma registada enquanto a Travel Rule está desativada, é faturada como triagem de transações; as transferências recebidas, como os fluxos que a Didit cria no lado do beneficiário, não pagam a taxa da Travel Rule.

> [accordion] Serei cobrado duas vezes quando a Travel Rule e a monitorização de cripto forem executadas em simultâneo?
>
> Não.
> Uma transação `travelRule` é faturada numa única linha: a taxa da Travel Rule (\$0.02) quando inicia uma troca enviada; caso contrário, como triagem de transações padrão. A consulta de análise de blockchain é cobrada uma vez: se a monitorização de cripto já tiver analisado a carteira de destino na transação, a [atribuição](#atribuição-por-análise-de-blockchain) reutiliza esse resultado guardado sem custos adicionais.
> Os fluxos recebidos que a Didit cria no lado do beneficiário nunca são faturados com a taxa da Travel Rule.

> [accordion] A Didit pode fornecer documentação ou uma declaração de capacidades para o meu processo de licenciamento de VASP ou para o meu processo junto do regulador?
>
> Sim. O KYT e a monitorização de transações, triagem AML e de sanções, risco de carteira por análise de blockchain e as capacidades da Travel Rule da Didit estão todos documentados publicamente em docs.didit.me, e pode citar livremente estas páginas num processo regulatório. Para uma declaração formal de capacidades do produto adaptada a uma submissão específica - por exemplo, um pedido de licença VASP no âmbito da AIFC/AFSA, MiCA ou outro -, contacte a equipa responsável pela sua conta Didit com o formato exigido pelo seu regulador.

### Operações e dados

> [accordion] O que acontece às transferências abaixo do meu limiar?
>
> Resolvem-se imediatamente para `NOT_APPLICABLE`: nenhum canal é utilizado e nenhum dado de identidade sai da Didit.
> A transação é faturada como Triagem de transações padrão, e não com a tarifa da Travel Rule.
> A Didit compara o limiar com o montante convertido para a moeda predefinida da sua aplicação.
> Se a Didit não conseguir converter o montante, o limiar não é aplicado e a transferência é trocada.
> O TFR da UE não tem valor mínimo, pelo que os CASP da UE devem manter `threshold_amount` em `0.00`.

> [accordion] E se a contraparte nunca responder?
>
> A transferência permanece em `AWAITING_COUNTERPARTY` até que `confirmation_timeout_hours` decorra, momento em que um processo de limpeza move-a para `EXPIRED` e aplica o seu `timeout_outcome` à transação subjacente - `HOLD` para revisão, `REJECT` para recusar ou `PROCEED` para a deixar inalterada. A regra predefinida `tr_eu_expired_review` apresenta adicionalmente cada expiração aos seus analistas. Uma contraparte que nunca chega a receber a mensagem é um caso diferente: a Didit tenta novamente e, após a sexta tentativa falhada, a transferência passa para `COUNTERPARTY_VASP_NOT_REACHABLE` (consulte [Entrega e tentativas](#entrega-e-tentativas)).

> [accordion] A minha contraparte não tem quaisquer ferramentas de Travel Rule. Ainda assim posso cumprir?
>
> Sim - esse é o canal `EMAIL`. O respetivo contacto de conformidade recebe uma ligação de recolha de utilização única e pode confirmar ou recusar a troca a partir de uma página alojada sem conta Didit, sem chave de API e sem integração. Para depósitos que já tenham sido liquidados antes de qualquer troca ser possível, utilize o [registo sunrise pós-depósito](#registo-sunrise-posterior-ao-depósito).

> [accordion] Como funcionam os levantamentos para a própria carteira do utilizador?
>
> Declare o destino como autocustodiado (`payment_method.method_type: "unhosted_wallet"`). A Didit ignora o encaminhamento do VASP e, em alternativa, recolhe a prova de que o seu cliente controla a carteira - assinatura de mensagens, teste Satoshi, captura de ecrã ou autodeclaração - através do [widget de propriedade da carteira](https://docs.didit.me/pt/transaction-monitoring/wallet-ownership-widget.md). Essa é a obrigação de carteira autocustodiada do TFR da UE em formato de API.

> [accordion] Os dados pessoais da contraparte estão protegidos durante a troca?
>
> Sim.
> Até que a propriedade da carteira seja confirmada do seu lado, os dados pessoais da contraparte numa transferência de entrada são mascarados, tanto no objeto da transferência como na parte da contraparte da transação (consulte [Dados mascarados da contraparte](#dados-da-contraparte-mascarados)).
> As páginas de recolha por e-mail mostram apenas o resumo da transferência (nome do VASP ordenante, montante, carteira de destino), nunca os payloads relativos às pessoas.
> As trocas através de canais são realizadas através de HTTPS, e os canais de rede (`GTR`, `TRUST`, `VERIFYVASP`, `SYGNA`) encriptam adicionalmente o payload IVMS com a chave pública do VASP destinatário.

> [accordion] Já monitorizo a conformidade com a Travel Rule através do meu próprio processo. Posso apenas registá-la?
>
> Sim. Com a Travel Rule desativada, quaisquer `travel_rule_details` que submeta (incluindo um `status` fornecido pelo chamador, atual ou legado) são registados passivamente na transação - nenhum canal é acionado, nada é negociado. Utilize isto para preenchimento retroativo ou para executar o seu próprio processo mantendo um único sistema de registo.

> [accordion] Como testo isto antes de avançar para produção?
>
> Utilize uma aplicação sandbox com a Travel Rule ativada. O ambiente sandbox ignora regras, faturação e os webhooks `transaction.created` e `transaction.status.updated`, e cada troca de **saída** segue para o [Didit Test VASP](https://docs.didit.me/pt/transaction-monitoring/travel-rule-sandbox.md) no canal `TEST_VASP`, que responde no interior da Didit com o cenário que selecionar: aceitar, recusar, divergência de nomes, não acessível, tempo limite excedido ou autocustodiada. Recebe webhooks `travel_rule.status.updated` marcados com `environment: sandbox`, e nenhuma mensagem chega a uma contraparte real.
> Para **entrada**, peça ao VASP de teste que lhe envie uma transferência com [Acionar transferência de entrada do Test VASP](https://docs.didit.me/pt/management-api/travel-rule/trigger-test-vasp-inbound.md), ou registe uma com `POST /v3/travel-rule/inbound/`; ambas são avaliadas com base no seu livro de endereços de carteiras - `ON_HOLD`, `UNCONFIRMED_OWNERSHIP`, `COUNTERPARTY_MISMATCHED_DATA`, ou `COMPLETED` e depois `FINISHED`.
> Para uma troca entre duas partes com outra aplicação real, utilize duas das suas próprias aplicações de **produção** no canal `INTERNAL`: a que recebe tem de estar disponível para descoberta e provar o controlo da carteira de destino com uma mensagem assinada ou um depósito de teste.

## Passos seguintes

> [card] [Widget de propriedade da carteira](https://docs.didit.me/pt/transaction-monitoring/wallet-ownership-widget.md)
>
> Comprove que um cliente controla uma carteira através de assinatura, teste Satoshi, captura de ecrã ou autodeclaração.

> [card] [Interoperabilidade](https://docs.didit.me/pt/transaction-monitoring/travel-rule-interoperability.md)
>
> Os endpoints destinados às contrapartes, que outros VASP utilizam para comunicar consigo: TRP, callbacks, recolha por e-mail, sunrise.

> [card] [Redes](https://docs.didit.me/pt/transaction-monitoring/travel-rule-networks.md)
>
> O alcance atual de cada canal e rede e o que ainda aguarda adesão.

> [card] [Testar em sandbox](https://docs.didit.me/pt/transaction-monitoring/travel-rule-sandbox.md)
>
> Teste todos os resultados com o Didit Test VASP antes de avançar para produção.

> [card] [Submeter transações](https://docs.didit.me/pt/transaction-monitoring/transactions.md)
>
> Como incluir dados da Travel Rule no payload do Create Transaction.

> [card] [Biblioteca de regras](https://docs.didit.me/pt/transaction-monitoring/rules-library.md)
>
> O catálogo completo de regras predefinidas, incluindo o pacote da Travel Rule.

> [card] [Webhooks](https://docs.didit.me/pt/integration/webhooks.md)
>
> Subscreva travel\_rule.status.updated e todas as outras famílias de eventos.

> [card] [Guia da consola](https://docs.didit.me/pt/transaction-monitoring/console.md)
>
> Visualizar o estado da Travel Rule na vista de detalhe da transação.


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