Exemplos - EnemHub API

Todos os exemplos assumem a chave em ENEMHUB_API_KEY e a base https://api.enemhub.com.br.

Filtrar questões

GET /v1/enem/questions aceita quatro filtros, todos opcionais e combináveis:

Parâmetro	Tipo	Observação
`year`	inteiro	Ano do exame, ex. `2023`.
`subjectId`	uuid	ID da matéria. Vem no campo `subject.id` de qualquer questão.
`difficulty`	`easy` \| `medium` \| `hard`	Nível de dificuldade.
`page`	inteiro	Começa em `1`. Padrão `1`.
`limit`	inteiro	De `1` a `100`. Padrão `20`.

Questões difíceis de 2023

curl -G https://api.enemhub.com.br/v1/enem/questions \
  -H "X-API-Key: $ENEMHUB_API_KEY" \
  -d year=2023 \
  -d difficulty=hard \
  -d limit=50

Não existe endpoint para listar matérias no produto ENEM. Para descobrir um subjectId, puxe uma página de questões e leia o subject.id — os IDs são estáveis.

Paginar até o fim

meta.total é a contagem do conjunto filtrado inteiro, então dá para calcular o número de páginas antes de começar:

const BASE = "https://api.enemhub.com.br/v1/enem/questions";
const headers = { "X-API-Key": process.env.ENEMHUB_API_KEY };

async function todasAsQuestoes(filtros = {}) {
  const limit = 100; // o máximo aceito — menos páginas, menos requisições
  const todas = [];

  for (let page = 1; ; page++) {
    const query = new URLSearchParams({ ...filtros, page, limit });
    const res = await fetch(`${BASE}?${query}`, { headers });

    if (!res.ok) throw new Error(`${res.status} ao buscar a página ${page}`);

    const { data, meta } = await res.json();
    todas.push(...data);

    if (todas.length >= meta.total || data.length === 0) return todas;
  }
}

const questoes = await todasAsQuestoes({ year: 2023 });

limit=100 é o teto. Puxar 250.000 questões a 20 por vez custa 12.500 requisições da sua cota; a 100 por vez, 2.500.

Buscar uma questão específica

Diferente da listagem, esta rota devolve a questão sem envelope:

curl https://api.enemhub.com.br/v1/enem/questions/9f3c1a2e-... \
  -H "X-API-Key: $ENEMHUB_API_KEY"

Um ID que não existe — ou que pertence a um exame fora do produto ENEM — devolve 404:

{ "error": "Questão não encontrada" }

Montar uma prova

Correta e alternativas vêm juntas na resposta, então embaralhar e esconder o gabarito é trabalho do seu lado:

function paraOAluno(questao) {
  return {
    id: questao.id,
    enunciado: questao.statement,
    imagem: questao.imageUrl,
    // `isCorrect` e `correctAlternative` ficam de fora — o gabarito não desce
    // para o cliente.
    alternativas: questao.alternatives.map(({ id, letter, text, imageUrl }) => ({
      id, letra: letter, texto: text, imagem: imageUrl,
    })),
  };
}

function corrigir(questao, alternativaId) {
  return questao.alternatives.find((a) => a.id === alternativaId)?.isCorrect ?? false;
}

Lidar com limites

Toda resposta de /v1/* traz dois headers:

Header	Significado
`X-RateLimit-Limit`	Requisições por minuto permitidas pelo seu plano.
`X-RateLimit-Remaining`	Quantas ainda cabem no minuto corrente.

Ao estourar, a resposta é 429 com Retry-After: 60. São três limites independentes:

Por minuto — definido pelo plano.
Por dia — 10.000 requisições, igual para todos os planos.
Por mês — a cota do plano. Ao estourar, a mensagem pede upgrade.

Uma requisição recusada com 429 não consome cota mensal. Estourar o limite por minuto não queima o seu volume contratado.

Retry com backoff

async function comRetry(url, init, tentativas = 3) {
  for (let i = 0; i < tentativas; i++) {
    const res = await fetch(url, init);
    if (res.status !== 429) return res;

    const espera = Number(res.headers.get("Retry-After") ?? 60);
    await new Promise((r) => setTimeout(r, espera * 1000));
  }
  throw new Error("Rate limit persistente após 3 tentativas");
}

Tratar erros

Status	`error`	Quando acontece
`401`	`Unauthorized`	Header `X-API-Key` ausente, ou chave inválida, revogada ou expirada.
`403`	`Forbidden`	A chave é de outro produto, ou a organização não tem assinatura ativa.
`404`	—	O recurso não existe, ou não pertence ao produto da sua chave.
`429`	`Too Many Requests`	Estourou o limite por minuto, por dia ou a cota mensal do plano.
`500`	—	Erro interno. Se persistir, fale com o suporte.

O corpo do erro não é uniforme em toda a API — documentamos o que existe hoje, não o que gostaríamos que existisse.As rotas de gestão devolvem { "error", "message", "statusCode" }. Os erros de autenticação e de rate limit devolvem { "error", "message" }, sem statusCode. E o 404 das rotas de questão devolve só { "error": "Questão não encontrada" }.Ou seja: trate pelo status HTTP, que é consistente, e use error / message apenas para exibir ou registrar em log.

Um wrapper que cobre o caso comum:

async function enemhub(caminho, params = {}) {
  const query = new URLSearchParams(params);
  const res = await fetch(`https://api.enemhub.com.br${caminho}?${query}`, {
    headers: { "X-API-Key": process.env.ENEMHUB_API_KEY },
  });

  if (res.ok) return res.json();

  // Trate pelo status: o corpo do erro não tem formato único na API.
  const corpo = await res.json().catch(() => ({}));
  throw Object.assign(
    new Error(corpo.message ?? corpo.error ?? `HTTP ${res.status}`),
    { status: res.status },
  );
}

​Filtrar questões

​Paginar até o fim

​Buscar uma questão específica

​Montar uma prova

​Lidar com limites

​Tratar erros

Filtrar questões

Paginar até o fim

Buscar uma questão específica

Montar uma prova

Lidar com limites

Tratar erros