A API permite gravar ou alterar dados no EduPrime?

Não. Os dois endpoints são somente leitura: consultam alunos e frequência e não criam, alteram nem apagam registros.

Por que o mesmo aluno aparece mais de uma vez na lista de alunos?

A lista traz um item por matrícula ativa. Um aluno matriculado em mais de uma turma no mesmo ano, como a turma regular e a de um programa complementar, aparece uma vez para cada matrícula. Use o campo matricula como identificador do item.

Consigo consultar anos letivos anteriores?

O parâmetro ano aceita anos anteriores, mas a resposta só inclui matrículas ativas. Como as matrículas de anos encerrados deixam de estar ativas, a consulta de um ano anterior costuma voltar vazia.

Os dados da API são atualizados em tempo real?

Sim. A API consulta a base do EduPrime no momento da chamada, sem cache: a frequência aparece assim que o professor salva a chamada do dia.

Início
/
Documentação
/
Integrações
/
Piauí Primeira Infância

Piauí Primeira Infância

Q: Como obtenho o token de acesso à API?

A Secretaria Municipal de Educação solicita o acesso à equipe EduPrime. Criamos uma conta de integração somente leitura, vinculada à rede, e entregamos o token à equipe técnica responsável por canal seguro.

API para o programa estadual importar alunos e frequência das escolas da rede

Integração

O Piauí Primeira Infância é o programa do Governo do Estado do Piauí voltado ao desenvolvimento de crianças de 0 a 6 anos. Com esta integração, a plataforma do programa importa do EduPrime os alunos matriculados e a frequência lançada pelos professores, sem que a escola digite os dados duas vezes. Este guia é para a equipe técnica que vai consumir a API.

Endereço base

https://app.eduprime.chat

Autenticação

Token no cabeçalho Authorization: Bearer

Formato

JSON em UTF-8, sempre pelo método GET

Acesso

Somente leitura, restrito às escolas da rede

Como começar

Solicite o acesso

A Secretaria Municipal de Educação pede a liberação à equipe EduPrime. Criamos uma conta de integração somente leitura, vinculada à rede, e entregamos o token à equipe técnica do programa por canal seguro.

Envie o token em toda chamada

Todas as chamadas usam o método GET e levam o cabeçalho Authorization: Bearer SEU_TOKEN. Sem ele, ou com um token inválido, a API responde 401.

Consulte cada escola pelo código INEP

A escola é identificada pelo código INEP de 8 dígitos. Com ele você importa a lista de alunos e, depois, a frequência de cada dia letivo.

O token dá acesso a dados pessoais de alunos e responsáveis, como nomes, CPFs, datas de nascimento e informações de saúde, protegidos pela LGPD. Veja os cuidados com o token antes de colocar a integração em produção.

1. Alunos da escola

GET

/escola-importacao/escolas/alunos

Retorna as matrículas ativas da escola no ano letivo, com dados do aluno, dos responsáveis e dos professores da turma. Alunos transferidos, inativos e concluintes ficam de fora.

Parâmetros de consulta

Parâmetro	Obrigatório	Descrição
`inep`	Sim	Código INEP da escola, com 8 dígitos.
`ano`	Não	Ano letivo. Se omitido, vale o ano corrente no horário de Brasília.
`aluno_cpf`	Não	Filtra um único aluno pelo CPF: 11 dígitos, com ou sem pontuação.
`limit`	Não	Itens por página, de 1 a 500. Padrão: 100.
`offset`	Não	Quantos itens pular antes da página. Padrão: 0.

Exemplo de requisição

cURL

curl "https://app.eduprime.chat/escola-importacao/escolas/alunos?inep=12345678&limit=100&offset=0" \
  -H "Authorization: Bearer SEU_TOKEN"

Exemplo de resposta

JSON · dados fictícios

{
  "data": [
    {
      "matricula": "2026000123",
      "aluno_nome": "Maria da Silva",
      "sexo": "F",
      "aluno_cpf": "00000000000",
      "data_nascimento": "2020-03-15",
      "turma_codigo": "Pré II A",
      "serie_descricao": "Pré-escola II",
      "nivelEnsino": "EDUCAÇÃO INFANTIL",
      "comorbidades": [],
      "responsaveis": [
        {
          "nome": "Ana da Silva",
          "parentesco": "mae",
          "telefone": "86900000000",
          "responsavel_cpf": "00000000000"
        }
      ],
      "professores": [
        {
          "nome": "João Souza",
          "professor_cpf": "00000000000",
          "disciplina": "Campos de Experiência"
        }
      ]
    }
  ],
  "total": 320,
  "limit": 100,
  "offset": 0
}

Campos de cada item

Campo	Tipo	Descrição
`matricula`	texto	Código da matrícula. Identifica o item de forma única.
`aluno_nome`	texto	Nome completo do aluno.
`sexo`	"M" ou "F"	Sexo informado no cadastro.
`aluno_cpf`	texto	CPF com 11 dígitos, sem pontuação. Vem nulo quando não está cadastrado.
`data_nascimento`	AAAA-MM-DD	Data de nascimento do aluno.
`turma_codigo`	texto	Nome da turma, único dentro da escola.
`serie_descricao`	texto	Série ou etapa da matrícula.
`nivelEnsino`	texto	Nível de ensino em caixa alta, como "EDUCAÇÃO INFANTIL" ou "ENSINO FUNDAMENTAL".
`comorbidades`	lista de textos	Deficiência ou condição informada no cadastro. Lista vazia quando não há.
`responsaveis`	lista	Mãe, pai e responsável legal cadastrados: nome, parentesco ("mae", "pai" ou "responsavel"), telefone e responsavel_cpf.
`professores`	lista	Professores da turma: nome, professor_cpf e disciplina.

Há um item por matrícula, não por aluno. Quem tem mais de uma matrícula ativa no ano, como a turma regular e a de um programa complementar, aparece uma vez para cada matrícula.
Anos anteriores costumam voltar vazios, porque só matrículas ativas entram na resposta.
A Especificação Técnica API Escola Importação do programa prevê a data de nascimento do responsável. Esse dado não existe no cadastro escolar, por isso não é enviado.

2. Frequência da escola em um dia

GET

/escola-importacao/escolas/frequencias

Retorna um item por aluno com frequência lançada no dia consultado, já consolidando todas as aulas daquele dia.

Parâmetros de consulta

Parâmetro	Obrigatório	Descrição
`inep`	Sim	Código INEP da escola, com 8 dígitos.
`data`	Sim	Dia da frequência, no formato AAAA-MM-DD.
`aluno_cpf`	Não	Filtra um único aluno pelo CPF: 11 dígitos, com ou sem pontuação.
`limit`	Não	Itens por página, de 1 a 500. Padrão: 100.
`offset`	Não	Quantos itens pular antes da página. Padrão: 0.

Exemplo de requisição

cURL

curl "https://app.eduprime.chat/escola-importacao/escolas/frequencias?inep=12345678&data=2026-09-30" \
  -H "Authorization: Bearer SEU_TOKEN"

Exemplo de resposta

JSON · dados fictícios

{
  "data": [
    {
      "aluno_cpf": "00000000000",
      "aluno_nome": "Maria da Silva",
      "matricula": "2026000123",
      "turma": "Pré II A",
      "data_referencia": "2026-09-30",
      "situacao_frequencia": "P",
      "professores": [
        {
          "nome": "João Souza",
          "disciplina": "Campos de Experiência"
        }
      ]
    }
  ],
  "total": 287,
  "limit": 100,
  "offset": 0
}

Campos de cada item

Campo	Tipo	Descrição
`aluno_cpf`	texto	CPF com 11 dígitos, sem pontuação. Vem nulo quando não está cadastrado.
`aluno_nome`	texto	Nome completo do aluno.
`matricula`	texto	Código da matrícula, o mesmo da lista de alunos.
`turma`	texto	Nome da turma, o mesmo de turma_codigo na lista de alunos.
`data_referencia`	AAAA-MM-DD	Dia consultado.
`situacao_frequencia`	"P" ou "F"	"P" para presente e "F" para falta.
`professores`	lista	Professores que registraram a chamada no dia: nome e disciplina.

Uma falta em qualquer aula do dia marca o aluno como "F".
Só aparecem alunos com frequência lançada na data. Dia sem chamada registrada volta com a lista vazia.
Aqui, total é o número de alunos do dia, não o de aulas.

3. Paginação

As duas respostas vêm paginadas: data traz os itens da página e total, quantos existem ao todo. Quando total for maior que limit, busque as próximas páginas somando limit ao offset (100, 200, 300…). A Especificação Técnica do programa previa uma lista simples; a paginação mantém as respostas leves em escolas grandes.

JavaScript · Node 18+

const BASE = 'https://app.eduprime.chat/escola-importacao/escolas/alunos'
const headers = { Authorization: `Bearer ${process.env.EDUPRIME_TOKEN}` }

async function buscarTodosOsAlunos(inep) {
  const alunos = []
  let offset = 0
  let total = Infinity

  while (offset < total) {
    const resposta = await fetch(`${BASE}?inep=${inep}&limit=500&offset=${offset}`, { headers })
    const corpo = await resposta.json()
    if (!resposta.ok)
      throw new Error(`${corpo.statusCode}: ${corpo.message}`)

    alunos.push(...corpo.data)
    total = corpo.total
    offset += corpo.limit
  }

  return alunos
}

4. Códigos de erro

Todo erro volta em JSON, com o código HTTP e uma mensagem em português que explica o que corrigir.

JSON · resposta de erro

{
  "statusCode": 400,
  "message": "O parâmetro inep deve ter os 8 dígitos do código INEP da escola"
}

Código	Significado
400	Parâmetro ausente ou em formato inválido. A mensagem indica qual.
401	Token ausente ou inválido.
402	Acesso da rede suspenso. Fale com o suporte.
403	O token não tem permissão para usar a integração.
404	Nenhuma escola da rede encontrada para o INEP informado.
405	Método diferente de GET.
409	O INEP informado está cadastrado em mais de uma escola.
413	A consulta ultrapassaria o limite de registros. Restrinja com aluno_cpf.
500	Erro interno. Tente de novo e, se persistir, avise o suporte.

5. Cuidados com o token e LGPD

O token dá acesso a dados pessoais de crianças e de seus responsáveis. Trate-o como uma senha.

Guarde o token em um cofre de segredos ou em variável de ambiente do servidor.

Use-o só em chamadas de servidor para servidor, nunca dentro de aplicativo de celular ou de página web.

Não compartilhe o token por canais públicos nem o coloque em repositório de código, planilha, documento ou captura de tela.

Se houver suspeita de vazamento, avise o suporte: revogamos o token e emitimos outro.

Perguntas Frequentes

Voltar: Integrações

Pronto para transformar sua escola?

Comece a usar o EduPrime gratuitamente ou agende uma demonstração com nossa equipe.

Começar Grátis Agendar Demo