Listagem de Turmas Ativas — Especificação Técnica

1. Visão Geral

1.1 Objetivo

Este documento especifica como um sistema parceiro pode consultar, via uma chamada HTTP simples, quais turmas da sua instituição estão ativas na Plataforma Semente — organizadas por série escolar.

Esse endpoint é independente do fluxo de SSO e do Cadastro de Usuários — não é necessário implementar nenhum dos dois para usar esta consulta, e vice-versa. Basta a API Key já cadastrada da instituição, sem necessidade de login de usuário ou token JWT.

1.2 Fluxo Resumido

O parceiro monta uma URL de consulta contendo sua API Key.
O backend do parceiro faz uma requisição GET diretamente a esse endpoint — chamada servidor-a-servidor, sem necessidade de partir do navegador do usuário.
A Semente valida a API Key e devolve um JSON com as turmas ativas, agrupadas por série escolar.

Importante: Assim como em qualquer integração com API Key, a chamada deve partir do back-end do parceiro. A API Key nunca deve ser exposta no front-end, em aplicativos móveis ou em qualquer código acessível ao usuário final.

1.3 Diagrama do Fluxo

O diagrama abaixo ilustra a sequência da integração, sempre servidor-a-servidor entre o back-end do parceiro e a Plataforma Semente:

Caso a API Key seja inválida ou não seja informada, a Semente responde com erro diretamente na chamada — o parceiro deve tratar essa resposta antes de considerar a consulta como concluída.

2. Pré-requisito: API Key

Cada instituição parceira possui uma API Key própria, cadastrada pela Semente. É a mesma API Key eventualmente já usada em outras integrações existentes com essa instituição, como o Cadastro de Usuários.

Se você ainda não possui uma API Key para a sua instituição, solicite-a ao time da Semente.

A API Key identifica apenas a instituição: Não um usuário — todo o resultado retornado é sempre relativo às turmas dessa instituição.

3. Endpoint

3.1 URL e Método

Endpoint

GET https://integracao.sementeeducacao.com.br/api/v0/plataforma-turmas/listaTurmas?apikey=<API_KEY>

Parâmetro	Onde	Obrigatório	Descrição
`apikey`	query string	Sim	API Key da instituição.

3.2 Exemplo de Requisição

Requisição

GET https://integracao.sementeeducacao.com.br/api/v0/plataforma-turmas/listaTurmas?apikey=SUA_API_KEY_AQUI

Sem headers adicionais: Não é necessário nenhum header de autenticação adicional (sem Authorization, sem cookies) — a API Key na query string é suficiente.

3.3 Resposta de Sucesso

200 OK

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "serieId": 5,
    "serie": "1º Ano",
    "descricao": "1º Ano - Ensino Médio",
    "turmas": [
      { "turmaId": 101, "nome": "1º A" },
      { "turmaId": 102, "nome": "1º B" }
    ]
  },
  {
    "serieId": 6,
    "serie": "2º Ano",
    "descricao": "2º Ano - Ensino Médio",
    "turmas": [
      { "turmaId": 110, "nome": "2º A" }
    ]
  }
]

A resposta é uma lista de séries, uma entrada por série escolar que tenha ao menos uma turma ativa.
Dentro de cada série, turmas é a lista de turmas ativas daquela série, ordenadas por nome.
As séries vêm ordenadas conforme a progressão letiva (ex: 1º Ano antes de 2º Ano).
Se a instituição não tiver nenhuma turma ativa, a resposta é uma lista vazia: [].
"Turma ativa" significa que a turma existe e não foi removida/desativada na plataforma — turmas excluídas não aparecem na lista.

3.4 Resposta de Erro

400 Bad Request

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "mensagem": "API Key inválida."
}

Outras mensagens possíveis com o mesmo status:

"API Key não fornecida." — quando o parâmetro apikey está ausente ou vazio na URL.
"API Key inválida." — quando a API Key não corresponde a nenhuma instituição cadastrada (ou a instituição está inativa).

3.5 Códigos de Retorno

HTTP	Situação	Descrição
200	Sucesso	API Key válida. Retorna a lista de séries com suas turmas ativas (pode ser uma lista vazia).
400	Requisição inválida	API Key ausente ou inválida.
429	Muitas requisições	Limite de requisições excedido para a API Key. Ver seção 3.6.

3.6 Limite de Requisições (Rate Limit)

Este endpoint aplica um limite de requisições por API Key: em média 1 requisição por segundo, com uma pequena folga de burst — no máximo 5 chamadas em uma janela de 5 segundos.

Ao exceder esse limite, a Semente responde com 429 Too Many Requests:

429 Too Many Requests

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "mensagem": "Muitas requisições. Tente novamente em breve."
}

Como tratar o 429: Ao receber esse erro, aguarde cerca de 5 segundos antes de tentar novamente. Evite implementar retries imediatos em loop — isso apenas prolonga o bloqueio e não acelera a resposta.

4. Pontos de Atenção para a Implementação

Chamada servidor-a-servidor: assim como o Cadastro de Usuários, esta consulta pode (e deve) ser feita diretamente pelo backend do parceiro — não há necessidade de passar pelo navegador do usuário.
A API Key trafega na URL (query string): evite registrá-la em logs de acesso não protegidos do seu lado, e trate-a como uma credencial sensível, da mesma forma que qualquer outra API Key.
Os identificadores (serieId, turmaId) são estáveis e podem ser usados como referência para vincular turmas em outras integrações com a Semente que também referenciem série/turma.
Não é necessário estar autenticado como usuário para consumir este endpoint — apenas a API Key da instituição é validada.

Atenção com a API Key em logs: Como a API Key é enviada via query string, ela pode acabar registrada em logs de servidores proxy, CDNs ou ferramentas de observabilidade. Configure seu ambiente para não persistir query strings sensíveis em texto claro, quando possível.

5. Exemplos de Chamada

A seguir, exemplos de como montar e enviar a requisição GET nas linguagens mais comuns, usando apenas bibliotecas padrão (sem dependências externas).

5.1 C# (.NET)

Biblioteca: System.Net.Http (nativa, sem dependências adicionais).

C#

using System.Net.Http;

// apikey é fornecida pela Semente no provisionamento
string apikey = "SUA_API_KEY_AQUI";
string url = $"https://integracao.sementeeducacao.com.br/api/v0/plataforma-turmas/listaTurmas?apikey={apikey}";

using var client = new HttpClient();
var response = await client.GetAsync(url);
string json = await response.Content.ReadAsStringAsync();

5.2 Python

Biblioteca: requests (pip install requests).

Python

import requests

# apikey é fornecida pela Semente no provisionamento
apikey = "SUA_API_KEY_AQUI"
url = "https://integracao.sementeeducacao.com.br/api/v0/plataforma-turmas/listaTurmas"

response = requests.get(url, params={"apikey": apikey})
turmas_por_serie = response.json()

5.3 Java

Biblioteca: java.net.http.HttpClient (nativa a partir do JDK 11).

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

// apikey é fornecida pela Semente no provisionamento
String apikey = "SUA_API_KEY_AQUI";
String url = "https://integracao.sementeeducacao.com.br/api/v0/plataforma-turmas/listaTurmas?apikey=" + apikey;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .GET()
        .build();

HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());

5.4 Node.js

fetch nativo (Node.js 18+, sem dependências adicionais).

Node.js

// apikey é fornecida pela Semente no provisionamento
const apikey = "SUA_API_KEY_AQUI";
const url = `https://integracao.sementeeducacao.com.br/api/v0/plataforma-turmas/listaTurmas?apikey=${apikey}`;

const response = await fetch(url);
const turmasPorSerie = await response.json();

5.5 PHP

Extensão: curl (nativa em praticamente qualquer instalação PHP).

PHP

<?php

// apikey é fornecida pela Semente no provisionamento
$apikey = "SUA_API_KEY_AQUI";
$url = "https://integracao.sementeeducacao.com.br/api/v0/plataforma-turmas/listaTurmas?apikey=" . urlencode($apikey);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$turmasPorSerie = json_decode($response, true);

6. Checklist de Integração

Obtive a API Key da instituição junto ao time da Semente (caso ainda não a possuísse) — seção 2.
Implementei a chamada GET ao endpoint, passando a API Key na query string — seção 3.1.
Tratei a resposta de sucesso (200), incluindo o caso de lista vazia (instituição sem turmas ativas) — seção 3.3.
Tratei o erro 400 (API Key ausente ou inválida) com uma mensagem adequada no meu sistema — seção 3.4.
Tratei o erro 429 (limite de requisições excedido), aguardando cerca de 5 segundos antes de tentar novamente, sem retries imediatos em loop — seção 3.6.
A chamada parte do back-end do parceiro, nunca do front-end ou de código acessível ao usuário final — seção 4.
Confirmei que meus logs não expõem a API Key em texto claro — seção 4.

7. Perguntas Frequentes

Não. Este endpoint é independente das demais integrações — basta possuir a API Key da instituição já cadastrada com a Semente.

Sim. É a mesma API Key da instituição, eventualmente já usada em outras integrações existentes.

A resposta é 200 com uma lista vazia ([]), e não um erro.

Não. Apenas turmas ativas são retornadas — turmas excluídas ou desativadas na plataforma não aparecem na lista.

Sim. Esses identificadores são estáveis e podem ser usados para vincular turmas em outras integrações com a Semente que também referenciem série/turma.

Em média 1 requisição por segundo por API Key, com uma folga de burst de até 5 chamadas em uma janela de 5 segundos. Ao exceder esse limite, a resposta é 429 Too Many Requests — aguarde cerca de 5 segundos antes de tentar novamente (seção 3.6).

Entre em contato com o time técnico da Semente através do canal combinado no momento do provisionamento da API Key.