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.
Al asignar la excepción, pasa de OPEN a ASSIGNED. La API no expone una operación para quitar la asignación; assignee es obligatorio y no puede estar vacío.
Forzar coincidencia y ajustar asiento conservan PENDING_RESOLUTION solo mientras la operación está en curso. Si la operación tiene éxito, la excepción pasa a RESOLVED; si falla, vuelve a su estado anterior, OPEN o ASSIGNED.
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 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`	Forzar coincidencia o ajustar asiento está en curso	Sistema
`RESOLVED`	Cerrada con una resolución auditable	Analista, Sistema

Endpoints de la máquina de estados

Los siguientes endpoints de excepción individual cambian el ciclo de vida o registran acciones relacionadas. 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`	Envía la excepción mediante 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` (requerido), `reason` (opcional). Refleja la validación de resolución en lote 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; después resuelve o vuelve al estado anterior si falla.
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). Usa `PENDING_RESOLUTION` mientras la operación está en curso; después resuelve o vuelve al estado anterior si falla.
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)

Matcher conecta la ruta de webhook y el manejo de callbacks. El código del conector de JIRA existe, pero no está configurado por defecto. MANUAL confirma el despacho localmente sin llamar a un sistema externo. El despacho a ServiceNow no está implementado: SERVICENOW llega a la ruta genérica de falla por destino no soportado y devuelve HTTP 500. Consulta Enrutamiento de excepciones para conocer el contrato completo de despacho.

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": "Varianza dentro de la tolerancia" }'

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": "Corrección de una discrepancia en la tarifa de procesamiento"
 }'

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

Matcher expone tres acciones para resolver excepciones.

1. Resolver directamente

Cierra una excepción con un valor resolution requerido y un reason opcional cuando no necesitas forzar una coincidencia ni crear un ajuste.

2. 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).

3. Crear ajuste

Crea un asiento de ajuste para contabilizar una variación o equilibrar un elemento no conciliado. Códigos de razón del ajuste:

Código de razón	Caso de uso
`AMOUNT_CORRECTION`	Corrige el monto de la transacción
`CURRENCY_CORRECTION`	Corrige la moneda de la transacción
`DATE_CORRECTION`	Corrige la fecha efectiva
`OTHER`	Registra otra corrección documentada

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.
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 flujo de auditoría.

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

Matcher no expone contratos de resolución para dividir excepciones ni para cancelarlas de forma 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 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 '{
   "exceptionIds": ["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 '{
   "exceptionIds": ["019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f", "019c96a0-2b20-7123-9a1b-2c3d4e5f6a7b"],
   "resolution": "ACCEPTED",
   "reason": "Verificadas como tarifas bancarias válidas"
 }'

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 '{
   "exceptionIds": ["019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f"],
   "targetSystem": "WEBHOOK",
   "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": "Contacté al banco para verificar la tarifa de la transferencia. Espero su confirmación."
 }'

El listado (GET) devuelve el hilo completo ordenado del más antiguo al más reciente. No puedes agregar comentarios después de que se resuelve una excepción. Solo quien escribió el 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

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.

Resolver directamente: puedes cerrar la excepción sin forzar una coincidencia ni crear un ajuste.
Forzar coincidencia: encontraste la contraparte correcta.
Ajustar: necesitas un asiento de ajuste para la variació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 mediante el conector de webhook configurado. El despacho registra la acción, pero no cambia el estado de la excepción. JIRA requiere una configuración de conector que Matcher no proporciona por defecto; ServiceNow no está disponible.

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.

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.

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. Resolver directamente

2. Forzar coincidencia

3. Crear ajuste

Registros 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. Resolver directamente

​2. Forzar coincidencia

​3. Crear ajuste

​Registros 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. Resolver directamente

2. Forzar coincidencia

3. Crear ajuste

Registros 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