> ## 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

<Tip>
  **Esta guía está dirigida a desarrolladores.** Si buscas una visión general a nivel de negocio de lo que hace Matcher y cómo ayuda a tu equipo, consulta [¿Qué es Matcher?](/es/matcher/what-is-matcher).
</Tip>

Pon Matcher en funcionamiento en minutos. Esta guía recorre el camino completo, desde la creación del primer contexto de conciliación hasta la revisión de transacciones conciliadas.

## Antes de comenzar

***

Necesitas:

* Una instancia de Matcher en ejecución
* Un token JWT válido para 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: Crear un contexto de conciliación

***

Un contexto define el alcance de tu conciliación: qué estás comparando y cómo.

<Tip>
  Referencia de API: [Crear contexto](/es/reference/matcher/create-context)
</Tip>

```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 se parean las transacciones:

| Tipo  | Descripción                                                |
| ----- | ---------------------------------------------------------- |
| `1:1` | Cada transacción coincide con exactamente una contraparte  |
| `1:N` | Una transacción puede coincidir con múltiples contrapartes |
| `N:M` | Múltiples transacciones pueden coincidir entre ambos lados |

Guarda el `id` de la respuesta. Lo usarás en todos los pasos siguientes.

```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"
}
```

<Info>
  El contexto inicia con estado DRAFT. Cambia a ACTIVE cuando esté listo para ejecutar la conciliación.
</Info>

## Paso 2: Agregar fuentes de datos

***

Todo contexto necesita al menos dos fuentes: los sistemas cuyas transacciones deseas comparar.

<Tip>
  Referencia de API: [Crear fuente](/es/reference/matcher/create-source)
</Tip>

### Crear 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"
 }'
```

### Crear 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 valores de `id` de ambas fuentes.

### Tipos de fuente

| Tipo      | Caso de uso                        |
| --------- | ---------------------------------- |
| `BANK`    | Extractos bancarios                |
| `LEDGER`  | Libro mayor / exportaciones de ERP |
| `GATEWAY` | Datos de procesadores de pago      |
| `CUSTOM`  | Cualquier otra fuente de datos     |

## Paso 3: Mapear campos de las fuentes

***

Tus archivos de origen probablemente usan nombres de columna diferentes a los que Matcher espera. Los mapas de campos los traducen al schema estándar de Matcher.

<Tip>
  Referencia de API: [Crear mapa de campos](/es/reference/matcher/create-field-map)
</Tip>

### Mapear 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"
   }
 }'
```

### Mapear 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

Toda transacción debe tener estos campos después del mapeo:

| Campo            | Tipo    | Descripción                             |
| ---------------- | ------- | --------------------------------------- |
| `transaction_id` | String  | Identificador único dentro de la fuente |
| `amount`         | Decimal | Monto de la transacción                 |
| `currency`       | String  | Código ISO 4217 (ej.: USD, BRL)         |
| `date`           | Date    | Fecha de la transacción (YYYY-MM-DD)    |

**Opcional pero recomendado:** `reference` (referencia externa o descripción).

## Paso 4: Crear reglas de match

***

Las reglas definen cómo Matcher compara transacciones. Comienza con una regla exact, que es la más precisa.

<Tip>
  Referencia de API: [Crear regla de match](/es/reference/matcher/create-match-rule)
</Tip>

### Crear regla exact

```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"
   }
 }'
```

### Agregar regla tolerance como fallback

Captura pequeñas diferencias como comisiones bancarias o redondeo:

```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
   }
 }'
```

<Tip>
  Matcher evalúa reglas por prioridad (número menor primero). La regla exact se ejecuta primero. Solo las transacciones sin match pasan a la regla tolerance.
</Tip>

### Tipos de regla

| Tipo        | Cuándo usar                             | Rango de prioridad |
| ----------- | --------------------------------------- | ------------------ |
| `EXACT`     | Los valores deben coincidir exactamente | 1-10               |
| `TOLERANCE` | Pequeñas diferencias esperadas          | 11-50              |
| `DATE_LAG`  | Retrasos de fecha entre sistemas        | 51-100             |

## Paso 5: Activar el contexto

***

Mueve el contexto de DRAFT a ACTIVE:

<Tip>
  Referencia de API: [Actualizar contexto](/es/reference/matcher/update-context)
</Tip>

```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: Subir archivos de transacciones

***

Sube un archivo por fuente. Matcher acepta formatos CSV, JSON y XML mediante upload multipart.

<Tip>
  * Referencia de API: [Subir archivo de transacciones](/es/reference/matcher/upload-transaction-file)
  * [Listar jobs de ingestión](/es/reference/matcher/list-ingestion-jobs)
</Tip>

### Subir 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"
```

### Subir 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 upload crea un job de ingestión. Verifica el estado del job:

```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 jobs alcancen el estado `COMPLETED` antes de ejecutar el matching.

## Paso 7: Ejecutar el matching

***

Comienza con un dry run para previsualizar resultados sin persistir:

<Tip>
  Referencia de API: [Ejecutar match](/es/reference/matcher/run-match)
</Tip>

```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 del dry run. Cuando estés satisfecho, ejecuta con COMMIT para persistir los matches:

```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: Revisar resultados

***

<Tip>
  * Referencia de API: [Listar grupos de match](/es/reference/matcher/list-match-run-groups)
  * [Deshacer match](/es/reference/matcher/unmatch-group)
</Tip>

### Ver grupos de match

```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 match contiene transacciones pareadas y un puntaje de confianza (0-100):

| Puntaje    | Qué sucede                                     |
| ---------- | ---------------------------------------------- |
| 90-100     | Auto-confirmado, ninguna acción necesaria      |
| 60-89      | Necesita revisión manual                       |
| Menor a 60 | Ningún match creado, se convierte en excepción |

### Deshacer un match incorrecto

Usa el endpoint de unmatch para rechazar un grupo de match y devolver las transacciones al pool de no conciliadas:

```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": "Las transacciones pertenecen a registros diferentes"
 }'
```

Las transacciones rechazadas regresan al pool de no conciliadas para la próxima ejecución.

## Paso 9: Manejar excepciones

***

Las excepciones son transacciones que no pudieron ser conciliadas automáticamente. Matcher clasifica cada excepción por severidad:

<Tip>
  Referencia de API: [Listar excepciones](/es/reference/matcher/list-exceptions)
</Tip>

| Severidad  | Criterio                        | SLA      |
| ---------- | ------------------------------- | -------- |
| `CRITICAL` | Monto >= 100.000 o edad >= 120h | 24 horas |
| `HIGH`     | Monto >= 10.000 o edad >= 72h   | 72 horas |
| `MEDIUM`   | Monto >= 1.000 o edad >= 24h    | 5 días   |
| `LOW`      | Todas las demás                 | 7 días   |

### Listar excepciones

```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/exceptions" \
 -H "Authorization: Bearer $TOKEN"
```

Resuelve excepciones forzando un match, creando ajustes o despachando a sistemas externos como JIRA.

## Próximos pasos

***

<CardGroup cols={2}>
  <Card title="Contextos y fuentes" icon="database" href="/es/matcher/configuration/matcher-contexts-and-sources">
    Guía completa de configuración de contextos y fuentes.
  </Card>

  <Card title="Reglas de match" icon="scale-balanced" href="/es/matcher/configuration/matcher-match-rules">
    Todos los tipos de regla y opciones de configuración en detalle.
  </Card>

  <Card title="Puntuación de confianza" icon="chart-simple" href="/es/matcher/reference/matcher-confidence-scoring">
    Cómo se calculan los puntajes y qué significan.
  </Card>

  <Card title="Resolver excepciones" icon="triangle-exclamation" href="/es/matcher/daily-reconciliation/matcher-resolving-exceptions">
    Maneja transacciones no conciliadas.
  </Card>
</CardGroup>