Pular para o conteúdo principal
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

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

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

​
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

StatusSignificado
200Progresso de configuração retornado
404Contexto não encontrado