Pular para o conteúdo principal
O DICT (Diretório de Identificadores de Contas Transacionais) é o diretório do BACEN que mapeia chaves Pix para contas transacionais. O Plugin Pix Indireto (BTG) atua como intermediário do DICT por meio do BTG, permitindo que você registre e resolva chaves, transfira chaves entre instituições via reivindicações, mantenha seus dados locais conciliados com o BACEN e gerencie marcadores de fraude do MED. O módulo DICT é organizado em seis domínios: Entradas, Chaves, Reivindicações, Relatórios de Infração, Solicitações de Devolução e Estatísticas. Este guia foca no ciclo de vida das chaves, nas reivindicações e na conciliação. As operações com escopo de conta exigem o cabeçalho X-Account-Id.

​
Entradas e chaves

Uma entrada é uma chave Pix registrada em uma de suas contas. O plugin resolve a conta subjacente e os dados do titular a partir do CRM, então você cria entradas por tipo de chave em vez de fornecer os detalhes da conta diretamente. Tipos de chave suportados:
TipoOrigem do valor
CPFDerivado automaticamente do documento do titular no CRM (não envie key)
CNPJDerivado automaticamente do documento do titular no CRM (não envie key)
EMAILFornecido na requisição (e-mail válido, ≤ 77 caracteres)
PHONEFornecido na requisição (^\+[1-9]\d{1,14}$)
EVPUUID aleatório gerado pelo sistema (não envie key)
POST /v1/dict/entries
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{ "keyType": "EMAIL", "key": "john.doe@example.com" }
Gerencie entradas com criar / listar / recuperar / atualizar / excluir (/v1/dict/entries). A criação/exclusão de entradas valida contra reivindicações ativas e a consistência entre a chave e o documento do titular (por exemplo, uma chave CPF deve corresponder ao CPF do titular).
O plugin não valida chaves com a Receita Federal nem realiza verificações de propriedade por MFA — ele presume que o cliente concluiu essas etapas antes da chamada. Consulte o guia de integração para os pré-requisitos.
Consultas de chave (GET /v1/dict/keys/{key}) resolvem uma chave para fins de pagamento — retornando o titular atual e a conta para que você possa iniciar um pagamento. Use o cabeçalho opcional X-EndToEnd-Id para rastreamento de pagamento e POST /v1/dict/keys/check para verificar a existência em lote. O plugin retorna os dados como recebidos do BTG; mascarar campos sensíveis antes da exibição é responsabilidade do cliente. Referência: Criar entrada · Listar · Recuperar · Atualizar · Excluir · Recuperar uma chave · Verificar chaves

​
Reivindicações: portabilidade e propriedade

Uma reivindicação transfere uma chave Pix entre instituições. Existem dois tipos:
  • PORTABILITY — move uma chave para outro banco para o mesmo titular. Permitido para CPF, CNPJ, PHONE e EMAIL.
  • OWNERSHIP — reivindica uma chave de uma pessoa diferente. Permitido somente para PHONE.
As duas partes são o doador (o participante que detém a chave atualmente) e o reivindicador (o participante que a solicita). Os dados de conta do reivindicador são obtidos do CRM via X-Account-Id; claimerParticipant e donorParticipant são definidos automaticamente pelo BTG.

​
Ciclo de vida da reivindicação

StatusSignificado
OPENReivindicação criada; aguardando o reconhecimento do doador
WAITING_RESOLUTIONDoador reconheceu; período de resolução em andamento (D+7)
CONFIRMEDDoador confirmou; a chave está bloqueada aguardando a conclusão
COMPLETEDTransferência da chave finalizada
CANCELLEDCancelada pelo doador ou reivindicador
Enquanto uma reivindicação está ativa (OPEN, WAITING_RESOLUTION ou CONFIRMED), a chave fica bloqueada: novas entradas e exclusões são impedidas. Durante OPEN/WAITING_RESOLUTION, o doador ainda pode atualizar os dados da conta e as consultas de chave retornam os dados do doador; uma vez CONFIRMED, as consultas retornam “chave não encontrada” até que a reivindicação esteja COMPLETED ou CANCELLED.
  • PORTABILITY pode ser concluída imediatamente após a confirmação.
  • OWNERSHIP tem uma janela de conclusão — resolutionPeriodEnd é D+7 e completionPeriodEnd é D+30.

​
Operações de reivindicação

OperaçãoPapelEndpoint
CriarReivindicadorPOST /v1/dict/claims
ReconhecerDoadorPOST /v1/dict/claims/{id}/acknowledge
ConfirmarDoadorPOST /v1/dict/claims/{id}/confirm
ConcluirReivindicadorPOST /v1/dict/claims/{id}/complete
CancelarDoador ou reivindicadorPOST /v1/dict/claims/{id}/cancel
As mudanças de status da reivindicação são entregues ao seu sistema por meio de webhooks de saída CLAIM. Consulte o guia de Webhooks. Referência: Criar uma reivindicação · Listar · Recuperar · Reconhecer · Confirmar · Concluir · Cancelar

​
Conciliação (VSync)

A conciliação mantém seus dados locais de DICT consistentes com os registros oficiais do BACEN. Ela é construída sobre dois conceitos:
  • CID (Content Identifier) — um hash HMAC-SHA256 de 256 bits dos atributos de uma entrada (tipo de chave, chave, titular, participante, agência, conta etc.).
  • VSync — um único checksum formado pelo XOR de todos os CIDs de um tipo de chave. Como o XOR é comutativo, comparar seu VSync com o do BTG/BACEN revela se o seu conjunto de entradas está sincronizado sem trocar todos os registros.
Existem dois caminhos:
  • API manual / administrativa — operadores disparam verificações sob demanda, baixam arquivos de CID e investigam inconsistências. Use Iniciar conciliação completa e Listar jobs de conciliação.
  • Worker VSync — um processo automatizado em segundo plano que compara periodicamente as entradas internas com o DICT e concilia divergências sem intervenção do usuário.
Configure a janela de tempo do worker de conciliação e a janela de bloqueio de escrita do DICT no guia de integração.
Durante a janela de bloqueio de escrita, o banco de dados bloqueia temporariamente as gravações para evitar inconsistências com o BACEN. Ancore a janela em America/Sao_Paulo e agende-a em períodos de baixo tráfego.

​
Marcadores de fraude (MED)

O DICT também expõe as ferramentas de prevenção a fraudes do MED (Mecanismo Especial de Devolução) do BACEN. Marcadores de fraude sinalizam uma chave ou conta como associada a fraude; você pode criá-los e cancelá-los, e os relatórios de infração e as solicitações de devolução relacionados conduzem o fluxo de disputa e recuperação. Referência: Criar um marcador de fraude · Cancelar um marcador de fraude · Listar marcadores de fraude · Criar um relatório de infração Para os fluxos completos de disputa e recuperação de fundos, consulte Operações de devolução e MED 2.0 — Recuperação de Fundos.

​
Próximos passos

  • QR Codes — Gerando QR Codes em chaves registradas
  • Webhooks — Notificações de reivindicação, infração e devolução
  • Integração — Conciliação do DICT e configuração do worker