Solicitações de treinamento
Os endpoints desta página atendem a tela Solicitações de treinamento. Uma solicitação é um pedido de treinamento feito por uma empresa cliente, para que funcionários dela façam cursos. Os pedidos chegam sozinhos, pela integração com o sistema da empresa, e não há criação manual pela API. Use estes endpoints para consultar as solicitações, alterar os dados e o status (inclusive para recusar um pedido), e matricular o participante a partir do pedido.
Endpoints
| Método | Caminho | Descrição |
|---|---|---|
GET | /comercial/training-requests | Lista as solicitações do cliente. |
GET | /comercial/training-requests/{uuid} | Consulta uma solicitação. |
PUT | /comercial/training-requests/{uuid} | Altera os dados, o status e o motivo da recusa de uma solicitação. |
POST | /comercial/training-requests/{uuid}/enroll | Matricula o participante a partir da solicitação. |
Solicitações
GET /comercial/training-requests
Lista as solicitações do cliente da sessão. Sem per_page, a resposta é a lista direta. Com per_page, a resposta vem paginada, como descrito em Convenções.
Parâmetros de URL
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
search | Não | Texto livre: busca pelo nome do curso, pelo nome do cliente, pelo nome do participante, pelo e-mail e pelo número do documento. |
column | Não | Coluna usada na ordenação. Usada junto com order. |
order | Não | Sentido da ordenação, como asc ou desc. Usado junto com column. |
per_page | Não | Quantidade de registros por página. |
page | Não | Número da página, quando per_page é informado. |
Resposta
200, com a lista de solicitações. Campos principais: uuid, full_name, email, document_type, document_number, course_id, course_name, external_course_name, modality, workload, validity, preferred_start_date, preferred_end_date, not_accepted_reason, notes, user_update_name e trainingRequestStatus, com o status da solicitação e o nome exibido.
Exemplo:
curl -G "https://api.pedagogo.app/comercial/training-requests" \
-H "Authorization: Bearer <token-de-sessao>" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
--data-urlencode "search=Curso exemplo" \
--data-urlencode "per_page=15"
Consultar e alterar
GET /comercial/training-requests/{uuid}
Devolve a solicitação identificada por {uuid}, com o curso (course) e o status (trainingRequestStatus).
PUT /comercial/training-requests/{uuid}
Altera a solicitação identificada por {uuid}. Envie só os campos que quer mudar. Os campos omitidos mantêm o valor atual.
Para recusar um pedido, envie status com o valor not_accepted e, junto, o motivo em not_accepted_reason. Quando o status muda, a alteração é enviada à origem da solicitação, em segundo plano. Solicitações sem identificação de origem não são enviadas.
Corpo
Nenhum campo é obrigatório. Os valores de status, modality e document_type são os códigos listados abaixo.
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
requester_user | Não | Texto (até 255 caracteres) | Usuário solicitante, como informado pela empresa. |
status | Não | Texto | Novo status da solicitação. Valores: received (Recebida), enrolled (Matriculada), completed (Concluída), cancelled (Cancelada) e not_accepted (Não aceita). |
not_accepted_reason | Não | Texto (até 1.000 caracteres) | Motivo da recusa. Enviado à origem da solicitação quando o status é not_accepted. |
full_name | Não | Texto (até 255 caracteres) | Nome completo do participante. |
email | Não | Texto (e-mail, até 255 caracteres) | E-mail do participante. |
document_type | Não | Texto | Tipo do documento do participante: cpf ou passport. |
document_number | Não | Texto (até 30 caracteres) | Número do documento do participante. |
course_id | Não | Número | id do curso. O curso precisa existir. Os ids vêm de GET /comercial/reports/courses. |
external_course_name | Não | Texto (até 255 caracteres) | Nome do curso como veio no pedido. |
validity | Não | Número inteiro | Validade do treinamento. |
workload | Não | Número inteiro | Carga horária do treinamento. |
modality | Não | Texto | Modalidade: in_company (empresa), online ou hybrid (híbrida). |
preferred_start_date | Não | Data | Data de início preferida. |
preferred_end_date | Não | Data | Data de término preferida. |
notes | Não | Texto | Observações. |
Resposta
200, com a solicitação alterada.
Exemplo de recusa:
curl -X PUT "https://api.pedagogo.app/comercial/training-requests/<uuid-da-solicitacao>" \
-H "Authorization: Bearer <token-de-sessao>" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"status": "not_accepted",
"not_accepted_reason": "Motivo exemplo"
}'
Matricular
POST /comercial/training-requests/{uuid}/enroll
Matricula o participante da solicitação {uuid} e atualiza o status da solicitação para Matriculada (enrolled). O corpo é opcional: sem ele, a matrícula usa o curso já vinculado à solicitação e é avulsa.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
course_id | Não | Número | id do curso da matrícula. Se omitido, usa o curso já vinculado à solicitação. Sem curso em nenhum dos dois, a resposta é 422. |
class_uuid | Não | Texto (uuid) | uuid da turma. Se informado, a matrícula é feita na turma. Se omitido, a matrícula é avulsa. A turma precisa existir. |
O que a matrícula faz
- Cadastra o participante como aluno do cliente, com o nome, o documento e o e-mail do pedido.
- Cria a matrícula do aluno no curso, com valor zero e a justificativa "Matrícula via solicitação de treinamento". A empresa solicitante fica vinculada à matrícula.
- Matrícula avulsa: a data de início é a data de início preferida do pedido (ou a data de hoje, se o pedido não tiver essa data), e a data de término é a data de término preferida. A matrícula também é enviada para a plataforma online/EAD, em segundo plano. Se a data de início for futura, o envio acontece nessa data.
- Matrícula em turma: as datas da matrícula passam a ser as da turma. A data de início é a de início da turma, e a data de término é a da turma (se a turma não tiver término, usa a data de término preferida do pedido). A data preferida do pedido não é usada.
- Vincula a solicitação ao aluno e à matrícula criados. Depois disso, o status da solicitação passa a acompanhar o status do aluno vinculado.
Resposta
200, com a solicitação atualizada, já com o status Matriculada e os vínculos com o aluno e a matrícula.
Se a solicitação não existir para o cliente da sessão, a resposta é 404.
Exemplo de matrícula em turma:
curl -X POST "https://api.pedagogo.app/comercial/training-requests/<uuid-da-solicitacao>/enroll" \
-H "Authorization: Bearer <token-de-sessao>" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"class_uuid": "<uuid-da-turma>"
}'