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:

Una instancia de Matcher en ejecución
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 URL de tu 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"
 }'

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

Guarda los dos valores id de las fuentes.

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

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

Campos obligatorios

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

Campo	Tipo	Descripción
`transaction_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 pero recomendado: reference (referencia externa o descripción).

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

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 "file=@bank_transactions.csv" \
 -F "format=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 "file=@ledger_entries.csv" \
 -F "format=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"
 }'

Ambas respuestas incluyen un runId. Guárdalo para el paso 8. Revisa los resultados de la ejecución de prueba. 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"
 }'

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, no requiere ninguna acción
60-89	Requiere revisión manual
Menos de 60	No se crea ninguna coincidencia; se convierte en una excepción

Deshaz una coincidencia incorrecta

Usa el endpoint de deshacer coincidencia para rechazar un grupo de coincidencia PROPOSED y devolver sus transacciones al conjunto de transacciones no conciliadas. Para un grupo CONFIRMED, Matcher primero verifica que puede revertir los efectos residuales o de partida abierta de esa confirmación. Un deshacer exitoso revierte esos efectos de forma atómica, junto con la revocación del grupo y la devolución de sus transacciones:

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

Si la reversión del grupo confirmado elimina la última contribución activa detrás de una obligación, la partida abierta pasa al estado terminal WITHDRAWN: permanece como historial, pero no es neteable ni se traslada a otra ejecución. Si una entrada activa posterior aún actúa sobre el residual, o si una obligación activa más nueva entraría en conflicto al restaurar una partida terminal con la misma identidad, Matcher devuelve 409 Conflict antes de modificar el grupo, las transacciones o las partidas abiertas. Después de un deshacer exitoso, las transacciones vuelven al conjunto de no conciliadas para la siguiente ejecución.

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	SLA
`CRITICAL`	Monto >= 100,000 o antigüedad >= 120h	24 horas
`HIGH`	Monto >= 10,000 o antigüedad >= 72h	72 horas
`MEDIUM`	Monto >= 1,000 o antigüedad >= 24h	5 días
`LOW`	Todos los demás	7 días

Consulta las excepciones

cURL

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

Resuelve las excepciones forzando la coincidencia, creando ajustes o enviándolas a sistemas externos configurados, como JIRA, ServiceNow o un webhook HTTP.

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