Progresso de configuração

​

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

​

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 mapeadas: as que têm um mapeamento de campos, mais as fontes CAMT.053, que são automapeadas (o parser embute o mapeamento ISO 20022 e ignora mapeamentos de campos).
• 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).
• next — a próxima ação de configuração determinística a executar, ou null quando o contexto está pronto (veja abaixo).

​

Prontidão e a checklist

{
  "ready": false,
  "missing": [
    "context.activation.requirement.source-mapping",
    "context.activation.requirement.match-rule"
  ]
}

• 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 não está mapeada: não tem mapeamento de campos e não é uma fonte CAMT.053 automapeada.
• context.activation.requirement.match-rule — o contexto precisa de pelo menos uma regra de matching.
• context.activation.requirement.fee-rule — o contexto habilita a normalização de tarifas, mas não tem nenhuma regra de tarifa. Esse requisito é condicional: só aparece quando feeNormalization está definido (NET ou GROSS) e espelha a precondição de execução, que exige regras de tarifa — não tabelas de tarifas — não vazias.

​

A próxima ação

{
  "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 satisfaz.
• operationId, method, path — o endpoint a chamar para satisfazer o requisito.
• requiredFields — os nomes dos campos que a requisição de criação exige. Eles nunca carregam valores; os valores são fornecidos por você.
• forSource — presente apenas na ação de mapeamento de fonte, indicando a primeira fonte não mapeada para que você preencha {sourceId} sem uma consulta adicional.

​

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 principal pelo next. Em vez de reimplementar a ordem dos requisitos no cliente, chame a operação que o next indica; depois releia o setup-progress para obter a ação seguinte.
3. 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.
4. 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.

​

Códigos de resposta