Resolver excepciones

Las excepciones son transacciones que Matcher no puede conciliar automáticamente. Esta guía muestra cómo revisar excepciones, priorizar el trabajo según la severidad y resolver elementos con el nivel de documentación adecuado.

¿Qué es una excepción?

Una excepción se crea cuando una transacción de una fuente no tiene contraparte válida en otra fuente. Entre las causas comunes están:

No se encontró candidato: ninguna transacción de la otra fuente cumple los criterios de la regla activa.
Por debajo del umbral de confianza: hay candidatos, pero puntúan por debajo de la confianza mínima (predeterminado: 60).
Rechazo por duplicado: una coincidencia anterior fue rechazada y no queda ningún candidato alternativo.
Desbalance entre fuentes: una fuente contiene transacciones que faltan en la otra.

Ciclo de vida de la excepción

Las excepciones avanzan por un workflow simple:

Cuando Matcher no puede conciliar una transacción, crea una excepción en estado OPEN.
Asignar la excepción la mueve de OPEN a ASSIGNED. La API no expone una operación para desasignar. Debes enviar un assignee no vacío.
Forzar coincidencia y ajustar asiento persisten PENDING_RESOLUTION solo mientras la operación está en curso. El éxito mueve la excepción a RESOLVED. El fallo la devuelve a su estado OPEN o ASSIGNED anterior.
La resolución directa mueve una excepción OPEN o ASSIGNED a RESOLVED.
El despacho envía la solicitud al conector, escribe un evento de auditoría DISPATCH y emite exception.dispatched. No cambia el estado de la excepción.

Ciclo de vida de excepciones de Matcher — El ciclo de vida de una excepción en Matcher

Definiciones de estado

Estado	Descripción	Quién puede hacer la transición
`OPEN`	Excepción nueva en espera de asignación	Sistema
`ASSIGNED`	Asignada a un analista para investigación	Sistema, analista
`PENDING_RESOLUTION`	Forzar coincidencia o ajustar asiento en curso	Sistema
`RESOLVED`	Cerrada con una resolución auditable	Analista, sistema

Endpoints de la máquina de estados

Los siguientes endpoints de una sola excepción cambian el ciclo de vida o registran acciones relacionadas. Cada uno se identifica con el exceptionId de la excepción en la ruta.

Endpoint	Método y ruta	Propósito
Asignar excepción	`POST /v1/exceptions/{exceptionId}/assign`	Asigna la excepción a un analista. Cuerpo: `assignee` (obligatorio). Devuelve la excepción actualizada. (`OPEN` → `ASSIGNED`)
Despachar excepción	`POST /v1/exceptions/{exceptionId}/dispatch`	Envía la excepción por el conector configurado. Escribe un evento de auditoría `DISPATCH` y emite `exception.dispatched` sin cambiar el estado.
Resolver excepción	`POST /v1/exceptions/{exceptionId}/resolve`	Resuelve una sola excepción. Cuerpo: `resolution` (obligatorio), `reason` (opcional). Refleja la validación de la resolución masiva para una excepción. (`OPEN` o `ASSIGNED` → `RESOLVED`)
Forzar coincidencia	`POST /v1/exceptions/{exceptionId}/force-match`	Resuelve una excepción con `overrideReason` y `notes`. Usa `PENDING_RESOLUTION` mientras la operación está en curso, luego resuelve o vuelve al estado anterior si falla.
Ajustar asiento	`POST /v1/exceptions/{exceptionId}/adjust-entry`	Resuelve una excepción creando un asiento contable de ajuste. Cuerpo: `amount`, `currency`, `effectiveAt`, `notes`, `reasonCode` (todos obligatorios). Usa `PENDING_RESOLUTION` mientras la operación está en curso, luego resuelve o vuelve al estado anterior si falla.
Historial de la excepción	`GET /v1/exceptions/{exceptionId}/history`	Devuelve el historial ordenado de transiciones de estado y acciones de la excepción (`HistoryResponse`). Admite paginación con `cursor`/`limit`. (solo lectura)
Seleccionar IDs de excepción	`GET /v1/exceptions/ids`	Devuelve el conjunto completo de IDs de excepción que coinciden con los filtros actuales (`contextId`, `status`, `severity`, `reason`, …). Úsalo para preparar una selección masiva antes de llamar a los endpoints masivos. (solo lectura)

Matcher admite el despacho WEBHOOK, JIRA, SERVICENOW y MANUAL. WEBHOOK requiere una URL provista por el despliegue y, cuando se requieren payloads firmados, un secreto compartido. JIRA y ServiceNow requieren su configuración de conector. MANUAL confirma el despacho localmente sin llamar a un sistema externo. Un conector ausente devuelve MTCH-0509. Un despacho no confirmado devuelve MTCH-0514, así que verifica el destino antes de reintentar porque puede que ya exista un registro de destino. Consulta Enrutamiento de excepciones para el contrato de despacho completo.

Referencia de API:

Ejemplo de asignación

cURL

curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/assign" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{ "assignee": "john.doe@company.com" }'

Ejemplo de resolución

cURL

curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/resolve" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{ "resolution": "ACCEPTED", "reason": "Variance within tolerance" }'

Ejemplo de ajuste de asiento

cURL

curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/adjust-entry" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "amount": "150.50",
   "currency": "BRL",
   "effectiveAt": "2026-02-02T16:40:00Z",
   "reasonCode": "AMOUNT_CORRECTION",
   "notes": "Correcting processing fee discrepancy"
 }'

Selección masiva con `selectExceptionIDs`

cURL

curl -X GET "https://api.matcher.example.com/v1/exceptions/ids?contextId={contextId}&status=OPEN&severity=CRITICAL" \
 -H "Authorization: Bearer $TOKEN"

Alimenta los IDs devueltos en las operaciones masivas de abajo.

Severidad de la excepción

Matcher clasifica las excepciones por severidad para que puedas trabajar la cola en el orden correcto.

Severidad	Criterio
Crítica	Monto >= 100,000 O antigüedad >= 120 horas
Alta	Monto >= 10,000 O antigüedad >= 72 horas
Media	Monto >= 1,000 O antigüedad >= 24 horas
Baja	Todas las demás

Estos umbrales repriorizan la excepción. No crean un plazo de SLA. Un callback entrante puede proporcionar dueAt, y los agregados del dashboard miden el cumplimiento de esos plazos provistos externamente. Define la política de tiempo de respuesta en el sistema externo que envía el callback.

Escalamiento de severidad

La severidad se reevalúa a medida que la excepción envejece. La clasificación usa lógica OR. El umbral de monto o el de antigüedad basta para disparar una severidad mayor:

Una excepción por debajo de 1,000 empieza como Baja, pero escala a Media después de 24 horas.
Una excepción por debajo de 10,000 escala a Alta después de 72 horas.
Cualquier excepción sin resolver escala a Crítica después de 120 horas.

Métodos de resolución

Matcher expone tres acciones de resolución de excepciones.

1. Resolver directamente

Cierra una excepción con un resolution obligatorio y un reason opcional cuando no hace falta una coincidencia forzada ni un ajuste.

2. Forzar coincidencia

Vincula transacciones manualmente cuando confirmaste que van juntas, pero el sistema no pudo hacerlas coincidir. Usa Forzar coincidencia cuando:

La contraparte correcta existe, pero las variaciones bloquearon la coincidencia automática.
Puedes explicar y documentar con claridad la justificación.
La variación es esperada (comisiones, tiempos, redondeo).

3. Crear ajuste

Crea un asiento de ajuste para registrar una variación o para balancear un elemento no conciliado. Códigos de motivo del ajuste:

Código de motivo	Caso de uso
`AMOUNT_CORRECTION`	Corregir el monto de la transacción
`CURRENCY_CORRECTION`	Corregir la moneda de la transacción
`DATE_CORRECTION`	Corregir la fecha efectiva
`OTHER`	Registrar otra corrección documentada

Reglas de validación:

Los montos de ajuste deben ser positivos. Una solicitud con un monto cero o negativo devuelve un error 400 Bad Request.
POST /v1/exceptions/{exceptionId}/adjust-entry requiere un código de moneda ISO 4217 válido. POST /v1/matching/adjustments acepta cualquier cadena de moneda no vacía y no valida la pertenencia a ISO 4217.
reasonCode debe usar AMOUNT_CORRECTION, CURRENCY_CORRECTION, DATE_CORRECTION u OTHER.

Registros de resolución

Matcher registra las acciones de resolución admitidas en el historial de la excepción y en el stream de auditoría.

Resolución	Campos de la solicitud
Resolución directa	`resolution` (obligatorio), `reason` (opcional)
Forzar coincidencia	`overrideReason`, `notes`
Ajustar asiento	`reasonCode`, `amount`, `currency`, `effectiveAt`, `notes`

Matcher no expone contratos de resolución de división de excepciones ni de baja contable independiente, y no aplica umbrales de aprobación basados en montos para estas acciones. Aplica cualquier requisito de aprobación adicional mediante los controles de tu organización.

Operaciones masivas

Cuando manejas grandes volúmenes de excepciones, los endpoints masivos permiten procesar hasta 100 excepciones en una sola solicitud.

Asignación masiva

Asigna varias excepciones a un integrante del equipo de una vez:

cURL

curl -X POST "https://api.matcher.example.com/v1/exceptions/bulk/assign" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "exceptionIds": ["019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f", "019c96a0-2b20-7123-9a1b-2c3d4e5f6a7b"],
   "assignee": "john.doe@company.com"
 }'

Referencia de API:

Resolución masiva

Resuelve varias excepciones con una resolución compartida:

cURL

curl -X POST "https://api.matcher.example.com/v1/exceptions/bulk/resolve" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "exceptionIds": ["019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f", "019c96a0-2b20-7123-9a1b-2c3d4e5f6a7b"],
   "resolution": "ACCEPTED",
   "reason": "Verified as valid bank fees"
 }'

La respuesta incluye los arreglos succeeded y failed, para que puedas manejar los fallos parciales de forma controlada.

Despacho masivo

Despacha varias excepciones a un sistema externo:

cURL

curl -X POST "https://api.matcher.example.com/v1/exceptions/bulk/dispatch" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "exceptionIds": ["019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f"],
   "targetSystem": "WEBHOOK",
   "queue": "RECON-TEAM"
 }'

Comentarios de la excepción

Los comentarios dan a cada excepción un registro de auditoría de notas de investigación y discusión del equipo. Agrega un comentario mientras un analista trabaja un elemento:

cURL

curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/comments" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "content": "Contacted bank to verify wire transfer fee. Awaiting confirmation."
 }'

El listado (GET) devuelve el hilo completo ordenado del más antiguo al más reciente. No puedes agregar comentarios después de que una excepción se resuelve. Solo el autor del comentario puede eliminarlo, y el comentario debe pertenecer a la excepción identificada en la URL.

Acción	Método y ruta	Campos clave
Agregar comentario	`POST /v1/exceptions/{exceptionId}/comments`	`content` (cuerpo del comentario)
Listar comentarios	`GET /v1/exceptions/{exceptionId}/comments`	— (devuelve el hilo completo, del más antiguo al más reciente)
Eliminar comentario	`DELETE /v1/exceptions/{exceptionId}/comments/{commentId}`	`commentId` en la ruta

Referencia de API:

Disputas

Cuando una excepción necesita investigación formal o involucra a un tercero (un chargeback, una consulta bancaria), escálala a una disputa. Las disputas registran la evidencia, los cambios de estado y el resultado final. Lista las disputas con GET /v1/disputes (filtra por state, p. ej. OPEN) o recupera una por su disputeId.

Referencia de API:

Estados y transiciones de la disputa

Una disputa tiene cinco estados: DRAFT, OPEN, PENDING_EVIDENCE, WON y LOST. El flujo no es estrictamente lineal:

PENDING_EVIDENCE es opcional. Una disputa OPEN puede pasar directamente a WON o LOST sin llegar a recolectar evidencia.
Una disputa LOST se puede reabrir a OPEN.
WON es terminal.

El conjunto completo de transiciones válidas:

Estado de origen	Estados siguientes permitidos	Notas
`DRAFT`	`OPEN`	La disputa se abre para investigación
`OPEN`	`PENDING_EVIDENCE`, `WON`, `LOST`	Puede resolverse directamente o pedir evidencia primero
`PENDING_EVIDENCE`	`OPEN`, `WON`, `LOST`	Vuelve a `OPEN` o se resuelve una vez revisada la evidencia
`WON`	(ninguno)	Estado terminal
`LOST`	`OPEN`	Una disputa perdida se puede reabrir

Workflow de resolución de excepciones

Usa este flujo para mantener las revisiones consistentes y aptas para auditoría.

Triaje

Revisa la cola por severidad y SLA. Empieza con Crítica y Alta.

Investigar

Usa el payload de la excepción para entender qué falló y qué candidatos existen.

Lee reason_details para ver por qué falló la coincidencia.
Revisa candidates en busca de coincidencias cercanas por debajo del umbral.
Busca patrones (misma contraparte, formatos de referencia recurrentes).

Resolver

Elige la resolución que mejor refleje la realidad y la política.

Resolver directamente: puedes cerrar la excepción sin una coincidencia forzada ni un ajuste.
Forzar coincidencia: encontraste la contraparte correcta.
Ajustar: necesitas un asiento de ajuste para la variación.

Documentar

Captura suficiente detalle para que otra persona pueda reproducir tu decisión después:

Qué revisaste
Qué concluiste
Enlaces o IDs de la evidencia de soporte

Despachar si hace falta

Si la excepción requiere manejo externo, despáchala por un conector configurado. El despacho registra la acción pero no cambia el estado de la excepción. WEBHOOK requiere una URL provista por el despliegue. JIRA y ServiceNow requieren su configuración de conector. Si un conector devuelve MTCH-0514, verifica el destino antes de reintentar porque puede que ya exista un registro de destino.

Mejores prácticas

Trabaja por severidad y SLA

Empieza con los elementos Crítica y Alta. Llevan el mayor riesgo y los plazos más ajustados.

Haz que las decisiones sean auditables

Las notas no son opcionales. Trátalas como parte de la resolución:

Qué revisaste
Por qué esta resolución es correcta
Cualquier ID de ticket, extracto o confirmación

Corrige los patrones en la fuente

Las excepciones repetidas suelen apuntar a problemas de configuración:

Misma contraparte → Normaliza nombres o mapeo
Misma ventana de fechas → Valida la integridad de la ingesta
Misma fuente → Revisa el mapeo de campos y las convenciones de signo

Trata las coincidencias forzadas como excepciones a la regla

Si fuerzas coincidencias con regularidad, tus reglas o tolerancias necesitan atención.

Asigna el trabajo de forma explícita

Asigna las excepciones mediante los endpoints de asignación. Matcher no aplica reglas de asignación automáticamente.

Próximos pasos

Generar informes

Crea informes de conciliación, exporta resultados y da soporte a las auditorías.

Enrutamiento de excepciones

Revisa los conceptos de severidad, SLA y enrutamiento para las excepciones.

Resumen

Guías

Matcher UI

Servidor MCP

Operaciones

Resolver excepciones

¿Qué es una excepción?

Ciclo de vida de la excepción

Definiciones de estado

Endpoints de la máquina de estados

Ejemplo de asignación

Ejemplo de resolución

Ejemplo de ajuste de asiento

Selección masiva con `selectExceptionIDs`

Severidad de la excepción

Escalamiento de severidad

Métodos de resolución

1. Resolver directamente

2. Forzar coincidencia

3. Crear ajuste

Registros de resolución

Operaciones masivas

Asignación masiva

Resolución masiva

Despacho masivo

Comentarios de la excepción

Disputas

Estados y transiciones de la disputa

Workflow de resolución de excepciones

Mejores prácticas

Próximos pasos

Generar informes

Enrutamiento de excepciones

​¿Qué es una excepción?

​Ciclo de vida de la excepción

​Definiciones de estado

​Endpoints de la máquina de estados

​Ejemplo de asignación

​Ejemplo de resolución

​Ejemplo de ajuste de asiento

​Selección masiva con selectExceptionIDs

​Severidad de la excepción

​Escalamiento de severidad

​Métodos de resolución

​1. Resolver directamente

​2. Forzar coincidencia

​3. Crear ajuste

​Registros de resolución

​Operaciones masivas

​Asignación masiva

​Resolución masiva

​Despacho masivo

​Comentarios de la excepción

​Disputas

​Estados y transiciones de la disputa

​Workflow de resolución de excepciones

​Mejores prácticas

​Próximos pasos

Generar informes

Enrutamiento de excepciones

¿Qué es una excepción?

Ciclo de vida de la excepción

Definiciones de estado

Endpoints de la máquina de estados

Ejemplo de asignación

Ejemplo de resolución

Ejemplo de ajuste de asiento

Selección masiva con `selectExceptionIDs`

Severidad de la excepción

Escalamiento de severidad

Métodos de resolución

1. Resolver directamente

2. Forzar coincidencia

3. Crear ajuste

Registros de resolución

Operaciones masivas

Asignación masiva

Resolución masiva

Despacho masivo

Comentarios de la excepción

Disputas

Estados y transiciones de la disputa

Workflow de resolución de excepciones

Mejores prácticas

Próximos pasos