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

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.

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 para los prerrequisitos.

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 · Listar · Consultar · Actualizar · Eliminar · Consultar una clave · Verificar claves

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. Referencia: Crear una reclamación · Listar · Consultar · Acusar · Confirmar · Completar · Cancelar

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 y Listar los trabajos de conciliación.
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.

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.

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

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.

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

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.

Referencia: Consultar las estadísticas de persona · Consultar las estadísticas de clave

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 · Cancelar un marcador de fraude · Listar los marcadores de fraude

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ó.

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. Referencia: Crear un informe de infracción · Acusar · Cerrar · Cancelar · Crear una solicitud de devolución Para los flujos de recuperación de fondos, consulta Operaciones de devolución y MED 2.0 — Recuperación de fondos.

Próximos pasos

QR Codes: generación de QR Codes sobre claves registradas
Webhooks: notificaciones de reclamación, infracción y devolución
Integración: conciliación de DICT y configuración del worker

​Entradas y claves

​Reclamaciones: portabilidad y titularidad

​Ciclo de vida de la reclamación

​Operaciones de reclamación

​Conciliación (VSync)

​Estadísticas

​Estadísticas de persona

​Estadísticas de clave

​Marcadores de fraude y MED 1.0

​Informes de infracción

​Solicitudes de devolución

​Próximos pasos

Entradas y claves

Reclamaciones: portabilidad y titularidad

Ciclo de vida de la reclamación

Operaciones de reclamación

Conciliación (VSync)

Estadísticas

Estadísticas de persona

Estadísticas de clave

Marcadores de fraude y MED 1.0

Informes de infracción

Solicitudes de devolución

Próximos pasos