> ## 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/rails/pix/btg/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/rails/pix/btg/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/rails/pix/btg/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>

# Estatísticas

***

O domínio **Estatísticas** expõe os agregados de risco e uso de Pix do BACEN, permitindo que você avalie uma contraparte **antes** de liquidar um pagamento. Ambos os endpoints consultam o provedor diretamente e **não armazenam dados localmente**, então trate cada chamada como uma consulta nova, em tempo real. Eles são marcados sob a API MED e exigem autenticação bearer.

| Endpoint                                   | Escopo                   | Use para                                                         |
| ------------------------------------------ | ------------------------ | ---------------------------------------------------------------- |
| `GET /v1/dict/statistics/persons/{tax_id}` | Uma pessoa (CPF ou CNPJ) | Avaliar um pagador/beneficiário em todas as suas chaves e contas |
| `GET /v1/dict/statistics/keys/{key}`       | Uma única chave Pix      | Avaliar uma chave específica, além do seu titular atual          |

## Estatísticas de pessoa

Passe o tax ID (CPF ou CNPJ) no caminho. A resposta agrega dados de liquidação, marcadores de fraude, relatórios de infração e informações de entradas em três janelas móveis: **d90** (últimos 90 dias), **m12** (últimos 12 meses) e **m60** (últimos 60 meses).

```json theme={null}
GET /v1/dict/statistics/persons/12345678901
→ 200 OK
{
  "taxId": "12345678901",
  "statistics": {
    "settlements": { "d90": 42, "m12": 310, "m60": 1580 },
    "fraudMarkers": { "d90": 0, "m12": 1 },
    "infractionReports": { "d90": 0, "m12": 2 }
  }
}
```

## Estatísticas de chave

Passe a chave Pix no caminho. A resposta retorna **tanto** as estatísticas em nível de chave (dados ligados à chave como entidade, independentes do seu titular atual) quanto as estatísticas em nível de titular (equivalentes às estatísticas de pessoa do titular atual da chave) em uma única chamada.

```json theme={null}
GET /v1/dict/statistics/keys/john.doe@example.com
→ 200 OK
{
  "keyStatistics": { "settlements": { "d90": 12 }, "ownershipChanges": { "m12": 1 } },
  "ownerStatistics": { "fraudMarkers": { "d90": 0 }, "infractionReports": { "m12": 0 } }
}
```

<Note>
  Use as estatísticas de chave quando estiver prestes a pagar uma chave específica, e as estatísticas de pessoa para uma visão mais ampla do risco da contraparte. Como nenhuma é persistida, faça cache com responsabilidade do seu lado se precisar reutilizar o resultado dentro de um fluxo de requisição.
</Note>

**Referência:** [Recuperar estatísticas de pessoa](/pt/reference/midaz/plugins/indirect-pix/retrieve-person-statistics) · [Recuperar estatísticas de chave](/pt/reference/midaz/plugins/indirect-pix/retrieve-key-statistics)

# Marcadores de fraude e MED 1.0

***

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** (tipos de fraude: `APPLICATION_FRAUD`, `MULE_ACCOUNT`, `SCAMMER_ACCOUNT`, `OTHER`). Os **relatórios de infração** e as **solicitações de devolução** relacionados conduzem o fluxo de disputa do MED 1.0.

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

## Relatórios de infração

Um **relatório de infração** notifica o PSP da contraparte de que uma transação está sendo contestada como fraude. Ele só pode ser aberto dentro de **90 dias** da data da transação, e segue um ciclo de vida **create → acknowledge → close/cancel**:

| Etapa       | Papel                       | Endpoint                                            |
| ----------- | --------------------------- | --------------------------------------------------- |
| Create      | Relator (PSP do pagador)    | `POST /v1/dict/infraction-reports`                  |
| Acknowledge | PSP da contraparte          | `POST /v1/dict/infraction-reports/{id}/acknowledge` |
| Close       | PSP do beneficiário/pagador | `POST /v1/dict/infraction-reports/{id}/close`       |
| Cancel      | Relator                     | `POST /v1/dict/infraction-reports/{id}/cancel`      |

* **Create** — abre o relatório contra o end-to-end ID contestado, ex.: `reason: REFUND_REQUEST`, `situationType: SCAM`.
* **Acknowledge** — o PSP receptor confirma que recebeu o relatório.
* **Close** — o PSP respondente envia seu resultado de análise (por exemplo `TOTALLY_ACCEPTED`) dentro de **7 dias**. Infrações `REFUND_REQUEST` são fechadas pelo PSP do beneficiário; infrações `REFUND_CANCELLED`, pelo PSP do pagador. Uma vez fechado, o relatório é imutável.
* **Cancel** — o relator retira um relatório que abriu.

```json theme={null}
POST /v1/dict/infraction-reports
{
  "transactionId": "E12345678202411241430ABCDEFGHIJK",
  "reason": "REFUND_REQUEST",
  "situationType": "SCAM",
  "reportDetails": "Customer reported receiving a call from a fake bank employee"
}
```

## Solicitações de devolução

Uma **solicitação de devolução** é o mecanismo do MED 1.0 para pedir ao PSP da contraparte que devolva os fundos contestados. Ela espelha o mesmo ciclo de vida **create → acknowledge → close/cancel**:

| Etapa           | Endpoint                                                             |
| --------------- | -------------------------------------------------------------------- |
| Create          | `POST /v1/dict/refund-requests`                                      |
| Retrieve / List | `GET /v1/dict/refund-requests/{id}` · `GET /v1/dict/refund-requests` |
| Close           | `POST /v1/dict/refund-requests/{id}/close`                           |
| Cancel          | `POST /v1/dict/refund-requests/{id}/cancel`                          |

**Close** registra o resultado da análise e finaliza a solicitação; **cancel** retira uma solicitação pendente. As mudanças de status tanto dos relatórios de infração quanto das solicitações de devolução são entregues por webhooks de saída — consulte o [guia de Webhooks](/pt/rails/pix/btg/indirect-pix-webhooks).

**Referência:** [Criar um relatório de infração](/pt/reference/midaz/plugins/indirect-pix/create-an-infraction-report) · [Confirmar](/pt/reference/midaz/plugins/indirect-pix/acknowledge-an-infraction-report) · [Fechar](/pt/reference/midaz/plugins/indirect-pix/close-an-infraction-report) · [Cancelar](/pt/reference/midaz/plugins/indirect-pix/cancel-an-infraction-report) · [Criar uma solicitação de devolução](/pt/reference/midaz/plugins/indirect-pix/create-a-refund-request)

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

# Próximos passos

***

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