> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Resolver excepciones > Revisa, prioriza y resuelve las transacciones que Matcher no pudo conciliar automáticamente con severidad, ciclo de vida y acciones aptas para auditoría. 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. * **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 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 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 ### 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` | Resuelve una excepción con `overrideReason` (`POLICY_EXCEPTION`, `OPS_APPROVAL`, `CUSTOMER_DISPUTE` o `DATA_CORRECTION`) 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)* | El despacho `MANUAL` confirma la entrega localmente sin llamar a un sistema externo. Referencia de API: * [Asignar excepción](/es/reference/products/matcher/assign-exception) * [Despachar excepción](/es/reference/products/matcher/dispatch-exception) * [Resolver excepción](/es/reference/products/matcher/resolve-exception) * [Forzar coincidencia](/es/reference/products/matcher/force-match-exception) * [Ajustar asiento](/es/reference/products/matcher/adjust-entry-exception) * [Obtener historial de la excepción](/es/reference/products/matcher/retrieve-exception-history) * [Seleccionar IDs de excepción](/es/reference/products/matcher/select-exception-ids) #### Ejemplo de asignación ```bash cURL theme={null} 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 ```bash cURL theme={null} 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 ```bash cURL theme={null} 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` ```bash cURL theme={null} 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](#bulk-operations) 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 | 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. * 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). Forzar coincidencia omite la puntuación y la lógica de reglas. Úsalo solo cuando puedes justificar la decisión por escrito. ### 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 código de moneda de tres caracteres 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: ```bash cURL theme={null} 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: * [Asignación masiva](/es/reference/products/matcher/bulk-assign-exceptions) * [Resolución masiva](/es/reference/products/matcher/bulk-resolve-exceptions) * [Despacho masivo](/es/reference/products/matcher/bulk-dispatch-exceptions) ### Resolución masiva Resuelve varias excepciones con una resolución compartida: ```bash cURL theme={null} 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: ```bash cURL theme={null} 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: ```bash cURL theme={null} 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: * [Listar comentarios](/es/reference/products/matcher/list-exception-comments) * [Agregar comentario](/es/reference/products/matcher/add-exception-comment) * [Eliminar comentario](/es/reference/products/matcher/delete-exception-comment) ## 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: * [Listar disputas](/es/reference/products/matcher/list-disputes) * [Obtener disputa](/es/reference/products/matcher/retrieve-dispute) * [Abrir disputa](/es/reference/products/matcher/open-dispute) * [Cerrar disputa](/es/reference/products/matcher/close-dispute) ### 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. Revisa la cola por severidad y SLA. Empieza con Crítica y Alta. 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). 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. 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 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 *** Empieza con los elementos Crítica y Alta. Llevan el mayor riesgo y los plazos más ajustados. 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 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 Si fuerzas coincidencias con regularidad, tus reglas o tolerancias necesitan atención. Asigna las excepciones mediante los endpoints de asignación. Matcher no aplica reglas de asignación automáticamente. ## Próximos pasos *** Crea informes de conciliación, exporta resultados y da soporte a las auditorías. Revisa los conceptos de severidad, SLA y enrutamiento para las excepciones. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.