> ## 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](https://mintcdn.com/lerian-49cb71fc/vdBt8wfgjsNRO1rf/images/pt/d2/matcher-pix-cashout-flow.svg?fit=max\&auto=format\&n=vdBt8wfgjsNRO1rf\&q=85\&s=84c07ddc5153a104f0dcdfd1708eec3a) Fluxo de saída de caixa: da iniciação pelo cliente, passando pela liquidação no SPI, até a conciliação no Matcher. 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](https://mintcdn.com/lerian-49cb71fc/vdBt8wfgjsNRO1rf/images/pt/d2/matcher-pix-cashin-flow.svg?fit=max\&auto=format\&n=vdBt8wfgjsNRO1rf\&q=85\&s=75a98f07014c01102d5cba7306a84944) Fluxo de entrada de caixa: da notificação recebida do SPI, passando pelo crédito no Midaz, até a conciliação no Matcher. 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. > [!NOTE] > > 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 *** **1. Crie o contexto** 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", "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. As regras de correspondência abaixo comparam os valores de forma exata. Definir `autoMatchOnUpload` como `false` dá a você o controle de quando a correspondência roda. Use esse controle quando você precisar das duas fontes ingeridas antes de a execução rodar. > [!TIP] > > Veja o schema completo da requisição em [Criar contexto](https://docs.lerian.studio/pt/reference/products/matcher/create-context.md). **2. Crie as fontes** 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](https://docs.lerian.studio/pt/products/matcher/integrations/matcher-midaz-integration.md) 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. > [!TIP] > > Veja o schema completo da requisição em [Criar fonte](https://docs.lerian.studio/pt/reference/products/matcher/create-source.md). **3. Crie os mapas de campo** 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 cujas chaves vêm do vocabulário fechado do Matcher: `external_id`, `amount`, `currency` e `date`, mais as opcionais `description`, `fee_amount`, `fee_currency` e `direction`. A chave `direction` recebe um objeto, `{column, debit, credit}`, para um arquivo que marca cada linha como débito ou crédito em uma coluna separada. Cada uma das outras chaves recebe o nome bruto de uma coluna na 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](https://docs.lerian.studio/pt/products/matcher/integrations/matcher-midaz-integration.md#custom-field-mapping)). > [!WARNING] > > `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" } } ``` > [!TIP] > > Veja [Criar mapa de campo](https://docs.lerian.studio/pt/reference/products/matcher/create-field-map.md) para o schema completo da requisição e [Mapeamento de campos](https://docs.lerian.studio/pt/products/matcher/configuration/matcher-field-mapping.md) para o vocabulário canônico. **4. Crie as regras de correspondência** 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 } } ``` 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, "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`. > [!TIP] > > Veja [Criar regra de correspondência](https://docs.lerian.studio/pt/reference/products/matcher/create-match-rule.md) para o schema completo da requisição e todos os tipos de regra disponíveis. **5. Ative e agende** 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. > [!TIP] > > Veja [Atualizar contexto](https://docs.lerian.studio/pt/reference/products/matcher/update-context.md) e [Criar agendamento](https://docs.lerian.studio/pt/reference/products/matcher/create-schedule.md) para os schemas completos das requisições. ## Operação diária *** Depois de configurado, o workflow diário de conciliação segue cinco passos. **1. Suba o extrato do BACEN** 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](https://docs.lerian.studio/pt/products/matcher/imports/matcher-import-formats.md) 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 "format=csv" \ -F "file=@bacen_spi_2026-03-17.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. **2. Suba a exportação do Midaz** 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](https://docs.lerian.studio/pt/products/matcher/integrations/matcher-midaz-integration.md) para o fluxo de exportação e importação. **3. O Matcher roda às 07:00 (ou na mã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" }' ``` **4. Revise os resultados** 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?contextId={contextId}" \ -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. **5. Resolva as exceções** 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. > [!TIP] > > 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 | Proposta, D+1 (DATE\_LAG, pontuação: 90) | | E11122...0007 | txn-004 ↔ nenhuma | Exceção (sem regra) | | E44455...0055 | nenhuma ↔ liq-8804 | Exceção (sem regra) | ### 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) propôs este par com pontuação de confiança 90. O Matcher nunca confirma automaticamente um grupo `DATE_LAG`: ele propõe o grupo, qualquer que seja a pontuação. Para parear as duas transações, confirme o grupo proposto com a operação de confirmação. * **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). | Investigue os registros originais. Crie uma correspondência manual se a diferença for aceitável. | | Divergência de data (>1 dia) | Transação retida, reprocessamento | Confirme que é o mesmo Pix. Crie uma correspondência manual, ou ignore a transação. | ### Correspondência manual Quando você confirmou que dois registros representam a mesma transação Pix mas o Matcher não conseguiu correspondência automática, junte os dois com uma correspondência manual. O Matcher cria um grupo de correspondência `CONFIRMED` com confiança 100. ```bash theme={null} curl -X POST "https://api.matcher.example.com/v1/matching/manual?contextId={contextId}" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "transactionIds": ["{midazTransactionId}", "{bacenTransactionId}"], "notes": "Same Pix confirmed via endToEndId lookup in SPI. 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" }' ``` > [!TIP] > > Veja [Criar correspondência manual](https://docs.lerian.studio/pt/reference/products/matcher/create-manual-match.md) e [Ignorar transação](https://docs.lerian.studio/pt/reference/products/matcher/ignore-transaction.md) 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, então o Matcher pode 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. > [!NOTE] > > 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](https://docs.lerian.studio/pt/interfaces/pix/pix-overview.md). ## Boas práticas *** > [accordion] Use o endToEndId como referência principal > > 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. > [accordion] Rode a conciliação no dia seguinte > > 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. > [accordion] Separe Pix IN e Pix OUT em alto volume > > 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. > [accordion] Monitore a taxa de correspondência > > 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. > [accordion] Tolerância zero é o padrão > > 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 `feeTolerance` em `0` na regra `DATE_LAG`. > [accordion] Veja a prévia antes de commitar > > 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 | > [!TIP] > > Use os endpoints de dashboard do Matcher para monitorar estas métricas. Veja [Métricas do dashboard](https://docs.lerian.studio/pt/reference/products/matcher/get-dashboard-metrics.md). ## Próximos passos *** > [card] [Contextos e fontes](https://docs.lerian.studio/pt/products/matcher/configuration/matcher-contexts-and-sources.md) > > Aprenda a configurar e gerenciar contextos de conciliação e fontes de dados. > [card] [Regras de correspondência](https://docs.lerian.studio/pt/products/matcher/configuration/matcher-match-rules.md) > > Explore todos os tipos de regra disponíveis e as configurações avançadas de correspondência. > [card] [Integração com o Midaz](https://docs.lerian.studio/pt/products/matcher/integrations/matcher-midaz-integration.md) > > Conheça o mapeamento de campos e a fonte de dados do Midaz Ledger. > [card] [Resolvendo exceções](https://docs.lerian.studio/pt/products/matcher/daily-reconciliation/matcher-resolving-exceptions.md) > > Guia detalhado sobre investigar, forçar correspondências e gerenciar exceções de conciliação. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.