Entrar Agendar demonstração

Documentação

Referência de API

Todos os endpoints REST, o modelo de autenticação, os papéis e os eventos Socket.io em tempo real — fiel ao backend em produção.

Convenções

  • Base: https://mathmaker.tricagono.com (todos os caminhos abaixo são relativos a essa base).
  • Formato: JSON em application/json. Erros retornam { "erro": "mensagem" }.
  • Autenticação web: cookie de sessão mathmaker.sid (httpOnly). O cliente usa credentials: 'include' e nunca lê o cookie diretamente.
  • Autenticação do tablet: headers x-bancada-id e x-kiosk-token (token kiosk da bancada).
  • Papéis: superadmin (Tricagono), admin (escola) e professor. Cada papel determina o escopo de leitura/escrita.
  • Multi-tenant: o escopo da escola (tenant) é derivado da sessão ou do token; os dados nunca cruzam entre escolas.
  • Paginação: listagens aceitam ?limit= e ?offset= (máximo 500 por página).

Autenticação — /api/auth

MétodoCaminhoAcessoDescrição
POST/api/auth/loginPúblicoAutentica com { email, senha } e retorna o usuário público.
POST/api/auth/logoutAutenticadoEncerra a sessão e retorna { ok: true }.
GET/api/auth/meAutenticadoRetorna o usuário autenticado atual.

O usuário público tem a forma { id, nome, email, papel, tenantId }.

Tenants — /api/tenants superadmin

MétodoCaminhoDescrição
GET/api/tenantsLista as escolas.
POST/api/tenantsCria uma escola com { nome, slug }.
GET/api/tenants/:idDetalha uma escola.

Usuários — /api/users

MétodoCaminhoAcessoDescrição
GET/api/usersAutenticadoSuperadmin vê todos; admin/professor veem o próprio tenant.
POST/api/usersAutenticadoCria usuário { nome, email, senha, papel } (papel: admin ou professor). Superadmin informa tenantId.

Turmas — /api/turmas

MétodoCaminhoAcessoDescrição
GET/api/turmasAutenticadoAdmin vê todas; professor vê só as suas.
POST/api/turmasAdminCria { nome, professorId? }.
GET/api/turmas/:idAutenticadoDetalha a turma (professor só a própria).
GET/api/turmas/:id/painelAutenticadoGrade de bancadas { turma, bancadas } (estado inicial).
PUT/api/turmas/:idAdminAtualiza { nome?, professorId? }.
DELETE/api/turmas/:idAdminRemove (204).

Alunos — /api/alunos

MétodoCaminhoAcessoDescrição
GET/api/alunos?turma=&limit=&offset=AutenticadoLista alunos do tenant, filtráveis por turma.
POST/api/alunosAdminCria { nome, turmaId?, serie?, foto? }.
GET/api/alunos/:idAutenticadoDetalha o aluno.
GET/api/alunos/:id/portfolioAutenticadoLinha do tempo de fotos do aluno (professor só da própria turma).
PUT/api/alunos/:idAdminAtualiza o aluno.
DELETE/api/alunos/:idAdminRemove (204).

Bancadas — /api/bancadas

MétodoCaminhoAcessoDescrição
GET/api/bancadas?limit=&offset=AutenticadoLista bancadas do tenant.
POST/api/bancadasAdminCria { nome } e retorna o token kiosk (única vez).
GET/api/bancadas/:idAutenticadoDetalha a bancada.
PUT/api/bancadas/:idAdminAtualiza { nome?, status? }.
POST/api/bancadas/:id/tokenAdminRegenera o token kiosk (revoga o anterior).
POST/api/bancadas/:id/atribuirAdmin/ProfessorAtribui { alunoId, pecaId } e cria a sessão.
DELETE/api/bancadas/:idAdminRemove (204).

Peças — /api/pecas admin · professor

MétodoCaminhoDescrição
GET/api/pecas?status=&limit=&offset=Lista peças (status: rascunho, publicada, arquivada).
POST/api/pecasCria { nome, desenho_svg?, descricao? }.
GET/api/pecas/:idDetalha a peça.
PUT/api/pecas/:idAtualiza a peça.
DELETE/api/pecas/:idRemove (204).
POST/api/pecas/:id/publicarPublica (versiona se já usada em sessão).
GET/api/pecas/:id/etapasLista etapas ordenadas.
POST/api/pecas/:id/etapasCria etapa vinculada à peça.

Etapa: { ordem, titulo, instrucao?, desenho?, tipo_acao, criterio_validacao?, medida_esperada_json?, aprovacao_modo, conteudo_matematico?, exige_epi }. tipo_acao ∈ medir, marcar, serrar, aplainar, encaixar, conferir. aprovacao_modo ∈ auto, humano, auto_com_revisao.

Etapas — /api/etapas admin · professor

MétodoCaminhoDescrição
PUT/api/etapas/:idAtualiza a etapa.
DELETE/api/etapas/:idRemove (204).

Tablet — /api/tablet kiosk

Todas as rotas exigem x-bancada-id + x-kiosk-token.

MétodoCaminhoDescrição
POST/api/tablet/bootstrapDescobre a bancada e a sessão ativa; marca online.
POST/api/tablet/sessaoRetorna a sessão ativa (409 se não atribuída).
POST/api/tablet/sessao/finalizarEncerra a sessão como concluída.
POST/api/tablet/etapas/:id/iniciarMarca a etapa como em andamento.
POST/api/tablet/validarMultipart: foto + etapaSessaoId. Cria a validação.
POST/api/tablet/epiMultipart: foto (+ tipo_epi). Verifica EPI via CV (503 se indisponível).

Revisão — /api/revisao admin · professor

MétodoCaminhoDescrição
GET/api/revisao/pendentesFila de validações aguardando decisão humana.
POST/api/revisao/:id/decisaoDecide { decisao: aprovado | reprovado, comentario? }.

Relatórios — /api/relatorios

MétodoCaminhoAcessoDescrição
GET/api/relatorios/turma/:idAutenticadoDesempenho agregado da turma.
GET/api/relatorios/turma/:id/pdfAutenticadoRelatório da turma em PDF.
GET/api/relatorios/aluno/:idAutenticadoDesempenho individual (uma linha por sessão).
GET/api/relatorios/aluno/:id/pdfAutenticadoRelatório do aluno em PDF.
GET/api/relatorios/segurancaAutenticadoLog de EPI (paginado) + resumo ok/falha.
GET/api/relatorios/custoAdminAuditoria de custo CV vs LLM.

Fotos — /api/fotos

MétodoCaminhoDescrição
GET/api/fotos/:tenantId/:sessaoId/:arquivoServe a foto da validação (autenticada; escopo professor↔turma).

Health

MétodoCaminhoDescrição
GET/healthRetorna { ok: true, ts }.

Socket.io — eventos em tempo real

O cliente web se autentica pelo cookie de sessão (mesmo domínio); o tablet pelos headers x-bancada-id + x-kiosk-token.

Servidor → cliente

EventoPayloadRoom
sessao:iniciadasessãobancada:{id}, turma:{id}
sessao:finalizadasessãobancada:{id}, turma:{id}
etapa:atualizadaetapa_sessaobancada:{id}, turma:{id}
validacao:resultadovalidaçãobancada:{id}, turma:{id}
revisao:pendentevalidaçãobancada:{id}, turma:{id}

Cliente → servidor

EventoUso
bancada:pingHeartbeat → marca a bancada como online.