> ## 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. # Conciliação de Pix > Configure o Matcher para conciliar os fluxos de entrada e de saída de caixa do Pix entre o Midaz Ledger e o extrato de liquidação do SPI do BACEN usando o endToEndId como chave de correspondência. Este guia mostra como conciliar transações Pix entre o Midaz Ledger e os dados de liquidação do BACEN (o Banco Central do Brasil) usando o Matcher. Ele cobre tanto o Pix enviado (saída de caixa) quanto o Pix recebido (entrada de caixa), da configuração à operação diária e ao tratamento de exceções. Ao fim deste guia, você terá um contexto do Matcher que concilia as suas transações Pix com os extratos de liquidação do SPI do BACEN todo dia. ## Fluxos de transações Pix *** Os dois fluxos abaixo mostram o que o Matcher precisa conciliar em cada lado. ### Pix enviado (saída de caixa) Fluxo de saída de caixa do Pix enviado 1. **Cliente inicia o Pix**: o usuário final dispara um pagamento Pix pelo app ou pela API. 2. **Plugin cria a iniciação**: o plugin Pix cria um registro de iniciação e resolve a conta de destino por 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 é efetivada. 5. **Matcher concilia**: o Matcher compara a transação efetivada no Midaz com a entrada correspondente no extrato de liquidação do SPI do BACEN. ### Pix recebido (entrada de caixa) Fluxo de entrada de caixa do Pix recebido 1. **Pix recebido chega**: o SPI envia um webhook síncrono com 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 CREDIT no Midaz para a conta do recebedor. 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 do Midaz com a entrada correspondente no extrato de liquidação do SPI do BACEN. Nos dois fluxos, o **endToEndId** é o identificador único que liga a transação do Midaz ao registro de liquidação do BACEN. Essa é a chave principal da conciliação. ## Configuração passo a passo *** Crie um contexto de conciliação para as transações Pix. Use o tipo `1:1` porque cada transação Pix tem exatamente uma entrada de liquidação correspondente no BACEN. ```json theme={null} { "name": "Pix Daily Reconciliation", "type": "1:1", "interval": "daily", "feeToleranceAbs": "0", "feeTolerancePct": "0", "autoMatchOnUpload": false } ``` As transações Pix não têm tarifas intermediárias nem liquidações parciais. Um Pix de R$ 150,00 no Midaz deve aparecer como exatamente R$ 150,00 no extrato do BACEN. Defina os dois valores de tolerância como zero. Eles são strings decimais, então passe `"0"`. Definir `autoMatchOnUpload` como `false` dá a você o controle de quando a correspondência roda. Esse controle importa quando você precisa das duas fontes ingeridas antes de a execução rodar. Veja o schema completo da requisição em [Criar contexto](/pt/reference/products/matcher/create-context). Cada contexto precisa de duas fontes: uma para as transações do Midaz e uma 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 internos de ledger. Não é um conector ativo do Midaz. Você exporta as transações Pix do dia a partir do Midaz, incluindo o metadado `endToEndId` como coluna plana. Depois você sobe a exportação para esta fonte, na mão ou por um pipeline automatizado. Veja [Matcher e Midaz](/pt/products/matcher/integrations/matcher-midaz-integration) para o fluxo de exportação e 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 você sobe o arquivo de liquidação do SPI na mão ou por um pipeline automatizado todo dia. Cada fonte deve declarar um `side` (`LEFT` ou `RIGHT`). Um contexto concilia a fonte `LEFT` dele contra a fonte `RIGHT` dele. Atribua um lado ao Midaz e o outro ao BACEN. Mantenha a atribuição consistente nas duas fontes. Veja o schema completo da requisição em [Criar fonte](/pt/reference/products/matcher/create-source). Os mapas de campo dizem ao Matcher como traduzir os campos de cada fonte para os campos canônicos usados na correspondência. Um mapa de campo é um objeto JSON na forma `{ "": "" }`. As chaves vêm do vocabulário canônico fechado do Matcher (`external_id`, `amount`, `currency`, `date` e, opcionais, `description`, `fee_amount`, `fee_currency`). Os valores são os nomes brutos das colunas em cada fonte. As buscas são **planas**. Um valor de mapeamento deve nomear uma coluna de primeiro nível na linha. Por isso a exportação do Midaz deve carregar `endToEndId` como uma coluna plana própria (veja [Matcher e Midaz — mapeamento de campos personalizado](/pt/products/matcher/integrations/matcher-midaz-integration#custom-field-mapping)). `external_id` é a **referência de correspondência entre os 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 de linha locais de um lado (o `id` da transação no Midaz, o `id_liquidacao` do BACEN) para `external_id`. Esses valores nunca batem entre as fontes, então a correspondência por referência nunca acharia uma contraparte. A tabela a seguir mostra como cada campo canônico mapeia para a coluna em cada fonte: | Campo canônico | Coluna da exportação do Midaz | Coluna do extrato do BACEN | | -------------- | ----------------------------- | -------------------------- | | `external_id` | `endToEndId` | `end_to_end_id` | | `amount` | `amount` | `valor` | | `currency` | `asset_code` | `moeda` | | `date` | `created_at` | `data_liquidacao` | **Mapa de campo da fonte Midaz:** ```json theme={null} { "mapping": { "external_id": "endToEndId", "amount": "amount", "currency": "asset_code", "date": "created_at" } } ``` **Mapa de campo da fonte BACEN:** ```json theme={null} { "mapping": { "external_id": "end_to_end_id", "amount": "valor", "currency": "moeda", "date": "data_liquidacao" } } ``` Veja [Criar mapa de campo](/pt/reference/products/matcher/create-field-map) para o schema completo da requisição e [Mapeamento de campos](/pt/products/matcher/configuration/matcher-field-mapping) para o vocabulário canônico. As regras de correspondência definem como o Matcher compara transações entre fontes. Na conciliação de Pix, duas regras cobrem a grande maioria dos cenários. **Regra 1 (correspondência exata 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 cerca de 95% dos casos. O `endToEndId` é único por transação Pix em todo o ecossistema. Uma correspondência por referência, valor, moeda e data dá uma conciliação confirmada com confiança máxima. A regra define `caseInsensitive` como `false` porque os valores de `endToEndId` diferenciam maiúsculas de minúsculas. A regra define `referenceMustSet` como `true`, então os dois lados devem carregar o `endToEndId` antes da comparação. Isso evita falsos positivos apenas por valor e data. **Regra 2 (alternativa 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 liquidar no BACEN no dia de calendário seguinte. Esta regra permite uma janela de 1 dia para cobrir cenários de liquidação em D+1. Esta regra depende apenas da correspondência de valor e de moeda. A Regra 1 cuida da comparação do `endToEndId`. Veja [Criar regra de correspondência](/pt/reference/products/matcher/create-match-rule) para o schema completo da requisição e todos os tipos de regra disponíveis. Com toda a configuração no lugar, ative o contexto e crie um agendamento diário. **Ative 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" }' ``` **Crie um agendamento para rodar 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 }' ``` Rodar às 07:00 UTC dá margem suficiente para as liquidações em D+1 aparecerem no extrato do BACEN. Também dá tempo de você subir o arquivo diário antes de a execução de correspondência rodar. Veja [Atualizar contexto](/pt/reference/products/matcher/update-context) e [Criar agendamento](/pt/reference/products/matcher/create-schedule) para os schemas completos das requisições. ## Operação diária *** Depois de configurado, o workflow diário de conciliação segue cinco passos. Suba o arquivo de liquidação do SPI do dia anterior para a fonte do BACEN. O Matcher interpreta CSV, JSON, XML e outros formatos do [catálogo de formatos](/pt/products/matcher/imports/matcher-import-formats) dele. ```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" ``` Você pode automatizar este passo com um pipeline que busca o arquivo do SPI e o sobe antes da execução de correspondência agendada. Exporte do Midaz as transações Pix efetivadas do dia anterior, incluindo o metadado `endToEndId` como coluna plana. Suba a exportação para a fonte Midaz do mesmo jeito. Em geral o mesmo pipeline automatiza este passo. Veja [Matcher e Midaz](/pt/products/matcher/integrations/matcher-midaz-integration) para o fluxo de exportação e importação. A execução agendada roda automaticamente às 07:00 UTC. Para rodar a correspondência na mão, 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 ver os resultados sem commitá-los. Quando estiver satisfeito, rode de novo 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" }' ``` Depois que a execução termina, busque os grupos correspondidos 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 correspondida e a entrada de liquidação do BACEN correspondente, junto com a regra que as correspondeu e a pontuação de confiança. As transações não conciliadas aparecem como exceções. Elas exigem investigação: uma transação presente em uma fonte mas não na outra, ou uma divergência de valor ou de data além da tolerância configurada. Revise as exceções, determine a causa raiz e resolva-as forçando a correspondência, ignorando ou corrigindo os dados de origem. Rode sempre um `DRY_RUN` primeiro ao testar novas regras ou depois de mudanças de configuração. Isso evita que o Matcher comite correspondências indesejadas. ## Exemplo prático: um dia de dados *** O exemplo a seguir ilustra uma execução completa de conciliação de 17 de março de 2026. ### Transações do 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 da correspondência | endToEndId | Midaz ↔ BACEN | Resultado (regra) | | ------------- | ------------------ | ------------------------------------------------- | | E12345...0001 | txn-001 ↔ liq-8801 | Correspondência — EXACT (pontuação: 100) | | E98765...0042 | txn-002 ↔ liq-8802 | Correspondência — EXACT (pontuação: 100) | | E55566...0099 | txn-003 ↔ liq-8803 | Correspondência (D+1) — DATE\_LAG (pontuação: 85) | | E11122...0007 | txn-004 ↔ — | Exceção — — | | E44455...0055 | — ↔ liq-8804 | Exceção — — | ### Análise * **txn-001 e txn-002:** correspondência exata por endToEndId, valor, moeda e data. A Regra 1 resolveu essas correspondências com pontuação 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 pontuação de confiança 85. Correspondências por defasagem de data nunca são autoconfirmadas. O par vai para a fila de revisão para uma pessoa confirmar. * **txn-004:** presente no Midaz mas ausente no BACEN. Possível falha de liquidação ou timeout do SPI. Investigue o status da transação pelo plugin Pix. * **liq-8804:** presente no BACEN mas ausente no Midaz. Este Pix recebido não chegou ao ledger. Confira a entrega do webhook ou reprocesse a mensagem. ## Tratando exceções de Pix *** A tabela a seguir cobre os cenários mais comuns de exceção de Pix e as ações recomendadas. | Cenário | Causa provável | Ação recomendada | | ---------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | No Midaz, não no BACEN | Falha de liquidação, timeout do SPI, transação rejeitada | Confira o status da transação no plugin Pix. Se foi rejeitada, estorne no Midaz. | | No BACEN, não no Midaz | Pix recebido não processado, falha de webhook | Reprocesse a mensagem. Crie uma transação manual se for preciso. | | Divergência de valor | Raro no Pix (sem tarifas intermediárias). Possível erro de arredondamento. | Investigue os registros originais. Force a correspondência se a diferença for aceitável. | | Divergência de data (>1 dia) | Transação retida, reprocessamento | Confirme que é o mesmo Pix. Force a correspondência ou ignore. | ### Correspondência forçada Quando você confirmou que dois registros representam a mesma transação Pix mas o Matcher não conseguiu correspondência automática, use a correspondência forçada. ```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 você deve excluir uma transação da conciliação (por exemplo, um lançamento duplicado 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 [Forçar correspondência](/pt/reference/products/matcher/force-match-exception) e [Ignorar transação](/pt/reference/products/matcher/ignore-transaction) para os schemas completos das requisições. ## Devoluções de Pix (refunds) *** As devoluções de Pix geram transações reversas que também precisam de conciliação. Quando o plugin Pix processa uma devolução, ele cria uma nova transação no Midaz com: * O `originalEndToEndId` que aponta de volta para a transação Pix original * Um novo `returnIdentification` (rtrId) que identifica a devolução de forma única no SPI O extrato de liquidação do BACEN inclui as entradas de devolução com os dois identificadores, o que permite ao Matcher conciliá-las com as transações de devolução correspondentes no Midaz. Em volumes baixos de devolução, você pode conciliá-las dentro do mesmo contexto Pix Daily Reconciliation. Em 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. Iniciar uma devolução por `POST /v1/transfers/{id}/refunds` é um endpoint do **plugin Pix**, **não** um endpoint do Matcher. O Matcher não inicia transferências nem devoluções. Ele apenas concilia as transações resultantes. Cada devolução carrega o `originalEndToEndId` e um novo `returnIdentification` para rastreio ponta a ponta, que o Matcher então usa para corresponder a devolução com o extrato de liquidação do BACEN. Para iniciar devoluções, veja a [documentação do plugin Pix](/pt/interfaces/pix/pix-overview). ## Boas práticas *** O `endToEndId` é o identificador único do Pix em todo o ecossistema, da instituição que inicia, passando pelo SPI, até a instituição que recebe. Guarde-o nos metadados da transação no Midaz e garanta que o extrato do BACEN o carregue. Sem ele, a conciliação cai para a correspondência por valor e data, que é bem menos confiável. Transações Pix perto do fim do dia podem liquidar no BACEN em D+1. Agendar o Matcher para 07:00 UTC garante que o extrato do BACEN inclua todas as liquidações do dia anterior antes de a correspondência rodar. Isso elimina falsas exceções causadas por timing. Ao processar volumes altos de Pix, crie dois contextos separados, um para a saída de caixa e um para a entrada de caixa. Isso simplifica a triagem de exceções, dá métricas mais granulares por fluxo e permite agendamento independente, se for preciso. Uma conciliação de Pix saudável chega a mais de 99% de taxa de correspondência automática. Se a taxa cai abaixo de 95%, investigue problemas sistêmicos como falhas do plugin, mudanças de formato do BACEN ou metadados faltando nas transações do Midaz. O Pix não tem tarifas intermediárias, liquidações parciais nem encargos de processamento. Se os valores divergem entre Midaz e BACEN, isso indica um problema real, não arredondamento. Mantenha os dois valores, `feeToleranceAbs` e `feeTolerancePct`, em zero. Rode sempre um `DRY_RUN` antes do `COMMIT`, principalmente depois de mudanças de regra ou de mapa de campo. Isso permite revisar os resultados de correspondência e pegar erros de configuração antes de eles afetarem os dados de produção. ## Métricas principais *** Acompanhe estas métricas para monitorar a saúde do seu processo de conciliação de Pix. | Métrica | Valor saudável | Limite de alerta | | ---------------------------------- | ------------------------ | ----------------- | | Taxa de correspondência automática | 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á 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/products/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 as configurações avançadas de correspondência. Conheça o mapeamento automático de campos e a fonte de dados do Midaz Ledger. Guia detalhado sobre investigar, forçar correspondências e gerenciar exceções de conciliação.