> ## 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 > 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 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 ```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 para el contexto Cardinalidad de coincidencia: `1:1`, `1:N` o `N:M` Frecuencia de conciliación (ej. `daily`, `weekly`) Tolerancia absoluta de comisiones para la comparación de montos Tolerancia porcentual de comisiones para la comparación de montos Modo de normalización de comisiones: `NET` o `GROSS` Ejecutar automáticamente una ejecución de coincidencia cuando se sube 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/matcher/create-context) ## 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](/es/matcher/configuration/matcher-schedules) 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: ```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" }' ``` 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](/es/reference/matcher/run-match) | [Listar ejecuciones de coincidencia](/es/reference/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 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`: ```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 análisis específicos de la fuente cuando se necesitan — por ejemplo una pasarela de pago en el 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`, `side` y `config` son todos obligatorios (`name` tiene entre 1 y 50 caracteres; `config` puede ser `{}`). Referencia de API: [Crear fuente](/es/reference/matcher/create-source) ### 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](#bindings-de-fuente) en el riel de consulta (`connectionId`) — consulta [Descubrimiento](/es/matcher/integrations/matcher-discovery) para saber cómo se configuran las 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" } }' ``` ## 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: * [Crear fuente](/es/reference/matcher/create-source) * [Obtener fuente](/es/reference/matcher/retrieve-source) * [Actualizar fuente](/es/reference/matcher/update-source) * [Archivar fuente](/es/reference/matcher/archive-source) * [Restaurar fuente](/es/reference/matcher/restore-source) ## 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](/es/matcher/integrations/matcher-discovery)). 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 ```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": "@every 1h", "enabled": true }' ``` #### Campos Riel en el que se extrae la fuente: `file` o `query` (obligatorio). Conexión del motor de descubrimiento en el riel de consulta. Obligatorio para `query`, rechazado para `file`. Formato declarado que produce el binding (clave de descriptor con espacio de nombres por región/familia, ej. `br/cnab400/default`). Programación por intervalo que lee el programador de bindings (cron o duración `@every`). Si el binding se ejecuta de inmediato. Por defecto es `true`. Referencia de API: * [Crear binding de fuente](/es/reference/matcher/create-source-binding) * [Listar bindings de fuente](/es/reference/matcher/list-source-bindings) * [Obtener binding de fuente](/es/reference/matcher/get-source-binding) * [Actualizar binding de fuente](/es/reference/matcher/update-source-binding) * [Eliminar binding de fuente](/es/reference/matcher/delete-source-binding) ## 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 ```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/matcher/update-context) ### Pausar un contexto Para detener temporalmente el uso de un contexto en ejecuciones de conciliación, 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: * 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. ```bash cURL theme={null} 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](#restaurar-un-contexto) Referencia de API: [Archivar contexto](/es/reference/matcher/archive-context) ### 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. ```bash cURL theme={null} 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](/es/reference/matcher/restore-context) ### 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. ```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, "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](/es/reference/matcher/clone-context) ## 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-un-contexto). 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](#restaurar-un-contexto). Ciclo de vida del 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 explícitos que reflejen cuentas, sistemas y propósito. Favorece la precisión sobre la automatización inicialmente. Ajusta los umbrales según los resultados observados. Usa múltiples contextos en lugar de una única conciliación amplia. Siempre marca las fuentes con requisitos de cumplimiento. Asegúrate de que las zonas horarias de las fuentes reflejen el feed de datos original. Define explícitamente la semántica de débito y crédito para cada fuente. ## Próximos pasos *** Define cómo los campos de origen se mapean al esquema de Matcher. Configura las reglas que impulsan la conciliación.