> ## 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 la configuración

> Lee en una sola solicitud el estado agregado de configuración y de preparación para la activación de un contexto, para alimentar una lista de verificación de incorporación o un asistente de configuración.

El endpoint setup-progress devuelve los conteos de recursos configurados, el estado de la última ejecución y la preparación para la activación de un contexto en un solo agregado. Un asistente de configuración o una lista de verificación de incorporación deriva su estado de una sola solicitud en lugar de muchas.

## Obtener el progreso de la 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`**: conteos de fuentes divididos por lado de coincidencia: `total`, `left`, `right`.
* **`fieldMaps.mappedSources`**: número de fuentes **mapeadas**. Este conteo cubre las fuentes con un mapa de campos, más las fuentes CAMT.053 automapeadas. Para esas, el parser incorpora el mapeo ISO 20022 e ignora los mapas de campos.
* **`matchRules.total`**: cantidad de reglas de coincidencia del contexto.
* **`schedules.total`**: cantidad de programaciones del contexto.
* **`lastRun`**: la ejecución de coincidencia más reciente (`id`, `status` de `PROCESSING`/`COMPLETED`/`FAILED` y `completedAt`). Es `null` cuando el contexto nunca se ejecutó.
* **`readiness`**: resumen de la preparación para la activación (ver abajo).
* **`next`**: la siguiente acción de configuración determinista que se debe tomar, o `null` cuando el contexto está listo (ver abajo).

## Preparación y la lista de verificación

***

El bloque `readiness` informa si el contexto cumple cada requisito de activación:

```json theme={null}
{
  "ready": false,
  "missing": [
    "context.activation.requirement.source-mapping",
    "context.activation.requirement.match-rule"
  ]
}
```

`missing` contiene **identificadores públicos estables de requisitos de activación** que puedes asociar a ítems de la lista de verificación. Los valores posibles son:

* `context.activation.requirement.left-source`: el contexto necesita al menos una fuente del lado LEFT.
* `context.activation.requirement.right-source`: el contexto necesita al menos una fuente del lado RIGHT.
* `context.activation.requirement.source-mapping`: al menos una fuente no tiene mapeo: no tiene mapa de campos y no es una fuente CAMT.053 automapeada.
* `context.activation.requirement.match-rule`: el contexto necesita al menos una regla de coincidencia.
* `context.activation.requirement.fee-rule`: el contexto habilita la normalización de comisiones pero no tiene ninguna regla de comisión. Este requisito es **condicional**. Aparece solo cuando configuras `feeNormalization` en `NET` o `GROSS`. Refleja la precondición de la ejecución, que exige que las **reglas** de comisión, no las tablas de comisiones, no estén vacías.

<Note>Si mueves un contexto a `ACTIVE` antes de que esté listo, la actualización falla con `409 Conflict` y el código `MTCH-0103`. Sus detalles de problema listan los mismos identificadores públicos de requisitos de activación. Úsalos, o vuelve a leer el progreso de la configuración, para mostrar la guía de configuración restante.</Note>

## La siguiente acción

***

`next` convierte `readiness.missing` en una llamada concreta. Proviene de `missing[0]`, el primer requisito sin cumplir en el orden estable de arriba. Es `null` cuando el contexto está listo:

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

* **`requirementId`**: el identificador público de requisito de activación que esta acción cumple.
* **`operationId`**, **`method`**, **`path`**: el endpoint que se debe llamar para cumplir el requisito.
* **`requiredFields`**: los **nombres** de los campos que la solicitud de creación exige. Nunca llevan valores. Esos los aportas tú.
* **`forSource`**: presente solo para la acción de mapeo de fuente, y nombra la primera fuente sin mapear para que puedas completar `{sourceId}` sin una búsqueda aparte.

La tabla completa de requisito a acción:

| `requirementId`                                 | Endpoint                                                      | `requiredFields`                |
| ----------------------------------------------- | ------------------------------------------------------------- | ------------------------------- |
| `context.activation.requirement.left-source`    | `POST /v1/contexts/{contextId}/sources`                       | `name`, `type`, `side`          |
| `context.activation.requirement.right-source`   | `POST /v1/contexts/{contextId}/sources`                       | `name`, `type`, `side`          |
| `context.activation.requirement.source-mapping` | `POST /v1/contexts/{contextId}/sources/{sourceId}/field-maps` | `mapping`                       |
| `context.activation.requirement.match-rule`     | `POST /v1/contexts/{contextId}/rules`                         | `priority`, `type`, `config`    |
| `context.activation.requirement.fee-rule`       | `POST /v1/contexts/{contextId}/fee-rules`                     | `side`, `feeScheduleId`, `name` |

Ambos requisitos de lado de fuente se resuelven en la misma operación `createSource`. El campo `side` es lo que los distingue.

## Cómo usarlo durante la configuración

***

1. **Muestra la lista de verificación.** En cada paso del asistente, haz un GET a setup-progress y usa los conteos (`sources`, `fieldMaps`, `matchRules`, `schedules`) para marcar los ítems completados.
2. **Controla el botón principal desde `next`.** No reimplementes el orden de los requisitos del lado del cliente. Llama a la operación que `next` nombra. Después vuelve a leer setup-progress para la siguiente acción.
3. **Condiciona el botón "Activate".** Habilita la activación solo cuando `readiness.ready` sea `true`. Si no, lista `readiness.missing` como los pasos restantes.
4. **Muestra la salud de la ejecución.** Una vez que `lastRun` está presente, expón su `status` y `completedAt` para que los operadores confirmen que el contexto produce resultados.

Todo el estado viene de una sola llamada. Puedes consultar este endpoint de forma periódica para mantener el asistente al día, sin lecturas aparte de fuentes, reglas y ejecuciones.

## Códigos de respuesta

***

| Estado | Significado                                 |
| ------ | ------------------------------------------- |
| `200`  | Se devolvió el progreso de la configuración |
| `404`  | Contexto no encontrado                      |