> ## 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. # Conciliación de Pix > Configura Matcher para conciliar los flujos de cash-in y cash-out de Pix entre Midaz Ledger y el extracto de liquidación SPI de BACEN usando endToEndId como clave de coincidencia. Esta guía explica cómo conciliar transacciones de Pix entre Midaz Ledger y los datos de liquidación de BACEN (Banco Central de Brasil) usando Matcher. Cubre tanto el Pix enviado (cash-out) como el Pix recibido (cash-in), desde la configuración hasta la operación diaria y el manejo de excepciones. Al final de esta guía, tendrás un contexto de Matcher que concilia tus transacciones de Pix contra los extractos de liquidación SPI de BACEN todos los días. ## Flujos de transacciones de Pix *** Los dos flujos siguientes muestran qué necesita conciliar Matcher en cada lado. ### Pix enviado (cash-out) Flujo de cash-out de Pix enviado 1. **El cliente inicia el Pix**: el usuario final activa un pago Pix mediante la aplicación o la API. 2. **El plugin crea la iniciación**: el plugin de Pix crea un registro de iniciación y resuelve la cuenta de destino mediante una consulta a DICT. 3. **El plugin procesa el pago**: el plugin debita la cuenta del cliente en Midaz (transacción en estado `pending`) y envía la instrucción de pago a SPI. 4. **Liquidación confirmada**: SPI envía un webhook que confirma la liquidación. La transacción de Midaz queda confirmada. 5. **Matcher concilia**: Matcher compara la transacción confirmada de Midaz con la entrada correspondiente en el extracto de liquidación SPI de BACEN. ### Pix recibido (cash-in) Flujo de cash-in de Pix recibido 1. **Llega un Pix entrante**: SPI envía un webhook síncrono con los datos del Pix entrante. 2. **El plugin valida**: el plugin de Pix valida el payload y aprueba la transacción. 3. **Se crea la transacción de crédito**: el plugin crea una transacción CREDIT en Midaz para la cuenta receptora. 4. **Liquidación confirmada**: el webhook de liquidación confirma que la transacción es definitiva. 5. **Matcher concilia**: Matcher compara la transacción de crédito de Midaz con la entrada correspondiente en el extracto de liquidación SPI de BACEN. En ambos flujos, el **endToEndId** es el identificador único que enlaza la transacción de Midaz con el registro de liquidación de BACEN. Esta es la clave principal para la conciliación. ## Configuración paso a paso *** Crea un contexto de conciliación para las transacciones de Pix. Usa el tipo `1:1` porque cada transacción de Pix tiene exactamente una entrada de liquidación correspondiente en BACEN. ```json theme={null} { "name": "Pix Daily Reconciliation", "type": "1:1", "interval": "daily", "feeToleranceAbs": "0", "feeTolerancePct": "0", "autoMatchOnUpload": false } ``` Las transacciones de Pix no tienen tarifas intermedias ni liquidaciones parciales. Un Pix de R$ 150.00 en Midaz debe aparecer como exactamente R$ 150.00 en el extracto de BACEN. Configura ambos valores de tolerancia en cero. Son cadenas decimales, así que pasa `"0"`. Configurar `autoMatchOnUpload` en `false` te da control sobre cuándo se ejecuta el emparejamiento. Ese control importa cuando necesitas que ambas fuentes estén ingeridas antes de que se ejecute la corrida. Consulta el esquema completo de la solicitud en [Crear contexto](/es/reference/products/matcher/create-context). Cada contexto necesita dos fuentes: una para las transacciones de Midaz y otra para el extracto de liquidación de BACEN. **Fuente A, Midaz (tipo `LEDGER`):** ```json theme={null} { "name": "Midaz - Pix Transactions", "type": "LEDGER", "side": "LEFT", "config": {} } ``` `LEDGER` es la categoría de Matcher para los datos del ledger interno. No es un conector en vivo de Midaz. Exportas las transacciones de Pix del día desde Midaz, incluyendo los metadatos de `endToEndId` como una columna plana. Luego subes la exportación a esta fuente, de forma manual o mediante un pipeline automatizado. Consulta [Matcher y Midaz](/es/products/matcher/integrations/matcher-midaz-integration) para ver el flujo de exportación e importación. **Fuente B, extracto SPI de BACEN (tipo `CUSTOM`):** ```json theme={null} { "name": "BACEN SPI Settlement Extract", "type": "CUSTOM", "side": "RIGHT", "config": { "description": "Daily SPI settlement file from BACEN" } } ``` La fuente de BACEN usa el tipo `CUSTOM` porque subes el archivo de liquidación SPI de forma manual o mediante un pipeline automatizado cada día. Cada fuente debe declarar un `side` (`LEFT` o `RIGHT`). Un contexto concilia su fuente `LEFT` contra su fuente `RIGHT`. Asigna un lado a Midaz y el otro a BACEN. Mantén la asignación consistente en ambas fuentes. Consulta el esquema completo de la solicitud en [Crear fuente](/es/reference/products/matcher/create-source). Los mapas de campos le indican a Matcher cómo traducir los campos de cada fuente a los campos canónicos que se usan para el emparejamiento. Un mapa de campos es un objeto JSON con la forma `{ "": "" }`. Las claves provienen del vocabulario canónico cerrado de Matcher (`external_id`, `amount`, `currency`, `date` y, de forma opcional, `description`, `fee_amount`, `fee_currency`). Los valores son los nombres de columna sin procesar en cada fuente. Las búsquedas son **planas**. Un valor de mapeo debe nombrar una columna de nivel superior en la fila. Por lo tanto, la exportación de Midaz debe llevar `endToEndId` como su propia columna plana (consulta [Matcher y Midaz — mapeo de campos personalizado](/es/products/matcher/integrations/matcher-midaz-integration#custom-field-mapping)). `external_id` es la **referencia de coincidencia entre lados**: el valor que el motor compara entre las dos fuentes cuando una regla configura `matchReference`. Mapéalo al `endToEndId` en **ambos** lados. No mapees IDs de fila propios de cada lado (el `id` de la transacción de Midaz, el `id_liquidacao` de BACEN) a `external_id`. Esos valores nunca coinciden entre fuentes, así que la coincidencia por referencia nunca encontraría una contraparte. La siguiente tabla muestra cómo se mapea cada campo canónico a la columna de cada fuente: | Campo canónico | Columna de exportación de Midaz | Columna del extracto de BACEN | | -------------- | ------------------------------- | ----------------------------- | | `external_id` | `endToEndId` | `end_to_end_id` | | `amount` | `amount` | `valor` | | `currency` | `asset_code` | `moeda` | | `date` | `created_at` | `data_liquidacao` | **Mapa de campos de la fuente Midaz:** ```json theme={null} { "mapping": { "external_id": "endToEndId", "amount": "amount", "currency": "asset_code", "date": "created_at" } } ``` **Mapa de campos de la fuente BACEN:** ```json theme={null} { "mapping": { "external_id": "end_to_end_id", "amount": "valor", "currency": "moeda", "date": "data_liquidacao" } } ``` Consulta [Crear mapa de campos](/es/reference/products/matcher/create-field-map) para ver el esquema completo de la solicitud y [Mapeo de campos](/es/products/matcher/configuration/matcher-field-mapping) para ver el vocabulario canónico. Las reglas de coincidencia definen cómo Matcher compara las transacciones entre fuentes. Para la conciliación de Pix, dos reglas cubren la gran mayoría de los escenarios. **Regla 1 (coincidencia exacta por endToEndId, prioridad 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 regla resuelve aproximadamente el 95% de los casos. El `endToEndId` es único por transacción de Pix en todo el ecosistema. Una coincidencia en referencia, monto, moneda y fecha da una conciliación confirmada con la máxima confianza. La regla configura `caseInsensitive` en `false` porque los valores de `endToEndId` distinguen mayúsculas de minúsculas. La regla configura `referenceMustSet` en `true`, así que ambos lados deben llevar el `endToEndId` antes de la comparación. Esto evita falsos positivos basados solo en monto y fecha. **Regla 2 (respaldo con tolerancia de fecha, prioridad 51):** ```json theme={null} { "type": "DATE_LAG", "priority": 51, "config": { "maxDays": 1, "minDays": 0, "inclusive": true, "direction": "ABS", "feeTolerance": 0, "matchScore": 85, "matchCurrency": true } } ``` Un Pix iniciado a las 23:58 puede liquidarse en BACEN al día calendario siguiente. Esta regla permite una ventana de 1 día para cubrir escenarios de liquidación D+1. Esta regla depende únicamente de la coincidencia de monto y moneda. La Regla 1 se encarga de la comparación de `endToEndId`. Consulta [Crear regla de coincidencia](/es/reference/products/matcher/create-match-rule) para ver el esquema completo de la solicitud y todos los tipos de regla disponibles. Una vez que toda la configuración esté lista, activa el contexto y crea una programación diaria. **Activa el 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" }' ``` **Crea una programación para ejecutarse a diario a las 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 }' ``` Ejecutarse a las 07:00 UTC brinda margen suficiente para que las liquidaciones D+1 aparezcan en el extracto de BACEN. También te da tiempo para subir el archivo diario antes de que se ejecute la corrida de emparejamiento. Consulta [Actualizar contexto](/es/reference/products/matcher/update-context) y [Crear programación](/es/reference/products/matcher/create-schedule) para ver los esquemas completos de la solicitud. ## Operación diaria *** Una vez configurado, el flujo de conciliación diaria sigue cinco pasos. Sube el archivo de liquidación SPI del día anterior a la fuente de BACEN. Matcher analiza CSV, JSON, XML y otros formatos de su [catálogo de formatos](/es/products/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" ``` Puedes automatizar este paso con un pipeline que obtenga el archivo SPI y lo suba antes de la corrida de emparejamiento programada. Exporta las transacciones de Pix confirmadas del día anterior desde Midaz, incluyendo los metadatos de `endToEndId` como una columna plana. Sube la exportación a la fuente de Midaz de la misma forma. Por lo general, el mismo pipeline automatiza este paso. Consulta [Matcher y Midaz](/es/products/matcher/integrations/matcher-midaz-integration) para ver el flujo de exportación e importación. La corrida programada se ejecuta automáticamente a las 07:00 UTC. Para ejecutar el emparejamiento manualmente, usa el endpoint de ejecución. ```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" }' ``` Usa `DRY_RUN` primero para previsualizar los resultados sin confirmarlos. Cuando estés conforme, ejecuta de nuevo con `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" }' ``` Después de que la corrida termine, obtén los grupos emparejados para ver los resultados. ```bash theme={null} curl -X GET "https://api.matcher.example.com/v1/matching/runs/{runId}/groups" \ -H "Authorization: Bearer $TOKEN" ``` Cada grupo muestra la transacción de Midaz emparejada y su entrada correspondiente de liquidación en BACEN, junto con la regla que las emparejó y la puntuación de confianza. Las transacciones no conciliadas aparecen como excepciones. Estas requieren investigación: una transacción presente en una fuente pero no en la otra, o una discrepancia de monto o fecha que supera la tolerancia configurada. Revisa las excepciones, determina la causa raíz y resuélvelas forzando la coincidencia, ignorándolas o corrigiendo los datos subyacentes. Ejecuta siempre un `DRY_RUN` primero al probar reglas nuevas o después de cambios de configuración. Esto evita que Matcher confirme coincidencias no deseadas. ## Ejemplo práctico: un día de datos *** El siguiente ejemplo ilustra una corrida de conciliación completa para el 17 de marzo de 2026. ### Transacciones de Midaz (Fuente A) | ID (tipo) | endToEndId | Monto · fecha | | ----------------- | ---------------------- | -------------------------- | | 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 | ### Extracto SPI de BACEN (Fuente 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 de la coincidencia | endToEndId | Midaz ↔ BACEN | Resultado (regla) | | ------------- | ------------------ | ----------------------------------------------- | | E12345...0001 | txn-001 ↔ liq-8801 | Coincidencia — EXACT (puntuación: 100) | | E98765...0042 | txn-002 ↔ liq-8802 | Coincidencia — EXACT (puntuación: 100) | | E55566...0099 | txn-003 ↔ liq-8803 | Coincidencia (D+1) — DATE\_LAG (puntuación: 85) | | E11122...0007 | txn-004 ↔ — | Excepción — — | | E44455...0055 | — ↔ liq-8804 | Excepción — — | ### Análisis * **txn-001 y txn-002:** coincidencia exacta en endToEndId, monto, moneda y fecha. La Regla 1 resolvió estas con una puntuación de confianza de 100. * **txn-003:** Pix iniciado a las 23:58, liquidado en BACEN el 2026-03-18. La Regla 2 (DATE\_LAG con ventana de 1 día) emparejó este caso con una puntuación de confianza de 85. Las coincidencias con tolerancia de fecha nunca se confirman automáticamente. El par queda en la cola de revisión para que una persona lo confirme. * **txn-004:** presente en Midaz pero ausente en BACEN. Posible falla de liquidación o timeout de SPI. Investiga el estado de la transacción a través del plugin de Pix. * **liq-8804:** presente en BACEN pero ausente en Midaz. Este Pix entrante no llegó al ledger. Revisa la entrega del webhook o reprocesa el mensaje. ## Gestión de excepciones de Pix *** La siguiente tabla cubre los escenarios de excepción de Pix más comunes y las acciones recomendadas. | Escenario | Causa probable | Acción recomendada | | ------------------------------ | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | En Midaz, no en BACEN | Falla de liquidación, timeout de SPI, transacción rechazada | Revisa el estado de la transacción en el plugin de Pix. Si fue rechazada, revierte en Midaz. | | En BACEN, no en Midaz | Pix entrante no procesado, falla del webhook | Reprocesa el mensaje. Crea una transacción manual si es necesario. | | Discrepancia de monto | Poco común en Pix (sin tarifas intermedias). Posible error de redondeo. | Investiga los registros originales. Fuerza la coincidencia si la diferencia es aceptable. | | Discrepancia de fecha (>1 día) | Transacción retenida, reprocesamiento | Verifica que sea el mismo Pix. Fuerza la coincidencia o ignórala. | ### Forzar coincidencia Cuando hayas confirmado que dos registros representan la misma transacción de Pix pero Matcher no pudo emparejarlos automáticamente, usa la función de forzar coincidencia. ```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 transacción Cuando debas excluir una transacción de la conciliación (por ejemplo, una entrada duplicada o un Pix ya revertido), márcala 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" }' ``` Consulta [Forzar coincidencia](/es/reference/products/matcher/force-match-exception) e [Ignorar transacción](/es/reference/products/matcher/ignore-transaction) para ver los esquemas completos de la solicitud. ## Devoluciones de Pix (devoluções) *** Las devoluciones de Pix generan transacciones inversas que también necesitan conciliación. Cuando el plugin de Pix procesa una devolución, crea una nueva transacción en Midaz con: * El `originalEndToEndId` que enlaza de vuelta con la transacción de Pix original * Un nuevo `returnIdentification` (rtrId) que identifica de forma única la devolución en SPI El extracto de liquidación de BACEN incluye entradas de devolución con ambos identificadores, lo que permite que Matcher las concilie contra las transacciones de devolución correspondientes en Midaz. Para volúmenes bajos de devoluciones, puedes conciliarlas dentro del mismo contexto de Pix Daily Reconciliation. Para volúmenes altos, crea un contexto separado dedicado a la conciliación de devoluciones. Esto simplifica el triaje de excepciones y mantiene las métricas de devoluciones aisladas de las métricas del flujo estándar de Pix. La iniciación de la devolución mediante `POST /v1/transfers/{id}/refunds` es un endpoint del **plugin de Pix**, **no** un endpoint de Matcher. Matcher no inicia transferencias ni devoluciones. Solo concilia las transacciones resultantes. Cada devolución lleva el `originalEndToEndId` y un nuevo `returnIdentification` para el seguimiento de extremo a extremo, que Matcher usa después para emparejar la devolución con el extracto de liquidación de BACEN. Para la iniciación de la devolución, consulta la [documentación del plugin de Pix](/es/interfaces/pix/pix-overview). ## Mejores prácticas *** El `endToEndId` es el identificador único de Pix en todo el ecosistema, desde la institución iniciadora, pasando por SPI, hasta la institución receptora. Guárdalo en los metadatos de la transacción de Midaz y asegúrate de que el extracto de BACEN lo lleve. Sin él, la conciliación recae en la coincidencia por monto y fecha, que es mucho menos confiable. Las transacciones de Pix cercanas al final del día pueden liquidarse en BACEN en D+1. Programar Matcher para las 07:00 UTC garantiza que el extracto de BACEN incluya todas las liquidaciones del día anterior antes de que se ejecute el emparejamiento. Esto elimina las excepciones falsas causadas por diferencias de horario. Cuando proceses volúmenes altos de Pix, crea dos contextos separados, uno para cash-out y otro para cash-in. Esto simplifica el triaje de excepciones, brinda métricas más granulares por flujo y permite una programación independiente si es necesario. Una conciliación de Pix saludable alcanza una tasa de coincidencia automática superior al 99%. Si la tasa cae por debajo del 95%, investiga problemas sistémicos como fallas del plugin, cambios en el formato de BACEN o metadatos faltantes en las transacciones de Midaz. Pix no tiene tarifas intermedias, liquidaciones parciales ni cargos de procesamiento. Si los montos difieren entre Midaz y BACEN, indica un problema real, no un redondeo. Mantén tanto `feeToleranceAbs` como `feeTolerancePct` en cero. Ejecuta siempre un `DRY_RUN` antes de `COMMIT`, en especial después de cambios en reglas o mapas de campos. Esto te permite revisar los resultados de la coincidencia y detectar errores de configuración antes de que afecten los datos de producción. ## Métricas clave *** Da seguimiento a estas métricas para monitorear la salud de tu proceso de conciliación de Pix. | Métrica | Valor saludable | Umbral de alerta | | --------------------------------- | ---------------------------- | ---------------- | | Tasa de coincidencia automática | Superior al 99% | Inferior al 95% | | Excepciones diarias | Inferior al 0.5% del volumen | Superior al 2% | | Tiempo de resolución promedio | Menos de 4 horas | Más de 24 horas | | Excepciones sin resolver por 48h+ | 0 | Más de 5 | Usa los endpoints del dashboard de Matcher para monitorear estas métricas en tiempo real. Consulta [Métricas del dashboard](/es/reference/products/matcher/get-dashboard-metrics). ## Próximos pasos *** Aprende a configurar y gestionar contextos de conciliación y fuentes de datos. Explora todos los tipos de regla disponibles y las configuraciones de coincidencia avanzadas. Aprende sobre el mapeo automático de campos y la fuente de datos de Midaz Ledger. Guía detallada sobre cómo investigar, forzar coincidencias y gestionar excepciones de conciliación.