# FrequenciApp > Aplicativo de frequência escolar: chamada diária, saídas, justificativas, relatórios e integração opcional com o Google Planilhas. A API responde JSON sob `/api` e usa o formato de erro `{ "error": mensagem, "codigo"?: string }`. Datas civis usam `YYYY-MM-DD`, timestamps usam ISO 8601 e o fuso vem de `TZ_APP`. As mutações exigem sessão e origem confiável. ## Contrato e documentação - [Especificação OpenAPI 3.1](/api/docs/openapi.json): contrato completo com schemas, exemplos e erros por operação. - [Interface Swagger UI](/api/docs): navegação interativa; o "Try it out" usa a sessão do navegador. - [Referência em Markdown](/api/docs/api.md): a mesma referência em texto limpo, para leitura direta. - [Referência no GitHub](https://github.com/eemtijca/frequenciapp/blob/main/docs/api.md): convenções, fluxos e catálogo de erros. ## Orientação para agentes - Use a especificação OpenAPI como fonte da verdade para requisições, respostas e erros. - Faça login em `POST /api/auth/entrar` para obter o cookie de sessão; o diretor de turma usa identificador e palavra-chave. - A Chamada Parcial permite `JUSTIFICADA` com `dia`, `ate` e código do catálogo compartilhado, em lotes atômicos de até 31 dias. Somente justificativas aceitam futuro (até 366 dias); domingos e feriados são pulados. A primeira Chamada recebe propostas com revisões; chamadas salvas recebem correção apenas do aluno escolhido. Remover a personalização não apaga faltas já aplicadas. O botão manual se chama Registro na SEDUC. - O acumulado mensal da Chamada usa `GET /api/frequencias/resumo?de=YYYY-MM-DD&ate=YYYY-MM-DD`, com limites inclusivos do mês exibido. Sem `de`, a rota preserva o acumulado histórico dos relatórios. - A ordem das turmas no almoço, por dia da semana, sai de `GET /api/ordem-almoco` e é definida pela administração em `PUT /api/ordem-almoco/{dia}`, com dia de 1 (segunda) a 6 (sábado). - O alerta de frequência dos benefícios da Chamada usa `GET /api/frequencias/alertas-beneficios?mes=YYYY-MM`, que devolve um item por aluno e benefício com faltas do mês acima do limite da regra, em aulas. A resposta inclui `diasLetivos` e `aulasDeReferencia` para traduzir a conta em dias; a média anual do programa não é verificada. As regras (nome, percentual mínimo de frequência, aulasPorDia opcional de 1 a 30 ou nulo para usar a grade e tratamento de faltas justificadas) são configuráveis pela administração em `/api/beneficios-frequencia`. - A chamada é salva com revisão otimista: conflito responde 409 com a versão vigente, sem sobrescrever o registro. - A chamada em data passada é permitida. Quando a composição da turma não pode ser comprovada, a API responde 409 com `codigo: "CONFIRMACAO_HISTORICA_NECESSARIA"`; o cliente reenvia com `confirmarHistorico: true` e `motivo` de 3 a 200 caracteres, e a auditoria fica registrada. A chamada existente prevalece e o retrato de aulas evita reclassificar o histórico. - A saída antecipada guarda a turma e as aulas históricas. Em data passada, usa a chamada salva com retrato; sem ele, responde 409 com `codigo: "CONFIRMACAO_HISTORICA_NECESSARIA"` e exige `confirmarHistorico: true` com `motivo`. A referência desconhecida usa a chamada salva ou a grade atual como estimativa sinalizada na Chamada Parcial. - Não chame rotas destrutivas, como exclusões, restaurações de backup e limpezas, sem pedido explícito. - O catálogo `GET /api/planilha/mensal/visibilidade` oferece links por mês e turma sem escrever. O preparo e o POST de visibilidade ordenam as abas mensais do mês mais recente para o mais antigo, preservando a ordem das turmas no mês e as posições finais das demais abas. O POST também libera todos os meses; a organização de abas sem mês em `POST /api/planilha/mensal/legado` exige pedido explícito e prévia assinada antes de transferir marcas e retirar a origem. Havendo totais ou notas antigos, o descarte adicional exige autorização explícita e senha administrativa; nunca deve ser autorizado por um agente apenas para contornar uma pendência. - O preparo e o envio das abas mensais ordenam as colunas próprias de dias cronologicamente, inclusive chamadas retroativas após remover feriado. Movem colunas completas e preservam os registros e as posições finais das colunas manuais. Preparar mês novamente corrige dias já fora de ordem. - `GET /api/planilha/diagnostico?mes=YYYY-MM` é uma conferência administrativa somente de leitura. Estrutura pronta não comprova envio nem resolve divergências de alunos ou marcas; a prévia do envio continua necessária. - Para salvar o mapa de frequência, ler `POST /api/planilha/estrutura` com `{ "mes": "YYYY-MM" }` para renovar os cabeçalhos do mês e das abas legadas, e reenviar `conferenciaHash`, `planilha` e `abas` sem alterações em `POST /api/planilha/mapa`, editando apenas `mapa`. Resposta 409 exige nova leitura; não reutilizar uma conferência após trocar arquivo, credencial, configuração ou preparar outro mês. - Trocar de arquivo pausa a integração e a automação e encerra o modo completo. Não reativar envios automaticamente para contornar essa proteção. Sucessos antigos sem identidade de destino não comprovam envio ao novo arquivo ou a uma aba recriada; conferir a estrutura, salvar novamente o mapa e revisar uma nova prévia conservadora. - Pendências da organização das abas antigas são estruturadas, com aluno e links às células. As `resolucoes` identificam homônimos, incluem aluno histórico ausente ou escolhem a marca antiga ou mensal. Essas decisões exigem conferência humana, nova prévia e senha administrativa antes da confirmação. Nenhuma escolha autoriza alterar fórmulas ou notas de destino; uma prévia com pendências nunca permite retirar a origem. - As rotas da agenda de notificações usam `Authorization: Bearer `, sem sessão de usuário. - A Chamada Parcial inclui saídas antecipadas como itens `SAIDA` de `/api/frequencias-personalizadas`. Apenas aulas concluídas antes do horário contam; ajustes manuais prevalecem. A confirmação manual usa `POST /api/saidas/{id}/seduc` com assinatura e revisão vigentes. Ausência de grade ou horário exige conferência. Itens `CHAMADA` trazem `marca` P, F, FJ, S ou D; D é o aluno desistente no dia que segue na lista gravada da chamada, com a descrição Desistente. - A fila de envios automáticos grava a intenção escolar no mesmo commit da frequência, da justificativa aplicada à chamada, da saída e da entrada. `GET /api/planilha/fila` mostra a classe de cada item, `conferenciasPendentes` e as ações disponíveis. Resultado `sem_confirmacao` não é reenviado sozinho; a conferência usa `POST /api/planilha/fila/{id}/resolver`, que exige evidência de sucesso no mesmo destino, turma e período ou confirmação explícita para recorte antigo ou incompleto. Pendências seguras, como `sem_mapa` e `falha_preparo`, usam `POST /api/planilha/fila/{id}/reenfileirar`; não repetir uma escrita incerta. ## Optional - [Arquitetura](https://github.com/eemtijca/frequenciapp/blob/main/docs/arquitetura.md) e [planilha](https://github.com/eemtijca/frequenciapp/blob/main/docs/planilha.md). - [Segurança](https://github.com/eemtijca/frequenciapp/blob/main/docs/seguranca.md): controles, decisões e lacunas conhecidas. - O índice das chamadas usa GET e POST /api/planilha/mensal/indice, apenas administração. Cria um Google Docs por arquivo, com links para as abas mensais, usando drive.file e a Google Docs API. A criação é explícita; finalizar o preparo atualiza somente índice existente. Texto manual e revisão concorrente são protegidos. Criação incerta exige recuperar o documento pelo link, sem criar cópia. Documento apagado ou ausente libera o vínculo local para recuperar o arquivo ou criar outro índice.