> ## 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 > Como o Plugin Pix Indireto (BTG) gerencia chaves Pix no DICT: vínculos, consultas de chave, reivindicações de portabilidade e de posse, conciliação (VSync) e marcações de fraude. O **DICT** (Diretório de Identificadores de Contas Transacionais) é o diretório do BACEN que associa **chaves Pix** a contas transacionais. O Plugin Pix Indireto (BTG) conecta você ao DICT pelo BTG. Você registra e resolve chaves, transfere chaves entre instituições com reivindicações, concilia seus dados locais com o BACEN e gerencia as marcações de fraude do MED. A API do DICT abrange vários domínios: vínculos e chaves, reivindicações, conciliação, estatísticas e as ferramentas de fraude do MED. As operações no escopo de conta exigem o header `X-Account-Id`. # Vínculos e chaves *** Um **vínculo** associa uma chave Pix a uma das suas contas. O plugin resolve os dados da conta e do titular a partir do CRM. Você cria vínculos por tipo de chave, em vez de por dados da conta. **Tipos de chave aceitos:** | Tipo | Origem do valor | | - | - | | `CPF` | Informado na requisição (deve corresponder ao CPF do titular no CRM) | | `CNPJ` | Informado na requisição (deve corresponder ao CNPJ do titular no CRM) | | `EMAIL` | Informado na requisição (e-mail válido, ≤ 77 caracteres) | | `PHONE` | Informado na requisição (`^\+[1-9][0-9]\d{1,14}$`) | | `EVP` | UUID aleatório gerado pelo sistema (não envie `key`) | ```json theme={null} POST /v1/dict/entries X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d X-Reason: USER_REQUESTED { "keyType": "EMAIL", "key": "john.doe@example.com" } ``` Gerencie os vínculos com criar / listar / consultar / atualizar / excluir (`/v1/dict/entries`). A criação, a atualização e a exclusão exigem um header `X-Reason`. A criação e a exclusão validam as reivindicações ativas e conferem a chave com o documento do titular. Por exemplo, uma chave `CPF` deve corresponder ao CPF do titular. Um titular pode ter até 5 chaves (`NATURAL_PERSON`) ou 20 chaves (`LEGAL_PERSON`), e as reivindicações ativas contam para esse limite. A criação de vínculo e a criação de reivindicação retornam `PIX-0129` quando a conta do titular é uma conta salário (`SLRY`). A atualização do vínculo retorna `PIX-0129` quando move uma chave de outro tipo de conta para `SLRY`. > [!NOTE] > > O plugin não valida chaves na Receita Federal e não executa verificações de posse com MFA. Ele supõe que você concluiu essas verificações antes de chamá-lo. Veja os pré-requisitos no [guia de integração](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-integration.md). As **consultas de chave** (`GET /v1/dict/keys/{key}`) resolvem uma chave para pagamento. A resposta traz o dono atual e a conta, para você iniciar um pagamento. A consulta exige o header `X-End-To-End-Id` para o rastreamento do pagamento. Use `POST /v1/dict/keys/check` para checar a existência em lote. O plugin devolve os dados como os recebe do BTG. Mascare os campos sensíveis antes de mostrá-los no seu lado. **Referência:** [Criar vínculo](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/create-entry.md) · [Listar](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/list-entries.md) · [Consultar](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/retrieve-an-entry.md) · [Atualizar](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/update-an-entry.md) · [Excluir](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/delete-an-entry.md) · [Consultar uma chave](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/retrieve-a-key.md) · [Checar chaves](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/check-keys-existence.md) # Reivindicações: portabilidade e posse *** Uma **reivindicação** transfere uma chave Pix entre instituições. Existem dois tipos: * **PORTABILITY**: move uma chave para outro banco para o mesmo titular. Permitida para `CPF`, `CNPJ`, `PHONE` e `EMAIL`. * **OWNERSHIP**: reivindica uma chave de uma pessoa diferente. Permitida apenas para `PHONE`. As duas partes são o **doador** (o participante que detém a chave hoje) e o **reivindicador** (o participante que a solicita). O plugin busca os dados da conta do reivindicador no CRM pelo `X-Account-Id`. O BTG define `claimerParticipant` e `donorParticipant` automaticamente. ## Ciclo de vida da reivindicação | Status | Significado | | - | - | | `OPEN` | Reivindicação criada; aguarda o reconhecimento do doador | | `WAITING_RESOLUTION` | Doador reconheceu; período de resolução em andamento (D+7) | | `CONFIRMED` | Doador confirmou; a chave fica bloqueada até a conclusão | | `COMPLETED` | Transferência da chave finalizada | | `CANCELLED` | Reivindicação cancelada | Enquanto uma reivindicação está ativa (`OPEN`, `WAITING_RESOLUTION` ou `CONFIRMED`), ela trava a chave. O plugin bloqueia novos vínculos e exclusões. Durante `OPEN` e `WAITING_RESOLUTION`, o doador ainda pode atualizar os dados da conta, e as consultas de chave devolvem os dados do doador. Depois de `CONFIRMED`, as consultas devolvem "chave não encontrada" até a reivindicação chegar a `COMPLETED` ou `CANCELLED`. * **PORTABILITY** pode ser concluída logo após a confirmação. * **OWNERSHIP** acrescenta uma janela de conclusão. O BTG devolve `resolutionPeriodEnd` (D+7) e `completionPeriodEnd` na reivindicação. ## Operações de reivindicação | Operação | Papel | Endpoint | | - | - | - | | Criar | Reivindicador | `POST /v1/dict/claims` | | Reconhecer | Doador | `POST /v1/dict/claims/{id}/acknowledge` | | Confirmar | Doador | `POST /v1/dict/claims/{id}/confirm` | | Concluir | Reivindicador | `POST /v1/dict/claims/{id}/complete` | | Cancelar | Doador ou reivindicador | `POST /v1/dict/claims/{id}/cancel` | Apenas o doador pode cancelar com o motivo `COURT_ORDER`. Se o reivindicador o enviar, o plugin retorna `PIX-0136`. Os webhooks de saída CLAIM entregam as mudanças de status das reivindicações ao seu sistema. Veja o [guia de Webhooks](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-webhooks.md). **Referência:** [Criar uma reivindicação](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/create-a-claim.md) · [Listar](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/list-claims.md) · [Consultar](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/retrieve-a-claim.md) · [Reconhecer](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/acknowledge-a-claim.md) · [Confirmar](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/confirm-a-claim.md) · [Concluir](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/complete-a-claim.md) · [Cancelar](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/cancel-a-claim.md) # Conciliação (VSync) *** A **conciliação** mantém seus dados locais do DICT consistentes com os registros oficiais do BACEN. Ela usa dois conceitos: * **CID** (Content Identifier): um hash HMAC-SHA256 de 256 bits dos atributos de um vínculo (tipo de chave, chave, dono, participante, agência, conta etc.). * **VSync**: um único checksum que aplica XOR a cada CID de um tipo de chave. Como o XOR é comutativo, você compara o seu VSync com o do BTG/BACEN para revelar se seus vínculos estão sincronizados, sem trocar todos os registros. Existem dois caminhos: * **API manual / administrativa**: os operadores disparam verificações sob demanda, baixam arquivos de CID e investigam inconsistências. Use [Iniciar conciliação completa](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/start-full-reconciliation.md) e [Listar jobs de conciliação](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/list-all-reconciliation-jobs.md). * **Worker VSync**: um processo automático em background que compara periodicamente os vínculos internos com o DICT e concilia as divergências sem intervenção do usuário. Configure a janela de horário do worker de conciliação e a janela de bloqueio de escrita do DICT no [guia de integração](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-integration.md#7-dict-reconciliation-vsync). > [!WARNING] > > Durante a janela de bloqueio de escrita, a API rejeita as requisições de criação, atualização e exclusão de chaves Pix para evitar inconsistências com o BACEN. O plugin lê a janela no horário de `America/Sao_Paulo`. Agende-a em períodos de baixo tráfego. # Estatísticas *** O domínio **Statistics** expõe os agregados de risco e de uso do Pix do BACEN. Você pode avaliar uma contraparte antes de liquidar um pagamento. Os dois endpoints consultam o provedor diretamente e não armazenam dados localmente. Trate cada chamada como uma consulta nova, em tempo real. | Endpoint | Escopo | Use para | | - | - | - | | `GET /v1/dict/statistics/persons/{tax_id}` | Uma pessoa (CPF ou CNPJ) | Avaliar um pagador/recebedor em todas as chaves e contas dele | | `GET /v1/dict/statistics/keys/{key}` | Uma única chave Pix | Avaliar uma chave específica e o dono atual dela | ## Estatísticas da pessoa Passe o documento fiscal (CPF ou CNPJ) no path. A resposta agrega dados de liquidação, marcações de fraude, relatos de infração e informações de vínculo. Ela cobre três janelas móveis: **d90** (últimos 90 dias), **m12** (últimos 12 meses) e **m60** (últimos 60 meses). ```json theme={null} GET /v1/dict/statistics/persons/12345678901 → 200 OK { "spi": { "settlements": { "d90": "42", "m12": "310", "m60": "1580" } }, "fraudMarkers": { "muleAccounts": { "d90": "0", "m12": "1" } }, "infractionReports": { "openReports": 0, "rejectedReports": { "m12": "2" } }, "entries": { "registeredAccounts": 2 } } ``` ## Estatísticas da chave Passe a chave Pix no path. A resposta devolve duas estatísticas em uma única chamada: no nível da chave e no nível do dono. As estatísticas no nível da chave se ligam à chave como entidade, independentemente do dono atual dela. As estatísticas no nível do dono correspondem às estatísticas da pessoa referentes ao dono atual da chave. ```json theme={null} GET /v1/dict/statistics/keys/john.doe@example.com → 200 OK { "keyStatistics": { "spi": { "settlements": { "d90": "12" } }, "infractionReports": { "openReports": 0 }, "entries": { "distinctAccounts": { "m12": "1" } } }, "ownerStatistics": { "fraudMarkers": { "muleAccounts": { "d90": "0" } }, "infractionReports": { "openReports": 0 }, "entries": { "registeredAccounts": 1 } } } ``` > [!NOTE] > > Use as estatísticas da chave quando você paga uma chave específica. Use as estatísticas da pessoa para uma visão mais ampla do risco da contraparte. O plugin não persiste nenhum dos dois resultados. Faça cache com responsabilidade no seu lado se reutilizar um resultado dentro de um fluxo de requisição. **Referência:** [Consultar estatísticas da pessoa](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/retrieve-person-statistics.md) · [Consultar estatísticas da chave](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/retrieve-key-statistics.md) # Marcações de fraude e MED 1.0 *** O DICT também expõe as ferramentas de prevenção a fraude do **MED** (Mecanismo Especial de Devolução) do BACEN. As **marcações de fraude** sinalizam uma chave ou conta como associada a fraude. Você pode criar e cancelar essas marcações (tipos de fraude: `APPLICATION_FRAUD`, `MULE_ACCOUNT`, `SCAMMER_ACCOUNT`, `OTHER`). Os **relatos de infração** e as **solicitações de devolução** relacionados conduzem o workflow de disputa do MED 1.0. **Referência:** [Criar uma marcação de fraude](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/create-a-fraud-marker.md) · [Cancelar uma marcação de fraude](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/cancel-a-fraud-marker.md) · [Listar marcações de fraude](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/list-fraud-markers.md) ## Relatos de infração Um **relato de infração** avisa o PSP da contraparte que você contesta uma transação como fraude. Você pode abrir um relato apenas dentro de 90 dias a partir da data da transação. O relato segue um ciclo de vida criar → reconhecer → encerrar/cancelar: | Etapa | Papel | Endpoint | | - | - | - | | Criar | Relator (PSP do pagador) | `POST /v1/dict/infraction-reports` | | Reconhecer | PSP da contraparte | `POST /v1/dict/infraction-reports/{id}/acknowledge` | | Encerrar | PSP do recebedor/pagador | `POST /v1/dict/infraction-reports/{id}/close` | | Cancelar | Relator | `POST /v1/dict/infraction-reports/{id}/cancel` | * **Criar**: abre o relato contra o end-to-end ID contestado, por exemplo `reason: REFUND_REQUEST`, `situationType: SCAM`. * **Reconhecer**: o PSP que recebe confirma o recebimento do relato. * **Encerrar**: o PSP que responde envia o resultado da análise (`AGREED` ou `DISAGREED`) em até 7 dias. O PSP do recebedor fecha as infrações `REFUND_REQUEST`. O PSP do pagador fecha as infrações `REFUND_CANCELLED`. Depois do encerramento, o relato fica imutável. * **Cancelar**: o relator retira um relato que ele abriu. ```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" } ``` ## Solicitações de devolução Uma **solicitação de devolução** é o mecanismo do MED 1.0 para pedir ao PSP da contraparte que devolva os recursos contestados. Ela segue um ciclo de vida criar → encerrar/cancelar: | Etapa | Endpoint | | - | - | | Criar | `POST /v1/dict/refund-requests` | | Consultar / Listar | `GET /v1/dict/refund-requests/{id}` · `GET /v1/dict/refund-requests` | | Encerrar | `POST /v1/dict/refund-requests/{id}/close` | | Cancelar | `POST /v1/dict/refund-requests/{id}/cancel` | **Encerrar** registra o resultado da análise e finaliza a solicitação. O `effectiveRefundedAmount` deve combinar com o `refundAnalysisResult`: é igual ao valor solicitado para `TOTALLY_ACCEPTED`, é maior que zero e menor que o valor solicitado para `PARTIALLY_ACCEPTED`, e é zero para `REJECTED`. Qualquer outro valor responde `400` `PIX-0246`. **Cancelar** retira uma solicitação pendente. Os webhooks de saída entregam as mudanças de status tanto dos relatos de infração quanto das solicitações de devolução. Veja o [guia de Webhooks](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-webhooks.md). **Referência:** [Criar um relato de infração](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/create-an-infraction-report.md) · [Reconhecer](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/acknowledge-an-infraction-report.md) · [Encerrar](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/close-an-infraction-report.md) · [Cancelar](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/cancel-an-infraction-report.md) · [Criar uma solicitação de devolução](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/create-a-refund-request.md) Para os fluxos de recuperação de recursos, veja [Operações de devolução](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-refund-operations.md) e [MED 2.0: Recuperação de Fundos](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-med-2-funds-recovery.md). # Próximos passos *** * [QR Codes](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-qrcodes.md): gerar QR Codes em chaves registradas * [Webhooks](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-webhooks.md): notificações de reivindicação, de infração e de devolução * [Integração](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-integration.md): conciliação do DICT e configuração do worker This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.