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

---

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

{
  "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:

{
  "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.

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.

​

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:

{
  "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