> ## 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 transacciones que Matcher no pudo conciliar automáticamente usando 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 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 ### 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](/es/matcher/configuration/matcher-exception-routing) para conocer el contrato completo de despacho. API Reference: [Assign exception](/es/reference/matcher/assign-exception) | [Dispatch exception](/es/reference/matcher/dispatch-exception) | [Resolve exception](/es/reference/matcher/resolve-exception) | [Force match](/es/reference/matcher/force-match-exception) | [Adjust entry](/es/reference/matcher/adjust-entry-exception) | [Get exception history](/es/reference/matcher/retrieve-exception-history) | [Select exception IDs](/es/reference/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": "Varianza dentro de la tolerancia" }' ``` #### 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": "Corrección de una discrepancia en la tarifa de procesamiento" }' ``` #### Selección en lote 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 en lote](#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). Forzar coincidencia omite la lógica de puntuación y de reglas. Úsala solo cuando puedas justificar la decisión por escrito. ### 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: ```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" }' ``` API Reference: [Bulk assign](/es/reference/matcher/bulk-assign-exceptions) | [Bulk resolve](/es/reference/matcher/bulk-resolve-exceptions) | [Bulk dispatch](/es/reference/matcher/bulk-dispatch-exceptions) ### Resolución en lote Resuelve múltiples 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": "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: ```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": "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: ```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": "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](/es/reference/matcher/list-exception-comments) | [Add comment](/es/reference/matcher/add-exception-comment) | [Delete comment](/es/reference/matcher/delete-exception-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](/es/reference/matcher/list-disputes) | [Get dispute](/es/reference/matcher/retrieve-dispute) | [Open dispute](/es/reference/matcher/open-dispute) | [Close dispute](/es/reference/matcher/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. Revisa la cola por severidad y SLA. Comienza con Crítica y Alta. 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). 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. 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 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 *** Comienza con los elementos Críticos y Altos. Conllevan el mayor riesgo y los plazos más ajustados. 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 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 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 reportes de conciliación, exporta resultados y da soporte a auditorías. Revisa los conceptos de severidad, SLA y enrutamiento de excepciones.