API — Simulados externos (admin-ext)

Contexto

Item	Valor
Prefixo global da API	/api
Prefixo do grupo	/admin-ext/simulados
Base completa	/api/admin-ext/simulados
Autenticação	Header Authorization: Bearer {token} (ou cookie de sessão, se o cliente estiver configurado assim); perfil institucional com instituição vinculada.

Respostas não listadas explicitamente como erro costumam ser JSON com código HTTP correspondente. Erros de validação costumam retornar 422 com corpo JSON (o formato pode variar por rota; ver exemplos em cada seção).

---

1. Resumo por status

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

Entrada

Nenhum parâmetro.

Saída (200)

Objeto com totais de simulados externos agrupados por status lógico:

{
  "total": 0,
  "by_status": {
    "agendados": 0,
    "ativos": 0,
    "encerrado": 0,
    "rascunho": 0
  }
}

---

2. Listar simulados (paginado)

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

Entrada (query string)

Parâmetro	Tipo	Padrão	Observação
page	int	1
limit	int	10
sort	string	start_date	Ordenação: name, start_date, end_date ou created_at; outros valores equivalem a start_date.
direction	string	asc	desc ou outro valor (tratado como asc quando não for desc).
status	string	—	Filtro: agendado, agendados, ativo, ativos, encerrado, rascunho.
search	string	—	Busca por nome (correspondência parcial).

Saída (200)

{
  "total": 0,
  "data": [
    {
      "id": "1",
      "name": "",
      "duration": 0,
      "start_date": null,
      "end_date": null,
      "questions_count": 0,
      "status": "agendado"
    }
  ]
}

Valores possíveis de status na listagem: agendado, ativo, encerrado, Rascunho (a capitalização pode variar conforme o retorno da API).

---

3. Detalhe de um simulado

Campo	Valor
Método	GET
Path	/api/admin-ext/simulados/{id}

Entrada

• Path: id — identificador do simulado (inteiro).

Saída (200)

{
  "id": "1",
  "name": "",
  "description": null,
  "duration_minutes": 0,
  "start_date": null,
  "end_date": null,
  "questions_count": 0,
  "status": "Rascunho",
  "created_at": "2026-01-01T00:00:00+00:00",
  "updated_at": "2026-01-01T00:00:00+00:00"
}

status na resposta: Rascunho, Agendado, Ativo, Encerrado.

Erros

• 404 — simulado não encontrado.

---

4. Criar simulado

Campo	Valor
Método	POST
Path	/api/admin-ext/simulados

Regras de validação (body JSON)

Campo	Regras
name	obrigatório, string, máx. 255, único entre simulados externos
description	opcional, string, nullable
duration_minutes	obrigatório, inteiro, mínimo 1
start_date	obrigatório, data válida
end_date	obrigatório, data válida, maior ou igual a start_date

Saída (201)

{
  "id": "1",
  "status": "created"
}

Erros adicionais (422)

• Corpo pode ser { "error": "Já existe um simulado com este nome" } para conflito de nome.
• Ou { "success": false, "message": "Falha na validação", "data": { ... } } para outros erros de validação.
• { "error": "Usuário institucional sem produto vinculado" } quando a conta institucional não possui produto associado.

---

5. Atualizar simulado

Campo	Valor
Método	PUT
Path	/api/admin-ext/simulados/{id}

Entrada

• Path: id
• Body JSON — todos os campos abaixo são opcionais; apenas os enviados são atualizados:

Campo	Regras
name	string, máx. 255, único entre externos ignorando o próprio id
description	nullable, string
duration_minutes	inteiro, mínimo 1
start_date	data
end_date	data, deve ser maior ou igual a start_date

Saída (200)

{
  "status": "updated"
}

Erros (422)

• Nome duplicado: { "error": "Já existe um simulado com este nome" }.
• Alteração de start_date quando o simulado já iniciou: { "error": "Não é permitido alterar a data de início de um simulado já iniciado" }.

Erros (404)

• Simulado não encontrado.

---

6. Excluir simulado

Campo	Valor
Método	DELETE
Path	/api/admin-ext/simulados/{id}

Saída (200)

{
  "status": "deleted"
}

Erros (404)

• Simulado não encontrado.

---

7. Listar questões do simulado (com filtros)

Campo	Valor
Método	GET
Path	/api/admin-ext/simulados/{id}/questions

Consistência do simulated_id

Se simulated_id for enviado na query e for diferente do {id} do path, a API responde 422 com mensagem: O parâmetro simulated_id deve ser igual ao id do simulado na URL.

Parâmetros de query permitidos

Somente as chaves abaixo são aceitas; outras geram erro de validação (“Parâmetro não permitido.”).

Parâmetro	Regras
name	nullable, string, máx. 65535
page	nullable, inteiro ≥ 1
limit	nullable, inteiro entre 1 e 100
simulated_id	nullable, inteiro ≥ 1
included	nullable, boolean
uf	nullable, string, tamanho 2
specificallies	nullable, array de inteiros ≥ 1
tests	nullable, array de inteiros ≥ 1
type	nullable, objetiva ou discursiva
commented	nullable, boolean
themes, areas, specialties, years, institutions	nullable, arrays de inteiros ≥ 1

Saída (200)

{
  "simulated_id": "1",
  "total": 0,
  "data": [
    {
      "id": "1",
      "statement": "",
      "type": "objetiva",
      "themes": [],
      "areas": [],
      "specialties": [],
      "specifically": null,
      "status": "ativa",
      "order": 1,
      "exam": null,
      "commented": false,
      "alternatives": [],
      "correct": null,
      "created_at": "2026-01-01T00:00:00+00:00"
    }
  ]
}

status da questão pode ser, entre outros: ativa, inativa, anulada, desatualizada.

Erros (404)

• Simulado não encontrado.

Erros (422)

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

---

8. Adicionar questões ao simulado

Campo	Valor
Método	POST
Path	/api/admin-ext/simulados/{id}/questions

Regras de validação (body JSON)

Campo	Regras
questions	obrigatório, array com pelo menos 1 item
questions.*	inteiro, distintos entre si, cada um deve ser o ID de uma questão existente

Saída (200)

{
  "added": 0
}

added é a quantidade de questões inseridas.

Erros (422)

• Validação: { "success": false, "message": "Erro de validação", "errors": { ... } }.
• Questão já vinculada: { "error": "Questão já adicionada ao simulado" }.

Erros (404)

• Simulado não encontrado.

---

9. Remover questão do simulado

Campo	Valor
Método	DELETE
Path	/api/admin-ext/simulados/{id}/questions/{questionId}

Saída (200)

{
  "status": "removed"
}

Erros (404)

• Simulado não encontrado (ou recurso relacionado indisponível).

---

10. Detalhe de uma questão no simulado

Campo	Valor
Método	GET
Path	/api/admin-ext/simulados/{id}/questions/{questionId}

Saída (200)

{
  "statement": "",
  "type": "objetiva",
  "alternatives": [],
  "correct": null,
  "comment": null,
  "exam": null
}

Erros (404)

• Questão não pertence ao simulado ou não encontrada.

---

11. Atualizar ordem da questão no simulado

Campo	Valor
Método	PATCH
Path	/api/admin-ext/simulados/{id}/questions/{questionId}/ordem

Entrada (body)

Campo	Observação
order	Número inteiro da nova ordem; se ausente ou não numérico, a API pode interpretar como 0.

Saída (200)

{
  "status": "order_updated"
}

Erros (404)

• Simulado não encontrado.

---

Path resume vs. {id}

O segmento fixo resume no path (GET /api/admin-ext/simulados/resume) não é um identificador numérico de simulado; use sempre esse path completo para o resumo por status.