Convenções

Regras que valem para todos os endpoints. As páginas de cada módulo só repetem o que for diferente.

Endereço base

https://api.pedagogo.app

Os caminhos nas páginas da referência são relativos a esse endereço. Não há prefixo de versão: o caminho começa pelo módulo, por exemplo /comercial/courses ou /administrative/departments.

Cabeçalhos

Cabeçalho	Valor	Quando
Authorization	Bearer <token-de-sessao>	Em todas as chamadas, exceto POST /auth/login-by-token
Accept	application/json	Sempre. Sem ele, erros de validação podem voltar como redirecionamento em vez de JSON
Content-Type	application/json	Em chamadas com corpo JSON. Para envio de arquivos, use multipart/form-data

Identificadores

A maioria dos registros é identificada por um uuid (por exemplo 3f1c0b6e-8a2d-4c57-9b1e-2d7a5f0e6a11), usado no caminho: GET /administrative/departments/{uuid}. A resposta de criação devolve o uuid do novo registro. Alguns recursos auxiliares usam o id numérico; as páginas de cada módulo indicam qual.

Verbos

Verbo	Uso
GET	Consultar uma lista ou um registro
POST	Criar um registro ou executar uma ação
PUT / PATCH	Alterar um registro
DELETE	Apagar um registro

Listagens

Os endpoints de listagem aceitam estes parâmetros na URL:

Parâmetro	Descrição
search	Texto livre para buscar nas colunas principais do recurso
per_page	Quantidade de registros por página. Se for omitido, a API devolve todos os registros de uma vez, em uma lista simples
page	Número da página, quando per_page é informado

Com per_page, a resposta é paginada:

{
  "current_page": 1,
  "data": [ { "uuid": "...", "department": "Comercial" } ],
  "from": 1,
  "to": 1,
  "per_page": 15,
  "total": 1
}

Sem per_page, a resposta é a lista direta: [ { ... }, { ... } ].

Filtros e ordenações específicos de cada recurso (por exemplo, filtrar por nome do departamento) estão descritos na página do recurso.

Criar e alterar

Envie os campos em JSON. Os campos obrigatórios de cada endpoint estão na tabela Corpo da página do recurso. O servidor preenche sozinho o que é do sistema: o uuid, a empresa cliente e o usuário que criou ou alterou o registro.

Erros

Status	Significado
401	Autenticação ou acesso negado, com {"error": "..."}. Veja Autenticação
404	Registro não encontrado, ou que pertence a outra empresa cliente
422	Dados inválidos. O corpo traz message e errors, com a lista de mensagens por campo

Exemplo de erro de validação:

{
  "message": "The department field is required.",
  "errors": {
    "department": ["The department field is required."]
  }
}

Acesso por tela

Cada endpoint pertence a uma tela do menu. Para chamá-lo, o pacote do cliente precisa incluir essa tela e o grupo de acesso do usuário precisa liberá-la (veja Pacotes e Grupos de acesso). Caso contrário, a resposta é 401 com You do not have access to this page..