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/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Conciliación bancaria diaria",
   "description": "Cuenta Chase Bank 1234 vs Libro mayor GL 1000",
   "type": "ONE_TO_ONE",
   "tenant_id": "tenant_001",
   "settings": {
     "date_tolerance_days": 3,
     "auto_confirm_threshold": 90,
     "review_threshold": 60
   }
 }'

Respuesta

{
  "id": "{contextId}",
  "name": "Conciliación bancaria diaria",
  "description": "Cuenta Chase Bank 1234 vs Libro mayor GL 1000",
  "type": "ONE_TO_ONE",
  "tenant_id": "tenant_001",
  "status": "ACTIVE",
  "settings": {
    "date_tolerance_days": 3,
    "auto_confirm_threshold": 90,
    "review_threshold": 60
  },
  "sources": [],
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}

API Reference: Crear contexto

Configuraciones del contexto

Configuración	Tipo	Por defecto	Descripción
`date_tolerance_days`	Integer	3	Diferencia máxima de fechas permitida
`auto_confirm_threshold`	Integer	90	Puntaje de confianza requerido para auto-confirmación
`review_threshold`	Integer	60	Puntaje mínimo para proponer una conciliación
`allow_partial_match`	Boolean	false	Permitir conciliación parcial de montos
`require_currency_match`	Boolean	true	Exigir consistencia de moneda
`enable_many_to_many`	Boolean	false	Habilitar conciliación N:M

Programación automática de conciliaciones

Matcher puede ejecutar trabajos de conciliación automáticamente en intervalos programados. Una vez configurado, el sistema procesará todas las transacciones disponibles de tus fuentes en la frecuencia definida.

Configuración de programación

Configura la programación automática al crear o actualizar un contexto:

{
  "schedule": {
    "enabled": true,
    "frequency": "daily",
    "time": "06:00",
    "timezone": "UTC",
    "on_weekends": false,
    "retry_on_failure": true,
    "max_retries": 3
  }
}

Frecuencias de programación

Frecuencia	Descripción	Caso de uso típico
`hourly`	Cada hora en el minuto :00	Conciliación de pagos en tiempo real
`daily`	Una vez al día a la hora especificada	Conciliación de extractos bancarios
`weekly`	Una vez por semana en el día especificado	Informes semanales de tesorería
`monthly`	Primer día del mes a la hora especificada	Conciliación de cierre de mes
`custom`	Expresión cron	Necesidades de programación complejas

Programaciones personalizadas

Para programación avanzada, usa expresiones cron:

{
  "schedule": {
    "enabled": true,
    "frequency": "custom",
    "cron": "0 6,18 * * 1-5",
    "timezone": "America/New_York"
  }
}

Patrones cron comunes:

0 6 * * * - Diariamente a las 6:00 AM
0 6,18 * * 1-5 - Dos veces al día (6 AM, 6 PM) en días laborables
0 0 1 * * - Mensualmente el día 1 a medianoche
0 */4 * * * - Cada 4 horas

Comportamiento de la ejecución de conciliación

Cuando se ejecuta una conciliación programada:

Verificación de ingesta: Verifica que todas las fuentes tengan datos recientes
Recuperación de transacciones: Obtiene transacciones no conciliadas de todas las fuentes
Aplicación de reglas: Aplica las reglas de conciliación en orden de prioridad
Puntuación de confianza: Calcula la confianza para cada conciliación propuesta
Auto-confirmación: Confirma conciliaciones por encima del umbral de auto-confirmación
Creación de excepciones: Crea excepciones para elementos no conciliados
Notificación: Envía alertas según la configuración de notificaciones

Ver historial de ejecuciones de conciliación

cURL

curl -X GET "https://api.matcher.example.com/v1/contexts/{contextId}/match-runs" \
 -H "Authorization: Bearer $TOKEN" \
 -G \
 -d "date_from=2024-01-01" \
 -d "date_to=2024-01-31"

API Reference: Listar ejecuciones de conciliación

Response

{
  "match_runs": [
    {
      "id": "run_001",
      "context_id": "{contextId}",
      "status": "COMPLETED",
      "trigger": "SCHEDULED",
      "started_at": "2024-01-20T06:00:00Z",
      "completed_at": "2024-01-20T06:05:23Z",
      "duration_seconds": 323,
      "statistics": {
        "transactions_processed": 1250,
        "matches_found": 1180,
        "matches_confirmed": 1120,
        "matches_pending_review": 60,
        "exceptions_created": 70
      }
    },
    {
      "id": "run_002",
      "context_id": "{contextId}",
      "status": "COMPLETED",
      "trigger": "MANUAL",
      "started_at": "2024-01-19T06:00:00Z",
      "completed_at": "2024-01-19T06:04:51Z",
      "duration_seconds": 291,
      "statistics": {
        "transactions_processed": 1198,
        "matches_found": 1145,
        "matches_confirmed": 1090,
        "matches_pending_review": 55,
        "exceptions_created": 53
      }
    }
  ],
  "pagination": {
    "total": 31,
    "page": 1,
    "per_page": 20
  }
}

Ejecuciones manuales de conciliación

También puedes activar la conciliación manualmente:

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/match-runs" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "dry_run": false,
   "date_range": {
     "from": "2024-01-15",
     "to": "2024-01-20"
   }
 }'

API Reference: Ejecutar conciliación

Establece dry_run: true para previsualizar resultados sin confirmar conciliaciones.

Configuración avanzada de contexto

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Conciliación de pagos multi-moneda",
   "description": "Transacciones de pasarela de pago en múltiples monedas",
   "type": "ONE_TO_MANY",
   "tenant_id": "tenant_001",
   "settings": {
     "date_tolerance_days": 5,
     "auto_confirm_threshold": 95,
     "review_threshold": 70,
     "allow_partial_match": true,
     "require_currency_match": false,
     "enable_many_to_many": false,
     "amount_tolerance": {
       "type": "percentage",
       "value": 1.0
     },
     "fx_settings": {
       "enabled": true,
       "rate_source": "daily_close",
       "tolerance_percent": 2.0
     }
   },
   "schedule": {
     "frequency": "daily",
     "time": "06:00",
     "timezone": "UTC"
   },
   "notifications": {
     "on_complete": [
       "finanzas@empresa.com"
     ],
     "on_exceptions": [
       "equipo-conciliacion@empresa.com"
     ]
   }
 }'

¿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

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 - Cuenta 1234",
   "type": "BANK",
   "description": "Feed diario de extracto bancario de Chase",
   "direction": "EXTERNAL",
   "settings": {
     "currency": "USD",
     "timezone": "America/New_York"
   }
 }'

API Reference: Crear fuente

Agregar una fuente interna

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Libro mayor - GL 1000",
   "type": "LEDGER",
   "description": "Cuenta de efectivo del libro mayor del ERP",
   "direction": "INTERNAL",
   "settings": {
     "currency": "USD",
     "timezone": "America/New_York"
   }
 }'

Tipos de fuente

Tipo	Descripción	Dirección típica
`BANK`	Extractos bancarios	Externa
`LEDGER`	Cuentas del libro mayor	Interna
`PAYMENT_GATEWAY`	Transacciones de procesadores de pago	Externa
`ERP`	Sistemas empresariales	Interna
`CUSTOM`	Integraciones personalizadas	Varía

Dirección de la fuente

La dirección de la fuente indica la propiedad y el origen de los datos.

Dirección	Descripción	Ejemplos
`INTERNAL`	Origina de sistemas internos	Libro mayor, ERP
`EXTERNAL`	Proporcionada por terceros	Bancos, pasarelas

La dirección se usa para:

Clasificación y enrutamiento de excepciones
Atribución de auditoría
Análisis de propiedad de variaciones

Opciones de configuración de fuente

Configuraciones básicas

{
  "settings": {
    "currency": "USD",
    "timezone": "America/New_York",
    "date_format": "YYYY-MM-DD",
    "amount_sign_convention": "NATURAL"
  }
}

Convenciones de signo de monto

Convención	Descripción	Ejemplo
`NATURAL`	Positivo = crédito, negativo = débito	+100 / -50
`ABSOLUTE_WITH_TYPE`	Siempre positivo, dirección definida por separado	100 crédito / 50 débito
`INVERTED`	Positivo = débito, negativo = crédito	Signos invertidos

Indicadores regulatorios

{
  "settings": {
    "regulatory": true,
    "regulatory_type": "SOX",
    "retention_years": 7
  }
}

Cuando está habilitado, las fuentes regulatorias:

Elevan excepciones a severidad crítica
Requieren justificación para resoluciones
Aplican retención extendida de auditoría

Gestionando contextos

Actualizar configuraciones del contexto

cURL

curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "settings": {
     "auto_confirm_threshold": 85,
     "date_tolerance_days": 5
   }
 }'

API Reference: Actualizar contexto

Desactivar un contexto

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

Desactivar un contexto:

Detiene las ejecuciones programadas
Preserva los datos históricos
Permite reactivación futura

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 Cierra, 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

​Respuesta

​Configuraciones del contexto

​Programación automática de conciliaciones

​Configuración de programación

​Frecuencias de programación

​Programaciones personalizadas

​Comportamiento de la ejecución de conciliación

​Ver historial de ejecuciones de conciliación

​Ejecuciones manuales de conciliación

​Configuración avanzada de contexto

​¿Qué es una fuente?

​Agregando fuentes a un contexto

​Crear una fuente

​Agregar una fuente interna

​Tipos de fuente

​Dirección de la fuente

​Opciones de configuración de fuente

​Configuraciones básicas

​Convenciones de signo de monto

​Indicadores regulatorios

​Gestionando contextos

​Actualizar configuraciones del contexto

​Desactivar un contexto

​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

Respuesta

Configuraciones del contexto

Programación automática de conciliaciones

Configuración de programación

Frecuencias de programación

Programaciones personalizadas

Comportamiento de la ejecución de conciliación

Ver historial de ejecuciones de conciliación

Ejecuciones manuales de conciliación

Configuración avanzada de contexto

¿Qué es una fuente?

Agregando fuentes a un contexto

Crear una fuente

Agregar una fuente interna

Tipos de fuente

Dirección de la fuente

Opciones de configuración de fuente

Configuraciones básicas

Convenciones de signo de monto

Indicadores regulatorios

Gestionando contextos

Actualizar configuraciones del contexto

Desactivar un contexto

Ciclo de vida del contexto

Mejores prácticas

Próximos pasos