Contextos y fuentes

Los contextos y las fuentes son la forma de indicarle a Matcher qué conciliar y de dónde vienen los números. Configuras estos dos bloques antes de que ocurra cualquier coincidencia.

Un contexto es una sola conciliación que te importa. Por ejemplo, “nuestra cuenta bancaria principal vs. nuestros libros.” Define el alcance: qué sistemas comparar y qué reglas aplican.
Una fuente es uno de los sistemas que alimentan números a esa comparación: un extracto bancario, una exportación de ERP, el archivo de liquidación de un procesador de pagos o un ledger.

Cada contexto compara exactamente dos lados entre sí, así que cada uno necesita al menos dos fuentes. La coincidencia, las excepciones y los informes dependen de estos dos.

¿Qué es un contexto de conciliación?

Un contexto de conciliación define los límites operativos de un proceso de conciliación. Especifica:

Qué fuentes de datos comparar
Qué reglas de coincidencia aplican
Cómo manejar las excepciones

Ejemplos comunes:

Cuenta bancaria 1234 vs contabilidad general (conciliación bancaria diaria)
Gateway de pagos vs sistema de ingresos (conciliación de pagos)
Entidad intercompañía A vs entidad B (conciliación intercompañía)

Tipos de contexto

Matcher permite usar distintas cardinalidades de conciliación según la estructura de la transacción.

Uno a uno (1:1)

Matcher concilia cada transacción contra una sola contraparte. Casos de uso típicos:

Extractos bancarios
Coincidencia directa de pagos

Uno a muchos (1:N)

Matcher concilia una transacción contra múltiples contrapartes. Casos de uso típicos:

Pagos divididos
Depósitos en lote
Facturas consolidadas

Muchos a muchos (N:M)

Matcher concilia múltiples transacciones entre múltiples contrapartes. Casos de uso típicos:

Acuerdos de neteo
Asignación compleja de pagos
Flujos financieros de múltiples tramos

Crear un contexto de conciliación

Cuando ya sabes qué vas a conciliar, crea el contexto. En esta etapa declaras sobre todo la cardinalidad (type), una etiqueta de ejecución obligatoria (interval) y cualquier tolerancia de comisión que la comparación deba permitir. El valor de interval no programa ejecuciones. La ejecución automática requiere una programación de conciliación aparte.

Solicitud

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Daily Bank Reconciliation",
   "interval": "daily",
   "type": "1:1",
   "feeToleranceAbs": "0",
   "feeTolerancePct": "0",
   "feeNormalization": "NET",
   "autoMatchOnUpload": false
 }'

Campos del contexto

string

Nombre descriptivo del contexto

string

Cardinalidad de coincidencia: 1:1, 1:N o N:M

string

Etiqueta de ejecución obligatoria (por ejemplo, daily, weekly). No programa ejecuciones.

string

predeterminado:"0"

Tolerancia absoluta cuando Matcher compara una comisión real con la comisión esperada, como cadena decimal (por ejemplo, "0.01")

string

predeterminado:"0"

Tolerancia relativa para la misma comparación de comisiones, como fracción en una cadena decimal ("0.02" tolera 2%)

string

Modo opcional de normalización de comisiones: NET o GROSS. Omítelo para dejar deshabilitada la normalización de comisiones.

boolean

predeterminado:"false"

Dispara automáticamente una ejecución de coincidencia después de subir un archivo

string

predeterminado:"SAME"

Cómo los datos del contexto llevan el signo: SAME u OPPOSITE. Con SAME, un pago lleva el mismo signo que lo que liquida, y un importe negativo es una reversión. Con OPPOSITE, un pago lleva el signo opuesto al de la factura que liquida. Después de que el contexto lleva un saldo parcial, Matcher rechaza el cambio con 409. También rechaza el cambio mientras una ejecución de coincidencia está en curso.

integer

Límite opcional de antigüedad de las partidas abiertas, en días (1 o más). En una ejecución COMMIT, un saldo de partida abierta más antiguo que este límite genera una excepción AGED_BREAK. Omítelo para deshabilitar la antigüedad. En una actualización, 0 la deshabilita.

string

Calendario opcional de días hábiles para agedBreakThresholdDays: US_FED o BR_ANBIMA. Omítelo para contar días naturales.

Respuesta

{
  "id":"019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f",
  "tenantId":"11111111-1111-1111-1111-111111111111",
  "name":"Daily Bank Reconciliation",
  "type":"1:1",
  "interval":"daily",
  "status":"DRAFT",
  "feeToleranceAbs":"0",
  "feeTolerancePct":"0",
  "feeNormalization":"NET",
  "autoMatchOnUpload":false,
  "signConvention":"SAME",
  "createdAt":"2026-02-02T16:31:22Z",
  "updatedAt":"2026-02-02T16:31:22Z"
}

Referencia de API: Crear contexto

Ejecutar la conciliación

Un contexto no concilia por sí solo. Tú disparas una ejecución de coincidencia. Una ejecución aplica las reglas del contexto a las transacciones de sus fuentes y luego produce coincidencias y excepciones. Puedes disparar ejecuciones a mano o dejar que una programación las dispare automáticamente. Cada ejecución funciona en uno de dos modos:

Modo	Qué hace
`DRY_RUN`	No persiste resultados de coincidencia, mutaciones de transacciones, artefactos de comisión ni excepciones, pero sí persiste un `MatchRun` completado y sus estadísticas
`COMMIT`	Ejecuta la coincidencia y persiste los resultados

Dispara una ejecución para un contexto:

cURL

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"
 }'

De forma predeterminada, una ejecución es síncrona: corre dentro de la solicitud y la respuesta lleva el estado final. Para volúmenes grandes, define "async": true para enviar la ejecución y consultar su progreso en su lugar. Cuando el envío asíncrono no está disponible, Matcher rechaza "async": true con HTTP 503.

Ambos modos devuelven HTTP 202 Accepted cuando tienen éxito, así que lee el status de la respuesta para distinguirlos.Una ejecución síncrona devuelve COMPLETED. Cuando falla, la solicitud devuelve una respuesta de problema. Una ejecución asíncrona devuelve QUEUED y consultas GET /v1/matching/runs/{runId}.Mientras está en curso, una ejecución pasa por PROCESSING y FINALIZING (trata ambos como no terminados) antes de llegar a COMPLETED o FAILED.

Para revisar ejecuciones pasadas, lista el historial de ejecuciones de un contexto con GET /v1/matching/contexts/{contextId}/runs.

Referencia de API:

¿Qué es una fuente?

Una fuente representa un sistema o feed de datos que suministra transacciones a un contexto de conciliación. Cada contexto requiere al menos dos fuentes. Las fuentes típicas incluyen:

Feeds de extractos bancarios
Exportaciones de contabilidad general de ERP
Streams de transacciones de procesadores de pago
Sistemas contables internos

Agregar fuentes a un contexto

Un contexto necesita al menos dos fuentes, una por cada lado de la comparación. El campo side (LEFT o RIGHT) declara a qué lado alimenta una fuente. Matcher concilia el lado LEFT contra el lado RIGHT. Asigna un lado a cada fuente y mantén la asignación consistente. Crea una fuente con un name, un type, un side y un objeto config. Deja config vacío ({}) cuando la fuente no necesita ajustes específicos de conexión, como en un feed bancario del lado LEFT. El objeto config también guarda ajustes de importación, como la detección de duplicados:

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Chase Bank - Account 1234",
   "type": "BANK",
   "side": "LEFT",
   "config": {}
 }'

Apunta el otro lado a una segunda fuente, por ejemplo un gateway de pagos del lado RIGHT:

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Payment Gateway",
   "type": "GATEWAY",
   "side": "RIGHT"
 }'

name, type y side son obligatorios (name tiene de 1 a 50 caracteres). config es opcional y, de forma predeterminada, es un objeto vacío cuando se omite.

Referencia de API: Crear fuente

Tipos de fuente

Tipo	Descripción	Uso típico
`LEDGER`	Ledger interno	Sistemas contables internos (incluido Midaz)
`BANK`	Feed de extractos bancarios	Feeds bancarios externos
`GATEWAY`	Gateway de pagos	Procesadores de pago (Stripe, Adyen, PayPal)
`CUSTOM`	Feed a medida	Cualquier otra fuente de datos
`FETCHER`	Fuente del motor de Discovery	Filas que el motor de extracción obtiene de una conexión de Discovery

Fuentes de Discovery

FETCHER identifica un tipo de fuente. Su config debe llevar connection_id, el id de una conexión de Discovery, y cada conexión alimenta una fuente FETCHER. Las filas que el motor de extracción obtiene de esa conexión llegan a esta fuente. Para extraer de forma programada, agrega un binding de fuente en el riel de consulta con el mismo connectionId.

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Open Banking Aggregator",
   "type": "FETCHER",
   "side": "LEFT",
   "config": {
     "connection_id": "8f14e45f-ceea-4f6a-9d1b-2b6f3c7a9e10"
   }
 }'

Gestionar las fuentes

Las fuentes admiten un ciclo de vida CRUD completo bajo /v1/contexts/{contextId}/sources. Puedes renombrar o reconfigurar una fuente en cualquier momento, y el archivado es suave y reversible. Una fuente archivada queda excluida de la readiness del contexto, de la coincidencia y del listado predeterminado de fuentes, pero conserva todo su historial hasta que la restaures. Archivar no deshabilita sus bindings. Deshabilítalos o elimínalos por separado para detener el despacho del programador.

Acción	Método y ruta	Notas
Crear fuente	`POST /v1/contexts/{contextId}/sources`	Cuerpo: `name`, `type`, `side`, `config` (ver arriba).
Listar fuentes	`GET /v1/contexts/{contextId}/sources`	Lista las fuentes del contexto. Agrega `includeArchived=true` para incluir las fuentes archivadas.
Obtener fuente	`GET /v1/contexts/{contextId}/sources/{sourceId}`	Recupera una sola fuente por id.
Actualizar fuente	`PATCH /v1/contexts/{contextId}/sources/{sourceId}`	Actualiza los campos mutables de la fuente (por ejemplo, `name`, `config`).
Archivar fuente	`POST /v1/contexts/{contextId}/sources/{sourceId}/archive`	Excluye la fuente de la readiness, de la coincidencia y del listado predeterminado; los bindings siguen habilitados hasta que se cambien por separado.
Restaurar fuente	`POST /v1/contexts/{contextId}/sources/{sourceId}/restore`	Reactiva una fuente archivada previamente.

Referencia de API:

Bindings de fuente

Los bindings definen cómo el programador de bindings puede extraer datos de la fuente sin subir un archivo a mano. Un binding de fuente vincula una fuente al riel que suministra sus transacciones, más una duración que determina cuándo vence. Exactamente un riel aplica a cada kind de binding:

file: obtiene archivos mediante un transporte (rellena transportConfig).
query: extrae filas mediante una conexión del motor de Discovery (rellena connectionId). Las filas llegan a la fuente FETCHER cuyo config.connection_id coincide, sin importar la fuente ni el format que nombre el binding. Consulta Discovery.

Los bindings viven bajo /v1/contexts/{contextId}/sources/{sourceId}/bindings.

Las extracciones programadas se ejecutan cuando Lerian habilita el programador de bindings. Un binding se despacha solo cuando está habilitado y vence. Crear o habilitar un binding no lo ejecuta de inmediato.

Acción	Método y ruta
Crear binding	`POST /v1/contexts/{contextId}/sources/{sourceId}/bindings`
Listar bindings	`GET /v1/contexts/{contextId}/sources/{sourceId}/bindings`
Obtener binding	`GET /v1/contexts/{contextId}/sources/{sourceId}/bindings/{bindingId}`
Actualizar binding	`PATCH /v1/contexts/{contextId}/sources/{sourceId}/bindings/{bindingId}`
Eliminar binding	`DELETE /v1/contexts/{contextId}/sources/{sourceId}/bindings/{bindingId}`

El listado devuelve todos los bindings, habilitados y deshabilitados, así que un binding deshabilitado sigue visible en lugar de desaparecer en silencio.

Crear un binding del riel de consulta

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{sourceId}/bindings" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "kind": "query",
   "connectionId": "550e8400-e29b-41d4-a716-446655440000",
   "format": "br/cnab400/febraban-base",
   "scheduleSpec": "1h",
   "enabled": true
 }'

Campos

string

requerido

Riel por el que el programador extrae la fuente: file o query (obligatorio).

string (UUID)

Conexión del motor de Discovery del riel de consulta. Obligatoria para query, rechazada para file.

string

requerido

Formato declarado que produce el binding (clave de descriptor con namespace de región/familia, por ejemplo br/cnab400/febraban-base).

string

requerido

Cadena de duración de Go que lee el programador de bindings, como 1h o 30m. La sintaxis de cron y @every no es válida.

boolean

Si el programador puede despachar el binding cuando vence. De forma predeterminada es true. Habilitarlo no lo ejecuta de inmediato.

Referencia de API:

Gestionar los contextos

Puedes cambiar la configuración de un contexto, pausarlo, retirarlo o copiarlo. Estas operaciones de ciclo de vida conservan el historial para que nunca pierdas un registro de auditoría.

Actualizar un contexto

cURL

curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Daily Bank Reconciliation - Updated",
   "interval": "weekly",
   "status": "PAUSED"
 }'

Referencia de API: Actualizar contexto

Pausar un contexto

Para mantener un contexto fuera de las ejecuciones de conciliación de forma temporal, actualiza su estado a PAUSED:

cURL

curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "status": "PAUSED"
 }'

Pausar un contexto:

Impide nuevas ejecuciones de coincidencia
Conserva los datos históricos
Permite reactivarlo después al volver a poner el estado en ACTIVE

Archivar un contexto

El archivado es un borrado suave reversible. En lugar de eliminar un contexto de forma permanente, mueve el contexto al estado ARCHIVED y conserva todo su historial (fuentes, reglas, ejecuciones de coincidencia y registros de auditoría) mientras lo excluye del listado de contextos predeterminado.

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/archive" \
 -H "Authorization: Bearer $TOKEN"

Archivar un contexto:

Pone el estado del contexto en ARCHIVED
Conserva el historial completo y el registro de auditoría
Excluye el contexto del listado predeterminado
Es reversible en cualquier momento con el endpoint restore

Referencia de API: Archivar contexto

Restaurar un contexto

Restaurar revierte un archivado. Mueve el contexto de ARCHIVED de vuelta a DRAFT, para que puedas revisar y reconfigurar el contexto antes de reactivarlo.

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/restore" \
 -H "Authorization: Bearer $TOKEN"

Restaurar un contexto:

Pone el estado del contexto de ARCHIVED de vuelta en DRAFT
No reanuda la coincidencia automáticamente. Revisa y reactiva el contexto para volver a ejecutar la conciliación
Devuelve 409 Conflict si se llama sobre un contexto que no está archivado

Referencia de API: Restaurar contexto

Clonar un contexto

Para duplicar un contexto existente con sus fuentes, reglas, reglas de comisión y mapas de campos, usa el endpoint de clonado. Úsalo para crear plantillas. Las reglas de comisión clonadas siguen referenciando las mismas tablas de comisiones que el contexto de origen. Matcher no copia las tablas de comisiones en sí.

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/clone" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Q1 2025 Reconciliation (Copy)",
   "includeSources": true,
   "includeRules": true
 }'

La respuesta informa cuántas fuentes, reglas, reglas de comisión y mapas de campos copió Matcher. Un clonado exitoso vuelve en estado ACTIVE.

Referencia de API: Clonar contexto

Ciclo de vida del contexto

Un contexto de conciliación sigue un ciclo de vida que controla cuándo puede correr la coincidencia y cómo se conservan los datos.

Un contexto empieza en Draft, donde configuras fuentes y ajustes.
Un contexto permanece en Draft hasta que una actualización explícita lo pone en ACTIVE. La activación valida las fuentes obligatorias en ambos lados, LEFT y RIGHT, los mapeos de campos u opciones CAMT, las reglas de coincidencia y las reglas de comisión cuando habilitas la normalización de comisiones.
Un contexto activo puede ponerse temporalmente en Paused para detener la ejecución sin afectar la configuración ni los datos históricos.
Cuando ya no necesitas un contexto, muévelo a Archived con el endpoint archive. El archivado es un borrado suave reversible: mueve el contexto a ARCHIVED, conserva el historial completo y los registros de auditoría, y lo excluye del listado predeterminado. Un contexto archivado puede volver a Draft en cualquier momento con el endpoint restore.

Ciclo de vida del contexto de Matcher — Ciclo de vida de un contexto de Matcher

Mejores prácticas

Usa nombres descriptivos

Usa nombres explícitos que reflejen cuentas, sistemas y propósito.

Empieza con umbrales conservadores

Al principio, prioriza la exactitud sobre la automatización. Ajusta los umbrales según los resultados observados.

Separa responsabilidades

Usa varios contextos en lugar de una sola conciliación amplia.

Próximos pasos

Mapeo de campos

Define cómo los campos de la fuente se asignan al esquema de Matcher.

Reglas de coincidencia

Configura las reglas que rigen la conciliación.

Resumen

Guías

Console

Operaciones

Contextos y fuentes

¿Qué es un contexto de conciliación?

Tipos de contexto

Uno a uno (1:1)

Uno a muchos (1:N)

Muchos a muchos (N:M)

Crear un contexto de conciliación

Solicitud

Campos del contexto

Respuesta

Ejecutar la conciliación

¿Qué es una fuente?

Agregar fuentes a un contexto

Tipos de fuente

Fuentes de Discovery

Gestionar las fuentes

Bindings de fuente

Crear un binding del riel de consulta

Campos

Gestionar los contextos

Actualizar un contexto

Pausar un contexto

Archivar un contexto

Restaurar un contexto

Clonar un contexto

Ciclo de vida del contexto

Mejores prácticas

Próximos pasos

Mapeo de campos

Reglas de coincidencia

​¿Qué es un contexto de conciliación?

​Tipos de contexto

​Uno a uno (1:1)

​Uno a muchos (1:N)

​Muchos a muchos (N:M)

​Crear un contexto de conciliación

​Solicitud

​Campos del contexto

​Respuesta

​Ejecutar la conciliación

​¿Qué es una fuente?

​Agregar fuentes a un contexto

​Tipos de fuente

​Fuentes de Discovery

​Gestionar las fuentes

​Bindings de fuente

​Crear un binding del riel de consulta

​Campos

​Gestionar los contextos

​Actualizar un contexto

​Pausar un contexto

​Archivar un contexto

​Restaurar un contexto

​Clonar un contexto

​Ciclo de vida del contexto

​Mejores prácticas

​Próximos pasos

Mapeo de campos

Reglas de coincidencia

¿Qué es un contexto de conciliación?

Tipos de contexto

Uno a uno (1:1)

Uno a muchos (1:N)

Muchos a muchos (N:M)

Crear un contexto de conciliación

Solicitud

Campos del contexto

Respuesta

Ejecutar la conciliación

¿Qué es una fuente?

Agregar fuentes a un contexto

Tipos de fuente

Fuentes de Discovery

Gestionar las fuentes

Bindings de fuente

Crear un binding del riel de consulta

Campos

Gestionar los contextos

Actualizar un contexto

Pausar un contexto

Archivar un contexto

Restaurar un contexto

Clonar un contexto

Ciclo de vida del contexto

Mejores prácticas

Próximos pasos