API de Notas

Endpoint

GET /exportarNotas

Autenticação

Toda chamada exige um header Authorization com um token Bearer. Cada integração recebe um token exclusivo, vinculado a uma escola e a um sistema específico — o mesmo token não funciona para outra escola ou outro sistema.

Authorization: Bearer <token-da-integracao>

Tokens são emitidos manualmente pela equipe Guby. Solicite o seu informando o nome da escola e do sistema que vai consumir a API.

Parâmetros

Obrigatórios

Parâmetro	Tipo	Descrição
`escola`	string	Nome da escola, exatamente como cadastrado no Guby.
`sistema`	string	Identificador do sistema consumidor (ex: `SistemaTeste1`). Deve bater com o token usado.
`ano`	string	Ano letivo, ex: `2026`.

Filtros opcionais

Parâmetro	Tipo	Descrição
`turma`	string	Nome da turma (ex: `6º Ano A`). Não é o ID interno do Guby.
`disciplina`	string	Nome da disciplina, ex: `Português`.
`segmento`	string	Segmento escolar (ex: `Fundamental II`).
`serie`	number	Série/ano escolar.

Sem filtros, a resposta traz todos os alunos e disciplinas da escola no ano informado. Para escolas grandes, recomendamos paginar a coleta por turma, segmento ou serie em vez de uma única chamada.

Exemplo de requisição

curl "https://apinotas.guby.com.br/exportarNotas?escola=Escola%20modelo&sistema=lugarest&ano=2026&turma=EF9A" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI"

Exemplo de resposta

200 OK

{
  "escola": "Escola modelo",
  "ano": "2026",
  "organizacaoNotas": {
    "descricao": "Cada posição do array 'notas' corresponde a uma avaliação fixa, na ordem abaixo.",
    "posicoes": [
      "bim1_av1", "bim1_av2", "bim1_av3", "bim1_media", "bim1_recuperacao",
      "bim2_av1", "bim2_av2", "bim2_av3", "bim2_media", "bim2_recuperacao",
      "bim3_av1", "bim3_av2", "bim3_av3", "bim3_media", "bim3_recuperacao",
      "bim4_av1", "bim4_av2", "bim4_av3", "bim4_media", "bim4_recuperacao",
      "media_final", "recuperacao_final"
    ]
  },
  "alunos": [
    {
      "matricula": "25001018",
      "nome": "Nome do Aluno",
      "turma": "EF9A",
      "disciplina": "Português",
      "bimestre": "1",
      "faltas": 0,
      "cargaHoraria": 1,
      "notas": ["2.0", "1.0", "1.0", "4.0", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", ""],
      "situacaoFinal": ""
    }
  ]
}

O campo organizacaoNotas é fixo e descreve a posição de cada nota dentro do array notas — use-o para mapear os índices, em vez de assumir a ordem manualmente.

Erros

Status	Causa
400	Faltou `escola`, `sistema` ou `ano` na query string.
401	Token ausente, inválido, ou não corresponde ao par escola+sistema informado.
429	Limite de chamadas excedido (veja Rate Limit abaixo).
500	Erro interno ao processar a exportação.

Rate limit

Cada par escola+sistema pode fazer até 10 requisições por minuto. Ao exceder, a API responde 429 Too Many Requests até a janela seguinte.

Fonte dos dados

As notas exportadas vêm do diário oficial já fechado e revisado pelos professores — a mesma fonte usada para gerar boletins e documentos. Notas em rascunho (ainda não fechadas pelo professor) não aparecem nesta API.