Contextos y fuentes

Los contextos y las fuentes son la forma en que le dices a Matcher qué conciliar y de dónde vienen los números. Son los dos bloques de construcción que configuras antes de que ocurra cualquier coincidencia.

Un contexto es una conciliación puntual que te importa — por ejemplo, “nuestra cuenta bancaria principal vs. nuestros libros.” Define el alcance: qué sistemas se comparan, qué reglas aplican y sobre qué período.
Una fuente es uno de los sistemas que aporta números a esa comparación — un extracto bancario, una exportación de un ERP, el archivo de liquidación de un procesador de pagos o un libro mayor.

Cada contexto compara exactamente dos lados entre sí, por lo que cada uno necesita al menos dos fuentes. Acierta con estos y todo lo que viene después — la coincidencia, las excepciones y los reportes — se sigue de ahí.

¿Qué es un contexto de conciliación?

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

Qué fuentes de datos se comparan
Qué reglas de coincidencia aplican
Cómo se manejan las excepciones
La ventana de tiempo cubierta por la conciliación

Ejemplos comunes:

Cuenta bancaria 1234 vs Libro mayor (conciliación bancaria diaria)
Pasarela de pago 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 diferentes cardinalidades de conciliación según la estructura de las transacciones.

Uno a uno (1:1)

Cada transacción se concilia contra una única contraparte. Casos de uso típicos:

Extractos bancarios
Conciliación directa de pagos

Uno a muchos (1:n)

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

Pagos divididos
Depósitos por lotes
Facturas consolidadas

Muchos a muchos (n:m)

Múltiples transacciones se concilian entre múltiples contrapartes. Casos de uso típicos:

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

Creando un contexto de conciliación

Una vez que sabes qué vas a conciliar, crea el contexto. En esta etapa principalmente declaras la cardinalidad (type), con qué frecuencia se ejecuta (interval) y cualquier tolerancia de comisiones que la comparación deba permitir. Un contexto nuevo inicia en DRAFT para que puedas agregar fuentes y reglas antes de ponerlo en marcha.

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

name

string

Nombre descriptivo para el contexto

type

string

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

interval

string

Frecuencia de conciliación (ej. daily, weekly)

feeToleranceAbs

decimal

predeterminado:"0"

Tolerancia absoluta de comisiones para la comparación de montos

feeTolerancePct

decimal

predeterminado:"0"

Tolerancia porcentual de comisiones para la comparación de montos

feeNormalization

string

predeterminado:"NET"

Modo de normalización de comisiones: NET o GROSS

autoMatchOnUpload

boolean

predeterminado:"false"

Ejecutar automáticamente una ejecución de coincidencia cuando se sube un archivo

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,
  "createdAt":"2026-02-02T16:31:22Z",
  "updatedAt":"2026-02-02T16:31:22Z"
}

Referencia de API: Crear contexto

Ejecutando conciliación

Un contexto no se concilia por sí solo — tú activas una ejecución de coincidencia. Una ejecución aplica las reglas activas del contexto a las transacciones de sus fuentes y luego produce coincidencias y excepciones. Puedes activar ejecuciones manualmente o dejar que una programación las dispare automáticamente. Cada ejecución opera en uno de dos modos:

Modo	Qué hace
`DRY_RUN`	Previsualiza coincidencias sin guardar nada — úsalo para validar cambios de reglas de forma segura
`COMMIT`	Ejecuta la coincidencia y persiste los resultados

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

Por defecto una ejecución es síncrona — se ejecuta dentro de la solicitud y la respuesta lleva el estado final. Para volúmenes grandes, establece "async": true para enviar la ejecución y consultar su progreso en su lugar.

Ambos modos devuelven HTTP 202 Accepted, así que lee el status de la respuesta, no el código HTTP, para conocer el resultado. Una ejecución síncrona devuelve un estado terminal COMPLETED o FAILED; una ejecución asíncrona devuelve QUEUED, y consultas GET /v1/matching/runs/{runId}. Mientras está en curso, una ejecución transita por PROCESSING y FINALIZING (trata ambos como aún no terminados) antes de alcanzar 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: Ejecutar coincidencia | Listar ejecuciones de coincidencia

¿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 del libro mayor del ERP
Flujos de transacciones de procesadores de pago
Sistemas contables internos

Agregando fuentes a un contexto

Un contexto necesita al menos dos fuentes — una para 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, type, side y un objeto config. Deja config vacío ({}) cuando la fuente no necesita ajustes específicos de conexión — como en el caso de un feed bancario en el lado LEFT:

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. config lleva los ajustes de conexión y análisis específicos de la fuente cuando se necesitan — por ejemplo una pasarela de pago en el 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",
   "config": {
     "currency": "USD",
     "provider": "stripe"
   }
 }'

name, type, side y config son todos obligatorios (name tiene entre 1 y 50 caracteres; config puede ser {}).

Referencia de API: Crear fuente

Tipos de fuente

Tipo	Descripción	Uso típico
`LEDGER`	Libro mayor interno	Sistemas contables internos (incluido Midaz)
`BANK`	Feed de extractos bancarios	Feeds bancarios externos
`GATEWAY`	Pasarela de pago	Procesadores de pago (Stripe, Adyen, PayPal)
`CUSTOM`	Feed a medida	Cualquier otra fuente de datos
`FETCHER`	Extracción por motor de descubrimiento	Conexiones de agregador extraídas automáticamente

Fuentes fetcher

Una fuente FETCHER obtiene sus datos automáticamente en lugar de que se suban. Créala como cualquier otra fuente y luego conecta la conexión del agregador upstream mediante un binding de fuente en el riel de consulta (connectionId) — consulta Descubrimiento para saber cómo se configuran las conexiones.

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": {
     "provider": "pluggy"
   }
 }'

Gestionando 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 lógico y reversible — una fuente archivada deja de alimentar datos nuevos pero conserva todo su historial hasta que la restauras.

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.
Obtener fuente	`GET /v1/contexts/{contextId}/sources/{sourceId}`	Recupera una única fuente por id.
Actualizar fuente	`PATCH /v1/contexts/{contextId}/sources/{sourceId}`	Actualiza campos mutables de la fuente (ej. `name`, `config`).
Archivar fuente	`POST /v1/contexts/{contextId}/sources/{sourceId}/archive`	Archiva de forma lógica la fuente; deja de alimentar datos nuevos pero se conserva.
Restaurar fuente	`POST /v1/contexts/{contextId}/sources/{sourceId}/restore`	Reactiva una fuente previamente archivada.

Referencia de API:

Bindings de fuente

Los bindings son la forma en que una fuente obtiene sus propios datos automáticamente, para que nadie tenga que subir archivos a mano. Un binding de fuente vincula una fuente al riel que suministra sus transacciones, además de una programación por intervalo que define con qué frecuencia extraer. Exactamente un riel es relevante por kind de binding:

file — obtiene archivos a través de un transporte (llena transportConfig).
query — extrae filas a través de una conexión del motor de descubrimiento (llena connectionId; consulta Descubrimiento).

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

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}`

La operación de listado devuelve todos los bindings, habilitados y deshabilitados, de modo que un binding deshabilitado permanece visible en lugar de desaparecer silenciosamente.

Crear un binding en el 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/default",
   "scheduleSpec": "@every 1h",
   "enabled": true
 }'

Campos

kind

string

requerido

Riel en el que se extrae la fuente: file o query (obligatorio).

connectionId

string (UUID)

Conexión del motor de descubrimiento en el riel de consulta. Obligatorio para query, rechazado para file.

format

string

Formato declarado que produce el binding (clave de descriptor con espacio de nombres por región/familia, ej. br/cnab400/default).

scheduleSpec

string

Programación por intervalo que lee el programador de bindings (cron o duración @every).

enabled

boolean

Si el binding se ejecuta de inmediato. Por defecto es true.

Referencia de API:

Gestionando contextos

A medida que las conciliaciones evolucionan, ajustarás los ajustes de un contexto, lo pausarás, lo retirarás o lo copiarás. Estas operaciones de ciclo de vida preservan el historial para que nunca pierdas un rastro 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 detener temporalmente el uso de un contexto en ejecuciones de conciliación, 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:

Previene nuevas ejecuciones de coincidencia
Preserva los datos históricos
Permite reactivación futura estableciendo el estado de vuelta a ACTIVE

Archivar un contexto

Archivar es un borrado lógico reversible. En lugar de eliminar permanentemente un contexto, lo mueve al estado ARCHIVED, preservando 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:

Establece el estado del contexto en ARCHIVED
Preserva el historial completo y el rastro de auditoría
Excluye el contexto del listado predeterminado
Puede revertirse en cualquier momento con el endpoint de restauración

Referencia de API: Archivar contexto

Restaurar un contexto

Restaurar revierte un archivado, moviendo el contexto de ARCHIVED de vuelta a DRAFT para que pueda ser revisado y reconfigurado antes de ser reactivado.

cURL

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

Restaurar un contexto:

Establece el estado del contexto de ARCHIVED de vuelta a DRAFT
No reanuda la coincidencia automáticamente: revisa y reactiva el contexto para volver a ejecutar la conciliación
Devuelve 409 Conflict si se invoca en 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 tarifas y mapeos de campos, utiliza el endpoint de clonación. Esto es útil para crear plantillas o replicar configuraciones entre entornos. Las reglas de tarifas clonadas siguen referenciando los mismos programas de tarifas que el contexto de origen; los programas de tarifas en sí no se copian.

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,
   "includeFeeSchedules": true
 }'

La respuesta reporta cuántas fuentes, reglas, reglas de tarifas y mapeos de campos se copiaron. El contexto clonado inicia en estado DRAFT, para que puedas revisar y ajustar la configuración antes de activarlo.

Referencia de API: Clonar contexto

Ciclo de vida del contexto

Un contexto de conciliación sigue un ciclo de vida bien definido que controla cuándo puede ejecutarse la conciliación y cómo se preservan los datos.

Un contexto se crea primero en Draft, donde se configuran las fuentes y los ajustes.
Una vez que todas las fuentes requeridas están en su lugar, el contexto se vuelve Active y es elegible para ejecuciones de conciliación.
Un contexto activo puede ser temporalmente Paused para detener la ejecución sin afectar la configuración o los datos históricos.
Cuando un contexto ya no es necesario, puede ser Archived mediante el endpoint de archivado. Archivar es un borrado lógico reversible: mueve el contexto a ARCHIVED, preserva 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 de restauración.

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

Este ciclo de vida asegura control operacional, ejecución predecible y trazabilidad completa a través de los períodos de conciliación.

Mejores prácticas

Usa nombres descriptivos

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

Comienza con umbrales conservadores

Favorece la precisión sobre la automatización inicialmente. Ajusta los umbrales según los resultados observados.

Separa las preocupaciones

Usa múltiples contextos en lugar de una única conciliación amplia.

Marca las fuentes regulatorias

Siempre marca las fuentes con requisitos de cumplimiento.

Alinea las zonas horarias

Asegúrate de que las zonas horarias de las fuentes reflejen el feed de datos original.

Documenta las convenciones de signo

Define explícitamente la semántica de débito y crédito para cada fuente.

Próximos pasos

Mapeo de campos

Define cómo los campos de origen se mapean al esquema de Matcher.

Reglas de coincidencia

Configura las reglas que impulsan la conciliación.

Resumen

Guías

Matcher UI

Servidor MCP

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)

Creando un contexto de conciliación

Solicitud

Campos del contexto

Respuesta

Ejecutando conciliación

¿Qué es una fuente?

Agregando fuentes a un contexto

Tipos de fuente

Fuentes fetcher

Gestionando fuentes

Bindings de fuente

Crear un binding en el riel de consulta

Campos

Gestionando 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)

​Creando un contexto de conciliación

​Solicitud

​Campos del contexto

​Respuesta

​Ejecutando conciliación

​¿Qué es una fuente?

​Agregando fuentes a un contexto

​Tipos de fuente

​Fuentes fetcher

​Gestionando fuentes

​Bindings de fuente

​Crear un binding en el riel de consulta

​Campos

​Gestionando 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)

Creando un contexto de conciliación

Solicitud

Campos del contexto

Respuesta

Ejecutando conciliación

¿Qué es una fuente?

Agregando fuentes a un contexto

Tipos de fuente

Fuentes fetcher

Gestionando fuentes

Bindings de fuente

Crear un binding en el riel de consulta

Campos

Gestionando 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