> ## 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`. * 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 ### 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*) | | | API Reference: [Assign exception](/es/reference/matcher/assign-exception) | [Dispatch exception](/es/reference/matcher/dispatch-exception) | [Resolve exception](/es/reference/matcher/resolve-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": "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": "FEE_ADJUSTMENT", "notes": "Correcting processing fee discrepancy" }' ``` #### 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 *** 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). Forzar coincidencia omite la lógica de puntuación y de reglas. Úsala solo cuando puedas justificar la decisión por escrito. ### 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 | Las cancelaciones eliminan elementos del resultado de tu conciliación. Trátalas como una decisión de política, no como una conveniencia. ### 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: ```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 '{ "exception_ids": ["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 '{ "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: ```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 '{ "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: ```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 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](/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. * **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). 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 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 *** 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. Usa reglas de asignación para reducir el tiempo de triaje y mantener clara la propiedad. Si cancelas con frecuencia, revisa los umbrales, el alcance del contexto o la calidad de los datos upstream. ## Próximos pasos *** Crea reportes de conciliación, exporta resultados y da soporte a auditorías. Configura reglas de severidad, SLAs y asignación automática.