Revisar coincidencias

Después de ejecutar un trabajo de conciliación, necesitas revisar los resultados. Esta guía explica cómo interpretar los resultados, entender las puntuaciones de confianza y rechazar grupos propuestos o revocar grupos confirmados.

Ciclo de vida del estado de la coincidencia

Las coincidencias avanzan a través de un ciclo de vida definido:

Cuando el motor de conciliación encuentra un par de transacciones que pertenecen juntas, crea una coincidencia en estado PROPOSED.
Las coincidencias elegibles creadas por el motor (puntuación 90 o superior) de las reglas EXACT y TOLERANCE se auto-confirman de inmediato. Las coincidencias manuales se crean con estado CONFIRMED. Las coincidencias FUZZY y DATE_LAG permanecen en PROPOSED y nunca se auto-confirman.
Las coincidencias que no se confirman automáticamente permanecen en PROPOSED. La API pública de grupos de coincidencias no expone una confirmación manual, pero puedes rechazar un grupo propuesto mediante la operación unmatch y un motivo obligatorio.
Rechazar un grupo PROPOSED devuelve sus transacciones al pool de no coincididas. Solo puedes revocar un grupo CONFIRMED cuando Matcher también puede revertir cada efecto residual/de partida abierta que aplicó esa confirmación; si tiene éxito, esos cambios y la devolución de las transacciones ocurren de forma atómica.

Las coincidencias FUZZY y DATE_LAG nunca se auto-confirman. La auto-confirmación con puntuación ≥ 90 aplica a coincidencias elegibles EXACT y TOLERANCE creadas por el motor. Una coincidencia manual se crea con estado CONFIRMED. Una coincidencia producida por una regla FUZZY o DATE_LAG permanece en PROPOSED, sin importar su puntuación — incluso una coincidencia FUZZY con puntuación 90+. Puedes rechazarla mediante la operación unmatch; no existe una operación pública de confirmación manual. Consulta Puntuación de confianza.

Ciclo de vida del estado de una coincidencia.

Definiciones de estado

Estado	Descripción	Siguientes acciones
`PROPOSED`	Coincidencia identificada por el sistema, pero no confirmada	Revisar o rechazar mediante la operación unmatch
`CONFIRMED`	La coincidencia se confirmó automáticamente o se creó como coincidencia manual	Revocar mediante la operación unmatch si es incorrecta
`REJECTED`	La coincidencia fue rechazada	Las transacciones vuelven al pool de no coincididas
`REVOKED`	Una coincidencia previamente confirmada fue revocada	Las transacciones vuelven al pool de no coincididas

Niveles de confianza

Matcher asigna una puntuación de confianza (0-100) a cada coincidencia propuesta. La puntuación determina cómo se maneja la coincidencia.

Niveles de confianza

Nivel	Rango de puntuación	Comportamiento
Auto-aprobado	90-100	Las coincidencias elegibles EXACT y TOLERANCE creadas por el motor se confirman automáticamente sin revisión manual. Las coincidencias manuales se crean `CONFIRMED`; las coincidencias FUZZY y DATE_LAG permanecen en `PROPOSED`.
Requiere revisión	60-89	Las coincidencias de confianza media permanecen en `PROPOSED`. Puedes revisarlas y rechazarlas, pero la API pública no expone una confirmación manual.
Sin coincidencia	Menor a 60	Los candidatos de baja confianza no se proponen como coincidencias y se convierten en excepciones.

Entender la puntuación

La puntuación de confianza se calcula a partir de componentes ponderados:

Componente	Peso	Qué mide
Coincidencia de monto	40%	Qué tan cerca están alineados los montos de las transacciones
Coincidencia de moneda	30%	Si las monedas son iguales
Tolerancia de fecha	20%	Qué tan cerca están las fechas de las transacciones
Coincidencia de referencia	10%	Si las referencias de las transacciones coinciden

Ejemplo de desglose de puntuación:

Match: BANK-001 ↔ LED-001

Amount: $1,000.00 vs $1,000.00 → 100% × 40% = 40 points
Currency: USD vs USD → 100% × 30% = 30 points
Date: 2024-01-15 vs 2024-01-15 → 100% × 20% = 20 points
Reference: PAY-001 vs PAY-001 → match → 10 points
 ─────────────────────────
Total Confidence: 100 points

Entender las variaciones

Cuando las coincidencias tienen diferencias, revisa los detalles de la variación:

Variación de monto

Causas comunes de variación de monto:

Comisiones bancarias
Diferencias de conversión de moneda
Diferencias de redondeo
Pagos parciales

Variación de fecha

Causas comunes de variación de fecha:

Tiempo de liquidación
Diferencias de zona horaria
Fecha de contabilización vs. fecha de la transacción
Procesamiento de fin de semana/feriado

Candidatos de coincidencia, partidas abiertas y ajustes

A medida que trabajas una cola de revisión, tres preguntas surgen una y otra vez: ¿por qué el motor propuso este emparejamiento?, ¿qué queda sin resolver después de una coincidencia parcial? y ¿cómo registro una pequeña diferencia para que ambos lados cuadren? Matcher responde cada una con una superficie dedicada — candidatos de coincidencia, partidas abiertas y ajustes.

Listar candidatos de coincidencia

Recupera las propuestas de candidatos clasificadas que el motor consideró para una transacción — el “porqué” detrás de una coincidencia propuesta, incluyendo las contribuciones por componente.

cURL

curl -X GET "https://api.matcher.example.com/v1/matching/candidates?contextId={contextId}&transactionId={transactionId}&limit=20" \
 -H "Authorization: Bearer $TOKEN"

GET /v1/matching/candidates acepta los parámetros de consulta contextId, transactionId y limit, y devuelve un CandidateProposalsResponse. El valor predeterminado de limit es 50 y acepta valores de 1 a 200. El selector de candidatos examina como máximo 5000 transacciones no coincidentes del lado opuesto y devuelve solo candidatos 1:1. Aplica el puntuador compartido a los datos sin procesar, sin la normalización de comisiones en tiempo de ejecución ni la coincidencia por banda de variación de FX que usa una ejecución de conciliación.

Listar partidas abiertas

Las partidas abiertas son saldos residuales que quedan cuando una transacción solo se compensa parcialmente. Rastréalas para sacar a la luz montos que aún necesitan liquidarse o que han superado su umbral de antigüedad.

cURL

curl -X GET "https://api.matcher.example.com/v1/matching/contexts/{contextId}/open-items?status=OPEN&limit=50" \
 -H "Authorization: Bearer $TOKEN"

GET /v1/matching/contexts/{contextId}/open-items admite un filtro status, además de paginación limit/cursor.

Estados de partida abierta

Estado	Cuándo ocurre
`OPEN`	Residual reciente — la partida tiene un saldo restante y ningún tramo se ha compensado contra ella todavía.
`PARTIALLY_CLEARED`	Al menos un tramo se ha compensado contra el saldo, pero aún queda un residual.
`CLEARED`	El residual se ha compensado por completo dentro de la tolerancia.
`AGED`	La partida permaneció abierta más allá de su umbral de antigüedad, medido desde la fecha de negocio de la obligación o desde la primera detección para datos heredados.
`WITHDRAWN`	Un unmatch de un grupo confirmado eliminó la última contribución activa detrás de la obligación. La partida permanece como historial, pero es terminal y no se puede compensar ni llevar hacia adelante.

El ciclo de vida normal fluye OPEN → PARTIALLY_CLEARED → CLEARED, y cualquier partida aún abierta puede pasar a AGED una vez que supera el umbral de antigüedad. Un unmatch exitoso de un grupo confirmado revierte los efectos residuales de ese grupo. Si no queda ninguna contribución activa detrás de la obligación, la partida termina en WITHDRAWN: fue retirada, no compensada ni envejecida.

Crear un ajuste

Registra un ajuste contable para dar cuenta de una variación (comisión bancaria, diferencia de FX, redondeo, cancelación (write-off), etc.) contra un grupo de coincidencia o una transacción.

cURL

curl -X POST "https://api.matcher.example.com/v1/matching/adjustments?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "amount": "10.50",
   "currency": "BRL",
   "direction": "DEBIT",
   "type": "BANK_FEE",
   "reason": "Diferencia por comisión de procesamiento bancario",
   "description": "Ajuste de comisión por transferencia bancaria",
   "matchGroupId": "019c96a0-0b74-768c-8d25-2bf065dca2f8"
 }'

POST /v1/matching/adjustments requiere el parámetro de consulta contextId. Campos del cuerpo:

String

requerido

Monto del ajuste

String

requerido

Cadena de moneda no vacía. Matcher no valida la pertenencia a ISO 4217 para este ajuste.

String

requerido

DEBIT o CREDIT

String

requerido

BANK_FEE, FX_DIFFERENCE, ROUNDING, WRITE_OFF o MISCELLANEOUS

String

requerido

Motivo de negocio del ajuste

String

requerido

Descripción legible para humanos

UUID

Grupo de coincidencia al que aplica el ajuste

UUID

Transacción a la que aplica el ajuste

Se requiere al menos uno de los campos matchGroupId o transactionId.

Referencia de API: Listar candidatos de coincidencia | Listar partidas abiertas | Crear ajuste

Rechazar o revocar grupos de coincidencias

Usa la operación unmatch para rechazar un grupo PROPOSED o revocar uno CONFIRMED. Después de una operación exitosa, Matcher devuelve las transacciones del grupo al estado UNMATCHED para que puedan volver a coincidirse. Usa DELETE /v1/matching/groups/{matchGroupId} con el parámetro de consulta obligatorio contextId y un reason en el cuerpo de la solicitud (operationId unmatch):

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": "incorrect match - amounts do not match"
 }'

Un unmatch exitoso devuelve 204 No Content. El campo reason es obligatorio (no vacío). Para un grupo CONFIRMED, Matcher verifica la reversión residual/de partidas abiertas antes de cambiar el grupo o sus transacciones; una operación exitosa agrega de forma atómica los asientos compensatorios del ledger, revoca el grupo y devuelve sus transacciones a UNMATCHED.

La operación unmatch requiere un motivo no vacío. Para un grupo confirmado, o bien revierte los efectos residuales/de partidas abiertas junto con el grupo y sus transacciones, o devuelve 409 Conflict antes de cambiar nada. Una entrada posterior aún activa sobre el residual bloquea la reversión anterior; una obligación más reciente y activa con la misma identidad también la bloquea cuando restaurar una partida terminal causaría un conflicto.

Cuándo rechazar o revocar

Escenarios comunes para rechazar o revocar un grupo:

Coincidencia incorrecta confirmada: La coincidencia fue aprobada pero las transacciones en realidad pertenecen a registros diferentes
Nueva información: Datos adicionales muestran que la coincidencia está mal
Corrección de origen: El sistema de origen emitió una corrección o reversión
Transacción duplicada: Una de las transacciones era un duplicado que debe eliminarse

Qué sucede después de unmatch

Cuando se deshace la coincidencia de un grupo:

Primero se verifican los residuales confirmados: Matcher verifica que cada efecto residual/de partida abierta de un grupo CONFIRMED pueda revertirse. Si una entrada posterior o una obligación más reciente en conflicto lo bloquea, la operación devuelve 409 Conflict y deja sin cambios el grupo, las transacciones y las partidas abiertas.
El estado de la coincidencia cambia: Un grupo CONFIRMED pasa a REVOKED; un grupo aún en PROPOSED pasa a REJECTED.
Transacciones devueltas: Si tiene éxito, todas las transacciones asociadas vuelven al estado UNMATCHED.
Se revierten los efectos de partidas abiertas: En un unmatch de un grupo confirmado, los asientos compensatorios del ledger retiran los efectos residuales del grupo en la misma transacción. Si no queda una contribución activa detrás de una obligación, pasa al estado terminal WITHDRAWN y no se lleva hacia adelante.
Motivo registrado: El grupo almacena el motivo de rechazo o revocación proporcionado.
Evento de streaming emitido: Se emite un evento match_group.unmatched solo cuando el grupo estaba previamente en CONFIRMED.
Reconciliación posible de nuevo: Las transacciones pueden volver a coincidirse en la siguiente ejecución después de un unmatch exitoso.

Mejores prácticas

Comienza con las coincidencias de menor confianza

Revisa primero las coincidencias con las puntuaciones de confianza más bajas. Estas son las más propensas a ser incorrectas y necesitan más atención.

Entiende los umbrales de confianza fijos

Los umbrales de confianza son fijos en el sistema. Las coincidencias elegibles EXACT y TOLERANCE creadas por el motor con puntuaciones de 90 o superior se auto-confirman. Las coincidencias manuales se crean CONFIRMED. Las puntuaciones entre 60 y 89 permanecen en PROPOSED, y las puntuaciones menores a 60 se convierten en excepciones. Estos valores no son configurables por contexto. Las coincidencias FUZZY y DATE_LAG son la excepción: nunca se auto-confirman y permanecen en PROPOSED, sin importar la puntuación. Usa el ajuste de reglas (prioridad, valores de tolerancia) para influir en cuántas coincidencias caen en cada nivel.

Proporciona un motivo claro

Proporciona un motivo específico al rechazar un grupo propuesto o revocar uno confirmado. La operación unmatch lo exige y lo almacena con el grupo.

Rechaza solo después de comprobar los datos de origen

Revisa el grupo y sus transacciones de origen antes de usar la operación unmatch. Matcher expone esta operación por grupo; no expone una confirmación masiva.

Revisa cuidadosamente las coincidencias de alto valor

Independientemente de la puntuación de confianza, presta atención extra a las coincidencias de alto valor. El impacto de una coincidencia incorrecta es proporcional al monto.

Resumen

Guías

Matcher UI

Servidor MCP

Operaciones

Revisar coincidencias

Ciclo de vida del estado de la coincidencia

Definiciones de estado

Niveles de confianza

Niveles de confianza

Entender la puntuación

Entender las variaciones

Variación de monto

Variación de fecha

Candidatos de coincidencia, partidas abiertas y ajustes

Listar candidatos de coincidencia

Listar partidas abiertas

Estados de partida abierta

Crear un ajuste

Rechazar o revocar grupos de coincidencias

Cuándo rechazar o revocar

Qué sucede después de unmatch

Mejores prácticas

Próximos pasos

Resolver excepciones

Puntuación de confianza

​Ciclo de vida del estado de la coincidencia

​Definiciones de estado

​Niveles de confianza

​Niveles de confianza

​Entender la puntuación

​Entender las variaciones

​Variación de monto

​Variación de fecha

​Candidatos de coincidencia, partidas abiertas y ajustes

​Listar candidatos de coincidencia

​Listar partidas abiertas

​Estados de partida abierta

​Crear un ajuste

​Rechazar o revocar grupos de coincidencias

​Cuándo rechazar o revocar

​Qué sucede después de unmatch

​Mejores prácticas

​Próximos pasos

Resolver excepciones

Puntuación de confianza

Ciclo de vida del estado de la coincidencia

Definiciones de estado

Niveles de confianza

Niveles de confianza

Entender la puntuación

Entender las variaciones

Variación de monto

Variación de fecha

Candidatos de coincidencia, partidas abiertas y ajustes

Listar candidatos de coincidencia

Listar partidas abiertas

Estados de partida abierta

Crear un ajuste

Rechazar o revocar grupos de coincidencias

Cuándo rechazar o revocar

Qué sucede después de unmatch

Mejores prácticas

Próximos pasos