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.
  • 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. 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."
}

3. 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.

4. 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
    }
  ]
}

5. 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.

6. 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
    }
  }
}

7. 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
  }
}

8. 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.

9. Resumo institucional da última semana

Campo Valor
Método GET
Path /api/institution/summary/last-week

Entrada (query params)

Campo Tipo Obrigatório Descrição
turma inteiro não ID da turma para filtrar o resumo.

Regra de período

Este endpoint calcula automaticamente o período da semana passada completa (início e fim da semana anterior no servidor) e aplica no resumo institucional.

Saída (200)

{
  "success": true,
  "data": {
    "institution_name": "Instituição X",
    "products": [
      { "id": 1, "name": "Produto Y" }
    ],
    "students": {
      "enrolled": 120,
      "active": 95
    },
    "metrics": {
      "total_questions_realized": {
        "total": 3500,
        "by_weekday": [
          { "weekday": 1, "name": "Segunda-feira", "count": 500 }
        ]
      },
      "average_questions_accuracy": 72.35,
      "followed_mock_tests": 8,
      "average_lessons_adherence": 61.2,
      "average_watched_time_per_student": 1840.5,
      "average_questions_per_student": 36.842,
      "average_mock_tests_per_student": 1.474
    }
  }
}

Erros

  • 401/403 — conforme regras de autenticação institucional.

10. Métricas essenciais do aluno na última semana

Campo Valor
Método GET
Path /api/institution/students/{id}/metrics/last-week

Entrada

Path params

Campo Tipo Obrigatório Descrição
id inteiro sim ID do aluno.

Query params

Campo Tipo Obrigatório Descrição
mock_test_id inteiro não Filtra métricas dos simulados por um simulado específico.

Regra de período

Este endpoint calcula automaticamente o período da semana passada completa e retorna as métricas essenciais do aluno nesse intervalo.

Saída (200)

{
  "success": true,
  "data": {
    "student": {
      "name": "Aluno A",
      "email": "aluno@email.com",
      "registration_number": "20260001"
    },
    "period": {
      "start_date": "2026-04-06",
      "end_date": "2026-04-12"
    },
    "metrics": {
      "questions_completed": 120,
      "mock_tests_completed": 2,
      "mock_tests_average_accuracy_percentage": 68.5,
      "mock_tests_in_period": [
        {
          "mock_test_id": 10,
          "name": "Simulado 1",
          "total_questions": 50,
          "total_correct": 35,
          "average_percentage": 70,
          "completed_at": "2026-04-10T20:10:00+00:00"
        }
      ],
      "flashcards_completed": 40,
      "total_correct_answers": 82,
      "average_questions_per_day": 17.14,
      "questions_average_accuracy_percentage": 68.33
    }
  }
}

Erros

  • 404 — { "success": false, "message": "Aluno não encontrado ou não pertence à sua instituição." }
  • 401/403 — conforme regras de autenticação institucional.

11. Top temas por grande área

Campo Valor
Método GET
Path /api/institution/metrics/top-themes

Regras de validação (query params)

Campo Regras
area obrigatório, inteiro, valores permitidos: 1,2,3,4,5
student opcional, inteiro, mínimo 1
startDate opcional, data válida (YYYY-MM-DD)
endDate opcional, data válida (YYYY-MM-DD), deve ser >= startDate

area mapeia para: - 1 = Ginecologia e Obstetrícia - 2 = Pediatria - 3 = Clínica Médica - 4 = Cirurgia - 5 = Preventiva

Saída (200)

{
  "success": true,
  "data": {
    "area_id": 3,
    "area": "Clínica Médica",
    "themes": [
      { "theme_id": 101, "name": "Cardiologia", "percentage": 74.5 },
      { "theme_id": 115, "name": "Nefrologia", "percentage": 69.2 }
    ],
    "student_id": 55
  }
}

student_id só aparece quando o filtro student for enviado.

Erros

  • 422 — erro de validação dos query params.
  • 404 — { "success": false, "message": "Aluno não encontrado ou não pertence à sua instituição." } (quando student não pertence à instituição).
  • 401/403 — conforme regras de autenticação institucional.

12. Performance de temas por grande área (paginado)

Campo Valor
Método GET
Path /api/institution/metrics/themes-performance

Regras de validação (query params)

Campo Regras
area obrigatório, inteiro, valores permitidos: 1,2,3,4,5
student opcional, inteiro, mínimo 1
theme_name opcional, string, máx. 255
per_page opcional, inteiro, entre 1 e 50 (padrão 15)
page opcional, inteiro, mínimo 1 (padrão 1)

Saída (200)

{
  "success": true,
  "area_id": 3,
  "area": "Clínica Médica",
  "data": [
    { "theme_id": 101, "name": "Cardiologia", "percentage": 74.5 },
    { "theme_id": 115, "name": "Nefrologia", "percentage": 69.2 }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 15,
    "total": 58
  }
}

Erros

  • 422 — erro de validação dos query params.
  • 404 — { "success": false, "message": "Aluno não encontrado ou não pertence à sua instituição." } (quando student não pertence à instituição).
  • 401/403 — conforme regras de autenticação institucional.