Skip to content

API — Banco de questões (admin-ext)

Contexto

Item Valor
Prefixo global da API /api
Prefixo do grupo /admin-ext/questoes
Base completa /api/admin-ext/questoes
Autenticação Token Bearer; usuário institucional com instituição vinculada (mesmo critério de /api/admin-ext/simulados).

Respostas de validação na busca principal (GET /api/admin-ext/questoes):

{
  "success": false,
  "message": "Erro de validação",
  "errors": {}
}

HTTP 422.

1. Buscar questões (paginado)

Campo Valor
Método GET
Path /api/admin-ext/questoes

Parâmetros de query permitidos

Somente as chaves abaixo são aceitas; qualquer outra chave na query gera erro 422 (“Parâmetro não permitido.”).

Parâmetro Regras
name nullable, string, máx. 65535 — busca no texto do enunciado
page nullable, inteiro ≥ 1
limit nullable, inteiro de 1 a 100
simulated_id nullable, inteiro ≥ 1 — usado com included para filtrar questões já no simulado externo ou disponíveis
included nullable, boolean — com simulated_id: true = só questões já no simulado; false = só as que ainda não estão
uf nullable, string, tamanho 2 (UF da banca)
specificallies nullable, array de inteiros ≥ 1
tests nullable, array de inteiros ≥ 1 (IDs de provas)
type nullable, objetiva ou discursiva
commented nullable, boolean — filtra presença de comentário na questão
themes nullable, array de inteiros ≥ 1
areas nullable, array de inteiros ≥ 1
specialties nullable, array de inteiros ≥ 1
years nullable, array de inteiros ≥ 1
institutions nullable, array de inteiros ≥ 1

Observação: em alguns ambientes a mensagem de erro de validação da UF pode mencionar tamanho incorreto; o valor válido continua sendo string de 2 caracteres.

Comportamento da busca

  • Inclui, por padrão, questões ativas e não anuladas.
  • Ordenação por id descendente.
  • O parâmetro type filtra questões objetivas ou discursivas.

Saída (200)

{
  "total": 0,
  "page": 1,
  "limit": 10,
  "data": [
    {
      "id": "1",
      "statement": "",
      "type": "objetiva",
      "themes": [{ "id": 1, "name": "" }],
      "areas": [],
      "specialties": [],
      "specifically": null,
      "difficulty": null,
      "status": "ativa",
      "exam": null,
      "alternatives": [],
      "correct": null,
      "created_at": "2026-01-01T00:00:00+00:00"
    }
  ]
}

Valores típicos de status no item: ativa, inativa, anulada, desatualizada. Na busca padrão prevalecem questões ativas e não anuladas; outros status podem aparecer se os critérios da API forem alterados.

Campos extras quando simulated_id está presente

Se a requisição incluir simulated_id (validado), a resposta acrescenta contagens com os mesmos filtros da página atual, variando só included:

{
  "total": 0,
  "page": 1,
  "limit": 10,
  "data": [],
  "adicionadas": 0,
  "disponiveis": 0
}
  • adicionadas: total com included = true (questões já no simulado externo indicado).
  • disponiveis: total com included = false (não vinculadas a esse simulado externo).

2. Filtros — Temas

Campo Valor
Método GET
Path /api/admin-ext/questoes/filters/themes

Entrada (query)

Parâmetro Observação
specialties ou specialty Lista de IDs de especialidade. Aceita array na query (specialties[]=1&specialties[]=2), valor único ou string com vírgulas; apenas inteiros positivos são considerados.

Saída (200)

Array de objetos { "id", "name" } de temas, opcionalmente filtrados pelas especialidades informadas.

3. Filtros — Grandes áreas (medicina)

Campo Valor
Método GET
Path /api/admin-ext/questoes/filters/areas

Entrada

Nenhum.

Saída (200)

Array de { "id", "name" } de grandes áreas (medicina), ordenado por nome.

4. Filtros — Especialidades

Campo Valor
Método GET
Path /api/admin-ext/questoes/filters/specialties

Entrada (query)

Parâmetro Observação
areas ou area IDs de grande área; mesma convenção de lista que em Filtros — Temas.

Saída (200)

Array de { "id", "name" } de especialidades, filtrado pelas grandes áreas quando informadas.

5. Filtros — Finalidades (specificallies)

Campo Valor
Método GET
Path /api/admin-ext/questoes/filters/finalidades

Entrada

Nenhum.

Saída (200)

Array de { "id", "name" } de finalidades (specificallies), ordenado por nome.

6. Filtros — Provas (exams)

Campo Valor
Método GET
Path /api/admin-ext/questoes/filters/exams

Entrada (query)

Parâmetro Observação
uf UF da banca (string; comparada em maiúsculas)
ano ID do ano da prova
specificallies Array ou lista separada por vírgula com IDs de finalidade
institutions IDs de instituição (banca)

Considera provas no formato padrão do catálogo, relacionando banca e ano. Cada item retornado:

{
  "id": 1,
  "name": "Nome da banca Ano"
}

7. Filtros — Anos

Campo Valor
Método GET
Path /api/admin-ext/questoes/filters/years

Entrada (query)

Parâmetro Observação
uf Opcional; restringe a anos que aparecem em provas cuja instituição tem essa UF

Saída (200)

Array de { "id", "name" } de anos (únicos no resultado), ordenado por nome.

8. Filtros — Instituições (bancas)

Campo Valor
Método GET
Path /api/admin-ext/questoes/filters/institutions

Entrada (query)

Parâmetro Observação
prova ID da prova
finalidade ID da finalidade; combina com specificallies quando ambos forem enviados
specificallies IDs adicionais de finalidade
uf String ou array; vírgulas separam várias UFs; valores tratados em maiúsculas
year ou years IDs de ano

Saída (200)

Array de objetos com pelo menos id, name, uf de cada banca, ordenado por nome.

Agregado único de filtros

Não há endpoint que devolva todos os filtros (dificuldades, temas, áreas, etc.) em uma única resposta. Utilize os caminhos /filters/... documentados nesta página.