Qualquer sistema de gestão escolar conversa com o EYESchool AI
O EYESchool AI não substitui o sistema de matrícula da escola: ele se conecta a ele. A troca acontece por uma única porta HTTP, com vocabulário próprio e versionado. O EYESchool nunca acessa o banco do parceiro, e o parceiro nunca acessa o do EYESchool.
A porta é uma só
Todo envio de cadastro chega pelo mesmo endereço, autenticado por uma chave emitida para uma unidade escolar específica.
POST https://<seu-dominio>/api/public/sync
x-eyeschool-key: <chave da unidade>
Content-Type: application/jsonUma chave por unidade
A chave escreve somente na unidade para a qual foi emitida. Ela é um segredo de servidor: nunca deve aparecer no aplicativo do usuário.
20 envios por minuto
Corpo de até 4 MB por requisição. Lotes maiores devem ser divididos, com retentativa e espera progressiva em caso de 429.
Reenvio é seguro
A operação é idempotente: reenviar o mesmo external_id atualiza o registro existente, nunca duplica.
O pacote de cadastro
Todos os blocos são opcionais: envie apenas o que mudou. Os vínculos entre objetos são feitos pelos identificadores do seu sistema, nunca por nome.
{
"source": "nome-do-sistema-parceiro",
"grade_levels": [
{
"external_id": "b1f2...",
"name": "6º ano",
"stage": "Ensino Fundamental II",
"position": 6
}
],
"classes": [
{
"external_id": "c9a0...",
"name": "6A",
"code": "6A-M",
"shift": "manha",
"capacity": 32,
"grade_level_external_id": "b1f2..."
}
],
"people": [
{
"external_id": "p33d...",
"full_name": "Maria de Souza",
"social_name": "Maria",
"person_type": "aluno",
"document": "00000000000",
"email": "responsavel@exemplo.com",
"phone": "+5521999999999",
"birth_date": "2014-03-02",
"photo_url": "https://.../assinada?expira=3600"
}
],
"enrollments": [
{
"external_id": "m77a...",
"student_external_id": "p33d...",
"class_external_id": "c9a0...",
"status": "ativa",
"started_on": "2027-02-01",
"roll_number": 12
}
],
"guardianships": [
{
"student_external_id": "p33d...",
"guardian_external_id": "p91b...",
"relationship": "mae",
"is_legal_guardian": true,
"is_emergency_contact": true,
"contact_order": 1
}
],
"teaching_assignments": [
{
"teacher_external_id": "p14c...",
"class_external_id": "c9a0...",
"role": "titular"
}
]
}Vocabulário obrigatório
A tradução do vocabulário do seu sistema para o do EYESchool deve acontecer em um único ponto do seu código. Isso evita que cada tela invente um sinônimo.
| Campo | Onde | Valores aceitos |
|---|---|---|
| shift | Turma | manha · tarde · noite · integralTambém aceita matutino, vespertino e noturno. |
| person_type | Pessoa | aluno · professor · funcionario · responsavel · visitante · terceirizadoGestor e coordenador entram como funcionario. |
| status | Matrícula | ativa · transferida · trancada · concluida · canceladaAluno que sai nunca é apagado: muda de status. |
| role | Docência | titular · auxiliar · substitutoAusente ou desconhecido vira titular. |
Seis regras que não se negociam
Não são recomendações de boas práticas: são condições para a integração ser aceita e continuar ativa.
O identificador é para sempre
O external_id é a chave estável do seu sistema (a chave primária do registro). Nunca reutilize, nunca regenere. Se ele mudar, o EYESchool cria uma pessoa duplicada e a linha do tempo do aluno se parte em duas.
Só o mínimo necessário trafega
É proibido enviar senha, valor de contrato, mensalidade, desconto, cobrança, dado de saúde, laudo ou detalhe de restrição judicial. O EYESchool é um produto observacional: recebe apenas o suficiente para dar contexto a um evento.
Foto entra por link assinado
O campo photo_url precisa ser uma URL assinada, servida por HTTPS, válida por pelo menos 60 minutos e sem exigir sessão. O EYESchool baixa a imagem, guarda cópia privada com prazo de retenção e descarta o link. O balde de origem não pode ser público.
Cadastro é mão única
Séries, turmas, pessoas, matrículas e vínculos fluem do sistema parceiro para o EYESchool. O EYESchool nunca edita cadastro: ele espelha e complementa com contexto de ambiente e observação.
Observação volta como evento
Ocorrências, alertas e situações nascem no EYESchool e retornam ao parceiro como evento com evidência e status de validação humana. Nunca como rótulo, nota ou diagnóstico fixado no cadastro do aluno.
Consentimento viaja junto
Nenhuma foto de menor deve ser enviada sem base legal registrada no sistema de origem, com finalidade explícita e possibilidade de revogação.
O que nunca deve ser enviado
Escreva o exportador com uma lista de permissão explícita de campos, e não com uma lista de bloqueio. Assim, um campo novo criado no futuro não vaza por esquecimento.
- Senha ou hash de senha
- Mensalidade, desconto e contrato
- Cobranças, boletos e inadimplência
- Dados de saúde e laudos
- Necessidade especial detalhada
- Detalhe de impedimento judicial
Resposta e erros
{
"ok": true,
"batch_id": "7c1e...",
"criados": 128,
"atualizados": 14,
"ignorados": 0,
"conflitos": []
}- 200Lote aplicado. O corpo traz o resumo e a lista de conflitos.
- 400Payload inválido ou vocabulário desconhecido. O corpo aponta o campo.
- 401Chave ausente, inválida ou fonte desativada.
- 413Lote acima de 4 MB. Divida o envio.
- 429Acima de 20 envios por minuto. Respeite o cabeçalho retry-after.
Ordem de carga e periodicidade
Na carga inicial, envie na ordem abaixo: cada bloco depende do anterior para encontrar seus vínculos.
- 01Séries e anos
- 02Turmas
- 03Pessoas
- 04Matrículas
- 05Vínculos de responsável
- 06Atribuições de professor
Depois da carga inicial
Envio incremental a cada alteração relevante — aluno criado, troca de turma, mudança de status de matrícula, foto atualizada — ou uma sincronização completa por noite.
Aluno que sai da escola
Envie a matrícula com status transferida ou cancelada. Nunca remova o registro: o histórico de ocorrências precisa continuar explicável depois da saída.
A escola já tem um sistema de gestão. Falta ele conversar com o que as câmeras veem.
A chave de integração é emitida por unidade escolar, dentro da plataforma, e entregue por canal seguro à equipe técnica do parceiro.