> ## 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 clave, reclamaciones de portabilidad y titularidad, conciliación (VSync) y marcadores de fraude.

**DICT** (Diretório de Identificadores de Contas Transacionais) es el directorio de BACEN que asocia las **claves Pix** con cuentas transaccionales. El Plugin Pix Indirecto (BTG) te conecta con DICT a través de BTG. Registras y resuelves claves, transfieres claves entre instituciones con reclamaciones, concilias tus datos locales con BACEN y gestionas los marcadores de fraude de MED.

La API de DICT abarca varios dominios: entradas y claves, reclamaciones, conciliación, estadísticas y las herramientas de fraude de MED. Las operaciones con ámbito de cuenta requieren el header `X-Account-Id`.

# Entradas y claves

***

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

**Tipos de clave admitidos:**

| Tipo    | Origen del valor                                                            |
| ------- | --------------------------------------------------------------------------- |
| `CPF`   | Se envía en la solicitud (debe coincidir con el CPF del titular en el CRM)  |
| `CNPJ`  | Se envía en la solicitud (debe coincidir con el CNPJ del titular en el CRM) |
| `EMAIL` | Se envía en la solicitud (correo válido, ≤ 77 caracteres)                   |
| `PHONE` | Se envía en la solicitud (`^\+[1-9][0-9]\d{1,14}$`)                         |
| `EVP`   | UUID aleatorio que genera 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 **crear / listar / consultar / actualizar / eliminar** (`/v1/dict/entries`). Crear y eliminar validan contra las reclamaciones activas y verifican la clave contra el documento del titular. Por ejemplo, una clave `CPF` debe coincidir con el CPF del titular.

<Note>
  El plugin no valida las claves con Receita Federal y no ejecuta verificaciones de titularidad con MFA. Supone que completaste esas verificaciones antes de llamarlo. Consulta la [guía de integración](/es/interfaces/pix-btg/indirect-pix-integration) para los prerrequisitos.
</Note>

Las **consultas de clave** (`GET /v1/dict/keys/{key}`) resuelven una clave para el pago. La respuesta devuelve el titular y la cuenta actuales, 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 en bloque. El plugin devuelve los datos tal como los recibe de BTG. Enmascara los campos sensibles antes de mostrarlos de tu lado.

**Referencia:** [Crear entrada](/es/reference/interfaces/pix-btg/create-entry) · [Listar](/es/reference/interfaces/pix-btg/list-entries) · [Consultar](/es/reference/interfaces/pix-btg/retrieve-an-entry) · [Actualizar](/es/reference/interfaces/pix-btg/update-an-entry) · [Eliminar](/es/reference/interfaces/pix-btg/delete-an-entry) · [Consultar una clave](/es/reference/interfaces/pix-btg/retrieve-a-key) · [Verificar claves](/es/reference/interfaces/pix-btg/check-keys-existence)

# Reclamaciones: portabilidad y titularidad

***

Una **reclamación** transfiere una clave Pix entre instituciones. Hay dos tipos:

* **PORTABILITY**: mueve una clave a otro banco **para el mismo titular**. Se permite para `CPF`, `CNPJ`, `PHONE` y `EMAIL`.
* **OWNERSHIP**: reclama una clave de una **persona distinta**. Se permite solo para `PHONE`.

Las dos partes son el **donante** (el participante que tiene la clave en ese momento) y el **reclamante** (el participante que la solicita). El plugin obtiene los datos de la cuenta del reclamante desde el CRM con `X-Account-Id`. BTG define `claimerParticipant` y `donorParticipant` de forma automática.

## Ciclo de vida de la reclamación

| Estado               | Significado                                                         |
| -------------------- | ------------------------------------------------------------------- |
| `OPEN`               | Reclamación creada; espera el acuse del donante                     |
| `WAITING_RESOLUTION` | El donante dio acuse; corre el periodo de resolución (D+7)          |
| `CONFIRMED`          | El donante confirmó; la clave queda bloqueada hasta que se complete |
| `COMPLETED`          | Transferencia de la clave finalizada                                |
| `CANCELLED`          | Cancelada por el donante o el reclamante                            |

Mientras una reclamación está activa (`OPEN`, `WAITING_RESOLUTION` o `CONFIRMED`), la reclamación bloquea la clave. El plugin bloquea las entradas nuevas y las 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 "clave no encontrada" hasta que la reclamación llega a `COMPLETED` o `CANCELLED`.

* **PORTABILITY** puede completarse de inmediato después de la confirmación.
* **OWNERSHIP** agrega una ventana de finalización. BTG devuelve `resolutionPeriodEnd` (D+7) y `completionPeriodEnd` en la reclamación.

## Operaciones de reclamación

| Operación | Rol                  | Endpoint                                |
| --------- | -------------------- | --------------------------------------- |
| Crear     | Reclamante           | `POST /v1/dict/claims`                  |
| Acusar    | Donante              | `POST /v1/dict/claims/{id}/acknowledge` |
| Confirmar | Donante              | `POST /v1/dict/claims/{id}/confirm`     |
| Completar | Reclamante           | `POST /v1/dict/claims/{id}/complete`    |
| Cancelar  | Donante o reclamante | `POST /v1/dict/claims/{id}/cancel`      |

Los webhooks salientes CLAIM entregan los cambios de estado de las reclamaciones a tu sistema. Consulta la [guía de Webhooks](/es/interfaces/pix-btg/indirect-pix-webhooks).

**Referencia:** [Crear una reclamación](/es/reference/interfaces/pix-btg/create-a-claim) · [Listar](/es/reference/interfaces/pix-btg/list-claims) · [Consultar](/es/reference/interfaces/pix-btg/retrieve-a-claim) · [Acusar](/es/reference/interfaces/pix-btg/acknowledge-a-claim) · [Confirmar](/es/reference/interfaces/pix-btg/confirm-a-claim) · [Completar](/es/reference/interfaces/pix-btg/complete-a-claim) · [Cancelar](/es/reference/interfaces/pix-btg/cancel-a-claim)

# Conciliación (VSync)

***

La **conciliación** mantiene tus datos locales de DICT consistentes con los registros de referencia 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, titular, participante, sucursal, 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 saber si tus entradas están sincronizadas sin intercambiar cada registro.

Hay dos rutas:

* **API manual o administrativa**: los operadores disparan verificaciones bajo demanda, descargan archivos de CID e investigan inconsistencias. Usa [Iniciar la conciliación completa](/es/reference/interfaces/pix-btg/start-full-reconciliation) y [Listar los trabajos de conciliación](/es/reference/interfaces/pix-btg/list-all-reconciliation-jobs).
* **Worker VSync**: un proceso automatizado en segundo plano que compara periódicamente las entradas internas con DICT y concilia las divergencias sin intervención del usuario.

Configura la ventana de tiempo del worker de conciliación y la ventana de bloqueo de escritura de DICT en la [guía de integración](/es/interfaces/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 en periodos de bajo tráfico.
</Warning>

# Estadísticas

***

El dominio **Estadísticas** expone los agregados de riesgo y de 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                                   | Ámbito                   | Úsalo para                                                    |
| ------------------------------------------ | ------------------------ | ------------------------------------------------------------- |
| `GET /v1/dict/statistics/persons/{tax_id}` | Una persona (CPF o CNPJ) | Evaluar a un pagador o receptor en todas sus claves y cuentas |
| `GET /v1/dict/statistics/keys/{key}`       | Una sola clave Pix       | Evaluar una clave específica, más su titular actual           |

## Estadísticas de persona

Pasa el documento fiscal (CPF o CNPJ) en la ruta. La respuesta agrega datos de liquidación, marcadores de fraude, informes de infracción 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: por clave y por titular. Las estadísticas por clave se asocian a la clave como entidad, independiente de su titular actual. Las estadísticas por 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 pagas a 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 dos resultados. Guarda en cache con responsabilidad de tu lado si reutilizas un resultado dentro de un flujo de solicitud.
</Note>

**Referencia:** [Consultar las estadísticas de persona](/es/reference/interfaces/pix-btg/retrieve-person-statistics) · [Consultar las estadísticas de clave](/es/reference/interfaces/pix-btg/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 una cuenta como asociada a fraude. Puedes **crearlos** y **cancelarlos** (tipos de fraude: `APPLICATION_FRAUD`, `MULE_ACCOUNT`, `SCAMMER_ACCOUNT`, `OTHER`). Los **informes de infracción** y las **solicitudes de devolución** relacionados impulsan el flujo de disputas de MED 1.0.

**Referencia:** [Crear un marcador de fraude](/es/reference/interfaces/pix-btg/create-a-fraud-marker) · [Cancelar un marcador de fraude](/es/reference/interfaces/pix-btg/cancel-a-fraud-marker) · [Listar los marcadores de fraude](/es/reference/interfaces/pix-btg/list-fraud-markers)

## Informes de infracción

Un **informe de infracción** le indica al PSP de la contraparte que disputas una transacción por fraude. Puedes abrir un informe solo dentro de los **90 días** posteriores a la fecha de la transacción. El informe sigue un ciclo de vida de **crear → acusar → cerrar/cancelar**:

| Paso     | Rol                            | Endpoint                                            |
| -------- | ------------------------------ | --------------------------------------------------- |
| Crear    | Reportante (PSP del pagador)   | `POST /v1/dict/infraction-reports`                  |
| Acusar   | PSP de la contraparte          | `POST /v1/dict/infraction-reports/{id}/acknowledge` |
| Cerrar   | PSP del receptor o del pagador | `POST /v1/dict/infraction-reports/{id}/close`       |
| Cancelar | Reportante                     | `POST /v1/dict/infraction-reports/{id}/cancel`      |

* **Crear**: abre el informe contra el end-to-end ID disputado, por ejemplo `reason: REFUND_REQUEST`, `situationType: SCAM`.
* **Acusar**: el PSP receptor confirma la recepción del informe.
* **Cerrar**: el PSP que responde envía el resultado de su análisis (por ejemplo `TOTALLY_ACCEPTED`) dentro de **7 días**. El PSP del receptor cierra las infracciones `REFUND_REQUEST`. El PSP del pagador cierra las infracciones `REFUND_CANCELLED`. Después del cierre, el informe es inmutable.
* **Cancelar**: el reportante retira un informe 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"
}
```

## Solicitudes de devolución

Una **solicitud de devolución** es el mecanismo de MED 1.0 para pedirle al PSP de la contraparte que devuelva los fondos disputados. Refleja el mismo ciclo de vida de **crear → acusar → cerrar/cancelar**:

| Paso               | Endpoint                                                             |
| ------------------ | -------------------------------------------------------------------- |
| Crear              | `POST /v1/dict/refund-requests`                                      |
| Consultar / Listar | `GET /v1/dict/refund-requests/{id}` · `GET /v1/dict/refund-requests` |
| Cerrar             | `POST /v1/dict/refund-requests/{id}/close`                           |
| Cancelar           | `POST /v1/dict/refund-requests/{id}/cancel`                          |

**Cerrar** registra el resultado del análisis y finaliza la solicitud. **Cancelar** retira una solicitud pendiente. Los webhooks salientes entregan los cambios de estado tanto de los informes de infracción como de las solicitudes de devolución. Consulta la [guía de Webhooks](/es/interfaces/pix-btg/indirect-pix-webhooks).

**Referencia:** [Crear un informe de infracción](/es/reference/interfaces/pix-btg/create-an-infraction-report) · [Acusar](/es/reference/interfaces/pix-btg/acknowledge-an-infraction-report) · [Cerrar](/es/reference/interfaces/pix-btg/close-an-infraction-report) · [Cancelar](/es/reference/interfaces/pix-btg/cancel-an-infraction-report) · [Crear una solicitud de devolución](/es/reference/interfaces/pix-btg/create-a-refund-request)

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

# Próximos pasos

***

* [QR Codes](/es/interfaces/pix-btg/indirect-pix-qrcodes): generación de QR Codes sobre claves registradas
* [Webhooks](/es/interfaces/pix-btg/indirect-pix-webhooks): notificaciones de reclamación, infracción y devolución
* [Integración](/es/interfaces/pix-btg/indirect-pix-integration): conciliación de DICT y configuración del worker