Revisar coincidencias

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

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 de alta confianza (puntuación 90 o superior) de las reglas EXACT y TOLERANCE, más las coincidencias manuales, se auto-confirman de inmediato. Las coincidencias FUZZY y DATE_LAG siempre requieren revisión manual y nunca se auto-confirman.
Las coincidencias de menor confianza esperan revisión manual: un analista puede entonces confirmarlas o rechazarlas.
Las transacciones rechazadas vuelven al pool de no coincididas para otro intento de conciliación.

Las coincidencias FUZZY y DATE_LAG nunca se auto-confirman. La auto-confirmación con puntuación ≥ 90 aplica a las reglas EXACT y TOLERANCE, más las coincidencias manuales. Una coincidencia producida por una regla FUZZY o DATE_LAG siempre permanece en PROPOSED para revisión manual, sin importar su puntuación — incluso una coincidencia FUZZY con puntuación 90+. 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, en espera de confirmación	Revisar, confirmar o rechazar
`CONFIRMED`	La coincidencia ha sido aprobada (automática o manual)	Revocar 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 de alta confianza se confirman automáticamente sin revisión manual (reglas EXACT y TOLERANCE, más las coincidencias manuales; las coincidencias FUZZY y DATE_LAG siempre requieren revisión).
Requiere revisión	60-89	Las coincidencias de confianza media requieren revisión manual antes de la confirmación.
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.

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 superó su umbral de antigüedad mientras seguía abierta (sin resolver más allá del SLA configurado).

El ciclo de vida fluye OPEN → PARTIALLY_CLEARED → CLEARED, y cualquier partida aún abierta puede pasar a AGED una vez que supera el umbral de antigüedad.

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": "Variance due to bank processing fee",
   "description": "Bank wire fee adjustment",
   "matchGroupId": "019c96a0-0b74-768c-8d25-2bf065dca2f8"
 }'

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

amount

String

requerido

Monto del ajuste

currency

String

requerido

Código de moneda ISO 4217

direction

String

requerido

DEBIT o CREDIT

type

String

requerido

BANK_FEE, FX_DIFFERENCE, ROUNDING, WRITE_OFF o MISCELLANEOUS

reason

String

requerido

Motivo de negocio del ajuste

description

String

requerido

Descripción legible para humanos

matchGroupId

UUID

Grupo de coincidencia al que aplica el ajuste

transactionId

UUID

Transacción a la que aplica el ajuste

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

Revocar coincidencias confirmadas

A veces necesitas revertir una coincidencia porque fue aprobada incorrectamente. La operación unmatch rompe un grupo de coincidencia existente y devuelve sus transacciones 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).

Deshacer la coincidencia de un grupo crea un rastro de auditoría completo. Esta operación debe usarse con cuidado y solo cuando sea necesario.

Cuándo revocar

Escenarios comunes para revocar:

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 revocar

Cuando se deshace la coincidencia de un grupo:

El estado de la coincidencia cambia: Un grupo CONFIRMED pasa a REVOKED; un grupo aún en PROPOSED pasa a REJECTED
Transacciones devueltas: Todas las transacciones asociadas vuelven al estado UNMATCHED
Rastro de auditoría creado: Registro completo de quién deshizo la coincidencia y el motivo proporcionado
Webhook activado: Se emite un evento match_group.unmatched (solo cuando el grupo estaba previamente en CONFIRMED)
Re-conciliación posible: Las transacciones pueden volver a coincidirse en la siguiente ejecución

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. Para las reglas EXACT y TOLERANCE, más las coincidencias manuales, las puntuaciones de 90 o superior se auto-confirman. Las puntuaciones entre 60 y 89 requieren revisión manual. 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 siempre requieren revisión, sin importar la puntuación. Usa el ajuste de reglas (prioridad, valores de tolerancia) para influir en cuántas coincidencias caen en cada nivel.

Documenta tus decisiones

Siempre agrega notas al confirmar o rechazar coincidencias. Esto crea un rastro de auditoría y ayuda a los miembros del equipo a entender el razonamiento.

Usa las operaciones masivas con criterio

La confirmación masiva es eficiente, pero úsala solo después de revisar una muestra. Nunca confirmes masivamente sin entender lo que estás aprobando.

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.

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

Revocar coincidencias confirmadas

Cuándo revocar

Qué sucede después de revocar

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

​Revocar coincidencias confirmadas

​Cuándo revocar

​Qué sucede después de revocar

​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

Revocar coincidencias confirmadas

Cuándo revocar

Qué sucede después de revocar

Mejores prácticas

Próximos pasos