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

# Estadísticas

***

El dominio **Estadísticas** expone los agregados de riesgo y uso de Pix de BACEN, permitiéndote evaluar a una contraparte **antes** de liquidar un pago. Ambos endpoints consultan al proveedor directamente y **no almacenan datos localmente**, así que trata cada llamada como una consulta nueva en tiempo real. Están etiquetados bajo la API MED y requieren autenticación bearer.

| Endpoint                                   | Alcance                  | Úsalo para                                                      |
| ------------------------------------------ | ------------------------ | --------------------------------------------------------------- |
| `GET /v1/dict/statistics/persons/{tax_id}` | Una persona (CPF o CNPJ) | Evaluar a un pagador/beneficiario en todas sus claves y cuentas |
| `GET /v1/dict/statistics/keys/{key}`       | Una única clave Pix      | Evaluar una clave específica, junto con su titular actual       |

## Estadísticas de persona

Pasa el tax ID (CPF o CNPJ) en la ruta. La respuesta agrega datos de liquidación, marcadores de fraude, infraction reports e información de entradas a lo largo de tres ventanas móviles: **d90** (últimos 90 días), **m12** (últimos 12 meses) y **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 }
  }
}
```

## Estadísticas de clave

Pasa la clave Pix en la ruta. La respuesta devuelve **tanto** las estadísticas a nivel de clave (datos ligados a la clave como entidad, independientes de su titular actual) como las estadísticas a nivel de titular (equivalentes a las estadísticas de persona del titular actual de la clave) en una sola llamada.

```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>
  Usa las estadísticas de clave cuando estés a punto de pagar una clave específica, y las estadísticas de persona para una visión más amplia del riesgo de la contraparte. Como ninguna se persiste, cachea de forma responsable en tu lado si necesitas reutilizar el resultado dentro de un flujo de solicitud.
</Note>

**Referencia:** [Retrieve person statistics](/es/reference/midaz/plugins/indirect-pix/retrieve-person-statistics) · [Retrieve key statistics](/es/reference/midaz/plugins/indirect-pix/retrieve-key-statistics)

# Marcadores de fraude y MED 1.0

***

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** (tipos de fraude: `APPLICATION_FRAUD`, `MULE_ACCOUNT`, `SCAMMER_ACCOUNT`, `OTHER`). Los **infraction reports** y **refund requests** relacionados impulsan el flujo de disputa de MED 1.0.

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

## Infraction reports

Un **infraction report** notifica al PSP de la contraparte que una transacción está en disputa por fraude. Solo puede abrirse dentro de los **90 días** posteriores a la fecha de la transacción, y sigue un ciclo de vida **create → acknowledge → close/cancel**:

| Paso        | Rol                          | Endpoint                                            |
| ----------- | ---------------------------- | --------------------------------------------------- |
| Create      | Reportante (PSP del pagador) | `POST /v1/dict/infraction-reports`                  |
| Acknowledge | PSP de la contraparte        | `POST /v1/dict/infraction-reports/{id}/acknowledge` |
| Close       | PSP del beneficiario/pagador | `POST /v1/dict/infraction-reports/{id}/close`       |
| Cancel      | Reportante                   | `POST /v1/dict/infraction-reports/{id}/cancel`      |

* **Create** — abre el reporte contra el end-to-end ID en disputa, p. ej. `reason: REFUND_REQUEST`, `situationType: SCAM`.
* **Acknowledge** — el PSP receptor confirma que recibió el reporte.
* **Close** — el PSP que responde envía su resultado de análisis (por ejemplo `TOTALLY_ACCEPTED`) dentro de **7 días**. Las infracciones `REFUND_REQUEST` las cierra el PSP del beneficiario; las infracciones `REFUND_CANCELLED`, el PSP del pagador. Una vez cerrado, el reporte es inmutable.
* **Cancel** — el reportante retira un reporte que abrió.

```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"
}
```

## Refund requests

Un **refund request** es el mecanismo de MED 1.0 para pedir al PSP de la contraparte que devuelva los fondos en disputa. Refleja el mismo ciclo de vida **create → acknowledge → close/cancel**:

| Paso            | 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 el resultado del análisis y finaliza la solicitud; **cancel** retira una solicitud pendiente. Los cambios de estado tanto de los infraction reports como de los refund requests se entregan mediante webhooks salientes — consulta la [guía de Webhooks](/es/rails/pix/btg/indirect-pix-webhooks).

**Referencia:** [Create an infraction report](/es/reference/midaz/plugins/indirect-pix/create-an-infraction-report) · [Acknowledge](/es/reference/midaz/plugins/indirect-pix/acknowledge-an-infraction-report) · [Close](/es/reference/midaz/plugins/indirect-pix/close-an-infraction-report) · [Cancel](/es/reference/midaz/plugins/indirect-pix/cancel-an-infraction-report) · [Create a refund request](/es/reference/midaz/plugins/indirect-pix/create-a-refund-request)

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

# Próximos pasos

***

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