> ## 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.
# Reconciliación Pix
> Configura Matcher para conciliar transacciones Pix de cash-in y cash-out entre Midaz Ledger y los extractos de liquidación SPI del BACEN.
Esta guía describe el proceso de conciliación de transacciones Pix entre Midaz Ledger y los datos de liquidación del BACEN (Banco Central de Brasil) utilizando Matcher. Cubre tanto Pix enviado (cash-out) como 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 completamente configurado que concilia automáticamente tus transacciones Pix contra los extractos de liquidación SPI del BACEN de forma diaria.
## Flujos de transacciones Pix
***
Comprender cómo fluyen las transacciones Pix a través del sistema es esencial para configurar la conciliación correctamente. Los dos flujos a continuación muestran lo que Matcher necesita conciliar en cada lado.
### Pix enviado (cash-out)
1. **El cliente inicia el Pix** — El usuario final activa un pago Pix a través de la aplicación o 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 consulta 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 confirmando la liquidación. La transacción en Midaz se confirma.
5. **Matcher concilia** — Matcher compara la transacción confirmada en Midaz contra la entrada correspondiente en el extracto de liquidación SPI del BACEN.
### Pix recibido (cash-in)
1. **Pix entrante llega** — SPI envía un webhook sincrónico 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 del destinatario.
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 en Midaz contra la entrada correspondiente en el extracto de liquidación SPI del BACEN.
En ambos flujos, el **endToEndId** es el identificador único que vincula la transacción de Midaz con el registro de liquidación del BACEN. Esta es la clave primaria para la conciliación.
## Configuración paso a paso
***
Crea un contexto de conciliación para transacciones Pix. Utiliza el tipo `1:1` porque cada transacción Pix tiene exactamente una entrada de liquidación correspondiente en el BACEN.
```json theme={null}
{
"name": "Pix Daily Reconciliation",
"type": "1:1",
"interval": "daily",
"feeToleranceAbs": "0",
"feeTolerancePct": "0",
"autoMatchOnUpload": false
}
```
Las transacciones Pix no tienen comisiones intermedias ni liquidaciones parciales. Un Pix de R$ 150,00 en Midaz debe aparecer exactamente como R$ 150,00 en el extracto del BACEN. Establece ambos valores de tolerancia en cero — son strings decimales, así que pasa `"0"`.
Establecer `autoMatchOnUpload` en `false` te da control sobre cuándo se ejecuta la conciliación, lo cual es importante cuando necesitas que ambas fuentes estén ingestadas antes de ejecutar.
Consulta el esquema completo de la solicitud en [Crear contexto](/es/reference/matcher/create-context).
Cada contexto necesita dos fuentes: una para las transacciones de Midaz y otra para el extracto de liquidación del 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 datos de ledger interno — no es un conector directo con Midaz. Exportas las transacciones Pix del día desde Midaz (incluyendo el metadato `endToEndId` como columna plana) y subes la exportación a esta fuente, manualmente o mediante un pipeline automatizado. Consulta [Matcher y Midaz](/es/matcher/integrations/matcher-midaz-integration) para el flujo de exportación/importación.
**Fuente B — Extracto SPI del 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 del BACEN utiliza el tipo `CUSTOM` porque el archivo de liquidación SPI se carga manualmente 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`, así que asigna un lado a Midaz y el otro al BACEN, y mantén la asignación consistente en ambas fuentes.
Consulta el esquema completo de la solicitud en [Crear fuente](/es/reference/matcher/create-source).
Los mapeos de campos le indican a Matcher cómo traducir los campos de cada fuente a los campos canónicos utilizados para la conciliación.
Un mapeo 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 los opcionales `description`, `fee_amount`, `fee_currency`); los valores son los nombres de columna sin procesar en cada fuente. Las búsquedas son **planas**: el valor de un mapeo debe nombrar una columna de nivel superior de la fila, así que la exportación de Midaz debe traer el `endToEndId` como columna plana propia (consulta [Matcher y Midaz — mapeo de campos personalizado](/es/matcher/integrations/matcher-midaz-integration#mapeo-de-campos-personalizado)).
`external_id` es la **referencia de matching entre lados**: el valor que el motor compara entre las dos fuentes cuando una regla define `matchReference`. Mapéalo al `endToEndId` en **ambos** lados. No mapees IDs locales de cada lado (el `id` de la transacción en Midaz, el `id_liquidacao` del BACEN) en `external_id`: esos valores nunca coinciden entre fuentes, así que el matching por referencia jamás encontraría una contraparte.
La siguiente tabla muestra cómo cada campo canónico se mapea a la columna en cada fuente:
| Campo canónico | Columna de la exportación Midaz | Columna del extracto BACEN |
| -------------- | ------------------------------- | -------------------------- |
| `external_id` | `endToEndId` | `end_to_end_id` |
| `amount` | `amount` | `valor` |
| `currency` | `asset_code` | `moeda` |
| `date` | `created_at` | `data_liquidacao` |
**Fuente Midaz — mapeo de campos:**
```json theme={null}
{
"mapping": {
"external_id": "endToEndId",
"amount": "amount",
"currency": "asset_code",
"date": "created_at"
}
}
```
**Fuente BACEN — mapeo de campos:**
```json theme={null}
{
"mapping": {
"external_id": "end_to_end_id",
"amount": "valor",
"currency": "moeda",
"date": "data_liquidacao"
}
}
```
Consulta [Crear mapeo de campos](/es/reference/matcher/create-field-map) para el esquema completo de la solicitud y [Mapeo de campos](/es/matcher/configuration/matcher-field-mapping) para el vocabulario canónico.
Las reglas de conciliación definen cómo Matcher compara transacciones entre fuentes. Para la conciliación 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 Pix en todo el ecosistema. Cuando la referencia, el monto, la moneda y la fecha coinciden, es una conciliación confirmada con máxima confianza. Nota que `caseInsensitive` está en `false` porque los valores de `endToEndId` distinguen mayúsculas y minúsculas, y `referenceMustSet` está en `true` para asegurar que ambos lados contengan el `endToEndId` antes de comparar — esto previene falsos positivos basados solo en monto y fecha.
**Regla 2 — Tolerancia de fecha como respaldo (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 el BACEN al día calendario siguiente. Esta regla permite una ventana de 1 día para cubrir escenarios de liquidación D+1. Nota que esta regla se basa únicamente en la coincidencia de monto y moneda — la comparación del `endToEndId` se maneja en la Regla 1.
Consulta [Crear regla de conciliación](/es/reference/matcher/create-match-rule) para 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.
**Activar 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" }'
```
**Crear una programación para ejecutar diariamente 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
}'
```
Ejecutar a las 07:00 UTC proporciona margen suficiente para que las liquidaciones D+1 aparezcan en el extracto del BACEN y para que el archivo diario se cargue antes de que se ejecute la conciliación.
Consulta [Actualizar contexto](/es/reference/matcher/update-context) y [Crear programación](/es/reference/matcher/create-schedule) para los esquemas completos de solicitud.
## Operación diaria
***
Una vez configurado, el flujo de conciliación diaria sigue cinco pasos.
Carga el archivo de liquidación SPI del día anterior a la fuente del BACEN. Matcher interpreta CSV, JSON, XML y otros formatos de su [catálogo de formatos](/es/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 paso puede automatizarse mediante un pipeline que obtenga el archivo SPI y lo cargue antes de la ejecución programada de conciliación.
Exporta las transacciones Pix confirmadas del día anterior desde Midaz — incluyendo el metadato `endToEndId` como columna plana — y sube la exportación a la fuente de Midaz de la misma forma. Este paso suele automatizarse con el mismo pipeline. Consulta [Matcher y Midaz](/es/matcher/integrations/matcher-midaz-integration) para el flujo de exportación/importación.
La ejecución programada se realiza automáticamente a las 07:00 UTC. Para ejecutar la conciliación manualmente, utiliza 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" }'
```
Utiliza `DRY_RUN` primero para previsualizar resultados sin confirmarlos. Cuando estés satisfecho, ejecuta nuevamente 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 ejecución se complete, recupera los grupos conciliados 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 conciliada y su entrada de liquidación correspondiente del BACEN, junto con la regla que las concilió y el puntaje 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 en monto o fecha más allá de la tolerancia configurada.
Revisa las excepciones, determina la causa raíz y resuélvelas mediante forzar conciliación, ignorar o corregir los datos subyacentes.
Siempre ejecuta un `DRY_RUN` primero al probar nuevas reglas o después de cambios de configuración. Esto previene que coincidencias no deseadas se confirmen.
## Ejemplo práctico — un día de datos
***
El siguiente ejemplo ilustra una ejecución 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 del 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 conciliación
| endToEndId | Midaz ↔ BACEN | Resultado (regla) |
| ------------- | ------------------ | ---------------------------------------- |
| E12345...0001 | txn-001 ↔ liq-8801 | Conciliado — EXACT (score: 100) |
| E98765...0042 | txn-002 ↔ liq-8802 | Conciliado — EXACT (score: 100) |
| E55566...0099 | txn-003 ↔ liq-8803 | Conciliado (D+1) — DATE\_LAG (score: 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ó estos con puntaje de confianza 100.
* **txn-003:** Pix iniciado a las 23:58, liquidado en el BACEN el 2026-03-18. La Regla 2 (DATE\_LAG con ventana de 1 día) emparejó este con puntaje de confianza 85. Los matches de date-lag nunca se confirman automáticamente: el par va a la cola de revisión para confirmación humana.
* **txn-004:** Presente en Midaz pero ausente en el BACEN. Posible fallo de liquidación o timeout del SPI. Investiga el estado de la transacción a través del plugin de Pix.
* **liq-8804:** Presente en el BACEN pero ausente en Midaz. Un Pix entrante que no fue procesado. Verifica la entrega del webhook o reprocesa el mensaje.
## Manejo de excepciones Pix
***
La siguiente tabla cubre los escenarios de excepción Pix más comunes y las acciones recomendadas.
| Escenario | Causa probable | Acción recomendada |
| ------------------------------ | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| En Midaz, no en BACEN | Fallo de liquidación, timeout del SPI, transacción rechazada | Verifica 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, fallo de webhook | Reprocesa el mensaje. Crea una transacción manual si es necesario. |
| Discrepancia de monto | Raro en Pix (sin comisiones intermedias). Posible error de redondeo. | Investiga los registros originales. Fuerza la conciliación si la diferencia es aceptable. |
| Discrepancia de fecha (>1 día) | Transacción retenida, reprocesamiento | Verifica que sea el mismo Pix. Fuerza la conciliación o ignora. |
### Forzar conciliación
Cuando hayas confirmado que dos registros representan la misma transacción Pix pero Matcher no pudo conciliarlos automáticamente, utiliza forzar conciliación.
```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 una transacción debe excluirse 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 conciliación](/es/reference/matcher/force-match-exception) e [Ignorar transacción](/es/reference/matcher/ignore-transaction) para los esquemas completos de solicitud.
## Devoluciones Pix (devoluções)
***
Las devoluciones Pix generan transacciones inversas que también necesitan conciliación. Cuando se procesa una devolución, el plugin de Pix crea una nueva transacción en Midaz con:
* El `originalEndToEndId` que vincula de vuelta a la transacción Pix original
* Un nuevo `returnIdentification` (rtrId) que identifica de forma única la devolución en el SPI
El extracto de liquidación del BACEN incluye entradas de devolución con ambos identificadores, lo que permite a Matcher conciliarlas contra las transacciones de devolución correspondientes en Midaz.
Para volúmenes bajos de devoluciones, estas pueden conciliarse dentro del mismo contexto de Conciliación Diaria Pix. 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 devoluciones 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 luego usa para conciliar la devolución contra el extracto de liquidación del BACEN. Para la iniciación de devoluciones, consulte la [documentación del plugin de Pix](/es/midaz/plugins/pix/pix-overview).
## Mejores prácticas
***
El `endToEndId` es el identificador único de Pix en todo el ecosistema — desde la institución iniciadora a través del SPI hasta la institución receptora. Asegúrate de que esté almacenado en los metadatos de la transacción de Midaz y presente en el extracto del BACEN. Sin él, la conciliación recurre a la coincidencia por monto y fecha, lo cual es mucho menos confiable.
Las transacciones Pix cercanas al fin del día pueden liquidarse en el BACEN en D+1. Programar Matcher para las 07:00 UTC asegura que todas las liquidaciones del día anterior estén incluidas en el extracto del BACEN antes de que se ejecute la conciliación. Esto elimina excepciones falsas causadas por diferencias de horario.
Al procesar altos volúmenes de Pix, crea dos contextos separados — uno para cash-out y otro para cash-in. Esto simplifica el triaje de excepciones, proporciona métricas más granulares por flujo y permite programación independiente si es necesario.
Una conciliación Pix saludable alcanza una tasa de conciliación automática superior al 99%. Si la tasa cae por debajo del 95%, investiga problemas sistémicos como fallos del plugin, cambios en el formato del BACEN o metadatos faltantes en las transacciones de Midaz.
Pix no tiene comisiones intermedias, liquidaciones parciales ni cargos de procesamiento. Si los montos divergen entre Midaz y el BACEN, indica un problema real — no redondeo. Mantén tanto `feeToleranceAbs` como `feeTolerancePct` en cero.
Siempre ejecuta un `DRY_RUN` antes de `COMMIT`, especialmente después de cambios en reglas o mapeos de campos. Esto te permite revisar los resultados de la conciliación y detectar errores de configuración antes de que afecten los datos de producción.
## Métricas clave
***
Monitorea estas métricas para supervisar la salud de tu proceso de conciliación Pix.
| Métrica | Valor saludable | Umbral de alerta |
| ------------------------------- | ---------------------------- | ---------------- |
| Tasa de conciliación automática | Superior al 99% | Inferior al 95% |
| Excepciones diarias | Inferior al 0.5% del volumen | Superior al 2% |
| Tiempo promedio de resolución | Menos de 4 horas | Más de 24 horas |
| Excepciones sin resolver 48h+ | 0 | Más de 5 |
Utiliza los endpoints del dashboard de Matcher para monitorear estas métricas en tiempo real. Consulta [Métricas del dashboard](/es/reference/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 configuraciones avanzadas de conciliación.
Profundiza en el mapeo automático de campos y la sincronización en tiempo real con Midaz Ledger.
Guía detallada sobre investigación, forzar conciliación y gestión de excepciones de conciliación.