> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# DICT

> Como o Plugin Pix Indireto (BTG) gerencia chaves Pix no DICT — entradas, consultas de chaves, reivindicações de portabilidade e propriedade, conciliação (VSync) e marcadores de fraude.

O **DICT** (Diretório de Identificadores de Contas Transacionais) é o diretório do BACEN que mapeia **chaves Pix** para contas transacionais. O Plugin Pix Indireto (BTG) atua como intermediário do DICT por meio do BTG, permitindo que você registre e resolva chaves, transfira chaves entre instituições via reivindicações, mantenha seus dados locais conciliados com o BACEN e gerencie marcadores de fraude do MED.

O módulo DICT é organizado em seis domínios: **Entradas**, **Chaves**, **Reivindicações**, **Relatórios de Infração**, **Solicitações de Devolução** e **Estatísticas**. Este guia foca no ciclo de vida das chaves, nas reivindicações e na conciliação. As operações com escopo de conta exigem o cabeçalho `X-Account-Id`.

# Entradas e chaves

***

Uma **entrada** é uma chave Pix registrada em uma de suas contas. O plugin resolve a conta subjacente e os dados do titular a partir do CRM, então você cria entradas por tipo de chave em vez de fornecer os detalhes da conta diretamente.

**Tipos de chave suportados:**

| Tipo    | Origem do valor                                                           |
| ------- | ------------------------------------------------------------------------- |
| `CPF`   | Derivado automaticamente do documento do titular no CRM (não envie `key`) |
| `CNPJ`  | Derivado automaticamente do documento do titular no CRM (não envie `key`) |
| `EMAIL` | Fornecido na requisição (e-mail válido, ≤ 77 caracteres)                  |
| `PHONE` | Fornecido na requisição (`^\+[1-9]\d{1,14}$`)                             |
| `EVP`   | UUID aleatório gerado pelo sistema (não envie `key`)                      |

```json theme={null}
POST /v1/dict/entries
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{ "keyType": "EMAIL", "key": "john.doe@example.com" }
```

Gerencie entradas com **criar / listar / recuperar / atualizar / excluir** (`/v1/dict/entries`). A criação/exclusão de entradas valida contra reivindicações ativas e a consistência entre a chave e o documento do titular (por exemplo, uma chave `CPF` deve corresponder ao CPF do titular).

<Note>
  O plugin não valida chaves com a Receita Federal nem realiza verificações de propriedade por MFA — ele presume que o cliente concluiu essas etapas antes da chamada. Consulte o [guia de integração](/pt/midaz/plugins/pix/indirect/indirect-pix-integration) para os pré-requisitos.
</Note>

**Consultas de chave** (`GET /v1/dict/keys/{key}`) resolvem uma chave para **fins de pagamento** — retornando o titular atual e a conta para que você possa iniciar um pagamento. Use o cabeçalho opcional `X-EndToEnd-Id` para rastreamento de pagamento e `POST /v1/dict/keys/check` para verificar a existência em lote. O plugin retorna os dados como recebidos do BTG; mascarar campos sensíveis antes da exibição é responsabilidade do cliente.

**Referência:** [Criar entrada](/pt/reference/midaz/plugins/indirect-pix/create-entry) · [Listar](/pt/reference/midaz/plugins/indirect-pix/list-entries) · [Recuperar](/pt/reference/midaz/plugins/indirect-pix/retrieve-an-entry) · [Atualizar](/pt/reference/midaz/plugins/indirect-pix/update-an-entry) · [Excluir](/pt/reference/midaz/plugins/indirect-pix/delete-an-entry) · [Recuperar uma chave](/pt/reference/midaz/plugins/indirect-pix/retrieve-a-key) · [Verificar chaves](/pt/reference/midaz/plugins/indirect-pix/check-keys-existence)

# Reivindicações: portabilidade e propriedade

***

Uma **reivindicação** transfere uma chave Pix entre instituições. Existem dois tipos:

* **PORTABILITY** — move uma chave para outro banco **para o mesmo titular**. Permitido para `CPF`, `CNPJ`, `PHONE` e `EMAIL`.
* **OWNERSHIP** — reivindica uma chave de uma **pessoa diferente**. Permitido somente para `PHONE`.

As duas partes são o **doador** (o participante que detém a chave atualmente) e o **reivindicador** (o participante que a solicita). Os dados de conta do reivindicador são obtidos do CRM via `X-Account-Id`; `claimerParticipant` e `donorParticipant` são definidos automaticamente pelo BTG.

## Ciclo de vida da reivindicação

| Status               | Significado                                                     |
| -------------------- | --------------------------------------------------------------- |
| `OPEN`               | Reivindicação criada; aguardando o reconhecimento do doador     |
| `WAITING_RESOLUTION` | Doador reconheceu; período de resolução em andamento (D+7)      |
| `CONFIRMED`          | Doador confirmou; a chave está bloqueada aguardando a conclusão |
| `COMPLETED`          | Transferência da chave finalizada                               |
| `CANCELLED`          | Cancelada pelo doador ou reivindicador                          |

Enquanto uma reivindicação está ativa (`OPEN`, `WAITING_RESOLUTION` ou `CONFIRMED`), a chave fica **bloqueada**: novas entradas e exclusões são impedidas. Durante `OPEN`/`WAITING_RESOLUTION`, o doador ainda pode atualizar os dados da conta e as consultas de chave retornam os dados do doador; uma vez `CONFIRMED`, as consultas retornam "chave não encontrada" até que a reivindicação esteja `COMPLETED` ou `CANCELLED`.

* **PORTABILITY** pode ser concluída imediatamente após a confirmação.
* **OWNERSHIP** tem uma janela de conclusão — `resolutionPeriodEnd` é D+7 e `completionPeriodEnd` é D+30.

## Operações de reivindicação

| Operação   | Papel                   | Endpoint                                |
| ---------- | ----------------------- | --------------------------------------- |
| Criar      | Reivindicador           | `POST /v1/dict/claims`                  |
| Reconhecer | Doador                  | `POST /v1/dict/claims/{id}/acknowledge` |
| Confirmar  | Doador                  | `POST /v1/dict/claims/{id}/confirm`     |
| Concluir   | Reivindicador           | `POST /v1/dict/claims/{id}/complete`    |
| Cancelar   | Doador ou reivindicador | `POST /v1/dict/claims/{id}/cancel`      |

As mudanças de status da reivindicação são entregues ao seu sistema por meio de webhooks de saída **CLAIM**. Consulte o [guia de Webhooks](/pt/midaz/plugins/pix/indirect/indirect-pix-webhooks).

**Referência:** [Criar uma reivindicação](/pt/reference/midaz/plugins/indirect-pix/create-a-claim) · [Listar](/pt/reference/midaz/plugins/indirect-pix/list-claims) · [Recuperar](/pt/reference/midaz/plugins/indirect-pix/retrieve-a-claim) · [Reconhecer](/pt/reference/midaz/plugins/indirect-pix/acknowledge-a-claim) · [Confirmar](/pt/reference/midaz/plugins/indirect-pix/confirm-a-claim) · [Concluir](/pt/reference/midaz/plugins/indirect-pix/complete-a-claim) · [Cancelar](/pt/reference/midaz/plugins/indirect-pix/cancel-a-claim)

# Conciliação (VSync)

***

A **conciliação** mantém seus dados locais de DICT consistentes com os registros oficiais do BACEN. Ela é construída sobre dois conceitos:

* **CID** (Content Identifier) — um hash HMAC-SHA256 de 256 bits dos atributos de uma entrada (tipo de chave, chave, titular, participante, agência, conta etc.).
* **VSync** — um único checksum formado pelo XOR de todos os CIDs de um tipo de chave. Como o XOR é comutativo, comparar seu VSync com o do BTG/BACEN revela se o seu conjunto de entradas está sincronizado sem trocar todos os registros.

Existem dois caminhos:

* **API manual / administrativa** — operadores disparam verificações sob demanda, baixam arquivos de CID e investigam inconsistências. Use [Iniciar conciliação completa](/pt/reference/midaz/plugins/indirect-pix/start-full-reconciliation) e [Listar jobs de conciliação](/pt/reference/midaz/plugins/indirect-pix/list-all-reconciliation-jobs).
* **Worker VSync** — um processo automatizado em segundo plano que compara periodicamente as entradas internas com o DICT e concilia divergências sem intervenção do usuário.

Configure a janela de tempo do worker de conciliação e a janela de bloqueio de escrita do DICT no [guia de integração](/pt/midaz/plugins/pix/indirect/indirect-pix-integration#7-dict-reconciliation-vsync).

<Warning>
  Durante a janela de bloqueio de escrita, o banco de dados bloqueia temporariamente as gravações para evitar inconsistências com o BACEN. Ancore a janela em `America/Sao_Paulo` e agende-a em períodos de baixo tráfego.
</Warning>

# Marcadores de fraude (MED)

***

O DICT também expõe as ferramentas de prevenção a fraudes do **MED** (Mecanismo Especial de Devolução) do BACEN. **Marcadores de fraude** sinalizam uma chave ou conta como associada a fraude; você pode **criá-los** e **cancelá-los**, e os **relatórios de infração** e as **solicitações de devolução** relacionados conduzem o fluxo de disputa e recuperação.

**Referência:** [Criar um marcador de fraude](/pt/reference/midaz/plugins/indirect-pix/create-a-fraud-marker) · [Cancelar um marcador de fraude](/pt/reference/midaz/plugins/indirect-pix/cancel-a-fraud-marker) · [Listar marcadores de fraude](/pt/reference/midaz/plugins/indirect-pix/list-fraud-markers) · [Criar um relatório de infração](/pt/reference/midaz/plugins/indirect-pix/create-an-infraction-report)

Para os fluxos completos de disputa e recuperação de fundos, consulte [Operações de devolução](/pt/midaz/plugins/pix/indirect/indirect-pix-refund-operations) e [MED 2.0 — Recuperação de Fundos](/pt/midaz/plugins/pix/indirect/indirect-pix-med-2-funds-recovery).

# Próximos passos

***

* [QR Codes](/pt/midaz/plugins/pix/indirect/indirect-pix-qrcodes) — Gerando QR Codes em chaves registradas
* [Webhooks](/pt/midaz/plugins/pix/indirect/indirect-pix-webhooks) — Notificações de reivindicação, infração e devolução
* [Integração](/pt/midaz/plugins/pix/indirect/indirect-pix-integration) — Conciliação do DICT e configuração do worker