Contextos y fuentes

Aprende cómo los contextos definen el alcance de la conciliación y las fuentes conectan los sistemas que envían datos transaccionales a Matcher.

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 declaras principalmente la cardinalidad (type), una etiqueta de ejecución obligatoria (interval) y cualquier tolerancia de comisiones que deba permitir la comparación. El valor de interval no programa ejecuciones; la ejecución automática requiere una programación de conciliación separada. Un contexto nuevo inicia en DRAFT y permanece así hasta que lo actives explícitamente.

​

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

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

feeToleranceAbs · string · predeterminado: "0"

Tolerancia absoluta de comisiones para la comparación de montos, como cadena decimal (ej. "0.01")

feeTolerancePct · string · predeterminado: "0"

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

feeNormalization · string

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

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	No persiste resultados de coincidencia, mutaciones de transacciones, artefactos de tarifas ni excepciones, pero sí persiste un MatchRun completado y sus estadísticas
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. El envío asíncrono requiere que el worker de match runs esté habilitado; de lo contrario, 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 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 y side son obligatorios (name tiene entre 1 y 50 caracteres). config es opcional y por defecto es un objeto vacío cuando se omite.

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

​

Fuentes fetcher

FETCHER identifica un tipo de fuente; no habilita la extracción automática por sí solo. 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 se excluye de la preparación del contexto, la coincidencia y los listados de fuentes, pero conserva todo su historial hasta que la restauras. El archivado no deshabilita sus bindings; deshabilítalos o elimínalos por separado para detener los despachos 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 ú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	Excluye la fuente de la preparación, la coincidencia y los listados; los bindings permanecen habilitados hasta que los cambies por separado.
Restaurar fuente	POST /v1/contexts/{contextId}/sources/{sourceId}/restore	Reactiva una fuente previamente archivada.

Referencia de API:

• Crear fuente
• Obtener fuente
• Actualizar fuente
• Archivar fuente
• Restaurar fuente

​

Bindings de fuente

---

Los bindings definen cómo el programador de bindings puede extraer datos de una fuente sin una carga manual de archivos. Un binding de fuente vincula una fuente al riel que suministra sus transacciones, además de una duración que determina cuándo vence. 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.

Un binding solo se despacha cuando el programador de bindings está habilitado (está deshabilitado por defecto), el binding está habilitado y ya venció. Crear o habilitar un binding no lo ejecuta inmediatamente.

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": "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

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

enabled · boolean

Indica si el programador puede despachar el binding cuando vence. Por defecto es true; habilitarlo no lo ejecuta inmediatamente.

Referencia de API:

• Crear binding de fuente
• Listar bindings de fuente
• Obtener binding de fuente
• Actualizar binding de fuente
• Eliminar binding de fuente

​

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

La respuesta reporta cuántas fuentes, reglas, reglas de tarifas y mapeos de campos se copiaron. Un clon exitoso se devuelve en estado ACTIVE.

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.
• Un contexto permanece en Draft hasta que una actualización explícita establece su estado en ACTIVE. La activación valida las fuentes izquierda y derecha obligatorias, los mapeos de campos o las opciones CAMT, las reglas de coincidencia y las reglas de tarifas cuando la normalización de tarifas está habilitada.
• 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 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.