> ## 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. # Contextos y fuentes > Configura un contexto de conciliación y sus fuentes en Matcher. Elige la cardinalidad 1:1, 1:N o N:M, agrega feeds de banco y de ledger, y dispara ejecuciones de coincidencia. 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](/es/products/matcher/configuration/matcher-schedules) aparte. Un contexto nuevo empieza en `DRAFT` y se queda ahí hasta que lo actives de forma explícita. #### Solicitud ```bash cURL theme={null} 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 Nombre descriptivo del contexto Cardinalidad de coincidencia: `1:1`, `1:N` o `N:M` Etiqueta de ejecución obligatoria (por ejemplo, `daily`, `weekly`). No programa ejecuciones. Tolerancia absoluta de comisión para la comparación de montos, como cadena decimal (por ejemplo, `"0.01"`) Tolerancia porcentual de comisión para la comparación de montos, como cadena decimal (`"0.5"` significa 0.5%) Modo opcional de normalización de comisiones: `NET` o `GROSS`. Omítelo para dejar deshabilitada la normalización de comisiones. Dispara automáticamente una ejecución de coincidencia después de subir un archivo #### Respuesta ```json theme={null} { "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](/es/reference/products/matcher/create-context) ## 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](/es/products/matcher/configuration/matcher-schedules) 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: ```bash cURL 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" }' ``` 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: * [Ejecutar coincidencia](/es/reference/products/matcher/run-match) * [Listar ejecuciones de coincidencia](/es/reference/products/matcher/list-match-runs) ## ¿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`: ```bash cURL theme={null} 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`: ```bash cURL theme={null} 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](/es/reference/products/matcher/create-source) ### 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](#source-bindings) en el riel de consulta (`connectionId`). Consulta [Discovery](/es/products/matcher/integrations/matcher-discovery) para saber cómo configurar conexiones. ```bash cURL theme={null} 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: * [Crear fuente](/es/reference/products/matcher/create-source) * [Obtener fuente](/es/reference/products/matcher/retrieve-source) * [Actualizar fuente](/es/reference/products/matcher/update-source) * [Archivar fuente](/es/reference/products/matcher/archive-source) * [Restaurar fuente](/es/reference/products/matcher/restore-source)

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](/es/products/matcher/integrations/matcher-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 ```bash cURL theme={null} 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 Riel por el que el programador extrae la fuente: `file` o `query` (obligatorio). Conexión del motor de Discovery del riel de consulta. Obligatoria para `query`, rechazada para `file`. Formato declarado que produce el binding (clave de descriptor con namespace de región/familia, por ejemplo `br/cnab400/default`). 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. Si el programador puede despachar el binding cuando vence. De forma predeterminada es `true`. Habilitarlo no lo ejecuta de inmediato. Referencia de API: * [Crear binding de fuente](/es/reference/products/matcher/create-source-binding) * [Listar bindings de fuente](/es/reference/products/matcher/list-source-bindings) * [Obtener binding de fuente](/es/reference/products/matcher/get-source-binding) * [Actualizar binding de fuente](/es/reference/products/matcher/update-source-binding) * [Eliminar binding de fuente](/es/reference/products/matcher/delete-source-binding) ## 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 ```bash cURL theme={null} 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](/es/reference/products/matcher/update-context) ### Pausar un contexto Para mantener un contexto fuera de las ejecuciones de conciliación de forma temporal, actualiza su estado a `PAUSED`: ```bash cURL theme={null} 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. ```bash cURL theme={null} 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](#restore-a-context) Referencia de API: [Archivar contexto](/es/reference/products/matcher/archive-context)

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. ```bash cURL theme={null} 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](/es/reference/products/matcher/restore-context) ### 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í. ```bash cURL theme={null} 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](/es/reference/products/matcher/clone-context) ## 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](#archive-a-context). 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](#restore-a-context). Ciclo de vida del contexto de Matcher ## Mejores prácticas *** Usa nombres explícitos que reflejen cuentas, sistemas y propósito. Al principio, prioriza la exactitud sobre la automatización. Ajusta los umbrales según los resultados observados. Usa varios contextos en lugar de una sola conciliación amplia. Marca siempre las fuentes con requisitos de cumplimiento. Confirma que las zonas horarias de las fuentes reflejen el feed de datos original. Define de forma explícita la semántica de débito y crédito de cada fuente. ## Próximos pasos *** Define cómo los campos de la fuente se asignan al esquema de Matcher. Configura las reglas que rigen la conciliación.