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

> Cómo el Plugin Pix Indirecto (BTG) gestiona las claves Pix en DICT — entradas, consultas de claves, reclamos de portabilidad y titularidad, reconciliación (VSync) y marcadores de fraude.

**DICT** (Diretório de Identificadores de Contas Transacionais) es el directorio de BACEN que mapea **claves Pix** a cuentas transaccionales. El Plugin Pix Indirecto (BTG) actúa como intermediario hacia DICT a través de BTG, permitiéndote registrar y resolver claves, transferir claves entre instituciones mediante reclamos, mantener tus datos locales reconciliados con BACEN y gestionar marcadores de fraude MED.

El módulo DICT está organizado en seis dominios: **Entries**, **Keys**, **Claims**, **Infraction Reports**, **Refund Requests** y **Statistics**. Esta guía se centra en el ciclo de vida de las claves, los reclamos y la reconciliación. Las operaciones con alcance de cuenta requieren el header `X-Account-Id`.

# Entradas y claves

***

Una **entrada** es una clave Pix registrada en una de tus cuentas. El plugin resuelve la cuenta subyacente y los datos del titular desde CRM, por lo que creas entradas por tipo de clave en lugar de proporcionar los detalles de la cuenta directamente.

**Tipos de clave admitidos:**

| Tipo    | Origen del valor                                                            |
| ------- | --------------------------------------------------------------------------- |
| `CPF`   | Derivado automáticamente del documento del titular en CRM (no envíes `key`) |
| `CNPJ`  | Derivado automáticamente del documento del titular en CRM (no envíes `key`) |
| `EMAIL` | Proporcionado en la solicitud (email válido, ≤ 77 caracteres)               |
| `PHONE` | Proporcionado en la solicitud (`^\+[1-9]\d{1,14}$`)                         |
| `EVP`   | UUID aleatorio generado por el sistema (no envíes `key`)                    |

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

Gestiona las entradas con **create / list / retrieve / update / delete** (`/v1/dict/entries`). La creación/eliminación de entradas valida contra los reclamos activos y la consistencia entre la clave y el documento del titular (por ejemplo, una clave `CPF` debe coincidir con el CPF del titular).

<Note>
  El plugin no valida las claves con la Receita Federal ni realiza verificaciones de titularidad MFA: asume que el cliente las completó antes de la llamada. Consulta la [guía de integración](/es/midaz/plugins/pix/indirect/indirect-pix-integration) para conocer los requisitos previos.
</Note>

Las **consultas de clave** (`GET /v1/dict/keys/{key}`) resuelven una clave con **fines de pago**, devolviendo el propietario actual y la cuenta para que puedas iniciar un pago. Usa el header opcional `X-EndToEnd-Id` para el seguimiento del pago, y `POST /v1/dict/keys/check` para verificar la existencia de forma masiva. El plugin devuelve los datos tal como los recibe de BTG; enmascarar los campos sensibles antes de mostrarlos es responsabilidad del cliente.

**Referencia:** [Create entry](/es/reference/midaz/plugins/indirect-pix/create-entry) · [List](/es/reference/midaz/plugins/indirect-pix/list-entries) · [Retrieve](/es/reference/midaz/plugins/indirect-pix/retrieve-an-entry) · [Update](/es/reference/midaz/plugins/indirect-pix/update-an-entry) · [Delete](/es/reference/midaz/plugins/indirect-pix/delete-an-entry) · [Retrieve a key](/es/reference/midaz/plugins/indirect-pix/retrieve-a-key) · [Check keys](/es/reference/midaz/plugins/indirect-pix/check-keys-existence)

# Reclamos: portabilidad y titularidad

***

Un **reclamo** transfiere una clave Pix entre instituciones. Hay dos tipos:

* **PORTABILITY** — mueve una clave a otro banco **para el mismo titular**. Permitido para `CPF`, `CNPJ`, `PHONE` y `EMAIL`.
* **OWNERSHIP** — reclama una clave de una **persona diferente**. Permitido solo para `PHONE`.

Las dos partes son el **donante** (el participante que actualmente posee la clave) y el **reclamante** (el participante que la solicita). Los datos de la cuenta del reclamante se obtienen desde CRM mediante `X-Account-Id`; `claimerParticipant` y `donorParticipant` los establece BTG automáticamente.

## Ciclo de vida del reclamo

| Estado               | Significado                                                         |
| -------------------- | ------------------------------------------------------------------- |
| `OPEN`               | Reclamo creado; a la espera del reconocimiento del donante          |
| `WAITING_RESOLUTION` | El donante reconoció; periodo de resolución en curso (D+7)          |
| `CONFIRMED`          | El donante confirmó; la clave queda bloqueada hasta su finalización |
| `COMPLETED`          | Transferencia de clave finalizada                                   |
| `CANCELLED`          | Cancelado por el donante o el reclamante                            |

Mientras un reclamo está activo (`OPEN`, `WAITING_RESOLUTION` o `CONFIRMED`), la clave queda **bloqueada**: se impiden nuevas entradas y eliminaciones. Durante `OPEN`/`WAITING_RESOLUTION` el donante todavía puede actualizar los datos de la cuenta y las consultas de clave devuelven los datos del donante; una vez en `CONFIRMED`, las consultas devuelven "key not found" hasta que el reclamo pase a `COMPLETED` o `CANCELLED`.

* **PORTABILITY** puede completarse inmediatamente después de la confirmación.
* **OWNERSHIP** tiene una ventana de finalización: `resolutionPeriodEnd` es D+7 y `completionPeriodEnd` es D+30.

## Operaciones de reclamo

| Operación   | Rol                  | Endpoint                                |
| ----------- | -------------------- | --------------------------------------- |
| Create      | Reclamante           | `POST /v1/dict/claims`                  |
| Acknowledge | Donante              | `POST /v1/dict/claims/{id}/acknowledge` |
| Confirm     | Donante              | `POST /v1/dict/claims/{id}/confirm`     |
| Complete    | Reclamante           | `POST /v1/dict/claims/{id}/complete`    |
| Cancel      | Donante o reclamante | `POST /v1/dict/claims/{id}/cancel`      |

Los cambios de estado de los reclamos se entregan a tu sistema mediante webhooks salientes **CLAIM**. Consulta la [guía de Webhooks](/es/midaz/plugins/pix/indirect/indirect-pix-webhooks).

**Referencia:** [Create a claim](/es/reference/midaz/plugins/indirect-pix/create-a-claim) · [List](/es/reference/midaz/plugins/indirect-pix/list-claims) · [Retrieve](/es/reference/midaz/plugins/indirect-pix/retrieve-a-claim) · [Acknowledge](/es/reference/midaz/plugins/indirect-pix/acknowledge-a-claim) · [Confirm](/es/reference/midaz/plugins/indirect-pix/confirm-a-claim) · [Complete](/es/reference/midaz/plugins/indirect-pix/complete-a-claim) · [Cancel](/es/reference/midaz/plugins/indirect-pix/cancel-a-claim)

# Reconciliación (VSync)

***

La **reconciliación** mantiene tus datos locales de DICT consistentes con los registros autoritativos de BACEN. Se basa en dos conceptos:

* **CID** (Content Identifier) — un hash HMAC-SHA256 de 256 bits de los atributos de una entrada (tipo de clave, clave, propietario, participante, agencia, cuenta, etc.).
* **VSync** — un único checksum formado mediante XOR de cada CID de un tipo de clave. Como XOR es conmutativo, comparar tu VSync con el de BTG/BACEN revela si tu conjunto de entradas está sincronizado sin intercambiar cada registro.

Hay dos caminos:

* **API manual / administrativa** — los operadores activan verificaciones bajo demanda, descargan archivos CID e investigan inconsistencias. Usa [Start full reconciliation](/es/reference/midaz/plugins/indirect-pix/start-full-reconciliation) y [List reconciliation jobs](/es/reference/midaz/plugins/indirect-pix/list-all-reconciliation-jobs).
* **VSync worker** — un proceso automatizado en segundo plano que compara periódicamente las entradas internas con DICT y reconcilia las divergencias sin intervención del usuario.

Configura la ventana de tiempo del worker de reconciliación y la ventana de bloqueo de escritura de DICT en la [guía de integración](/es/midaz/plugins/pix/indirect/indirect-pix-integration#7-dict-reconciliation-vsync).

<Warning>
  Durante la ventana de bloqueo de escritura, la base de datos bloquea temporalmente las escrituras para evitar inconsistencias con BACEN. Ancla la ventana a `America/Sao_Paulo` y prográmala durante periodos de bajo tráfico.
</Warning>

# Marcadores de fraude (MED)

***

DICT también expone las herramientas de prevención de fraude **MED** (Mecanismo Especial de Devolução) de BACEN. Los **marcadores de fraude** señalan una clave o cuenta como asociada con fraude; puedes **crearlos** y **cancelarlos**, y los **infraction reports** y **refund requests** relacionados impulsan el flujo de disputa y recuperación.

**Referencia:** [Create a fraud marker](/es/reference/midaz/plugins/indirect-pix/create-a-fraud-marker) · [Cancel a fraud marker](/es/reference/midaz/plugins/indirect-pix/cancel-a-fraud-marker) · [List fraud markers](/es/reference/midaz/plugins/indirect-pix/list-fraud-markers) · [Create an infraction report](/es/reference/midaz/plugins/indirect-pix/create-an-infraction-report)

Para los flujos completos de disputa y recuperación de fondos, consulta [Operaciones de reembolso](/es/midaz/plugins/pix/indirect/indirect-pix-refund-operations) y [MED 2.0 — Recuperación de fondos](/es/midaz/plugins/pix/indirect/indirect-pix-med-2-funds-recovery).

# Próximos pasos

***

* [Códigos QR](/es/midaz/plugins/pix/indirect/indirect-pix-qrcodes) — Generación de códigos QR en claves registradas
* [Webhooks](/es/midaz/plugins/pix/indirect/indirect-pix-webhooks) — Notificaciones de reclamos, infracciones y reembolsos
* [Integración](/es/midaz/plugins/pix/indirect/indirect-pix-integration) — Reconciliación de DICT y configuración del worker