Revisar coincidencias

Revisa las coincidencias después de una ejecución. Entiende la puntuación de confianza de 0–100, sus cuatro componentes ponderados, las causas de variación y cómo rechazar o revocar un grupo de coincidencias.

Después de ejecutar un job de coincidencia, revisa los resultados. Esta guía explica cómo interpretar los resultados de coincidencia, entender las puntuaciones de confianza y rechazar grupos de coincidencias propuestos o revocar los confirmados.

​

Ciclo de vida del estado de la coincidencia

---

Las coincidencias avanzan por un ciclo de vida definido:

• Cuando el motor de coincidencias encuentra un par de transacciones que van juntas, crea una coincidencia en estado PROPOSED.
• Las coincidencias creadas por el motor con puntuación de 90 o más a partir de reglas EXACT y TOLERANCE se confirman automáticamente de inmediato. Las coincidencias manuales, creadas con POST /v1/matching/manual, empiezan en estado CONFIRMED. Las coincidencias FUZZY y DATE_LAG siguen en PROPOSED y nunca se confirman automáticamente.
• Las coincidencias que no se confirman automáticamente siguen en PROPOSED. La API pública de grupos de coincidencias no expone la confirmación manual, pero puedes rechazar un grupo propuesto con la operación de deshacer coincidencia y un motivo obligatorio.
• Rechazar un grupo PROPOSED o revocar un grupo CONFIRMED devuelve sus transacciones al conjunto de no conciliados. El cambio de estado y la devolución de las transacciones ocurren de forma atómica.
• Cuando Matcher cambia el estado de las transacciones de una coincidencia, cambia todas o ninguna. Una coincidencia manual que pierde una competencia por una transacción recibe 409, y Matcher no aplica nada.

Las coincidencias FUZZY y DATE_LAG nunca se confirman automáticamente. La confirmación automática con puntuación ≥ 90 aplica a las coincidencias EXACT y TOLERANCE creadas por el motor. Una coincidencia manual empieza en estado CONFIRMED. Una coincidencia producida por una regla FUZZY o DATE_LAG se queda en PROPOSED, sin importar su puntuación, incluso cuando obtiene 90+. Puedes rechazarla mediante la operación de deshacer coincidencia. 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	Acciones siguientes
PROPOSED	Coincidencia identificada por el sistema pero no confirmada	Revisar o rechazar mediante la operación de deshacer coincidencia
CONFIRMED	La coincidencia se confirmó automáticamente o se creó como coincidencia manual	Revocar mediante la operación de deshacer coincidencia si es incorrecta
REJECTED	La coincidencia fue rechazada	Las transacciones vuelven al conjunto de no conciliados
REVOKED	Una coincidencia confirmada antes fue revocada	Las transacciones vuelven al conjunto de no conciliados

​

Franjas de confianza

---

Matcher asigna una puntuación de confianza (0-100) a cada coincidencia propuesta. La puntuación determina qué le ocurre a la coincidencia.

​

Niveles de confianza

Franja	Rango de puntuación	Comportamiento
Elegible para confirmación automática	90-100	Las coincidencias EXACT y TOLERANCE creadas por el motor se confirman automáticamente sin revisión manual. Las coincidencias manuales se crean como CONFIRMED. Las coincidencias FUZZY y DATE_LAG siguen en PROPOSED.
Necesita revisión	60-89	Las coincidencias de confianza media siguen en PROPOSED. Puedes revisarlas y rechazarlas, pero la API pública no expone la confirmación manual.

​

Entender la puntuación

Matcher calcula la puntuación de confianza a partir de componentes ponderados:

Componente	Peso	Qué mide
Coincidencia de monto	40%	Qué tan cerca están los montos de las transacciones
Coincidencia de moneda	30%	Si las monedas son iguales
Tolerancia de fecha	20%	Qué tan cercanas son 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 la variación de monto:

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

​

Variación de fecha

Causas comunes de la variación de fecha:

• Tiempos de liquidación
• Diferencias de zona horaria
• Fecha de contabilización frente a fecha de transacción
• Procesamiento en fines de semana/feriados

​

Candidatos de coincidencia, partidas abiertas y ajustes

---

Matcher te da tres superficies para trabajar una cola de revisión: candidatos de coincidencia, partidas abiertas y ajustes.

​

Listar candidatos de coincidencia

Obtén los candidatos de contrapartida clasificados de una transacción, de la mayor puntuación a la menor. Cada candidato trae su puntuación de confianza, la regla que produjo la puntuación y las diferencias de monto y de fecha. Su objeto why muestra qué campos coinciden.

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 limit es 50 de forma predeterminada y acepta valores de 1 a 200.

El selector de candidatos escanea como máximo 5,000 transacciones no conciliadas en el contexto y devuelve solo candidatos 1:1 del lado opuesto. Aplica el puntuador compartido a los datos crudos de la transacción, sin la normalización de comisiones en tiempo de ejecución ni la coincidencia por bandas de variación de FX que usa una ejecución de coincidencia.

​

Listar partidas abiertas

Las partidas abiertas son saldos residuales que quedan cuando una transacción se netea solo en parte. Haz seguimiento de ellas para mostrar los montos que aún necesitan compensación o que superaron 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 con limit/cursor.

​

Estados de la partida abierta

Estado	Cuándo ocurre
OPEN	Residual nuevo. La partida tiene un saldo remanente y ningún tramo ha neteado contra ella todavía.
PARTIALLY_CLEARED	Al menos un tramo ha neteado contra el saldo, pero aún queda un residual.
CLEARED	El residual se neteó por completo dentro de la tolerancia.
AGED	La partida siguió abierta más allá de su umbral de antigüedad, medido desde la fecha hábil de la obligación o desde el tiempo de primera vista heredado.
WITHDRAWN	Deshacer una coincidencia retiró la coincidencia confirmada que creó la obligación.

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. WITHDRAWN es terminal.

​

Crear un ajuste

Registra un ajuste contable para contabilizar una variación (comisión bancaria, diferencia de FX, redondeo, baja contable, etc.) contra un grupo de coincidencias 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 de tres caracteres.

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 por humanos

matchGroupId · UUID

Grupo de coincidencias al que aplica el ajuste

transactionId · UUID

Transacción a la que aplica el ajuste

Envía al menos uno de matchGroupId o transactionId.

Para leer los ajustes registrados en un contexto, usa GET /v1/matching/contexts/{contextId}/adjustments. Acepta un filtro opcional matchGroupId y pagina con cursor.

Referencia de API:

• Listar candidatos de coincidencia
• Listar partidas abiertas
• Crear ajuste

​

Rechazar o revocar grupos de coincidencias

---

Usa la operación de deshacer coincidencia para rechazar un grupo PROPOSED o revocar un grupo CONFIRMED. Después de una operación exitosa, Matcher devuelve las transacciones del grupo a UNMATCHED. La siguiente ejecución puede volver a hacerlas coincidir.

Usa DELETE /v1/matching/groups/{matchGroupId} con el parámetro de consulta contextId obligatorio 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"
 }'

Una operación de deshacer coincidencia exitosa devuelve 204 No Content. El campo reason es obligatorio y no debe estar vacío.

​

Cuándo rechazar o revocar

Escenarios comunes para rechazar o revocar un grupo:

• Coincidencia incorrecta confirmada: las transacciones de un grupo confirmado pertenecen a registros distintos
• Información nueva: datos adicionales muestran que la coincidencia está mal
• Corrección en la fuente: el sistema de origen emitió una corrección o una reversión
• Transacción duplicada: una de las transacciones es un duplicado que se recomienda eliminar

​

Qué ocurre después de deshacer la coincidencia

Cuando deshaces la coincidencia de un grupo:

1. Cambia el estado de la coincidencia: un grupo CONFIRMED pasa a REVOKED. Un grupo aún en PROPOSED pasa a REJECTED.
2. Transacciones devueltas: todas las transacciones asociadas vuelven al estado UNMATCHED de forma atómica con el cambio de estado.
3. Efectos de la confirmación retirados: para un grupo CONFIRMED, Matcher también retira los residuales de partidas abiertas del grupo, anula sus variaciones de comisión y retira las excepciones que generó. Estos cambios y el cambio de estado ocurren en una sola transacción.
4. Motivo registrado: el grupo guarda el motivo de rechazo o revocación proporcionado.
5. Evento de streaming emitido: un evento match_group.unmatched se emite solo cuando el grupo estaba antes en CONFIRMED.
6. Nueva coincidencia posible: después de deshacer la coincidencia con éxito, la siguiente ejecución puede volver a hacer coincidir las transacciones.

​

Mejores prácticas

---

Empieza con las coincidencias de menor confianza

Revisa primero las coincidencias con las puntuaciones de confianza más bajas. Estas coincidencias son las que tienen más probabilidad de estar mal. Dales la mayor atención.

Entiende los umbrales de confianza fijos

Los umbrales de confianza no cambian. Las coincidencias EXACT y TOLERANCE creadas por el motor con puntuaciones de 90 o más se confirman automáticamente. Las coincidencias manuales empiezan en CONFIRMED. Las puntuaciones entre 60 y 89 siguen en PROPOSED. Estos valores no son configurables por contexto.

Las coincidencias FUZZY y DATE_LAG son la excepción. Nunca se confirman automáticamente y siguen 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 franja.

Da un motivo claro

Proporciona un motivo específico al rechazar un grupo propuesto o al revocar un grupo confirmado. La operación de deshacer coincidencia lo requiere y lo guarda con el grupo.

Rechaza solo después de revisar los datos de origen

Revisa el grupo y sus transacciones de origen antes de usar la operación de deshacer coincidencia. Matcher expone esta operación por grupo. No expone la confirmación masiva.

Revisa con cuidado las coincidencias de alto valor

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

​

Próximos pasos

---

Resolver excepciones

Maneja las transacciones sin coincidencia automática.

Puntuación de confianza

Conoce en detalle cómo Matcher calcula las puntuaciones de confianza.