Exemplos - EnemHub API

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

Listar os exames

É por aqui que se começa: /exams devolve o catálogo inteiro, sem paginação, e é dele que saem os examId usados como filtro.

curl https://api.enemhub.com.br/v1/vestibulares/exams \
  -H "X-API-Key: $ENEMHUB_API_KEY"

{
  "data": [
    { "id": "3b1e...", "name": "FUVEST 2023", "institution": "USP", "type": "vestibular" },
    { "id": "7c9a...", "name": "ENEM 2023", "institution": "INEP", "type": "enem" }
  ]
}

institution e type podem vir null para exames sem essa classificação. Não assuma que estão preenchidos.

Filtrar questões

GET /v1/vestibulares/questions aceita cinco filtros, todos opcionais e combináveis:

Parâmetro	Tipo	Observação
`examId`	uuid	ID do exame, vindo de `/exams`.
`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`.

Biológicas difíceis da FUVEST

curl -G https://api.enemhub.com.br/v1/vestibulares/questions \
  -H "X-API-Key: $ENEMHUB_API_KEY" \
  -d examId=3b1e... \
  -d difficulty=hard \
  -d limit=50

Sem examId, a listagem cobre todos os exames do produto, ENEM incluído.

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/vestibulares/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 fuvest = await todasAsQuestoes({ examId: "3b1e..." });

limit=100 é o teto. Espelhar um catálogo inteiro a 20 por vez custa cinco vezes mais requisições da sua cota do que a 100 por vez.

Espelhar o catálogo por exame

O caso mais comum de carga inicial: varrer exame a exame, para poder retomar de onde parou se algo falhar no meio.

const exames = await fetch("https://api.enemhub.com.br/v1/vestibulares/exams", { headers })
  .then((r) => r.json())
  .then((r) => r.data);

for (const exame of exames) {
  const questoes = await todasAsQuestoes({ examId: exame.id });
  await salvar(exame, questoes);
  console.log(`${exame.name}: ${questoes.length} questões`);
}

Buscar uma questão específica

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

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

Um ID que não existe — ou que pertence a um exame fora deste produto — 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,
    exame: questao.exam.name,
    // `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 },
  );
}

​Listar os exames

​Filtrar questões

​Paginar até o fim

​Espelhar o catálogo por exame

​Buscar uma questão específica

​Montar uma prova

​Lidar com limites

​Tratar erros

Listar os exames

Filtrar questões

Paginar até o fim

Espelhar o catálogo por exame

Buscar uma questão específica

Montar uma prova

Lidar com limites

Tratar erros