> ## 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, portabilidad, 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) te conecta a DICT a través de BTG. Registras y resuelves claves, transfieres claves entre instituciones con reclamos, reconcilias tus datos locales con BACEN y gestionas marcadores de fraude MED.

La API de DICT abarca varios dominios: entradas y claves, reclamos, reconciliación, estadísticas y las herramientas de fraude MED. Esta guía cubre el ciclo de vida de las claves, los reclamos, la reconciliación, las estadísticas y MED. Las operaciones con alcance de cuenta requieren el header `X-Account-Id`.

# Entradas y claves

***

Una **entrada** vincula una clave Pix a una de tus cuentas. El plugin resuelve los datos de la cuenta y del titular desde CRM. Creas entradas por tipo de clave en lugar de detalles de la cuenta.

**Tipos de clave admitidos:**

| Tipo    | Origen del valor                                                              |
| ------- | ----------------------------------------------------------------------------- |
| `CPF`   | Proporcionado en la solicitud (debe coincidir con el CPF del titular en CRM)  |
| `CNPJ`  | Proporcionado en la solicitud (debe coincidir con el CNPJ del titular en CRM) |
| `EMAIL` | Proporcionado en la solicitud (email válido, ≤ 77 caracteres)                 |
| `PHONE` | Proporcionado en la solicitud (`^\+[1-9][0-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 y la eliminación validan contra los reclamos activos y comprueban la clave frente al 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 completaste esas comprobaciones antes de llamarlo. 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. La respuesta devuelve el propietario actual y la cuenta, para que puedas iniciar un pago. La consulta requiere el header `X-End-To-End-Id` para el seguimiento del pago. Usa `POST /v1/dict/keys/check` para verificar la existencia de forma masiva. El plugin devuelve los datos tal como los recibe de BTG. Enmascara los campos sensibles antes de mostrarlos en tu lado.

**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). El plugin obtiene los datos de la cuenta del reclamante desde CRM mediante `X-Account-Id`. BTG establece `claimerParticipant` y `donorParticipant` 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`), el reclamo bloquea la clave. El plugin impide nuevas entradas y eliminaciones. Durante `OPEN` y `WAITING_RESOLUTION`, el donante todavía puede actualizar los datos de la cuenta, y las consultas de clave devuelven los datos del donante. Después de `CONFIRMED`, las consultas devuelven "key not found" hasta que el reclamo llega a `COMPLETED` o `CANCELLED`.

* **PORTABILITY** puede completarse inmediatamente después de la confirmación.
* **OWNERSHIP** añade una ventana de finalización. BTG devuelve `resolutionPeriodEnd` (D+7) y `completionPeriodEnd` en el reclamo.

## 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 webhooks salientes **CLAIM** entregan los cambios de estado del reclamo a tu sistema. 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. Usa 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 que aplica XOR a cada CID de un tipo de clave. Como XOR es conmutativo, comparas tu VSync con el de BTG/BACEN para revelar si tus entradas están sincronizadas 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. Puedes evaluar a una contraparte **antes** de liquidar un pago. Ambos endpoints consultan al proveedor directamente y **no almacenan datos localmente**. Trata cada llamada como una consulta nueva en tiempo real. Ambos endpoints 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. Cubre 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 dos estadísticas en una sola llamada: a nivel de clave y a nivel de titular. Las estadísticas a nivel de clave se refieren a la clave como entidad, independientes de su titular actual. Las estadísticas a nivel de titular coinciden con las estadísticas de persona del titular actual de la clave.

```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 pagues una clave específica. Usa las estadísticas de persona para una visión más amplia del riesgo de la contraparte. El plugin no persiste ninguno de los resultados. Cachea con responsabilidad en tu lado si reutilizas un 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** informa al PSP de la contraparte de que disputas una transacción como fraude. Solo puedes abrir un reporte dentro de los **90 días** posteriores a la fecha de la transacción. El reporte 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 la recepción del reporte.
* **Close** — el PSP que responde envía su resultado de análisis (por ejemplo `TOTALLY_ACCEPTED`) dentro de **7 días**. El PSP del beneficiario cierra las infracciones `REFUND_REQUEST`. El PSP del pagador cierra las infracciones `REFUND_CANCELLED`. Tras el cierre, 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 webhooks salientes entregan los cambios de estado tanto de los infraction reports como de los refund requests. 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