> ## 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. # Reconciliação Pix > Configure o Matcher para conciliar transações Pix de cash-in e cash-out entre o Midaz Ledger e os extratos de liquidação do SPI do BACEN. Este guia orienta a conciliação de transações Pix entre o Midaz Ledger e os dados de liquidação do BACEN (Banco Central do Brasil) usando o Matcher. Ele cobre tanto Pix enviado (cash-out) quanto Pix recebido (cash-in), desde a configuração até a operação diária e o tratamento de exceções. Ao final deste guia, você terá um contexto do Matcher totalmente configurado que concilia automaticamente suas transações Pix contra os extratos de liquidação SPI do BACEN em base diária. ## Fluxos de transação Pix *** Entender como as transações Pix fluem pelo sistema é essencial para configurar a conciliação corretamente. Os dois fluxos abaixo mostram o que o Matcher precisa conciliar em cada lado. ### Pix enviado (cash-out) Fluxo de cash-out Pix 1. **Cliente inicia o Pix** — O usuário final dispara um pagamento Pix via app ou API. 2. **Plugin cria a iniciação** — O plugin Pix cria um registro de iniciação e resolve a conta de destino via consulta ao DICT. 3. **Plugin processa o pagamento** — O plugin debita a conta do cliente no Midaz (transação em status `pending`) e envia a instrução de pagamento ao SPI. 4. **Liquidação confirmada** — O SPI envia um webhook confirmando a liquidação. A transação no Midaz é confirmada. 5. **Matcher concilia** — O Matcher compara a transação confirmada no Midaz contra a entrada correspondente no extrato de liquidação SPI do BACEN. ### Pix recebido (cash-in) Fluxo de cash-in Pix 1. **Pix de entrada chega** — O SPI envia um webhook síncrono contendo os dados do Pix recebido. 2. **Plugin valida** — O plugin Pix valida o payload e aprova a transação. 3. **Transação de crédito criada** — O plugin cria uma transação de CRÉDITO no Midaz para a conta do destinatário. 4. **Liquidação confirmada** — O webhook de liquidação confirma que a transação é final. 5. **Matcher concilia** — O Matcher compara a transação de crédito no Midaz contra a entrada correspondente no extrato de liquidação SPI do BACEN. Em ambos os fluxos, o **endToEndId** é o identificador único que vincula a transação do Midaz ao registro de liquidação do BACEN. Esta é a chave primária para a conciliação. ## Configuração passo a passo *** Crie um contexto de conciliação para transações Pix. Use o tipo `1:1` porque cada transação Pix tem exatamente uma entrada correspondente de liquidação no BACEN. ```json theme={null} { "name": "Pix Daily Reconciliation", "type": "1:1", "interval": "daily", "feeToleranceAbs": "0", "feeTolerancePct": "0", "autoMatchOnUpload": false } ``` Transações Pix não possuem taxas intermediárias ou liquidações parciais. Um Pix de R$ 150,00 no Midaz deve aparecer como exatamente R$ 150,00 no extrato do BACEN. Defina ambos os valores de tolerância como zero — eles são strings decimais, então passe `"0"`. Definir `autoMatchOnUpload` como `false` dá a você controle sobre quando o matching é executado, o que é importante quando você precisa que ambas as fontes sejam ingeridas antes da execução. Veja o schema completo da requisição em [Criar contexto](/pt/reference/matcher/create-context). Cada contexto precisa de duas fontes: uma para as transações do Midaz e outra para o extrato de liquidação do BACEN. **Fonte A — Midaz (tipo `LEDGER`):** ```json theme={null} { "name": "Midaz - Pix Transactions", "type": "LEDGER", "side": "LEFT", "config": {} } ``` `LEDGER` é a categoria do Matcher para dados de ledger interno — não é um conector direto com o Midaz. Você exporta as transações Pix do dia do Midaz (incluindo o metadado `endToEndId` como coluna plana) e envia a exportação para esta fonte, manualmente ou por um pipeline automatizado. Veja [Matcher e Midaz](/pt/matcher/integrations/matcher-midaz-integration) para o fluxo de exportação/importação. **Fonte B — Extrato SPI do BACEN (tipo `CUSTOM`):** ```json theme={null} { "name": "BACEN SPI Settlement Extract", "type": "CUSTOM", "side": "RIGHT", "config": { "description": "Daily SPI settlement file from BACEN" } } ``` A fonte do BACEN usa o tipo `CUSTOM` porque o arquivo de liquidação SPI é carregado manualmente ou via pipeline automatizado a cada dia. Cada fonte deve declarar um `side` (`LEFT` ou `RIGHT`). Um contexto concilia sua fonte `LEFT` contra sua fonte `RIGHT`, então atribua um lado ao Midaz e o outro ao BACEN, e mantenha a atribuição consistente em ambas as fontes. Veja o schema completo da requisição em [Criar fonte](/pt/reference/matcher/create-source). Os mapas de campos dizem ao Matcher como traduzir campos de cada fonte para os campos canônicos usados no matching. Um mapa de campos é um objeto JSON no formato `{ "": "" }`. As chaves vêm do vocabulário canônico fechado do Matcher (`external_id`, `amount`, `currency`, `date` e os opcionais `description`, `fee_amount`, `fee_currency`); os valores são os nomes de coluna brutos em cada fonte. As buscas são **planas** — o valor de um mapeamento precisa nomear uma coluna de nível superior da linha, então a exportação do Midaz precisa trazer o `endToEndId` como coluna plana própria (veja [Matcher e Midaz — mapeamento de campos customizado](/pt/matcher/integrations/matcher-midaz-integration#mapeamento-de-campos-customizado)). `external_id` é a **referência de matching entre lados** — o valor que o motor compara entre as duas fontes quando uma regra define `matchReference`. Mapeie-o para o `endToEndId` nos **dois** lados. Não mapeie IDs locais de cada lado (o `id` da transação no Midaz, o `id_liquidacao` do BACEN) em `external_id`: esses valores nunca coincidem entre as fontes, então o matching por referência jamais encontraria uma contraparte. A tabela a seguir mostra como cada campo canônico é mapeado para a coluna em cada fonte: | Campo canônico | Coluna da exportação Midaz | Coluna do extrato BACEN | | -------------- | -------------------------- | ----------------------- | | `external_id` | `endToEndId` | `end_to_end_id` | | `amount` | `amount` | `valor` | | `currency` | `asset_code` | `moeda` | | `date` | `created_at` | `data_liquidacao` | **Fonte Midaz — mapa de campos:** ```json theme={null} { "mapping": { "external_id": "endToEndId", "amount": "amount", "currency": "asset_code", "date": "created_at" } } ``` **Fonte BACEN — mapa de campos:** ```json theme={null} { "mapping": { "external_id": "end_to_end_id", "amount": "valor", "currency": "moeda", "date": "data_liquidacao" } } ``` Veja [Criar mapa de campos](/pt/reference/matcher/create-field-map) para o schema completo da requisição e [Mapeamento de campos](/pt/matcher/configuration/matcher-field-mapping) para o vocabulário canônico. As regras de match definem como o Matcher compara transações entre fontes. Para a conciliação Pix, duas regras cobrem a grande maioria dos cenários. **Regra 1 — Match exato por endToEndId (prioridade 1):** ```json theme={null} { "type": "EXACT", "priority": 1, "config": { "matchAmount": true, "matchCurrency": true, "matchDate": true, "matchReference": true, "datePrecision": "DAY", "caseInsensitive": false, "referenceMustSet": true, "matchScore": 100 } } ``` Esta regra resolve aproximadamente 95% dos casos. O `endToEndId` é único por transação Pix em todo o ecossistema. Quando a referência, o valor, a moeda e a data coincidem, é uma conciliação confirmada com confiança máxima. Note que `caseInsensitive` está definido como `false` porque os valores de `endToEndId` são case-sensitive, e `referenceMustSet` é `true` para garantir que ambos os lados possuam o `endToEndId` antes da comparação — isso previne falsos positivos baseados apenas em valor e data. **Regra 2 — Fallback com tolerância de data (prioridade 51):** ```json theme={null} { "type": "DATE_LAG", "priority": 51, "config": { "maxDays": 1, "minDays": 0, "inclusive": true, "direction": "ABS", "feeTolerance": 0, "matchScore": 85, "matchCurrency": true } } ``` Um Pix iniciado às 23:58 pode ser liquidado no BACEN no dia seguinte. Esta regra permite uma janela de 1 dia para cobrir cenários de liquidação D+1. Note que esta regra depende apenas da correspondência de valor e moeda — a comparação do `endToEndId` é tratada pela Regra 1. Veja [Criar regra de match](/pt/reference/matcher/create-match-rule) para o schema completo da requisição e todos os tipos de regra disponíveis. Com toda a configuração em vigor, ative o contexto e crie um agendamento diário. **Ativar o contexto:** ```bash theme={null} curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "status": "ACTIVE" }' ``` **Criar um agendamento para executar diariamente às 07:00 UTC:** ```bash theme={null} curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/schedules" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "cronExpression": "0 7 * * *", "enabled": true }' ``` Executar às 07:00 UTC fornece margem suficiente para que liquidações D+1 apareçam no extrato do BACEN e para que o arquivo diário seja carregado antes da execução do matching. Veja [Atualizar contexto](/pt/reference/matcher/update-context) e [Criar agendamento](/pt/reference/matcher/create-schedule) para os schemas completos das requisições. ## Operação diária *** Uma vez configurado, o fluxo de conciliação diária segue cinco passos. Carregue o arquivo de liquidação SPI do dia anterior na fonte do BACEN. O Matcher interpreta CSV, JSON, XML e outros formatos do seu [catálogo de formatos](/pt/matcher/imports/matcher-import-formats). ```bash theme={null} curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{sourceId}/upload" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: multipart/form-data" \ -F "file=@bacen_spi_2026-03-17.csv" \ -F "format=csv" ``` Este passo pode ser automatizado via pipeline que busca o arquivo SPI e o carrega antes da execução agendada de matching. Exporte as transações Pix confirmadas do dia anterior do Midaz — incluindo o metadado `endToEndId` como coluna plana — e envie a exportação para a fonte do Midaz da mesma forma. Este passo costuma ser automatizado pelo mesmo pipeline. Veja [Matcher e Midaz](/pt/matcher/integrations/matcher-midaz-integration) para o fluxo de exportação/importação. A execução agendada acontece automaticamente às 07:00 UTC. Para executar o matching manualmente, use o endpoint de execução. ```bash theme={null} curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "mode": "DRY_RUN" }' ``` Use `DRY_RUN` primeiro para visualizar os resultados sem confirmá-los. Quando estiver satisfeito, execute novamente com `COMMIT`: ```bash theme={null} curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "mode": "COMMIT" }' ``` Após a execução ser concluída, recupere os grupos de match para ver os resultados. ```bash theme={null} curl -X GET "https://api.matcher.example.com/v1/matching/runs/{runId}/groups" \ -H "Authorization: Bearer $TOKEN" ``` Cada grupo mostra a transação do Midaz conciliada com sua entrada correspondente de liquidação do BACEN, junto com a regra que as conciliou e o score de confiança. Transações não conciliadas aparecem como exceções. Elas requerem investigação — uma transação presente em uma fonte mas ausente da outra, ou uma divergência de valor ou data além da tolerância configurada. Revise as exceções, determine a causa raiz e resolva-as por force match, ignorando ou corrigindo os dados subjacentes. Sempre execute um `DRY_RUN` primeiro ao testar novas regras ou após alterações de configuração. Isso previne que matches indesejados sejam confirmados. ## Exemplo prático — um dia de dados *** O exemplo a seguir ilustra uma execução completa de conciliação para 17 de março de 2026. ### Transações Midaz (Fonte A) | ID (tipo) | endToEndId | Valor · data | | ----------------- | ---------------------- | -------------------------- | | txn-001 (Pix OUT) | E123456789202603170001 | 150.00 · 2026-03-17 10:15 | | txn-002 (Pix IN) | E987654321202603170042 | 3200.50 · 2026-03-17 11:30 | | txn-003 (Pix OUT) | E555666777202603170099 | 89.90 · 2026-03-17 23:58 | | txn-004 (Pix IN) | E111222333202603170007 | 500.00 · 2026-03-17 14:00 | ### Extrato SPI do BACEN (Fonte B) | id\_liquidacao | end\_to\_end\_id | valor / data\_liquidacao | | -------------- | ---------------------- | ------------------------ | | liq-8801 | E123456789202603170001 | 150.00 / 2026-03-17 | | liq-8802 | E987654321202603170042 | 3200.50 / 2026-03-17 | | liq-8803 | E555666777202603170099 | 89.90 / 2026-03-18 | | liq-8804 | E444555666202603170055 | 750.00 / 2026-03-17 | ### Resultados do matching | endToEndId | Midaz ↔ BACEN | Resultado (regra) | | ------------- | ------------------ | ----------------------------------- | | E12345...0001 | txn-001 ↔ liq-8801 | Match — EXACT (score: 100) | | E98765...0042 | txn-002 ↔ liq-8802 | Match — EXACT (score: 100) | | E55566...0099 | txn-003 ↔ liq-8803 | Match (D+1) — DATE\_LAG (score: 85) | | E11122...0007 | txn-004 ↔ — | Exceção — — | | E44455...0055 | — ↔ liq-8804 | Exceção — — | ### Análise * **txn-001 e txn-002:** Match exato por endToEndId, valor, moeda e data. A Regra 1 resolveu estes com score de confiança 100. * **txn-003:** Pix iniciado às 23:58, liquidado no BACEN em 2026-03-18. A Regra 2 (DATE\_LAG com janela de 1 dia) pareou este com score de confiança 85. Matches de date-lag nunca são confirmados automaticamente — o par vai para a fila de revisão para confirmação humana. * **txn-004:** Presente no Midaz mas ausente do BACEN. Possível falha de liquidação ou timeout SPI. Investigue o status da transação via plugin Pix. * **liq-8804:** Presente no BACEN mas ausente do Midaz. Um Pix de entrada que não foi processado. Verifique a entrega do webhook ou reprocesse a mensagem. ## Tratamento de exceções Pix *** A tabela a seguir cobre os cenários de exceção Pix mais comuns e as ações recomendadas. | Cenário | Causa provável | Ação recomendada | | ---------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | | No Midaz, não no BACEN | Falha de liquidação, timeout SPI, transação rejeitada | Verifique o status da transação no plugin Pix. Se rejeitada, reverta no Midaz. | | No BACEN, não no Midaz | Pix de entrada não processado, falha de webhook | Reprocesse a mensagem. Crie uma transação manual se necessário. | | Divergência de valor | Raro no Pix (sem taxas intermediárias). Possível erro de arredondamento. | Investigue os registros originais. Faça force match se a diferença for aceitável. | | Divergência de data (>1 dia) | Transação retida, reprocessamento | Verifique se é o mesmo Pix. Faça force match ou ignore. | ### Force match Quando você confirmou que dois registros representam a mesma transação Pix mas o Matcher não conseguiu conciliá-los automaticamente, use force match. ```bash theme={null} curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/force-match" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "notes": "Confirmed same Pix via endToEndId lookup in SPI", "overrideReason": "D+2 settlement delay confirmed with BACEN" }' ``` ### Ignorar transação Quando uma transação deve ser excluída da conciliação (por exemplo, uma entrada duplicada ou um Pix já estornado), marque-a como ignorada. ```bash theme={null} curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/transactions/{transactionId}/ignore" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "reason": "Pix reversal already processed — duplicate entry" }' ``` Veja [Force match](/pt/reference/matcher/force-match-exception) e [Ignorar transação](/pt/reference/matcher/ignore-transaction) para os schemas completos das requisições. ## Devoluções Pix *** Devoluções Pix geram transações reversas que também precisam de conciliação. Quando uma devolução é processada, o plugin Pix cria uma nova transação no Midaz com: * O `originalEndToEndId` vinculando à transação Pix original * Um novo `returnIdentification` (rtrId) que identifica unicamente a devolução no SPI O extrato de liquidação do BACEN inclui entradas de devolução com ambos os identificadores, permitindo que o Matcher as concilie contra as transações de devolução correspondentes no Midaz. Para volumes baixos de devolução, elas podem ser conciliadas dentro do mesmo contexto de Conciliação Pix Diária. Para volumes altos, crie um contexto separado dedicado à conciliação de devoluções. Isso simplifica a triagem de exceções e mantém as métricas de devolução isoladas das métricas do fluxo Pix padrão. A iniciação de devoluções via `POST /v1/transfers/{id}/refunds` é um endpoint do **plugin Pix**, **não** um endpoint do Matcher. O Matcher não inicia transferências ou devoluções — ele apenas concilia as transações resultantes. Cada devolução carrega o `originalEndToEndId` e um novo `returnIdentification` para rastreabilidade ponta a ponta, que o Matcher então usa para conciliar a devolução contra o extrato de liquidação do BACEN. Para a iniciação de devoluções, veja a [documentação do plugin Pix](/pt/midaz/plugins/pix/pix-overview). ## Boas práticas *** O `endToEndId` é o identificador Pix único em todo o ecossistema — da instituição iniciadora, passando pelo SPI, até a instituição recebedora. Garanta que ele esteja armazenado nos metadados da transação no Midaz e presente no extrato do BACEN. Sem ele, a conciliação recai em matching por valor e data, que é muito menos confiável. Transações Pix próximas ao fim do dia podem ser liquidadas no BACEN em D+1. Agendar o Matcher para 07:00 UTC garante que todas as liquidações do dia anterior estejam incluídas no extrato do BACEN antes da execução do matching. Isso elimina exceções falsas causadas por timing. Ao processar volumes altos de Pix, crie dois contextos separados — um para cash-out e outro para cash-in. Isso simplifica a triagem de exceções, fornece métricas mais granulares por fluxo e permite agendamento independente se necessário. Uma conciliação Pix saudável alcança uma taxa de match automático acima de 99%. Se a taxa cair abaixo de 95%, investigue problemas sistêmicos como falhas no plugin, mudanças no formato do BACEN ou metadados ausentes nas transações do Midaz. O Pix não possui taxas intermediárias, liquidações parciais ou cobranças de processamento. Se os valores divergirem entre o Midaz e o BACEN, isso indica um problema real — não arredondamento. Mantenha tanto `feeToleranceAbs` quanto `feeTolerancePct` em zero. Sempre execute um `DRY_RUN` antes do `COMMIT`, especialmente após alterações em regras ou mapas de campos. Isso permite revisar os resultados do matching e identificar erros de configuração antes que afetem os dados de produção. ## Métricas-chave *** Acompanhe estas métricas para monitorar a saúde do seu processo de conciliação Pix. | Métrica | Valor saudável | Limite de alerta | | -------------------------------------- | ------------------------ | ----------------- | | Taxa de match automático | Acima de 99% | Abaixo de 95% | | Exceções diárias | Abaixo de 0,5% do volume | Acima de 2% | | Tempo médio de resolução | Abaixo de 4 horas | Acima de 24 horas | | Exceções não resolvidas há mais de 48h | 0 | Mais de 5 | Use os endpoints de dashboard do Matcher para monitorar estas métricas em tempo real. Veja [Métricas do dashboard](/pt/reference/matcher/get-dashboard-metrics). ## Próximos passos *** Aprenda a configurar e gerenciar contextos de conciliação e fontes de dados. Explore todos os tipos de regra disponíveis e configurações avançadas de matching. Aprofunde-se no mapeamento automático de campos e sincronização em tempo real com o Midaz Ledger. Guia detalhado sobre investigação, force match e gerenciamento de exceções de conciliação.