Endpoints do dono
A API usa o prefixo /api e o access token da sessão (Authorization: Bearer). Escrita é recusada quando o módulo de checklist está desligado para a rede.
A biblioteca exige a permissão configuracao:editar e, no serviço, papel owner ou admin. O dono vê a rede. O administrador vê a tarefa quando toda atribuição cabe nos locais dele. Se a tarefa ainda não tem atribuição, ele a vê quando é autor de alguma versão.
A revisão exige checklist:aprovar. O dono vê a rede. Quem não é dono vê a execução da sua loja, ou a execução nominal de alguém vinculado a um local seu.
Biblioteca
POST /api/checklists cria a tarefa em rascunho, com a versão 1.
{
"nome": "Abertura da loja",
"atividades": [
{ "titulo": "Geladeira ligada", "tipo": "sim_nao" },
{
"titulo": "Temperatura da câmara",
"tipo": "temperatura",
"faixaMin": 0,
"faixaMax": 5,
"unidade": "°C",
"exigeEvidencia": true
}
]
}
obrigatoria e exigeEvidencia são opcionais. Sem atividades, a criação é recusada.
| Método | Caminho | Efeito |
|---|---|---|
GET | /api/checklists | Lista as tarefas visíveis, com a versão atual e a última publicada. |
GET | /api/checklists/:id | A tarefa e as atividades da versão atual. |
PATCH | /api/checklists/:id | Altera nome, atividades ou os dois. No modelo já publicado, as atividades abrem a versão seguinte. |
POST | /api/checklists/:id/publicar | Congela o rascunho. Devolve versaoId e numero. |
POST | /api/checklists/:id/arquivar | Passa a tarefa para arquivado. |
Atribuição
GET /api/checklists/:id/atribuicoes lista as atribuições visíveis no escopo.
POST /api/checklists/:id/atribuicoes acrescenta uma. Não substitui as anteriores. Na tela, Publicar checklist chama este endpoint para cada par de cargo e local marcado, e para a pessoa e a exceção quando Só uma pessoa está ligado, antes de publicar. Um par igual, com a mesma agenda, não é enviado de novo. Desligar um chip não apaga a atribuição já gravada.
{
"modo": "cargo_local",
"cargo": "store-manager",
"localId": "loja-centro",
"recorrencia": "abertura",
"horarioLimite": "08:00",
"prazoMinutos": 45
}
Para uma pessoa, modo é pessoa e o corpo leva pessoa no lugar de cargo e local. Para tirar alguém de um cargo naquela loja, modo é excecao, com pessoa e origemId da atribuição por cargo. A pessoa precisa estar num local que o autor administra. O dono não tem esse limite.
Revisão
A fila é toda execução concluido do escopo, sem corte de data. Os números e a tabela por loja seguem o período: dias=1 é hoje no fuso da rede, dias=7 são os últimos sete dias. Outro valor cai em um dia.
| Método | Caminho | Efeito |
|---|---|---|
GET | /api/checklists/revisao/contagem | Quantas execuções estão concluido no escopo. |
GET | /api/checklists/revisao?dias=1 | Fila, resumo do período e agrupamento por loja. |
GET | /api/checklists/revisao/:id | Atividades, respostas, evidências e, se houve troca de responsável, a trilha. |
POST | /api/checklists/revisao/:id/aprovar | Só a execução concluido passa para aprovado. |
POST | /api/checklists/revisao/:id/devolver | Grava o comentário, passa para devolvido e marca refazer nas atividades enviadas. |
O corpo da devolução:
{
"comentario": "A foto da vitrine está escura. Tire outra com a luz da loja acesa.",
"atividades": ["cka-…"]
}
O comentário é obrigatório e tem no máximo 500 caracteres. atividades pode ser vazio. Cada id marca a resposta daquela atividade com refazer. Um id que não existe na execução não cria resposta.
Aprovar ou devolver uma execução que não está concluido responde: "Só o checklist enviado entra na revisão." Fora do escopo, a execução é indisponível.
O detalhe traz troca nulo quando ninguém foi removido do cargo no meio da execução. Quando houve devolver_cargo, troca traz quem assumiu, quem devolveu, o motivo cargo ou saida, os papéis e as respostas já dadas até aquele instante. A tela monta a linha do tempo e a auditoria a partir disso.
Planilha
GET /revisao/exportar?dias=1 ou dias=7 é uma rota do app, não da API. Ela baixa o CSV do resumo por loja no período: feitos, total, situação, não conformidade e quantos estão a revisar. A fila completa não entra nessa planilha.