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)

POST /v1/dict/entries
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{ "keyType": "EMAIL", "key": "[e-mail]" }

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.

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 para conocer los requisitos previos.

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 · List · Retrieve · Update · Delete · Retrieve a key · Check keys

​

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.

Referencia: Create a claim · List · Retrieve · Acknowledge · Confirm · Complete · Cancel

​

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 y List 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.

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.

​

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

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.

GET /v1/dict/statistics/keys/[e-mail]
→ 200 OK
{
  "keyStatistics": { "settlements": { "d90": 12 }, "ownershipChanges": { "m12": 1 } },
  "ownerStatistics": { "fraudMarkers": { "d90": 0 }, "infractionReports": { "m12": 0 } }
}

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.

Referencia: Retrieve person statistics · 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 · Cancel a fraud marker · 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ó.

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.

Referencia: Create an infraction report · Acknowledge · Close · Cancel · Create a refund request

Para los flujos de recuperación de fondos, consulta Operaciones de reembolso y MED 2.0 — Recuperación de fondos.

​

Próximos pasos

---

• Códigos QR — Generación de códigos QR en claves registradas
• Webhooks — Notificaciones de reclamos, infracciones y reembolsos
• Integración — Reconciliación de DICT y configuración del worker