Inicio rápido de la API de Matcher

Esta guía está pensada para desarrolladores. Si buscas un resumen de negocio de lo que hace Matcher, consulta ¿Qué es Matcher?.

Esta guía te lleva desde la creación de tu primer contexto de conciliación hasta la revisión de las transacciones coincidentes.

Antes de empezar

Necesitas:

La dirección de la API de Matcher que te entrega Lerian
Un token JWT válido para la autenticación
Dos archivos de transacciones para conciliar (CSV, JSON o XML)

Todos los ejemplos usan cURL. Reemplaza $TOKEN con tu token JWT y https://api.matcher.example.com con la dirección de la API de Matcher.

Paso 1: Crea un contexto de conciliación

Un contexto define el alcance de tu conciliación: qué comparas y cómo.

Referencia de la API: Crear contexto

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",
   "type": "1:1",
   "interval": "daily"
 }'

El campo type define cómo Matcher empareja las transacciones:

Tipo	Descripción
`1:1`	Cada transacción coincide exactamente con una contraparte
`1:N`	Una transacción puede coincidir con varias contrapartes
`N:M`	Varias transacciones pueden coincidir en ambos lados

Guarda el id de la respuesta. Lo usarás en cada paso siguiente.

{
  "id": "019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f",
  "name": "Daily Bank Reconciliation",
  "type": "1:1",
  "interval": "daily",
  "status": "DRAFT",
  "createdAt": "2026-03-04T12:00:00Z",
  "updatedAt": "2026-03-04T12:00:00Z"
}

El contexto se inicia en estado DRAFT. Pasa a ACTIVE cuando estás listo para ejecutar la conciliación.

Paso 2: Agrega fuentes de datos

Para ejecutar una coincidencia, configura al menos dos fuentes: los sistemas cuyas transacciones quieres comparar.

Referencia de la API: Crear fuente

Crea una fuente bancaria

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": "RIGHT"
 }'

Crea una fuente de ledger

cURL

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

Guarda los dos valores id de las fuentes. Cada fuente necesita un side (LEFT o RIGHT): el contexto concilia sus fuentes LEFT contra sus fuentes RIGHT.

Tipos de fuente

Tipo	Caso de uso
`BANK`	Extractos bancarios
`LEDGER`	Ledger general / exportaciones de ERP
`GATEWAY`	Datos del procesador de pagos
`CUSTOM`	Cualquier otra fuente de datos
`FETCHER`	Datos extraídos mediante el motor de extracción integrado

Paso 3: Asigna los campos de la fuente

Es probable que los archivos de tu fuente usen nombres de columna distintos de los que espera Matcher. Los mapas de campos los traducen al esquema estándar de Matcher.

Referencia de la API: Crear mapa de campos

Asigna la fuente bancaria

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{bankSourceId}/field-maps" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mapping": {
     "external_id": "Transaction ID",
     "amount": "Amount",
     "currency": "Currency",
     "date": "Post Date",
     "description": "Description"
   }
 }'

Asigna la fuente de ledger

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{ledgerSourceId}/field-maps" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mapping": {
     "external_id": "entry_id",
     "amount": "debit_credit_amount",
     "currency": "currency_code",
     "date": "posting_date",
     "description": "memo"
   }
 }'

Campos obligatorios

Cada transacción debe tener estos campos después de la asignación:

Campo	Tipo	Descripción
`external_id`	String	Identificador único dentro de la fuente
`amount`	Decimal	Monto de la transacción
`currency`	String	Código de moneda ISO 4217 (por ejemplo, USD)
`date`	Date	Fecha de la transacción (YYYY-MM-DD)

Opcional: description, fee_amount, fee_currency y direction. Cada clave del mapeo es un campo de Matcher. Cada valor es el nombre de la columna en tu archivo, excepto para direction. Su valor es un objeto {column, debit, credit} para un archivo que marca cada fila como débito o crédito en una columna aparte. Una fila de débito se importa con un monto negativo, y una de crédito con uno positivo.

Paso 4: Crea reglas de coincidencia

Las reglas definen cómo Matcher compara las transacciones. Empieza con una regla exacta, que es la más precisa.

Referencia de la API: Crear regla de coincidencia

Crea una regla exacta

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "EXACT",
   "priority": 1,
   "config": {
     "matchAmount": true,
     "matchCurrency": true,
     "matchDate": true,
     "matchReference": true,
     "caseInsensitive": true,
     "datePrecision": "DAY"
   }
 }'

Agrega una regla de tolerancia como respaldo

Captura diferencias pequeñas, como comisiones bancarias o redondeos:

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "TOLERANCE",
   "priority": 20,
   "config": {
     "percentTolerance": 0.01,
     "absTolerance": 5.0,
     "dateWindowDays": 2,
     "matchCurrency": true,
     "matchReference": true,
     "caseInsensitive": true
   }
 }'

Matcher evalúa las reglas por prioridad (el número más bajo primero). La regla exacta se ejecuta primero. Solo las transacciones no conciliadas pasan a la regla de tolerancia.

Tipos de regla

Tipo	Cuándo usarla	Rango de prioridad
`EXACT`	Se recomienda que los valores coincidan exactamente	1-1000; único dentro del contexto
`TOLERANCE`	Diferencias pequeñas y esperadas	1-1000; único dentro del contexto
`DATE_LAG`	Retrasos de fecha entre sistemas; siempre se proponen para revisión	1-1000; único dentro del contexto
`FUZZY`	Referencias con puntuación de similitud; siempre se proponen para revisión	1-1000; único dentro del contexto

Paso 5: Activa el contexto

Mueve el contexto de DRAFT a ACTIVE:

Referencia de la API: Actualizar contexto

cURL

curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "status": "ACTIVE"
 }'

Si el contexto no está listo, Matcher rechaza la actualización con 409 Conflict y el código MTCH-0103. El array errors de la respuesta lista cada requisito faltante. El Progreso de la configuración lista los requisitos faltantes y la siguiente llamada que debes hacer.

Paso 6: Sube los archivos de transacciones

Sube un archivo por fuente. Matcher acepta los formatos CSV, JSON y XML mediante carga de formulario multipart.

Referencia de la API: Subir archivo de transacciones
Listar trabajos de ingesta

Sube las transacciones bancarias

cURL

curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{bankSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "format=csv" \
 -F "file=@bank_transactions.csv"

Sube las transacciones del ledger

cURL

curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{ledgerSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "format=csv" \
 -F "file=@ledger_entries.csv"

Cada carga crea un trabajo de ingesta. Revisa el estado del trabajo:

cURL

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

Espera a que ambos trabajos alcancen el estado COMPLETED antes de ejecutar la coincidencia.

Paso 7: Ejecuta la coincidencia

Empieza con una ejecución de prueba para previsualizar los resultados sin persistirlos:

Referencia de la API: Ejecutar coincidencia

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": "DRY_RUN"
 }'

La respuesta incluye un runId. Una ejecución de prueba no guarda grupos de coincidencia. Para revisar sus resultados, lee las estadísticas agregadas de la ejecución con Obtener ejecución de coincidencia. Cuando estés conforme, ejecuta con COMMIT para persistir las coincidencias:

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

Guarda el runId de la respuesta del COMMIT. Lo usas en el paso 8.

Paso 8: Revisa los resultados

Referencia de la API: Listar grupos de ejecución de coincidencia
Deshacer coincidencia de grupo

Consulta los grupos de coincidencia

cURL

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

Cada grupo de coincidencia contiene transacciones emparejadas y una puntuación de confianza (0-100):

Puntuación	Qué ocurre
90-100	Se confirma automáticamente para las coincidencias EXACT y TOLERANCE. Las coincidencias FUZZY y DATE_LAG necesitan revisión manual
60-89	Requiere revisión manual

Deshaz una coincidencia incorrecta

Usa el endpoint de deshacer coincidencia para rechazar un grupo de coincidencia PROPOSED o revocar uno CONFIRMED. Matcher devuelve las transacciones del grupo al conjunto de no conciliadas para la siguiente ejecución:

cURL

curl -X DELETE "https://api.matcher.example.com/v1/matching/groups/{matchGroupId}?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "reason": "Transactions belong to different records"
 }'

Paso 9: Gestiona las excepciones

Las excepciones son transacciones que Matcher no pudo hacer coincidir automáticamente. Matcher clasifica cada excepción por gravedad:

Referencia de la API: Listar excepciones

Gravedad	Criterio
`CRITICAL`	Monto >= 100,000 o antigüedad >= 120h
`HIGH`	Monto >= 10,000 o antigüedad >= 72h
`MEDIUM`	Monto >= 1,000 o antigüedad >= 24h
`LOW`	Todos los demás

Consulta las excepciones

cURL

curl -X GET "https://api.matcher.example.com/v1/exceptions" \
 -H "Authorization: Bearer $TOKEN"

Resuelve las excepciones directamente, forzando la coincidencia o creando asientos de ajuste.

Próximos pasos

Contextos y fuentes

Guía completa de la configuración de contextos y fuentes.

Reglas de coincidencia

Todos los tipos de regla y las opciones de configuración en detalle.

Puntuación de confianza

Cómo calcula Matcher las puntuaciones y qué significan.

Resolución de excepciones

Gestiona las transacciones no conciliadas.

​Antes de empezar

​Paso 1: Crea un contexto de conciliación

​Paso 2: Agrega fuentes de datos

​Crea una fuente bancaria

​Crea una fuente de ledger

​Tipos de fuente

​Paso 3: Asigna los campos de la fuente

​Asigna la fuente bancaria

​Asigna la fuente de ledger

​Campos obligatorios

​Paso 4: Crea reglas de coincidencia

​Crea una regla exacta

​Agrega una regla de tolerancia como respaldo

​Tipos de regla

​Paso 5: Activa el contexto

​Paso 6: Sube los archivos de transacciones

​Sube las transacciones bancarias

​Sube las transacciones del ledger

​Paso 7: Ejecuta la coincidencia

​Paso 8: Revisa los resultados

​Consulta los grupos de coincidencia

​Deshaz una coincidencia incorrecta

​Paso 9: Gestiona las excepciones

​Consulta las excepciones

​Próximos pasos

Contextos y fuentes

Reglas de coincidencia

Puntuación de confianza

Resolución de excepciones

Antes de empezar

Paso 1: Crea un contexto de conciliación

Paso 2: Agrega fuentes de datos

Crea una fuente bancaria

Crea una fuente de ledger

Tipos de fuente

Paso 3: Asigna los campos de la fuente

Asigna la fuente bancaria

Asigna la fuente de ledger

Campos obligatorios

Paso 4: Crea reglas de coincidencia

Crea una regla exacta

Agrega una regla de tolerancia como respaldo

Tipos de regla

Paso 5: Activa el contexto

Paso 6: Sube los archivos de transacciones

Sube las transacciones bancarias

Sube las transacciones del ledger

Paso 7: Ejecuta la coincidencia

Paso 8: Revisa los resultados

Consulta los grupos de coincidencia

Deshaz una coincidencia incorrecta

Paso 9: Gestiona las excepciones

Consulta las excepciones

Próximos pasos