Contextos y fuentes

Los contextos y las fuentes definen cómo se estructura la conciliación en Matcher. Un contexto establece el alcance de la conciliación, mientras que las fuentes representan los sistemas que proporcionan datos transaccionales.

¿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 conciliación 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

Creación básica de contexto

Solicitud

cURL

curl -X POST "https://api.matcher.example.com/v1/config/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Conciliación bancaria diaria",
   "interval": "daily",
   "type": "1:1",
   "rateId": "",
   "feeToleranceAbs": 0,
   "feeTolerancePct": 0,
   "feeNormalization": "NET",
   "autoMatchOnUpload": false
 }'

Campos del contexto

Campo	Tipo	Por defecto	Descripción
`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`)
`rateId`	String	`""`	Referencia a una configuración de tasa FX para coincidencia multi-moneda
`feeToleranceAbs`	Decimal	`0`	Tolerancia absoluta de comisiones para comparación de montos
`feeTolerancePct`	Decimal	`0`	Tolerancia porcentual de comisiones para comparación de montos
`feeNormalization`	String	`"NET"`	Modo de normalización de comisiones: `NET` o `GROSS`
`autoMatchOnUpload`	Boolean	`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":"Conciliación bancaria diaria",
  "type":"1:1",
  "interval":"daily",
  "status":"DRAFT",
  "rateId":"",
  "feeToleranceAbs":"0",
  "feeTolerancePct":"0",
  "feeNormalization":"NET",
  "autoMatchOnUpload":false,
  "createdAt":"2026-02-02T16:31:22Z",
  "updatedAt":"2026-02-02T16:31:22Z"
}

API Reference: Crear contexto

Ejecutando conciliación

Matcher procesa transacciones mediante ejecuciones de coincidencia. Puede activar la coincidencia manualmente o ver el historial de ejecuciones pasadas.

Ejecuciones manuales de conciliación

Active una ejecución de coincidencia 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"
 }'

Respuesta

{
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PROCESSING"
}

API Reference: Ejecutar conciliación

Establezca mode: "DRY_RUN" para previsualizar resultados sin confirmar conciliaciones.

Modos de ejecución de conciliación

Modo	Descripción
`DRY_RUN`	Previsualizar coincidencias sin persistir resultados
`COMMIT`	Ejecutar coincidencia y persistir resultados

Ver historial de ejecuciones de conciliación

cURL

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

Respuesta

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
      "mode": "COMMIT",
      "status": "COMPLETED",
      "startedAt": "2026-01-20T06:00:00Z",
      "completedAt": "2026-01-20T06:05:23Z",
      "createdAt": "2026-01-20T06:00:00Z"
    }
  ],
  "limit": 20,
  "hasMore": false
}

API Reference: Listar ejecuciones de conciliación

Estados de ejecución de conciliación

Estado	Descripción
`PENDING`	Ejecución en cola
`PROCESSING`	Ejecución en progreso
`COMPLETED`	Ejecución completada exitosamente
`FAILED`	Ejecución encontró un error

¿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

Crear una fuente bancaria

cURL

curl -X POST "https://api.matcher.example.com/v1/config/contexts/{contextId}/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Chase Bank - Cuenta 1234",
   "type": "BANK"
 }'

Respuesta

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "name": "Chase Bank - Cuenta 1234",
  "type": "BANK",
  "config": {},
  "createdAt": "2026-02-02T16:35:00Z",
  "updatedAt": "2026-02-02T16:35:00Z"
}

API Reference: Crear fuente

Crear una fuente de libro mayor

cURL

curl -X POST "https://api.matcher.example.com/v1/config/contexts/{contextId}/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Libro mayor - GL 1000",
   "type": "LEDGER"
 }'

Tipos de fuente

Tipo	Descripción	Uso típico
`LEDGER`	Cuentas del libro mayor	Sistemas contables internos
`BANK`	Extractos bancarios	Feeds bancarios externos
`GATEWAY`	Transacciones de procesadores de pago	Pasarelas de pago
`CUSTOM`	Integraciones personalizadas	Cualquier otra fuente de datos

Configuración de fuente

Las fuentes aceptan un objeto config opcional para metadatos adicionales, y un feeScheduleId opcional para asociar un programa de comisiones:

cURL

curl -X POST "https://api.matcher.example.com/v1/config/contexts/{contextId}/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Payment Gateway",
   "type": "GATEWAY",
   "feeScheduleId": "",
   "config": {
     "currency": "USD",
     "provider": "stripe"
   }
 }'

Campo	Tipo	Descripción
`name`	String	Nombre descriptivo de la fuente
`type`	String	Tipo de fuente: `LEDGER`, `BANK`, `GATEWAY` o `CUSTOM`
`feeScheduleId`	String	Referencia opcional a un programa de comisiones para esta fuente
`config`	Object	Pares clave-valor flexibles para metadatos de integración

Gestionando contextos

Actualizar un contexto

cURL

curl -X PATCH "https://api.matcher.example.com/v1/config/contexts/{contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Conciliación bancaria diaria - Actualizada",
   "interval": "weekly",
   "status": "PAUSED"
 }'

API Reference: Actualizar contexto

Pausar un contexto

Para detener temporalmente un contexto de ser usado en ejecuciones de conciliación, actualice su estado a PAUSED:

cURL

curl -X PATCH "https://api.matcher.example.com/v1/config/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

Eliminar un contexto

cURL

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

API Reference: Eliminar contexto

Clonar un contexto

Para duplicar un contexto existente con sus fuentes, reglas y programas de tarifas, utilice el endpoint de clonación. Esto es útil para crear plantillas o replicar configuraciones entre entornos.

cURL

curl -X POST "https://api.matcher.example.com/v1/config/contexts/{contextId}/clone" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Conciliación Q1 2025 (Copia)",
   "includeSources": true,
   "includeRules": true,
   "includeFeeSchedules": true
 }'

Respuesta

{
  "context": {
    "id": "019c96a0-2b20-7123-9a1b-2c3d4e5f6a7b",
    "name": "Conciliación Q1 2025 (Copia)",
    "type": "1:1",
    "status": "DRAFT"
  },
  "sourcesCloned": 3,
  "rulesCloned": 5,
  "fieldMapsCloned": 3,
  "feeSchedulesCloned": 2
}

API Reference: Clonar contexto

El contexto clonado inicia en estado DRAFT, para que pueda revisar y ajustar la configuración antes de activarlo.

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 Borrador, donde se configuran las fuentes y la configuración.
Una vez que todas las fuentes requeridas están en su lugar, el contexto se vuelve Activo y es elegible para ejecuciones de conciliación.
Un contexto activo puede ser temporalmente Pausado para detener la ejecución sin afectar la configuración o los datos históricos.
Cuando la conciliación para un período está completa, el contexto se Archiva, preservando todos los resultados y registros de auditoría para referencia futura.

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 conciliación

Configura las reglas que impulsan la conciliación.

Introduction

Primeros pasos

Configuración

Reconciliación diaria

Integraciones

Referencia

​¿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

​Creación básica de contexto

​Solicitud

​Campos del contexto

​Respuesta

​Ejecutando conciliación

​Ejecuciones manuales de conciliación

​Respuesta

​Modos de ejecución de conciliación

​Ver historial de ejecuciones de conciliación

​Respuesta

​Estados de ejecución de conciliación

​¿Qué es una fuente?

​Agregando fuentes a un contexto

​Crear una fuente bancaria

​Respuesta

​Crear una fuente de libro mayor

​Tipos de fuente

​Configuración de fuente

​Gestionando contextos

​Actualizar un contexto

​Pausar un contexto

​Eliminar un contexto

​Clonar un contexto

​Respuesta

​Ciclo de vida del contexto

​Mejores prácticas

​Próximos pasos

Mapeo de campos

Reglas de conciliación

¿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

Creación básica de contexto

Solicitud

Campos del contexto

Respuesta

Ejecutando conciliación

Ejecuciones manuales de conciliación

Respuesta

Modos de ejecución de conciliación

Ver historial de ejecuciones de conciliación

Respuesta

Estados de ejecución de conciliación

¿Qué es una fuente?

Agregando fuentes a un contexto

Crear una fuente bancaria

Respuesta

Crear una fuente de libro mayor

Tipos de fuente

Configuración de fuente

Gestionando contextos

Actualizar un contexto

Pausar un contexto

Eliminar un contexto

Clonar un contexto

Respuesta

Ciclo de vida del contexto

Mejores prácticas

Próximos pasos