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

# Progresso de configuração

> Leia o estado agregado de configuração e prontidão para ativação de um contexto em uma única requisição para conduzir uma checklist de onboarding ou um assistente de configuração.

O endpoint de setup-progress retorna as contagens de recursos configurados, o estado da última execução e a prontidão para ativação de um contexto em um único agregado — para que um assistente de configuração ou uma checklist de onboarding derive seu estado de uma única requisição em vez de várias.

## Obter o progresso de configuração

***

```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": []
  }
}
```

## O que ele retorna

***

* **`status`** — o estado do ciclo de vida do contexto: `DRAFT` (em configuração), `ACTIVE` (em execução), `PAUSED` (suspenso) ou `ARCHIVED` (aposentado).
* **`sources`** — contagens de fontes divididas por lado do matching: `total`, `left`, `right`.
* **`fieldMaps.mappedSources`** — número de fontes que têm um mapeamento de campos configurado.
* **`matchRules.total`** — contagem de regras de matching do contexto.
* **`schedules.total`** — contagem de agendamentos do contexto.
* **`lastRun`** — a execução de matching mais recente (`id`, `status` de `PROCESSING`/`COMPLETED`/`FAILED` e `completedAt`). É `null` quando o contexto nunca foi executado.
* **`readiness`** — resumo da prontidão para ativação (veja abaixo).

## Prontidão e a checklist

***

O bloco `readiness` informa se o contexto satisfaz todos os requisitos de ativação:

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

`missing` contém **slugs estáveis** que você pode mapear para itens de checklist por requisito. Os valores possíveis são:

* `sources_left` — o contexto precisa de pelo menos uma fonte do lado LEFT.
* `sources_right` — o contexto precisa de pelo menos uma fonte do lado RIGHT.
* `field_maps` — as fontes do contexto precisam de mapeamentos de campos configurados.
* `match_rules` — o contexto precisa de pelo menos uma regra de matching.

<Note>Esses slugs são um contrato de API compartilhado com o fluxo de ativação. Quando um contexto é transicionado para `ACTIVE` antes de estar pronto, a atualização é rejeitada com um `409` que carrega os mesmos slugs sob um código `context_not_ready` e um array `details.missing`. Ramifique com base nesses slugs para renderizar exatamente a mesma orientação que você exibe na checklist de configuração.</Note>

## Como usá-lo durante a configuração

***

1. **Renderize a checklist.** A cada passo do assistente, faça um GET no setup-progress e use as contagens (`sources`, `fieldMaps`, `matchRules`, `schedules`) para marcar os itens concluídos.
2. **Controle o botão "Ativar".** Habilite a ativação somente quando `readiness.ready` for `true`; caso contrário, liste `readiness.missing` como os passos restantes.
3. **Mostre a saúde das execuções.** Assim que `lastRun` estiver presente, exiba seu `status` e `completedAt` para que os operadores possam confirmar que o contexto está produzindo resultados.

Como todo o estado vem de uma única chamada, você pode fazer polling nesse endpoint para manter o assistente em tempo real sem orquestrar leituras separadas de fontes, regras e execuções.

## Códigos de resposta

***

| Status | Significado                         |
| ------ | ----------------------------------- |
| `200`  | Progresso de configuração retornado |
| `404`  | Contexto não encontrado             |