Metas

Metas e indicadores por departamento, com progresso calculado a partir de leituras (check-ins) ao longo do ciclo. A API de parceiro é leitura + registro de leitura — a criação e edição da meta em si (título, valor-alvo, ciclo) fica no painel administrativo, já que envolve decisões de planejamento. O uso típico é uma integração externa (ex.: um sistema de BI ou uma planilha de indicadores) registrando a leitura mais recente de uma métrica.

Plano Gestão Escolar (ERP): os endpoints desta página respondem somente para clientes do plano Gestão Escolar (ERP), como no sistema web. Para clientes do plano simplificado, a resposta é 403 com "code": "ERP_REQUIRED".

O modelo meta

rag_status (Red/Amber/Green) é calculado a cada leitura a partir do progresso vs. o tempo decorrido do ciclo — nunca armazenado.

id uuid

Identificador único da meta.

title string

Título da meta.

description string|null

Descrição livre.

metric_source string|null

Fonte automática do indicador, quando vinculada a um dado do sistema (ex.: taxa de frequência).

unit string

Unidade do valor (ex.: "%", "R$").

start_value decimal

Valor inicial no começo do ciclo.

target_value decimal

Valor-alvo.

current_value decimal

Valor mais recente registrado.

direction string

"increase" (quanto maior, melhor) ou "decrease".

progress_pct number

Percentual de progresso rumo ao alvo.

time_pct number

Percentual do ciclo já decorrido.

rag_status string

green, amber ou red.

cycle_label string

anual, semestral, bimestral ou personalizado.

start_date date

Início do ciclo.

end_date date

Fim do ciclo.

status string

active, completed, archived ou canceled.

department object|null

id e name do departamento (quando carregado).

responsible_user object|null

id e name do responsável pela meta (quando carregado).

latest_check_in object|null

A leitura mais recente, no formato do modelo de leitura abaixo (quando carregado).

notes string|null

Observações livres.

created_at datetime

Data de criação.

Modelo meta 
{
  "id": "g0a1l2s3-0000-0000-0000-000000000001",
  "title": "Taxa de presença acima de 90%",
  "unit": "%",
  "target_value": "90.00",
  "current_value": "82.00",
  "direction": "increase",
  "progress_pct": 73.3,
  "rag_status": "amber",
  "cycle_label": "anual",
  "start_date": "2026-01-01",
  "end_date": "2026-12-31",
  "status": "active"
}
GET /v1/partners/school/{cnpj}/goals/all

Listar metas

Retorna todas as metas da escola, mais recentes primeiro.

Códigos de resposta

200

Sucesso.

404

Escola não encontrada.

Requisição GET
GET /api/v1/partners/school/{cnpj}/goals/all
Resposta 
{
  "message": "Escola não encontrada."
}
GET /v1/partners/school/{cnpj}/goal/{id}

Obter uma meta

Retorna uma meta específica, incluindo sua leitura mais recente.

Códigos de resposta

200

Sucesso.

404

Meta não encontrada.

Requisição GET
GET /api/v1/partners/school/{cnpj}/goal/{id}
Resposta 
{
  "message": "Meta não encontrada."
}
POST /v1/partners/school/{cnpj}/goal/{id}/check-in

Registrar leitura

Registra uma nova leitura do indicador e atualiza current_value da meta. Toda leitura via esta API é marcada com source_type: "automatic", distinguindo-a das leituras digitadas manualmente no painel.

Corpo da requisição

value decimal obrigatório

Valor lido para o indicador.

note string opcional

Observação sobre esta leitura (até 1000 caracteres).

recorded_at datetime opcional

Data/hora da leitura. Padrão: agora.

Códigos de resposta

201

Leitura registrada.

422

Erro de validação.

404

Meta não encontrada.

Requisição POST
POST /api/v1/partners/school/{cnpj}/goal/{id}/check-in

{ "value": 95, "note": "Atualização mensal" }
Resposta 
{
  "id": "...",
  "value": "95.00",
  "source_type": "automatic",
  "note": "Atualização mensal",
  "recorded_at": "2026-09-02 16:00:00"
}