> ## 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 da configuração

> Leia em uma única requisição o estado agregado de configuração e de prontidão para ativação de um contexto, para alimentar um 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. Um assistente de configuração ou checklist de onboarding deriva o estado dele de uma requisição, em vez de várias.

## Obter o progresso da 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": []
  },
  "next": null
}
```

## O que ele retorna

***

* **`status`**: o status do ciclo de vida do contexto: `DRAFT` (em configuração), `ACTIVE` (em execução), `PAUSED` (suspenso) ou `ARCHIVED` (retirado de uso).
* **`sources`**: contagens de fontes divididas por lado da correspondência: `total`, `left`, `right`.
* **`fieldMaps.mappedSources`**: número de fontes **mapeadas**. Essa contagem cobre as fontes com mapa de campo, mais as fontes CAMT.053 automapeadas. Para essas, o parser embute o mapeamento ISO 20022 e ignora os mapas de campo.
* **`matchRules.total`**: número de regras de correspondência do contexto.
* **`schedules.total`**: número de agendamentos do contexto.
* **`lastRun`**: a execução de correspondência mais recente (`id`, `status` entre `PROCESSING`/`COMPLETED`/`FAILED` e `completedAt`). É `null` quando o contexto nunca rodou.
* **`readiness`**: resumo da prontidão para ativação (veja abaixo).
* **`next`**: a próxima ação determinística de configuração a executar, ou `null` quando o contexto está pronto (veja abaixo).

## Prontidão e o checklist

***

O bloco `readiness` informa se o contexto atende cada requisito de ativação:

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

`missing` guarda **identificadores públicos e estáveis de requisito de ativação** que você pode mapear para itens do checklist. Os valores possíveis são:

* `context.activation.requirement.left-source`: o contexto precisa de pelo menos uma fonte do lado LEFT.
* `context.activation.requirement.right-source`: o contexto precisa de pelo menos uma fonte do lado RIGHT.
* `context.activation.requirement.source-mapping`: pelo menos uma fonte está sem mapeamento: ela não tem mapa de campo e não é uma fonte CAMT.053 automapeada.
* `context.activation.requirement.match-rule`: o contexto precisa de pelo menos uma regra de correspondência.
* `context.activation.requirement.fee-rule`: o contexto habilita a normalização de tarifas, mas não tem regra de tarifa. Esse requisito é **condicional**. Ele aparece apenas quando você define `feeNormalization` como `NET` ou `GROSS`. Ele espelha a precondição de execução, que exige que as **regras** de tarifa, não as tabelas de tarifas, não estejam vazias.

<Note>Se você mover um contexto para `ACTIVE` antes de ele estar pronto, a atualização falha com `409 Conflict` e o código `MTCH-0103`. Os problem details dela listam os mesmos identificadores públicos de requisito de ativação. Use-os, ou releia o progresso da configuração, para mostrar a orientação de configuração restante.</Note>

## A próxima ação

***

`next` transforma `readiness.missing` em uma chamada concreta. Ele vem de `missing[0]`, o primeiro requisito não atendido na ordem estável acima. É `null` quando o contexto está pronto:

```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`**: o identificador público de requisito de ativação que essa ação atende.
* **`operationId`**, **`method`**, **`path`**: o endpoint a chamar para atender o requisito.
* **`requiredFields`**: os **nomes** dos campos que a requisição de criação exige. Eles nunca carregam valores. Você os fornece.
* **`forSource`**: presente apenas na ação de mapeamento de fonte, nomeando a primeira fonte sem mapeamento para você preencher `{sourceId}` sem uma consulta separada.

A tabela completa de requisito para ação:

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

Os dois requisitos de lado da fonte resolvem para a mesma operação `createSource`. O campo `side` é o que distingue um do outro.

## Como usar durante a configuração

***

1. **Monte o checklist.** Em cada passo do assistente, faça GET no setup-progress e use as contagens (`sources`, `fieldMaps`, `matchRules`, `schedules`) para marcar os itens concluídos.
2. **Comande o botão principal pelo `next`.** Não reimplemente a ordem dos requisitos no cliente. Chame a operação que `next` nomeia. Depois releia o setup-progress para saber a próxima ação.
3. **Controle o botão "Ativar".** Habilite a ativação apenas quando `readiness.ready` for `true`. Caso contrário, liste `readiness.missing` como os passos restantes.
4. **Mostre a saúde das execuções.** Quando `lastRun` estiver presente, mostre o `status` e o `completedAt` dele para que os operadores confirmem que o contexto produz resultados.

Todo o estado vem de uma chamada. Você pode fazer polling neste endpoint para manter o assistente atualizado, sem leituras separadas de fonte, de regra e de execução.

## Códigos de resposta

***

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