> ## 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. # Inicio rápido de la API de Matcher > Pon Matcher en funcionamiento: crea tu primer contexto de conciliación, sube archivos y revisa las transacciones coincidentes con cURL y la API de Matcher. **Esta guía está pensada para desarrolladores.** Si buscas un resumen de negocio de lo que hace Matcher, consulta [¿Qué es Matcher?](/es/products/matcher/what-is-matcher). Esta guía te lleva desde la creación de tu primer contexto de conciliación hasta la revisión de las transacciones coincidentes. ## Antes de empezar *** Necesitas: * Una instancia de Matcher en ejecución * Un token JWT válido para la autenticación * Dos archivos de transacciones para conciliar (CSV, JSON o XML) Todos los ejemplos usan `cURL`. Reemplaza `$TOKEN` con tu token JWT y `https://api.matcher.example.com` con la URL de tu Matcher. ## Paso 1: Crea un contexto de conciliación *** Un contexto define el alcance de tu conciliación: qué comparas y cómo. Referencia de la API: [Crear contexto](/es/reference/products/matcher/create-context) ```bash cURL theme={null} curl -X POST "https://api.matcher.example.com/v1/contexts" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Daily Bank Reconciliation", "type": "1:1", "interval": "daily" }' ``` El campo `type` define cómo Matcher empareja las transacciones: | Tipo | Descripción | | ----- | --------------------------------------------------------- | | `1:1` | Cada transacción coincide exactamente con una contraparte | | `1:N` | Una transacción puede coincidir con varias contrapartes | | `N:M` | Varias transacciones pueden coincidir en ambos lados | Guarda el `id` de la respuesta. Lo usarás en cada paso siguiente. ```json theme={null} { "id": "019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f", "name": "Daily Bank Reconciliation", "type": "1:1", "interval": "daily", "status": "DRAFT", "createdAt": "2026-03-04T12:00:00Z", "updatedAt": "2026-03-04T12:00:00Z" } ``` El contexto se inicia en estado DRAFT. Pasa a ACTIVE cuando estás listo para ejecutar la conciliación. ## Paso 2: Agrega fuentes de datos *** Para ejecutar una coincidencia, configura al menos dos fuentes: los sistemas cuyas transacciones quieres comparar. Referencia de la API: [Crear fuente](/es/reference/products/matcher/create-source) ### Crea una fuente bancaria ```bash cURL theme={null} curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Chase Bank - Account 1234", "type": "BANK" }' ``` ### Crea una fuente de ledger ```bash cURL theme={null} curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "General Ledger - GL 1000", "type": "LEDGER" }' ``` Guarda los dos valores `id` de las fuentes. ### Tipos de fuente | Tipo | Caso de uso | | --------- | --------------------------------------------------------- | | `BANK` | Extractos bancarios | | `LEDGER` | Ledger general / exportaciones de ERP | | `GATEWAY` | Datos del procesador de pagos | | `CUSTOM` | Cualquier otra fuente de datos | | `FETCHER` | Datos extraídos mediante el motor de extracción integrado | ## Paso 3: Asigna los campos de la fuente *** Es probable que los archivos de tu fuente usen nombres de columna distintos de los que espera Matcher. Los mapas de campos los traducen al esquema estándar de Matcher. Referencia de la API: [Crear mapa de campos](/es/reference/products/matcher/create-field-map) ### Asigna la fuente bancaria ```bash cURL theme={null} curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{bankSourceId}/field-maps" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "mapping": { "Transaction ID": "transaction_id", "Amount": "amount", "Currency": "currency", "Post Date": "date", "Description": "reference" } }' ``` ### Asigna la fuente de ledger ```bash cURL theme={null} curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{ledgerSourceId}/field-maps" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "mapping": { "entry_id": "transaction_id", "debit_credit_amount": "amount", "currency_code": "currency", "posting_date": "date", "memo": "reference" } }' ``` ### Campos obligatorios Cada transacción debe tener estos campos después de la asignación: | Campo | Tipo | Descripción | | ---------------- | ------- | -------------------------------------------- | | `transaction_id` | String | Identificador único dentro de la fuente | | `amount` | Decimal | Monto de la transacción | | `currency` | String | Código de moneda ISO 4217 (por ejemplo, USD) | | `date` | Date | Fecha de la transacción (YYYY-MM-DD) | **Opcional pero recomendado:** `reference` (referencia externa o descripción). ## Paso 4: Crea reglas de coincidencia *** Las reglas definen cómo Matcher compara las transacciones. Empieza con una regla exacta, que es la más precisa. Referencia de la API: [Crear regla de coincidencia](/es/reference/products/matcher/create-match-rule) ### Crea una regla exacta ```bash cURL theme={null} curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "EXACT", "priority": 1, "config": { "matchAmount": true, "matchCurrency": true, "matchDate": true, "matchReference": true, "caseInsensitive": true, "datePrecision": "DAY" } }' ``` ### Agrega una regla de tolerancia como respaldo Captura diferencias pequeñas, como comisiones bancarias o redondeos: ```bash cURL theme={null} curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "TOLERANCE", "priority": 20, "config": { "percentTolerance": 0.01, "absTolerance": 5.0, "dateWindowDays": 2, "matchCurrency": true, "matchReference": true, "caseInsensitive": true } }' ``` Matcher evalúa las reglas por prioridad (el número más bajo primero). La regla exacta se ejecuta primero. Solo las transacciones no conciliadas pasan a la regla de tolerancia. ### Tipos de regla | Tipo | Cuándo usarla | Rango de prioridad | | ----------- | -------------------------------------------------------------------------- | --------------------------------- | | `EXACT` | Se recomienda que los valores coincidan exactamente | 1-1000; único dentro del contexto | | `TOLERANCE` | Diferencias pequeñas y esperadas | 1-1000; único dentro del contexto | | `DATE_LAG` | Retrasos de fecha entre sistemas | 1-1000; único dentro del contexto | | `FUZZY` | Referencias con puntuación de similitud; siempre se proponen para revisión | 1-1000; único dentro del contexto | ## Paso 5: Activa el contexto *** Mueve el contexto de DRAFT a ACTIVE: Referencia de la API: [Actualizar contexto](/es/reference/products/matcher/update-context) ```bash cURL theme={null} curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "status": "ACTIVE" }' ``` ## Paso 6: Sube los archivos de transacciones *** Sube un archivo por fuente. Matcher acepta los formatos CSV, JSON y XML mediante carga de formulario multipart. * Referencia de la API: [Subir archivo de transacciones](/es/reference/products/matcher/upload-transaction-file) * [Listar trabajos de ingesta](/es/reference/products/matcher/list-ingestion-jobs) ### Sube las transacciones bancarias ```bash cURL theme={null} curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{bankSourceId}/upload" \ -H "Authorization: Bearer $TOKEN" \ -F "file=@bank_transactions.csv" \ -F "format=csv" ``` ### Sube las transacciones del ledger ```bash cURL theme={null} curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{ledgerSourceId}/upload" \ -H "Authorization: Bearer $TOKEN" \ -F "file=@ledger_entries.csv" \ -F "format=csv" ``` Cada carga crea un trabajo de ingesta. Revisa el estado del trabajo: ```bash cURL theme={null} curl -X GET "https://api.matcher.example.com/v1/imports/contexts/{contextId}/jobs" \ -H "Authorization: Bearer $TOKEN" ``` Espera a que ambos trabajos alcancen el estado `COMPLETED` antes de ejecutar la coincidencia. ## Paso 7: Ejecuta la coincidencia *** Empieza con una ejecución de prueba para previsualizar los resultados sin persistirlos: Referencia de la API: [Ejecutar coincidencia](/es/reference/products/matcher/run-match) ```bash cURL theme={null} curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "mode": "DRY_RUN" }' ``` Ambas respuestas incluyen un `runId`. Guárdalo para el paso 8. Revisa los resultados de la ejecución de prueba. Cuando estés conforme, ejecuta con COMMIT para persistir las coincidencias: ```bash cURL theme={null} curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "mode": "COMMIT" }' ``` ## Paso 8: Revisa los resultados *** * Referencia de la API: [Listar grupos de ejecución de coincidencia](/es/reference/products/matcher/list-match-run-groups) * [Deshacer coincidencia de grupo](/es/reference/products/matcher/unmatch-group) ### Consulta los grupos de coincidencia ```bash cURL theme={null} curl -X GET "https://api.matcher.example.com/v1/matching/runs/{runId}/groups?contextId={contextId}" \ -H "Authorization: Bearer $TOKEN" ``` Cada grupo de coincidencia contiene transacciones emparejadas y una puntuación de confianza (0-100): | Puntuación | Qué ocurre | | ----------- | -------------------------------------------------------------- | | 90-100 | Se confirma automáticamente, no requiere ninguna acción | | 60-89 | Requiere revisión manual | | Menos de 60 | No se crea ninguna coincidencia; se convierte en una excepción | ### Deshaz una coincidencia incorrecta Usa el endpoint de deshacer coincidencia para rechazar un grupo de coincidencia `PROPOSED` y devolver sus transacciones al conjunto de transacciones no conciliadas. Para un grupo `CONFIRMED`, Matcher primero verifica que puede revertir los efectos residuales o de partida abierta de esa confirmación. Un deshacer exitoso revierte esos efectos de forma atómica, junto con la revocación del grupo y la devolución de sus transacciones: ```bash cURL theme={null} curl -X DELETE "https://api.matcher.example.com/v1/matching/groups/{matchGroupId}?contextId={contextId}" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "reason": "Transactions belong to different records" }' ``` Si la reversión del grupo confirmado elimina la última contribución activa detrás de una obligación, la partida abierta pasa al estado terminal `WITHDRAWN`: permanece como historial, pero no es neteable ni se traslada a otra ejecución. Si una entrada activa posterior aún actúa sobre el residual, o si una obligación activa más nueva entraría en conflicto al restaurar una partida terminal con la misma identidad, Matcher devuelve `409 Conflict` antes de modificar el grupo, las transacciones o las partidas abiertas. Después de un deshacer exitoso, las transacciones vuelven al conjunto de no conciliadas para la siguiente ejecución. ## Paso 9: Gestiona las excepciones *** Las excepciones son transacciones que Matcher no pudo hacer coincidir automáticamente. Matcher clasifica cada excepción por gravedad: Referencia de la API: [Listar excepciones](/es/reference/products/matcher/list-exceptions) | Gravedad | Criterio | SLA | | ---------- | ------------------------------------- | -------- | | `CRITICAL` | Monto >= 100,000 o antigüedad >= 120h | 24 horas | | `HIGH` | Monto >= 10,000 o antigüedad >= 72h | 72 horas | | `MEDIUM` | Monto >= 1,000 o antigüedad >= 24h | 5 días | | `LOW` | Todos los demás | 7 días | ### Consulta las excepciones ```bash cURL theme={null} curl -X GET "https://api.matcher.example.com/v1/exceptions" \ -H "Authorization: Bearer $TOKEN" ``` Resuelve las excepciones forzando la coincidencia, creando ajustes o enviándolas a sistemas externos configurados, como JIRA, ServiceNow o un webhook HTTP. ## Próximos pasos *** Guía completa de la configuración de contextos y fuentes. Todos los tipos de regla y las opciones de configuración en detalle. Cómo calcula Matcher las puntuaciones y qué significan. Gestiona las transacciones no conciliadas.