Saltar al contenido principal
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:
TipoOrigen del valor
CPFDerivado automáticamente del documento del titular en CRM (no envíes key)
CNPJDerivado automáticamente del documento del titular en CRM (no envíes key)
EMAILProporcionado en la solicitud (email válido, ≤ 77 caracteres)
PHONEProporcionado en la solicitud (^\+[1-9]\d{1,14}$)
EVPUUID aleatorio generado por 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 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).
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 para conocer los requisitos previos.
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 · 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). 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

EstadoSignificado
OPENReclamo creado; a la espera del reconocimiento del donante
WAITING_RESOLUTIONEl donante reconoció; periodo de resolución en curso (D+7)
CONFIRMEDEl donante confirmó; la clave queda bloqueada hasta su finalización
COMPLETEDTransferencia de clave finalizada
CANCELLEDCancelado 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ónRolEndpoint
CreateReclamantePOST /v1/dict/claims
AcknowledgeDonantePOST /v1/dict/claims/{id}/acknowledge
ConfirmDonantePOST /v1/dict/claims/{id}/confirm
CompleteReclamantePOST /v1/dict/claims/{id}/complete
CancelDonante o reclamantePOST /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. 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. 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 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.

​
Marcadores de fraude (MED)

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, y los infraction reports y refund requests relacionados impulsan el flujo de disputa y recuperación. Referencia: Create a fraud marker · Cancel a fraud marker · List fraud markers · Create an infraction report Para los flujos completos de disputa y 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