Skip to content

API — Portal da instituição (/institution)

Contexto

Item Valor
Prefixo global da API /api
Prefixo do grupo /institution
Base completa /api/institution

Autenticação

  • Rotas públicas (sem token): POST /login, GET /images.
  • Demais rotas: Authorization: Bearer {token} com token obtido no login institucional.

Rotas protegidas (escopo institucional)

Nas rotas que exigem autenticação, o usuário deve estar autenticado, com perfil institucional e com instituição externa vinculada.

HTTP Resposta típica
401 { "message": "Não autenticado." } (sem usuário)
403 { "message": "Acesso restrito a usuários institucionais." }
403 { "message": "Usuário institucional sem instituição vinculada." }

1. Login institucional

Campo Valor
Método POST
Path /api/institution/login

Regras de validação (body JSON)

Campo Regras
email obrigatório, string, e-mail válido, máx. 255
password obrigatório, string, entre 6 e 100 caracteres

Saída (200)

{
  "success": true,
  "data": {
    "token": "...",
    "token_type": "Bearer",
    "user": {
      "id": 1,
      "name": "",
      "email": "",
      "external_institution_id": 1,
      "external_institution_name": ""
    }
  }
}

Erros

  • 422 — { "success": false, "message": "Falha na validação", "data": { ... } }
  • 401 — { "success": false, "message": "E-mail ou senha inválidos." } ou mensagem de usuário sem instituição vinculada

2. Listar imagens de instituições externas

Campo Valor
Método GET
Path /api/institution/images

Entrada

Nenhum parâmetro.

Saída (200)

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "",
      "image": "https://..."
    }
  ]
}

Retorno: instituições externas que possuem imagem cadastrada, ordenadas por nome.

3. Logout

Campo Valor
Método POST
Path /api/institution/logout

Encerra a sessão revogando os tokens de acesso associados ao usuário institucional.

Saída (200)

{
  "message": "Logout realizado com sucesso."
}

4. Perfil do usuário autenticado (me)

Campo Valor
Método GET
Path /api/institution/me

Saída (200)

{
  "id": 1,
  "name": "",
  "email": "",
  "external_institution_id": 1,
  "external_institution": null
}

external_institution reflete a instituição vinculada ao usuário; pode ser objeto ou null.

5. Turmas (class groups) da instituição

Campo Valor
Método GET
Path /api/institution/class-groups

Retorna apenas turmas ativas da instituição do usuário autenticado.

Saída (200)

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "",
      "external_institution_id": 1
    }
  ]
}

6. Métricas gerais

Campo Valor
Método GET
Path /api/institution/metrics

Entrada (query string)

Parâmetro Tipo Observação
turma int (opcional) ID da turma; restringe métricas aos alunos dessa turma.
startDate string (opcional) Início do período.
endDate string (opcional) Fim do período.

Use datas em formato comum YYYY-MM-DD, salvo indicação contrária do ambiente.

Saída (200)

{
  "success": true,
  "data": {
    "total_questions_realized": 0,
    "average_correct_percentage": 0,
    "average_by_mock_test": [],
    "performance_by_great_area": [],
    "lessons_watched": {},
    "metrics_by_source": [],
    "filters": {
      "class_group_id": null,
      "start_date": null,
      "end_date": null
    }
  }
}

Os arrays e objetos internos agregam simulados, áreas, aulas, fontes de tráfego etc., conforme filtros informados.

7. Resumo institucional

Campo Valor
Método GET
Path /api/institution/summary

Entrada (query string)

Mesmos parâmetros opcionais de Métricas gerais: turma, startDate, endDate.

Saída (200)

{
  "success": true,
  "data": {
    "institution_name": "",
    "product": {
      "name": "Extensivo ENAMED - São Camilo"
    },
    "students": {
      "enrolled": 0,
      "active": 0
    },
    "metrics": {
      "total_questions_realized": 0,
      "average_questions_accuracy": 0,
      "followed_mock_tests": 0,
      "average_lessons_adherence": 0,
      "average_watched_time_per_student": 0,
      "average_questions_per_student": 0,
      "average_mock_tests_per_student": 0
    }
  }
}

8. Listar alunos

Campo Valor
Método GET
Path /api/institution/students

Entrada (query string)

Parâmetro Tipo Padrão / limite
per_page int padrão 15, máximo 50
page int mínimo 1
name string filtro por nome (opcional)
email string filtro por e-mail (opcional)
turma int ID da turma (opcional)
startDate string período (opcional)
endDate string período (opcional)
media string filtro de desempenho (opcional); valores aceitos: above, below, above_50, below_50

Valores de media fora dessa lista são ignorados no filtro de desempenho.

Saída (200)

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "",
      "email": "",
      "registration_number": null,
      "class_group_id": 1,
      "active": 1,
      "created_at": "...",
      "class_group": { "id": 1, "name": "" },
      "metrics": {
        "media_aulas_assistidas": 0,
        "media_questoes_corretas": 0,
        "media_simulados": 0,
        "media_provas": 0,
        "media_pre": 0,
        "media_pos": 0,
        "media_bloco": 0
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 15,
    "total": 0
  },
  "summary": {
    "total_enrolled": 0,
    "total_active": 0
  }
}

9. Detalhe do aluno

Campo Valor
Método GET
Path /api/institution/students/{id}

Entrada

  • Path: id — identificador do aluno.
  • Query (opcional): startDate, endDate, mock_test_id (int) — restringe métricas de simulados a um mock test específico quando informado.

Saída (200)

{
  "success": true,
  "data": {
    "student": {
      "name": "",
      "email": "",
      "registration_number": null,
      "country": null,
      "state": null,
      "city": null,
      "registered_at": "2026-01-01T00:00:00+00:00"
    },
    "period": {
      "start_date": null,
      "end_date": null
    },
    "metrics": {
      "questions_completed": 0,
      "mock_tests_completed": 0,
      "mock_tests_average_accuracy_percentage": 0,
      "mock_tests_in_period": [],
      "flashcards_completed": 0,
      "schedule_adherence_percentage": 0,
      "lessons": {
        "request_period": null,
        "weekly": {},
        "monthly": {}
      },
      "total_correct_answers": 0,
      "average_questions_per_day": 0,
      "questions_average_accuracy_percentage": 0,
      "performance_by_area": {}
    }
  }
}

Chaves em performance_by_area podem incluir gynecology_obstetrics, pediatrics, clinical_medicine, surgery, preventive_medicine, conforme a grande área médica.

Erros

  • 404 — { "success": false, "message": "Aluno não encontrado ou não pertence à sua instituição." }
  • 403 — erros de permissão ou regra de negócio podem retornar 403 quando não for 404.