Inicio rápido de la API de Matcher

Esta guía está dirigida a desarrolladores. Si buscas una visión general a nivel de negocio de lo que hace Matcher y cómo ayuda a tu equipo, consulta ¿Qué es Matcher?.

Pon Matcher en funcionamiento en minutos. Esta guía recorre el camino completo, desde la creación del primer contexto de conciliación hasta la revisión de transacciones conciliadas.

Antes de comenzar

Necesitas:

Una instancia de Matcher en ejecución
Un token JWT válido para 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 URL de tu Matcher.

Paso 1: Crear un contexto de conciliación

Un contexto define el alcance de tu conciliación: qué estás comparando y cómo.

Referencia de 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 se parean las transacciones:

Tipo	Descripción
`1:1`	Cada transacción coincide con exactamente una contraparte
`1:N`	Una transacción puede coincidir con múltiples contrapartes
`N:M`	Múltiples transacciones pueden coincidir entre ambos lados

Guarda el id de la respuesta. Lo usarás en todos los pasos siguientes.

{
  "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 inicia con estado DRAFT. Cambia a ACTIVE cuando esté listo para ejecutar la conciliación.

Paso 2: Agregar fuentes de datos

Todo contexto necesita al menos dos fuentes: los sistemas cuyas transacciones deseas comparar.

Referencia de API: Crear fuente

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

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

Guarda los valores de id de ambas fuentes.

Tipos de fuente

Tipo	Caso de uso
`BANK`	Extractos bancarios
`LEDGER`	Libro mayor / exportaciones de ERP
`GATEWAY`	Datos de procesadores de pago
`CUSTOM`	Cualquier otra fuente de datos

Paso 3: Mapear campos de las fuentes

Tus archivos de origen probablemente usan nombres de columna diferentes a los que Matcher espera. Los mapas de campos los traducen al schema estándar de Matcher.

Referencia de API: Crear mapa de campos

Mapear 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": {
     "Transaction ID": "transaction_id",
     "Amount": "amount",
     "Currency": "currency",
     "Post Date": "date",
     "Description": "reference"
   }
 }'

Mapear 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": {
     "entry_id": "transaction_id",
     "debit_credit_amount": "amount",
     "currency_code": "currency",
     "posting_date": "date",
     "memo": "reference"
   }
 }'

Campos obligatorios

Toda transacción debe tener estos campos después del mapeo:

Campo	Tipo	Descripción
`transaction_id`	String	Identificador único dentro de la fuente
`amount`	Decimal	Monto de la transacción
`currency`	String	Código ISO 4217 (ej.: USD, BRL)
`date`	Date	Fecha de la transacción (YYYY-MM-DD)

Opcional pero recomendado: reference (referencia externa o descripción).

Paso 4: Crear reglas de match

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

Referencia de API: Crear regla de match

Crear regla exact

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

Agregar regla tolerance como fallback

Captura pequeñas diferencias como comisiones bancarias o redondeo:

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 reglas por prioridad (número menor primero). La regla exact se ejecuta primero. Solo las transacciones sin match pasan a la regla tolerance.

Tipos de regla

Tipo	Cuándo usar	Rango de prioridad
`EXACT`	Los valores deben coincidir exactamente	1-10
`TOLERANCE`	Pequeñas diferencias esperadas	11-50
`DATE_LAG`	Retrasos de fecha entre sistemas	51-100

Paso 5: Activar el contexto

Mueve el contexto de DRAFT a ACTIVE:

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

Paso 6: Subir archivos de transacciones

Sube un archivo por fuente. Matcher acepta formatos CSV, JSON y XML mediante upload multipart.

Referencia de API: Subir archivo de transacciones
Listar jobs de ingestión

Subir transacciones bancarias

cURL

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

Subir transacciones del ledger

cURL

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

Cada upload crea un job de ingestión. Verifica el estado del job:

cURL

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

Espera a que ambos jobs alcancen el estado COMPLETED antes de ejecutar el matching.

Paso 7: Ejecutar el matching

Comienza con un dry run para previsualizar resultados sin persistir:

Referencia de API: Ejecutar match

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

Ambas respuestas incluyen un runId. Guárdalo para el Paso 8. Revisa los resultados del dry run. Cuando estés satisfecho, ejecuta con COMMIT para persistir los matches:

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

Paso 8: Revisar resultados

Referencia de API: Listar grupos de match
Deshacer match

Ver grupos de match

cURL

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

Cada grupo de match contiene transacciones pareadas y un puntaje de confianza (0-100):

Puntaje	Qué sucede
90-100	Auto-confirmado, ninguna acción necesaria
60-89	Necesita revisión manual
Menor a 60	Ningún match creado, se convierte en excepción

Deshacer un match incorrecto

Usa el endpoint de unmatch para rechazar un grupo de match y devolver las transacciones al pool de no conciliadas:

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": "Las transacciones pertenecen a registros diferentes"
 }'

Las transacciones rechazadas regresan al pool de no conciliadas para la próxima ejecución.

Paso 9: Manejar excepciones

Las excepciones son transacciones que no pudieron ser conciliadas automáticamente. Matcher clasifica cada excepción por severidad:

Referencia de API: Listar excepciones

Severidad	Criterio	SLA
`CRITICAL`	Monto >= 100.000 o edad >= 120h	24 horas
`HIGH`	Monto >= 10.000 o edad >= 72h	72 horas
`MEDIUM`	Monto >= 1.000 o edad >= 24h	5 días
`LOW`	Todas las demás	7 días

Listar excepciones

cURL

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

Resuelve excepciones forzando un match, creando ajustes o despachando a sistemas externos como JIRA.

Próximos pasos

Contextos y fuentes

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

Reglas de match

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

Puntuación de confianza

Cómo se calculan los puntajes y qué significan.

Resolver excepciones

Maneja transacciones no conciliadas.

Listar contextos de conciliación

⌘I

​Antes de comenzar

​Paso 1: Crear un contexto de conciliación

​Paso 2: Agregar fuentes de datos

​Crear fuente bancaria

​Crear fuente de ledger

​Tipos de fuente

​Paso 3: Mapear campos de las fuentes

​Mapear la fuente bancaria

​Mapear la fuente de ledger

​Campos obligatorios

​Paso 4: Crear reglas de match

​Crear regla exact

​Agregar regla tolerance como fallback

​Tipos de regla

​Paso 5: Activar el contexto

​Paso 6: Subir archivos de transacciones

​Subir transacciones bancarias

​Subir transacciones del ledger

​Paso 7: Ejecutar el matching

​Paso 8: Revisar resultados

​Ver grupos de match

​Deshacer un match incorrecto

​Paso 9: Manejar excepciones

​Listar excepciones

​Próximos pasos

Contextos y fuentes

Reglas de match

Puntuación de confianza

Resolver excepciones

Antes de comenzar

Paso 1: Crear un contexto de conciliación

Paso 2: Agregar fuentes de datos

Crear fuente bancaria

Crear fuente de ledger

Tipos de fuente

Paso 3: Mapear campos de las fuentes

Mapear la fuente bancaria

Mapear la fuente de ledger

Campos obligatorios

Paso 4: Crear reglas de match

Crear regla exact

Agregar regla tolerance como fallback

Tipos de regla

Paso 5: Activar el contexto

Paso 6: Subir archivos de transacciones

Subir transacciones bancarias

Subir transacciones del ledger

Paso 7: Ejecutar el matching

Paso 8: Revisar resultados

Ver grupos de match

Deshacer un match incorrecto

Paso 9: Manejar excepciones

Listar excepciones

Próximos pasos