> ## 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: vínculos, consultas de chave, reivindicações de portabilidade e de posse, conciliação (VSync) e marcações de fraude.

O **DICT** (Diretório de Identificadores de Contas Transacionais) é o diretório do BACEN que associa **chaves Pix** a contas transacionais. O Plugin Pix Indireto (BTG) conecta você ao DICT pelo BTG. Você registra e resolve chaves, transfere chaves entre instituições com reivindicações, concilia seus dados locais com o BACEN e gerencia as marcações de fraude do MED.

A API do DICT abrange vários domínios: vínculos e chaves, reivindicações, conciliação, estatísticas e as ferramentas de fraude do MED. As operações no escopo de conta exigem o header `X-Account-Id`.

# Vínculos e chaves

***

Um **vínculo** associa uma chave Pix a uma das suas contas. O plugin resolve os dados da conta e do titular a partir do CRM. Você cria vínculos por tipo de chave, em vez de por dados da conta.

**Tipos de chave aceitos:**

| Tipo    | Origem do valor                                                       |
| ------- | --------------------------------------------------------------------- |
| `CPF`   | Informado na requisição (deve corresponder ao CPF do titular no CRM)  |
| `CNPJ`  | Informado na requisição (deve corresponder ao CNPJ do titular no CRM) |
| `EMAIL` | Informado na requisição (e-mail válido, ≤ 77 caracteres)              |
| `PHONE` | Informado na requisição (`^\+[1-9][0-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 os vínculos com **criar / listar / consultar / atualizar / excluir** (`/v1/dict/entries`). A criação e a exclusão validam as reivindicações ativas e conferem a chave com o documento do titular. Por exemplo, uma chave `CPF` deve corresponder ao CPF do titular.

<Note>
  O plugin não valida chaves na Receita Federal e não executa verificações de posse com MFA. Ele supõe que você concluiu essas verificações antes de chamá-lo. Veja os pré-requisitos no [guia de integração](/pt/interfaces/pix-btg/indirect-pix-integration).
</Note>

As **consultas de chave** (`GET /v1/dict/keys/{key}`) resolvem uma chave para pagamento. A resposta traz o dono atual e a conta, para você iniciar um pagamento. A consulta exige o header `X-End-To-End-Id` para o rastreamento do pagamento. Use `POST /v1/dict/keys/check` para checar a existência em lote. O plugin devolve os dados como os recebe do BTG. Mascare os campos sensíveis antes de mostrá-los no seu lado.

**Referência:** [Criar vínculo](/pt/reference/interfaces/pix-btg/create-entry) · [Listar](/pt/reference/interfaces/pix-btg/list-entries) · [Consultar](/pt/reference/interfaces/pix-btg/retrieve-an-entry) · [Atualizar](/pt/reference/interfaces/pix-btg/update-an-entry) · [Excluir](/pt/reference/interfaces/pix-btg/delete-an-entry) · [Consultar uma chave](/pt/reference/interfaces/pix-btg/retrieve-a-key) · [Checar chaves](/pt/reference/interfaces/pix-btg/check-keys-existence)

# Reivindicações: portabilidade e posse

***

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

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

As duas partes são o **doador** (o participante que detém a chave hoje) e o **reivindicador** (o participante que a solicita). O plugin busca os dados da conta do reivindicador no CRM pelo `X-Account-Id`. O BTG define `claimerParticipant` e `donorParticipant` automaticamente.

## Ciclo de vida da reivindicação

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

Enquanto uma reivindicação está ativa (`OPEN`, `WAITING_RESOLUTION` ou `CONFIRMED`), ela trava a chave. O plugin bloqueia novos vínculos e exclusões. Durante `OPEN` e `WAITING_RESOLUTION`, o doador ainda pode atualizar os dados da conta, e as consultas de chave devolvem os dados do doador. Depois de `CONFIRMED`, as consultas devolvem "chave não encontrada" até a reivindicação chegar a `COMPLETED` ou `CANCELLED`.

* **PORTABILITY** pode ser concluída logo após a confirmação.
* **OWNERSHIP** acrescenta uma janela de conclusão. O BTG devolve `resolutionPeriodEnd` (D+7) e `completionPeriodEnd` na reivindicação.

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

Os webhooks de saída CLAIM entregam as mudanças de status das reivindicações ao seu sistema. Veja o [guia de Webhooks](/pt/interfaces/pix-btg/indirect-pix-webhooks).

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

# Conciliação (VSync)

***

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

* **CID** (Content Identifier): um hash HMAC-SHA256 de 256 bits dos atributos de um vínculo (tipo de chave, chave, dono, participante, agência, conta etc.).
* **VSync**: um único checksum que aplica XOR a cada CID de um tipo de chave. Como o XOR é comutativo, você compara o seu VSync com o do BTG/BACEN para revelar se seus vínculos estão sincronizados, sem trocar todos os registros.

Existem dois caminhos:

* **API manual / administrativa**: os operadores disparam verificações sob demanda, baixam arquivos de CID e investigam inconsistências. Use [Iniciar conciliação completa](/pt/reference/interfaces/pix-btg/start-full-reconciliation) e [Listar jobs de conciliação](/pt/reference/interfaces/pix-btg/list-all-reconciliation-jobs).
* **Worker VSync**: um processo automático em background que compara periodicamente os vínculos internos com o DICT e concilia as divergências sem intervenção do usuário.

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

<Warning>
  Durante a janela de bloqueio de escrita, o banco bloqueia temporariamente as escritas 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 **Statistics** expõe os agregados de risco e de uso do Pix do BACEN. Você pode avaliar uma contraparte **antes** de liquidar um pagamento. Os dois endpoints consultam o provedor diretamente e **não armazenam dados localmente**. Trate cada chamada como uma consulta nova, em tempo real. Os dois endpoints exigem autenticação bearer.

| Endpoint                                   | Escopo                   | Use para                                                      |
| ------------------------------------------ | ------------------------ | ------------------------------------------------------------- |
| `GET /v1/dict/statistics/persons/{tax_id}` | Uma pessoa (CPF ou CNPJ) | Avaliar um pagador/recebedor em todas as chaves e contas dele |
| `GET /v1/dict/statistics/keys/{key}`       | Uma única chave Pix      | Avaliar uma chave específica e o dono atual dela              |

## Estatísticas da pessoa

Passe o documento fiscal (CPF ou CNPJ) no path. A resposta agrega dados de liquidação, marcações de fraude, relatos de infração e informações de vínculo. Ela cobre 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 da chave

Passe a chave Pix no path. A resposta devolve duas estatísticas em uma única chamada: no nível da chave e no nível do dono. As estatísticas no nível da chave se ligam à chave como entidade, independentemente do dono atual dela. As estatísticas no nível do dono correspondem às estatísticas da pessoa referentes ao dono atual da chave.

```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 da chave quando você paga uma chave específica. Use as estatísticas da pessoa para uma visão mais ampla do risco da contraparte. O plugin não persiste nenhum dos dois resultados. Faça cache com responsabilidade no seu lado se reutilizar um resultado dentro de um fluxo de requisição.
</Note>

**Referência:** [Consultar estatísticas da pessoa](/pt/reference/interfaces/pix-btg/retrieve-person-statistics) · [Consultar estatísticas da chave](/pt/reference/interfaces/pix-btg/retrieve-key-statistics)

# Marcações de fraude e MED 1.0

***

O DICT também expõe as ferramentas de prevenção a fraude do **MED** (Mecanismo Especial de Devolução) do BACEN. As **marcações de fraude** sinalizam uma chave ou conta como associada a fraude. Você pode **criar** e **cancelar** essas marcações (tipos de fraude: `APPLICATION_FRAUD`, `MULE_ACCOUNT`, `SCAMMER_ACCOUNT`, `OTHER`). Os **relatos de infração** e as **solicitações de devolução** relacionados conduzem o workflow de disputa do MED 1.0.

**Referência:** [Criar uma marcação de fraude](/pt/reference/interfaces/pix-btg/create-a-fraud-marker) · [Cancelar uma marcação de fraude](/pt/reference/interfaces/pix-btg/cancel-a-fraud-marker) · [Listar marcações de fraude](/pt/reference/interfaces/pix-btg/list-fraud-markers)

## Relatos de infração

Um **relato de infração** avisa o PSP da contraparte que você contesta uma transação como fraude. Você pode abrir um relato apenas dentro de **90 dias** a partir da data da transação. O relato segue um ciclo de vida **criar → reconhecer → encerrar/cancelar**:

| Etapa      | Papel                    | Endpoint                                            |
| ---------- | ------------------------ | --------------------------------------------------- |
| Criar      | Relator (PSP do pagador) | `POST /v1/dict/infraction-reports`                  |
| Reconhecer | PSP da contraparte       | `POST /v1/dict/infraction-reports/{id}/acknowledge` |
| Encerrar   | PSP do recebedor/pagador | `POST /v1/dict/infraction-reports/{id}/close`       |
| Cancelar   | Relator                  | `POST /v1/dict/infraction-reports/{id}/cancel`      |

* **Criar**: abre o relato contra o end-to-end ID contestado, por exemplo `reason: REFUND_REQUEST`, `situationType: SCAM`.
* **Reconhecer**: o PSP que recebe confirma o recebimento do relato.
* **Encerrar**: o PSP que responde envia o resultado da análise (por exemplo `TOTALLY_ACCEPTED`) em até **7 dias**. O PSP do recebedor fecha as infrações `REFUND_REQUEST`. O PSP do pagador fecha as infrações `REFUND_CANCELLED`. Depois do encerramento, o relato fica imutável.
* **Cancelar**: o relator retira um relato que ele 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 recursos contestados. Ela espelha o mesmo ciclo de vida **criar → reconhecer → encerrar/cancelar**:

| Etapa              | Endpoint                                                             |
| ------------------ | -------------------------------------------------------------------- |
| Criar              | `POST /v1/dict/refund-requests`                                      |
| Consultar / Listar | `GET /v1/dict/refund-requests/{id}` · `GET /v1/dict/refund-requests` |
| Encerrar           | `POST /v1/dict/refund-requests/{id}/close`                           |
| Cancelar           | `POST /v1/dict/refund-requests/{id}/cancel`                          |

**Encerrar** registra o resultado da análise e finaliza a solicitação. **Cancelar** retira uma solicitação pendente. Os webhooks de saída entregam as mudanças de status tanto dos relatos de infração quanto das solicitações de devolução. Veja o [guia de Webhooks](/pt/interfaces/pix-btg/indirect-pix-webhooks).

**Referência:** [Criar um relato de infração](/pt/reference/interfaces/pix-btg/create-an-infraction-report) · [Reconhecer](/pt/reference/interfaces/pix-btg/acknowledge-an-infraction-report) · [Encerrar](/pt/reference/interfaces/pix-btg/close-an-infraction-report) · [Cancelar](/pt/reference/interfaces/pix-btg/cancel-an-infraction-report) · [Criar uma solicitação de devolução](/pt/reference/interfaces/pix-btg/create-a-refund-request)

Para os fluxos de recuperação de recursos, veja [Operações de devolução](/pt/interfaces/pix-btg/indirect-pix-refund-operations) e [MED 2.0 — Funds Recovery](/pt/interfaces/pix-btg/indirect-pix-med-2-funds-recovery).

# Próximos passos

***

* [QR Codes](/pt/interfaces/pix-btg/indirect-pix-qrcodes): gerar QR Codes em chaves registradas
* [Webhooks](/pt/interfaces/pix-btg/indirect-pix-webhooks): notificações de reivindicação, de infração e de devolução
* [Integração](/pt/interfaces/pix-btg/indirect-pix-integration): conciliação do DICT e configuração do worker