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, qué reglas aplican y sobre qué período.
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
La ventana de tiempo que cubre la conciliación

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. Un contexto nuevo empieza en DRAFT y se queda ahí hasta que lo actives de forma explícita.

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 de comisión para la comparación de montos, como cadena decimal (por ejemplo, "0.01")

string

predeterminado:"0"

Tolerancia porcentual de comisión para la comparación de montos, como cadena decimal ("0.5" significa 0.5%)

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

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

Ejecutar la conciliación

Un contexto no concilia por sí solo. Tú disparas 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 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. El envío asíncrono requiere un worker de ejecución de coincidencia habilitado. Sin uno, Matcher rechaza "async": true con HTTP 503.

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 COMPLETED o FAILED terminal. 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:

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 de parseo específicos de la fuente cuando se necesitan, 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",
   "config": {
     "currency": "USD",
     "provider": "stripe"
   }
 }'

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	Conexiones de agregador suministradas mediante un binding de fuente

Fuentes de Discovery

FETCHER identifica un tipo de fuente. Por sí solo no habilita la extracción automática. Créalo 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 Discovery para saber cómo configurar 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"
   }
 }'

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 de los listados 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.
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 de los listados; 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). Consulta Discovery.

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

Un binding se despacha solo cuando el programador de bindings está habilitado (está deshabilitado de forma predeterminada), el binding está habilitado y el binding 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/default",
   "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

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

string

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 o replicar configuraciones entre entornos. 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.

Marca las fuentes regulatorias

Marca siempre las fuentes con requisitos de cumplimiento.

Alinea las zonas horarias

Confirma que las zonas horarias de las fuentes reflejen el feed de datos original.

Documenta las convenciones de signo

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

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

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)

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