Cursos
Esta página descreve os endpoints do recurso Cursos (tela Cursos, do menu Comercial), o catálogo de treinamentos da empresa cliente. Cada curso pode ser vendido no ponto de venda, incluído em combos e em contratos, e usado para abrir turmas. Os dados de cada curso que ficam em abas próprias (complementos, acreditações, assinaturas, conteúdo programático, instrutores, integrações e imagem de fundo) têm páginas nesta mesma pasta, listadas no fim desta página.
As regras gerais (endereço base, cabeçalhos, paginação e erros) estão em Convenções. A obtenção do token de sessão está em Autenticação.
Endpoints
| Método | Caminho | Descrição |
|---|---|---|
| GET | /comercial/courses | Lista os cursos |
| POST | /comercial/courses | Cadastra um curso |
| GET | /comercial/courses/{uuid} | Consulta um curso |
| PUT | /comercial/courses/{uuid} | Altera um curso |
| DELETE | /comercial/courses/{uuid} | Apaga um curso (exclusão lógica) |
| PATCH | /comercial/courses/{uuid}/inactivate | Ativa ou inativa o curso |
| PATCH | /comercial/courses/{uuid}/validity | Aplica a validade atual do curso a todos os treinamentos dele |
| GET | /comercial/courses/exports | Exporta a lista de cursos em planilha |
| GET | /comercial/courses/import-template | Baixa o modelo de planilha para importação |
| POST | /comercial/courses/import | Importa cursos a partir de planilha |
| GET | /comercial/courses/reports | Lista os relatórios de cursos disponíveis |
| GET | /comercial/courses/groups | Lista os grupos de cursos |
| GET | /comercial/courses/layouts | Lista os layouts de certificado |
| GET | /comercial/courses/modalities | Lista as modalidades de treinamento |
| GET | /comercial/courses/business | Lista as empresas clientes ativas |
Os caminhos alternativos desta listagem, usados por outras telas, estão em Caminhos alternativos, no fim desta página.
Sub-recursos do curso
| Aba da tela do curso | Página |
|---|---|
| Complementos do curso | Complementos |
| Complementos da empresa | Complementos da empresa |
| Acreditações | Acreditações |
| Assinaturas | Assinaturas |
| Conteúdo programático | Conteúdo programático |
| Instrutores | Instrutores |
| Instrutores qualificados | Instrutores qualificados |
| Integrações | Integrações |
| Imagem de fundo | Imagem de fundo |
Consultar e listar
GET /comercial/courses
Lista os cursos da empresa cliente do usuário. Sem per_page, a resposta é a lista direta; com per_page, a resposta é paginada.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
search | Texto livre: nome do curso, nome curto, código ou nome do grupo |
group_uuid | Lista apenas os cursos do grupo informado |
group_id | Idem, pelo id numérico do grupo |
practical | 1 lista os cursos com carga horária prática; 0 lista os que não têm carga prática (zero ou vazia) |
instructors | 0 lista os cursos sem instrutor; 1 lista os cursos com instrutor |
inactive | 0 ou 1, filtra pela situação do curso. Sem o parâmetro, a lista traz ativos e inativos |
column e order | Ordenação: nome da coluna e asc ou desc. Sem ordenação, a lista sai por grupo e, dentro do grupo, pelo nome do curso |
Resposta: lista de cursos. Campos principais: uuid, id, code (código sequencial por cliente), group_uuid, group_name, course, short_name, course_english, workload (carga horária total), theory_workload, practical_workload, validity (em meses), amount (valor de referência), online, photo, external_certification, inactive, instructors_count e os nomes de quem criou e alterou o registro.
GET /comercial/courses/{uuid}
Consulta um curso pelo uuid. A resposta é o mesmo objeto da listagem.
Cadastrar e alterar
POST /comercial/courses
Cadastra um curso. O sistema preenche sozinho o uuid, o code (sequencial por cliente), o workload (soma da carga teórica com a prática) e o registro de complementos do curso, que nasce vazio (veja Complementos).
Para copiar um curso existente, envie source_uuid. O novo curso recebe uma cópia de complementos, conteúdo programático, complementos por empresa, instrutores, assinaturas e acreditações. Imagem de fundo, integrações com plataformas externas e instrutores qualificados não são copiados.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
course | Sim | Texto | Nome do curso, como aparece em listas, contratos e documentos |
short_name | Sim | Texto | Nome curto, usado em listas e cabeçalhos |
group_uuid | Não | Texto (uuid) | Grupo do curso. Use um uuid da listagem de grupos |
theory_workload | Não | Inteiro | Carga horária teórica, em horas |
practical_workload | Não | Inteiro | Carga horária prática, em horas. Em branco, conta como zero |
course_english | Não | Texto | Nome do curso em inglês |
validity | Não | Inteiro | Validade do treinamento, em meses. Em branco, o curso não tem validade |
amount | Não | Número | Valor de referência do curso |
online | Não | Booleano | Marca o treinamento como somente online |
photo | Não | Booleano | Indica se a foto do aluno sai no certificado e na carteirinha |
external_certification | Não | Booleano | Indica que o treinamento requer certificação externa |
source_uuid | Não | Texto (uuid) | uuid de um curso existente, para copiar os dados dele |
Exemplo
curl -X POST "https://api.pedagogo.app/comercial/courses" \
-H "Authorization: Bearer <token-de-sessao>" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"course": "Curso exemplo", "short_name": "Curso exemplo", "theory_workload": 8, "practical_workload": 0}'
Resposta: 200 com o curso criado, incluindo uuid, id e code.
PUT /comercial/courses/{uuid}
Altera um curso. Envie os campos que quiser alterar, com os mesmos nomes do cadastro. Só group_uuid tem validação de formulário.
Ao salvar, o sistema recalcula o grupo e a carga horária total a partir dos campos enviados. Para não perder o grupo nem a carga horária, reenvie group_uuid, theory_workload e practical_workload com os valores atuais, mesmo que a alteração seja em outro campo.
Ao salvar um curso existente, a validade informada passa a valer para os treinamentos desse curso que ainda não foram concluídos.
Resposta: 200 com o curso alterado.
DELETE /comercial/courses/{uuid}
Apaga o curso. A exclusão é lógica: o curso sai das listagens, e os dados ficam guardados. Se o curso estiver vinculado a uma integração de ensino, os alunos dele que estão registrados na plataforma externa também são removidos dela. A API não verifica se o curso tem turmas ou alunos antes de apagar.
Resposta: 200, sem corpo.
PATCH /comercial/courses/{uuid}/inactivate
Alterna o curso entre ativo e inativo. Um curso inativo continua cadastrado e não é apagado.
Resposta: 200, sem corpo.
PATCH /comercial/courses/{uuid}/validity
Aplica a validade atual do curso a todos os treinamentos dele, inclusive os já concluídos. A tela só exibe esta ação para o perfil de permissão máxima. A alteração dispara um job com a lista dos alunos afetados.
Resposta: 200, sem corpo.
Importação e exportação
GET /comercial/courses/exports
Gera uma planilha xlsx com a lista de cursos, respeitando os mesmos search, column e order da listagem.
Resposta: arquivo xlsx para download.
GET /comercial/courses/import-template
Baixa o modelo de planilha para importação de cursos.
Resposta: arquivo xlsx para download.
POST /comercial/courses/import
Importa cursos a partir de uma planilha. Use multipart/form-data.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
file | Sim | Arquivo | Planilha xlsx, no modelo baixado em import-template |
A planilha tem uma linha por curso, com a primeira linha de cabeçalho. Só entram as linhas com Curso (coluna A), Nome curto (B) e Valor (E) preenchidos. As colunas são, na ordem: A) Curso; B) Nome curto; C) Curso em inglês; D) Validade (meses); E) Valor; F) Carga horária prática; G) Carga horária teórica; H) Norma; I) Norma em inglês; J) Descrição da norma; K) Descrição da norma em inglês; L) Público-alvo; M) Público-alvo em inglês; N) Metodologia; O) Metodologia em inglês; P) Pré-requisitos; Q) Pré-requisitos em inglês.
A importação não preenche grupo, layout, certificado nem conteúdo programático. Não verifica se o curso já existe: importar a mesma planilha duas vezes cria cursos duplicados. O resultado (total de linhas lidas e de cursos importados) é enviado como notificação ao usuário que fez a chamada.
Resposta: 201 com {"success": true}.
Listas de apoio
GET /comercial/courses/groups
Lista os grupos de cursos da empresa cliente. Parâmetros: search (nome do grupo), column e order. Campos principais: uuid e group.
GET /comercial/courses/layouts
Lista os layouts de certificado disponíveis. Parâmetros: search (nome do layout), column e order. Campos: id e layout. Use o id no campo layout_id dos complementos do curso.
GET /comercial/courses/modalities
Lista as modalidades de treinamento da empresa cliente. Parâmetros: search (nome da modalidade). Campos: id, uuid e modality.
GET /comercial/courses/business
Lista as empresas clientes ativas. Parâmetro: search. Use o id ou o uuid retornado nos campos que pedem uma empresa, conforme a página de cada recurso.
GET /comercial/courses/reports
Lista os relatórios de cursos disponíveis para a empresa cliente. Não recebe parâmetros.
Caminhos alternativos
As telas de turmas, pré-matrículas, solicitações e relatórios usam os mesmos controladores de algumas listas acima. A resposta é a mesma do endpoint principal indicado.
| Método | Caminho | Equivale a |
|---|---|---|
| GET | /comercial/classes/courses | GET /comercial/courses |
| GET | /comercial/classes/courses/{uuid} | GET /comercial/courses/{uuid} |
| GET | /comercial/classes/modalities | GET /comercial/courses/modalities |
| GET | /comercial/enrollments/pre-enrollments/courses | GET /comercial/courses |
| GET | /comercial/enrollments/requests/courses | GET /comercial/courses |
| GET | /comercial/reports/courses | GET /comercial/courses |
| GET | /comercial/reports/modalities | GET /comercial/courses/modalities |