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 severidad y resolver elementos con el nivel adecuado de documentación.

¿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. Las causas comunes incluyen:

Sin candidato encontrado: ninguna transacción en la otra fuente cumple los criterios de la regla activa.
Por debajo del umbral de confianza: existen candidatos, pero puntúan por debajo de la confianza mínima (por defecto: 60).
Rechazo por duplicado: una coincidencia previa fue rechazada y no queda candidato alternativo.
Desbalance de fuente: una fuente contiene transacciones que faltan en la otra.

Ciclo de vida de una excepción

Las excepciones avanzan a través de un flujo de trabajo simple:

Cuando Matcher no puede conciliar una transacción, crea una excepción en estado OPEN.
Desde ahí, la excepción se asigna a un analista para investigación (ASSIGNED).
Si la resolución depende de un sistema externo —como un issue despachado a JIRA o un callback de webhook— la excepción pasa a PENDING_RESOLUTION hasta que llega la respuesta externa.
Una vez que el analista resuelve la excepción (forzar coincidencia, ajuste o callback externo), transiciona a RESOLVED. La resolución no depende del despacho: una excepción puede pasar a RESOLVED desde OPEN, ASSIGNED o PENDING_RESOLUTION.

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

Definiciones de estado

Estado	Descripción	Quién puede transicionar
`OPEN`	Nueva excepción esperando asignación	Sistema
`ASSIGNED`	Asignada a un analista para investigación	Sistema, Analista
`PENDING_RESOLUTION`	Esperando respuesta externa (JIRA, callback de webhook)	Sistema
`RESOLVED`	Cerrada con una resolución auditable	Analista, Sistema

Endpoints de la máquina de estados

Los siguientes endpoints de excepción individual impulsan las transiciones del ciclo de vida anterior. Cada uno se direcciona mediante 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` (requerido). Devuelve la excepción actualizada. (`OPEN` → `ASSIGNED`)
Despachar excepción	`POST /v1/exceptions/{exceptionId}/dispatch`	Despacha la excepción a un sistema de tickets externo (por ejemplo, JIRA, ServiceNow). Cuerpo: `DispatchRequest`. Devuelve un `DispatchResponse`. (`ASSIGNED` → `PENDING_RESOLUTION`)
Resolver excepción	`POST /v1/exceptions/{exceptionId}/resolve`	Resuelve una sola excepción. Cuerpo: `resolution` (requerido), `reason` (opcional). Refleja la validación de resolución en lote para una excepción. (`OPEN`	`ASSIGNED`	`PENDING_RESOLUTION` → `RESOLVED`)
Ajustar asiento	`POST /v1/exceptions/{exceptionId}/adjust-entry`	Resuelve una excepción creando un asiento de ajuste contable. Cuerpo: `amount`, `currency`, `effectiveAt`, `notes`, `reasonCode` (todos requeridos). (resuelve mediante ajuste)
Historial de 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 impulsar una selección en lote antes de llamar a los endpoints en lote. (solo lectura)

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": "FEE_ADJUSTMENT",
   "notes": "Correcting processing fee discrepancy"
 }'

Selección en lote 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 en lote más abajo.

Severidad de las excepciones

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

Severidad	Criterio	SLA
Crítica	Monto >= 100,000 O antigüedad >= 120 horas	24 horas
Alta	Monto >= 10,000 O antigüedad >= 72 horas	72 horas
Media	Monto >= 1,000 O antigüedad >= 24 horas	120 horas (5 días)
Baja	Todas las demás	168 horas (7 días)

Escalamiento de severidad

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

Una excepción con monto menor a 1,000 comienza como Baja, pero escala a Media después de 24 horas.
Una excepción con monto menor a 10,000 escala a Alta después de 72 horas.
Cualquier excepción no resuelta escala a Crítica después de 120 horas.

Métodos de resolución

Puedes resolver una excepción de cuatro maneras.

1. Forzar coincidencia

Vincula manualmente transacciones cuando has confirmado que pertenecen juntas, pero el sistema no pudo conciliarlas. Usa Forzar coincidencia cuando:

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

2. Crear ajuste

Crea un asiento de ajuste para contabilizar una variación o equilibrar un elemento no conciliado. Tipos comunes de ajuste:

Tipo	Caso de uso
`BANK_FEE`	Cargos bancarios no registrados en el libro mayor
`FX_VARIANCE`	Diferencias de conversión de moneda
`TIMING_DIFFERENCE`	Ajustes de tiempo de liquidación
`ROUNDING`	Pequeñas diferencias de redondeo
`CORRECTION`	Correcciones de errores
`OTHER`	Otras variaciones documentadas

Reglas de validación:

Los montos de ajuste deben ser positivos. Una solicitud con monto cero o negativo devuelve un error 400 Bad Request.
Los códigos de moneda deben seguir el formato ISO 4217.
Los códigos de razón deben usar un valor predefinido válido: AMOUNT_CORRECTION, CURRENCY_CORRECTION, DATE_CORRECTION u OTHER.

3. Cancelación (write-off)

Cancela una transacción que no tiene contraparte válida. Esto debería ser poco frecuente y típicamente requiere aprobación. Razones de cancelación:

Razón	Descripción
`DUPLICATE_ENTRY`	La transacción fue ingresada dos veces
`CANCELLED`	La transacción fue revertida o cancelada
`NOT_APPLICABLE`	No pertenece al alcance de esta conciliación
`BELOW_THRESHOLD`	El monto está por debajo del umbral de investigación
`APPROVED_VARIANCE`	Variación aprobada por la gerencia

4. Dividir transacción

Usa la división cuando una transacción debe coincidir con múltiples contrapartes.

Requisitos de auditoría

Cada resolución crea un registro de auditoría. Algunos tipos de resolución requieren evidencia y aprobaciones más sólidas.

Documentación requerida por tipo de resolución

Resolución	Campos requeridos	Aprobación necesaria
Forzar coincidencia	`reason`, `notes`	No (a menos que monto > umbral)
Ajuste	`adjustment_type`, `amount`, `description`	Si monto > $1,000
Cancelación (write-off)	`reason`, `notes`, `reference_document`	Siempre
División	`splits[]` con montos y objetivos	No

Operaciones en lote

Cuando se manejan grandes volúmenes de excepciones, los endpoints en lote permiten procesar hasta 100 excepciones en una sola solicitud.

Asignación en lote

Asigna múltiples excepciones a un miembro del equipo de una sola vez:

cURL

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

API Reference: Bulk assign | Bulk resolve | Bulk dispatch

Resolución en lote

Resuelve múltiples 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 '{
   "exception_ids": ["019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f", "019c96a0-2b20-7123-9a1b-2c3d4e5f6a7b"],
   "resolution": "ACCEPTED",
   "reason": "Verified as valid bank fees"
 }'

La respuesta incluye los arrays succeeded y failed, para que puedas manejar fallas parciales de forma elegante.

Despacho en lote

Despacha múltiples 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 '{
   "exception_ids": ["019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f"],
   "target_system": "JIRA",
   "queue": "RECON-TEAM"
 }'

Comentarios de excepciones

Los comentarios dan a cada excepción un registro de auditoría de notas de investigación y discusión del equipo, invaluable cuando alguien más debe retomar o revisar el caso más adelante. Agrega un comentario a medida que 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 del más reciente al más antiguo con paginación mediante cursor/limit, y un comentario puede eliminarse por su commentId.

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`	`cursor`, `limit` (paginación)
Eliminar comentario	`DELETE /v1/exceptions/{exceptionId}/comments/{commentId}`	`commentId` en la ruta

API Reference: List comments | Add comment | Delete comment

Disputas

Cuando una excepción necesita una investigación formal o involucra a una parte externa —un contracargo, una consulta bancaria— escálala a una disputa. Las disputas rastrean evidencia, cambios de estado y el resultado final. Lista las disputas con GET /v1/disputes (filtra por state, por ejemplo OPEN) o recupera una por su disputeId.

API Reference: List disputes | Get dispute | Open dispute | Close dispute

Estados y transiciones de 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 recolectar evidencia.
Una disputa LOST puede reabrirse de vuelta 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 solicitar 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 puede reabrirse

Flujo de trabajo de resolución de excepciones

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

Triaje

Revisa la cola por severidad y SLA. Comienza 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.

Forzar coincidencia: encontraste la contraparte correcta.
Ajustar: necesitas un asiento de ajuste para la variación.
Dividir: una transacción mapea a múltiples contrapartes.
Cancelación (write-off): no existe contraparte y la política lo permite (se requiere aprobación).

Documentar

Captura suficiente detalle para que alguien más pueda reproducir tu decisión más adelante:

Qué verificaste
Qué concluiste
Enlaces o IDs de evidencia de soporte

Despachar si es necesario

Si la excepción requiere gestión externa, despáchala a JIRA o a un endpoint de webhook. La excepción pasa a PENDING_RESOLUTION hasta que un callback confirme el resultado.

Buenas prácticas

Trabaja por severidad y SLA

Comienza con los elementos Críticos y Altos. Conllevan 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é verificaste
Por qué esta resolución es correcta
Cualquier ID de ticket, extractos o confirmaciones

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 completitud 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.

Enruta el trabajo automáticamente

Usa reglas de asignación para reducir el tiempo de triaje y mantener clara la propiedad.

Las cancelaciones son decisiones de política

Si cancelas con frecuencia, revisa los umbrales, el alcance del contexto o la calidad de los datos upstream.

Resumen

Guías

Matcher UI

Servidor MCP

Operaciones

Resolver excepciones

¿Qué es una excepción?

Ciclo de vida de una 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 en lote con `selectExceptionIDs`

Severidad de las excepciones

Escalamiento de severidad

Métodos de resolución

1. Forzar coincidencia

2. Crear ajuste

3. Cancelación (write-off)

4. Dividir transacción

Requisitos de auditoría

Documentación requerida por tipo de resolución

Operaciones en lote

Asignación en lote

Resolución en lote

Despacho en lote

Comentarios de excepciones

Disputas

Estados y transiciones de disputa

Flujo de trabajo de resolución de excepciones

Buenas prácticas

Próximos pasos

Generando Reportes

Enrutamiento de Excepciones

​¿Qué es una excepción?

​Ciclo de vida de una 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 en lote con selectExceptionIDs

​Severidad de las excepciones

​Escalamiento de severidad

​Métodos de resolución

​1. Forzar coincidencia

​2. Crear ajuste

​3. Cancelación (write-off)

​4. Dividir transacción

​Requisitos de auditoría

​Documentación requerida por tipo de resolución

​Operaciones en lote

​Asignación en lote

​Resolución en lote

​Despacho en lote

​Comentarios de excepciones

​Disputas

​Estados y transiciones de disputa

​Flujo de trabajo de resolución de excepciones

​Buenas prácticas

​Próximos pasos

Generando Reportes

Enrutamiento de Excepciones

¿Qué es una excepción?

Ciclo de vida de una 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 en lote con `selectExceptionIDs`

Severidad de las excepciones

Escalamiento de severidad

Métodos de resolución

1. Forzar coincidencia

2. Crear ajuste

3. Cancelación (write-off)

4. Dividir transacción

Requisitos de auditoría

Documentación requerida por tipo de resolución

Operaciones en lote

Asignación en lote

Resolución en lote

Despacho en lote

Comentarios de excepciones

Disputas

Estados y transiciones de disputa

Flujo de trabajo de resolución de excepciones

Buenas prácticas

Próximos pasos