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

# Progreso de configuración

> Lee el estado de configuración y disponibilidad de activación de un contexto en una sola solicitud para impulsar una checklist de onboarding o un wizard.

El endpoint de setup-progress devuelve los recuentos de recursos configurados, el estado de la última ejecución y la disponibilidad de activación de un contexto en un solo agregado, de modo que un asistente de configuración o una lista de verificación de onboarding deriva su estado de una sola solicitud en lugar de muchas.

## Obtener el progreso de configuración

***

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

```json theme={null}
{
  "contextId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "DRAFT",
  "sources": { "total": 2, "left": 1, "right": 1 },
  "fieldMaps": { "mappedSources": 2 },
  "matchRules": { "total": 3 },
  "schedules": { "total": 1 },
  "lastRun": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "completedAt": "2025-01-15T10:30:00Z"
  },
  "readiness": {
    "ready": true,
    "missing": []
  },
  "next": null
}
```

## Qué devuelve

***

* **`status`** — el estado del ciclo de vida del contexto: `DRAFT` (en configuración), `ACTIVE` (en ejecución), `PAUSED` (suspendido) o `ARCHIVED` (retirado).
* **`sources`** — recuentos de fuentes divididos por lado de conciliación: `total`, `left`, `right`.
* **`fieldMaps.mappedSources`** — número de fuentes **mapeadas**: las que tienen un mapeo de campos, más las fuentes CAMT.053, que se automapean (el parser incorpora el mapeo ISO 20022 e ignora los mapeos de campos).
* **`matchRules.total`** — recuento de reglas de conciliación del contexto.
* **`schedules.total`** — recuento de programaciones del contexto.
* **`lastRun`** — la ejecución de conciliación más reciente (`id`, `status` de `PROCESSING`/`COMPLETED`/`FAILED` y `completedAt`). Es `null` cuando el contexto nunca se ha ejecutado.
* **`readiness`** — resumen de disponibilidad de activación (ver más abajo).
* **`next`** — la siguiente acción de configuración determinista a ejecutar, o `null` cuando el contexto está listo (ver más abajo).

## Disponibilidad y la lista de verificación

***

El bloque `readiness` indica si el contexto cumple todos los requisitos de activación:

```json theme={null}
{
  "ready": false,
  "missing": ["field_maps", "match_rules"]
}
```

`missing` contiene **slugs estables** que puedes asignar a elementos de la lista de verificación por requisito. Los valores posibles son:

* `sources_left` — el contexto necesita al menos una fuente del lado LEFT.
* `sources_right` — el contexto necesita al menos una fuente del lado RIGHT.
* `field_maps` — al menos una fuente no está mapeada: no tiene mapeo de campos y no es una fuente CAMT.053 automapeada.
* `match_rules` — el contexto necesita al menos una regla de conciliación.
* `fee_rules` — el contexto habilita la normalización de comisiones pero no tiene ninguna regla de comisión. Este requisito es **condicional**: solo aparece cuando `feeNormalization` está definido (`NET` o `GROSS`) y refleja la precondición de ejecución, que exige que las **reglas** de comisión — no los esquemas de comisiones — no estén vacías.

<Note>Cuando un contexto pasa a `ACTIVE` antes de estar listo, la actualización se rechaza con el `409` genérico de estado de configuración no válido. Esa respuesta no incluye los slugs faltantes. Vuelve a consultar el progreso de configuración después del conflicto y usa `readiness.missing` para mostrar las indicaciones de configuración pendientes.</Note>

## La siguiente acción

***

`next` convierte `readiness.missing` en una llamada concreta. Se deriva de `missing[0]` — el primer requisito no satisfecho en el orden estable de arriba — y es `null` cuando el contexto está listo:

```json theme={null}
{
  "slug": "field_maps",
  "action": "add_field_map",
  "operationId": "createFieldMap",
  "method": "POST",
  "path": "/v1/contexts/{contextId}/sources/{sourceId}/field-maps",
  "requiredFields": ["mapping"],
  "forSource": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Bank statement"
  }
}
```

* **`slug`** — el slug de disponibilidad que satisface esta acción.
* **`action`** — una etiqueta semántica estable sobre la que puedes basar los textos de la interfaz.
* **`operationId`**, **`method`**, **`path`** — el endpoint que debes llamar para satisfacer el requisito.
* **`requiredFields`** — los **nombres** de los campos que exige esa solicitud de creación. Nunca llevan valores; tú los proporcionas.
* **`forSource`** — presente solo en la acción `field_maps`, indicando la primera fuente sin mapear para que completes `{sourceId}` sin una consulta adicional.

La tabla completa de slug a acción:

| `slug`          | `action`           | Endpoint                                                      | `requiredFields`                |
| --------------- | ------------------ | ------------------------------------------------------------- | ------------------------------- |
| `sources_left`  | `add_left_source`  | `POST /v1/contexts/{contextId}/sources`                       | `name`, `type`, `side`          |
| `sources_right` | `add_right_source` | `POST /v1/contexts/{contextId}/sources`                       | `name`, `type`, `side`          |
| `field_maps`    | `add_field_map`    | `POST /v1/contexts/{contextId}/sources/{sourceId}/field-maps` | `mapping`                       |
| `match_rules`   | `add_match_rule`   | `POST /v1/contexts/{contextId}/rules`                         | `priority`, `type`, `config`    |
| `fee_rules`     | `add_fee_rule`     | `POST /v1/contexts/{contextId}/fee-rules`                     | `side`, `feeScheduleId`, `name` |

Las dos acciones de fuente resuelven a la misma operación `createSource` — el campo `side` es lo que las distingue.

## Cómo usarlo durante la configuración

***

1. **Renderiza la lista de verificación.** En cada paso del asistente, haz un GET a setup-progress y usa los recuentos (`sources`, `fieldMaps`, `matchRules`, `schedules`) para marcar los elementos completados.
2. **Controla el botón principal con `next`.** En lugar de reimplementar el orden de los requisitos en el cliente, llama a la operación que indica `next`; después vuelve a leer setup-progress para obtener la acción siguiente.
3. **Controla el botón "Activate".** Habilita la activación solo cuando `readiness.ready` sea `true`; de lo contrario, lista `readiness.missing` como los pasos restantes.
4. **Muestra el estado de las ejecuciones.** Una vez que `lastRun` esté presente, muestra su `status` y `completedAt` para que los operadores puedan confirmar que el contexto está produciendo resultados.

Como todo el estado proviene de una sola llamada, puedes hacer polling a este endpoint para mantener el asistente en tiempo real sin orquestar lecturas separadas de fuentes, reglas y ejecuciones.

## Códigos de respuesta

***

| Estado | Significado                        |
| ------ | ---------------------------------- |
| `200`  | Progreso de configuración devuelto |
| `404`  | Contexto no encontrado             |