Resolver excepciones

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 marca una transacción que necesita tu revisión. Entre las causas comunes están:

No se encontró candidato: ninguna transacción de la otra fuente cumple los criterios de la regla activa.
Rechazo por duplicado: una coincidencia anterior fue rechazada y no queda ningún candidato alternativo.
Desbalance entre fuentes: una fuente contiene transacciones que no están 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 definen PENDING_RESOLUTION mientras la operación está en curso. El éxito mueve la excepción a RESOLVED.
La resolución directa mueve una excepción OPEN o ASSIGNED a RESOLVED.
El despacho 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`	Registra un despacho a un sistema de destino. Cuerpo: `targetSystem` (obligatorio; `MANUAL` es el valor de destino que registra un despacho), `queue` (opcional). 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`	Marca la transacción de la excepción como conciliada y resuelve la excepción. Cuerpo: `overrideReason` (`POLICY_EXCEPTION`, `OPS_APPROVAL`, `CUSTOMER_DISPUTE` o `DATA_CORRECTION`) y `notes`. Usa `PENDING_RESOLUTION` mientras la operación está en curso.
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.
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 hasta 10,000 IDs de las excepciones que coinciden con los filtros actuales (`contextId`, `status`, `severity`, `reason`, …). `total` da el conteo completo, y `truncated` es `true` cuando la lista se detiene en el límite. Úsalo para preparar una selección masiva antes de llamar a los endpoints masivos. (solo lectura)

El despacho MANUAL confirma la entrega localmente sin llamar a un sistema externo.

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. El monto es el valor absoluto del monto base de la transacción o, cuando no tiene monto base, de su monto. Para una partida abierta vencida, es el valor absoluto del saldo abierto.

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

Matcher limita una excepción con motivo FEE_DATA_MISSING a Media, sin importar su monto o su antigüedad. 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

Cada vez que una ejecución de coincidencia en modo COMMIT encuentra una transacción aún no conciliada, Matcher recalcula la severidad de la excepción sin resolver de esa transacción, salvo si es una excepción de transacción duplicada. La antigüedad cuenta desde la fecha de la transacción o, para una partida abierta vencida, desde la fecha hábil de la obligación o el tiempo de primera vista. 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 recalculada escala así:

Una excepción por debajo de 1,000 empieza como Baja, pero escala a Media después de 24 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

Marca la transacción de la excepción como conciliada y resuelve la excepción. Forzar coincidencia no agrega la transacción a ningún grupo de coincidencia ni la une a ninguna contraparte. Para unir dos transacciones, crea una coincidencia manual con POST /v1/matching/manual. Usa Forzar coincidencia cuando:

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

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": "MANUAL",
   "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`	Ninguno (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 nueva está en OPEN. Cerrarla establece WON o LOST, y ambos resultados son terminales.

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 para ver por qué falló la coincidencia.
Llama a GET /v1/matching/candidates con el contextId del contexto de conciliación y el transactionId de la excepción para revisar 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: aceptas la transacción como conciliada sin una contraparte.
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. El despacho registra la acción pero no cambia el estado de la excepción.

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

Console

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