Alunos online

Alunos online são matrículas avulsas, sem turma presencial. Cada registro é um aluno matriculado em um curso, com data de início, valor, pagamentos, resultado e certificado. Na tela, o recurso fica em Alunos online.

Todas as rotas desta página começam por /comercial/online-students e pertencem à tela Alunos online. Os sub-recursos têm página própria, listada abaixo.

Recurso	Tela	Página
Matrícula na plataforma online/EAD	Alunos online, ações Matricular no EAD (linha e lote)	Matrícula na plataforma online/EAD
Pagamentos	Alunos online, botão Pagamentos	Pagamentos do aluno online
Qualificações	Alunos online, ação Qualificação	Qualificações do aluno online
Certificados	Alunos online, ações Impressões e área de certificado	Certificados do aluno online
Complementos	Alunos online, campos Solicitante, Informação adicional para o certificado e Comentários	Complementos do aluno online
Datas	Datas de treinamento do aluno (ver a nota na página)	Datas do aluno online

Identificadores

Nesta tela há dois identificadores de aluno, e cada rota usa um deles:

uuid da matrícula (training_students.uuid): usado em /comercial/online-students/{uuid}, em change-status (campo students_uuid) e nos sub-recursos que recebem {student_uuid} ou {training_student_uuid}.
customer_vendor_student_uuid do cadastro do aluno (a pessoa): usado em {uuid}/photo, {uuid}/show-signature, {uuid}/send-registration-link-by-email, {uuid}/send-registration-link-by-whatsapp e no campo uuids do relatório de carta de confirmação.

A listagem GET /comercial/online-students devolve os dois valores (uuid e customer_vendor_student_uuid).

Endpoints

Método	Caminho	Descrição
`GET`	`/comercial/online-students`	Lista as matrículas online
`POST`	`/comercial/online-students`	Cadastra uma matrícula online
`GET`	`/comercial/online-students/{uuid}`	Consulta uma matrícula
`PUT`	`/comercial/online-students/{uuid}`	Altera uma matrícula
`DELETE`	`/comercial/online-students/{uuid}`	Exclui uma matrícula
`GET`	`/comercial/online-students/import-template`	Baixa a planilha modelo de importação
`POST`	`/comercial/online-students/import`	Envia uma planilha para importação em segundo plano
`GET`	`/comercial/online-students/import-progress/{token}`	Consulta o andamento de uma importação
`POST`	`/comercial/online-students/change-status`	Altera o status de uma ou mais matrículas
`PATCH`	`/comercial/online-students/{uuid}/send-registration-link-by-email`	Envia por e-mail o link de cadastro da assinatura eletrônica
`PATCH`	`/comercial/online-students/{uuid}/send-registration-link-by-whatsapp`	Envia por WhatsApp o link de cadastro da assinatura eletrônica
`GET`	`/comercial/online-students/contacts`	Lista os contatos das empresas dos certificados selecionados (lista de apoio)
`POST`	`/comercial/online-students/send-certificates`	Envia por e-mail os certificados selecionados
`GET`	`/comercial/online-students/check-schedule`	Verifica se o aluno tem matrícula em conflito de datas
`GET`	`/comercial/online-students/{uuid}/show-signature`	Devolve a assinatura cadastrada do aluno
`POST`	`/comercial/online-students/{uuid}/photo`	Envia a foto do aluno
`GET`	`/comercial/online-students/report/training-confirmation-letter`	Gera a carta de confirmação de treinamento de um ou mais alunos (PDF)
`GET`	`/comercial/online-students/{student_uuid}/contract`	Gera o contrato individual do aluno (PDF)
`GET`	`/comercial/online-students/{student_uuid}/attendance-record-report`	Gera o controle de presença do aluno (PDF)
`GET`	`/comercial/online-students/{student_uuid}/document-delivery-protocol-report`	Gera o protocolo de entrega de documentos do aluno (PDF)
`GET`	`/comercial/online-students/students`	Lista os cadastros de alunos do cliente (lista de apoio)
`GET`	`/comercial/online-students/business`	Lista as empresas clientes ativas (lista de apoio)
`GET`	`/comercial/online-students/business/{customer_vendor_uuid}/cost-centers`	Lista os centros de custo de uma empresa cliente (lista de apoio)
`POST`	`/comercial/online-students/business/{customer_vendor_uuid}/cost-centers`	Cadastra um centro de custo para uma empresa cliente
`GET`	`/comercial/online-students/business/{customer_vendor_uuid}/cost-centers/{id}`	Consulta um centro de custo
`GET`	`/comercial/online-students/companies`	Lista as empresas cadastradas no cliente (lista de apoio)
`GET`	`/comercial/online-students/statuses`	Lista os status de matrícula (lista de apoio)
`GET`	`/comercial/online-students/integrations`	Lista o catálogo de integrações (lista de apoio)
`GET`	`/comercial/online-students/complements/users`	Lista os usuários do cliente (lista de apoio)

Os certificados (/certificates*) estão em Certificados do aluno online. Os complementos (/complements*) estão em Complementos do aluno online, as datas (/dates*) em Datas do aluno online, os pagamentos (/payments* e /payment-methods) em Pagamentos do aluno online, as qualificações (/qualifications*) em Qualificações do aluno online e a matrícula na plataforma online/EAD em Matrícula na plataforma online/EAD.

Listagem

GET `/comercial/online-students`

Lista as matrículas online do cliente. Só entram matrículas sem turma presencial.

Sem per_page, a resposta é uma lista simples. Com per_page, a resposta é paginada, como descrito em Convenções.

Parâmetros de URL

Parâmetro	Descrição
`search`	Busca por nome, documento, celular e e-mail do aluno, nome e documento da empresa, e nome ou sigla do curso
`course_id`	`id` numérico do curso
`course`	Texto do nome ou da sigla do curso
`student`	Texto do nome, e-mail, celular ou CPF do aluno
`student_uuid`	`uuid` da matrícula
`customer_vendor_student_uuid`	`uuid` do cadastro do aluno
`company_id`	`id` numérico da empresa cadastrada no cliente
`customer_vendor_business_id`	`id` numérico da empresa cliente
`customer_vendor_business`	Texto do nome ou da razão social da empresa cliente
`without_business`	Qualquer valor preenchido: só alunos sem empresa cliente
`with_business`	Qualquer valor preenchido: só alunos com empresa cliente
`with_contract`	`1` ou `0`: alunos com (ou sem) contrato do curso
`status_id`	`id` do status. Aceita lista
`not_status_id`	`id` do status a excluir. Aceita lista
`start_date` e `end_date`	Período da data de início. Com os dois, vale a data de início ou a data de término dentro do período. Com um só, vale a data exata
`create_start_date` e `create_end_date`	Período da data de cadastro
`practice_start_date` e `practice_end_date`	Período da data da prática
`practical`	`1` para cursos com carga prática, `0` para cursos sem
`responsible_id` e `agent_id`	`id` do responsável e do agente
`column` e `order`	Coluna e sentido da ordenação (`asc` ou `desc`)
`limit`	Quantidade máxima de registros
`per_page` e `page`	Paginação

Resposta: 200. Cada item traz os dados da matrícula (uuid, customer_vendor_student_uuid, course_id, course_name, student_name, student_document, company_name, business_name, start_date, end_date, practice_date, amount, status_id, status_name, class_id, created_at, updated_at), o certificado da matrícula e, quando a matrícula está vinculada à plataforma online/EAD, o campo ead_code. Para aluno online, class_id vem nulo.

Exemplo

curl -X GET "https://api.pedagogo.app/comercial/online-students?status_id=2&per_page=15" \
  -H "Authorization: Bearer <token-de-sessao>" \
  -H "Accept: application/json"

Cadastro

POST `/comercial/online-students`

Cadastra uma matrícula online.

Se o aluno já tem uma matrícula avulsa no mesmo curso e na mesma data de início, o sistema reaproveita esse registro em vez de criar outro. Se ele estava excluído, volta a ficar ativo e recebe os novos dados.

Com customer_vendor_business_id preenchido e o curso com contrato para essa empresa, o valor vem do contrato e os campos de contrato são preenchidos pelo sistema. Quando há empresa, o sistema também dispara um job de sincronização do aluno em segundo plano.

Corpo

Campo	Obrigatório	Tipo	Descrição
`course_id`	Sim	número	`id` do curso. Validade e carga horária vêm do curso, quando não informadas
`customer_vendor_student_id`	Sim	número	`id` do cadastro do aluno
`start_date`	Sim	data	Data de início da matrícula
`amount`	Sim	número	Valor do treinamento para o aluno
`justification_gratuity`	Sim quando `amount` for `0`	texto	Motivo do valor zero
`company_id`	Não	número	`id` da empresa cadastrada no cliente
`customer_vendor_business_id`	Não	número	`id` da empresa cliente
`cost_center_id`	Não	número	`id` do centro de custo da empresa cliente
`validity`	Não	número inteiro	Validade do treinamento, em meses. Se omitida, vem do curso
`end_date`	Não	data	Data de término. Aprovado, Reprovado e Não concluído exigem esta data
`practice_date`	Não	data	Data da parte prática
`contract_course_id`	Não	número	`id` do contrato do curso com a empresa cliente

Resposta: 200, com o registro criado.

Exemplo

curl -X POST "https://api.pedagogo.app/comercial/online-students" \
  -H "Authorization: Bearer <token-de-sessao>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "course_id": 12,
    "customer_vendor_student_id": 345,
    "start_date": "2026-03-10",
    "amount": 0,
    "justification_gratuity": "Cortesia comercial"
  }'

Consulta, alteração e exclusão

GET `/comercial/online-students/{uuid}`

Devolve a matrícula com os dados do aluno (student_name, student_document, student_passport), o curso (course_name, course_validity, course_workload), a turma (quando houver), os complementos e o faturamento vinculado.

Resposta: 200. Se a matrícula não existe ou é de outro cliente, a resposta é 404.

PUT `/comercial/online-students/{uuid}`

Altera a matrícula. As regras são as do cadastro, com os seguintes pontos:

Se a matrícula tem pagamentos e o valor informado é menor que o total pago, o valor gravado passa a ser o total pago.
Se a matrícula já tem faturamento vinculado, a empresa cliente não é alterada.
Com empresa cliente e contrato do curso, o valor e o contrato vêm do contrato.
A troca de status deve ser feita em change-status, que aplica as regras de status descritas abaixo.

Corpo

Campo	Obrigatório	Tipo	Descrição
`customer_vendor_student_id`	Sim	número	`id` do cadastro do aluno
`start_date`	Sim	data	Data de início da matrícula
`amount`	Sim	número	Valor do treinamento para o aluno
`justification_gratuity`	Sim quando `amount` for `0`	texto	Motivo do valor zero
`course_id`	Não	número	`id` do curso
`company_id`	Não	número	`id` da empresa cadastrada no cliente
`customer_vendor_business_id`	Não	número	`id` da empresa cliente
`cost_center_id`	Não	número	`id` do centro de custo
`validity`	Não	número inteiro	Validade, em meses
`end_date`	Não	data	Data de término
`practice_date`	Não	data	Data da prática
`contract_course_id`	Não	número	`id` do contrato do curso

Resposta: 200, com o registro alterado.

DELETE `/comercial/online-students/{uuid}`

Exclui a matrícula, com as despesas e os certificados ligados a ela. Se a matrícula estiver vinculada à plataforma online/EAD, o vínculo também é removido naquela plataforma (ver Matrícula na plataforma online/EAD).

A tela pede confirmação antes da exclusão.

Resposta: 200, sem corpo.

Importação por planilha

GET `/comercial/online-students/import-template`

Baixa a planilha modelo (.xlsx). A planilha deve seguir o modelo, com as colunas nele previstas.

Resposta: 200, com o arquivo para download.

POST `/comercial/online-students/import`

Envia uma planilha para importação em segundo plano. A resposta chega antes do fim do processamento: use o token em import-progress para acompanhar.

Corpo (multipart/form-data)

Campo	Obrigatório	Tipo	Descrição
`file`	Sim	arquivo	Planilha `.xlsx` no modelo da importação

Resposta: 202

Campo	Descrição
`token`	Identificador da importação, usado em `import-progress`
`channel`	Nome do canal de acompanhamento em tempo real. O acompanhamento por consulta usa o `token`

Ao final, o usuário recebe uma notificação com a quantidade de alunos criados, atualizados e com erro. Cada aluno importado segue as mesmas regras do cadastro, inclusive a matrícula automática na plataforma online/EAD.

GET `/comercial/online-students/import-progress/{token}`

Devolve o estado atual da importação. Esta consulta é a forma de acompanhar o andamento: ela é atualizada enquanto a importação roda.

Resposta: 200

Campo	Descrição
`status`	`pending` (na fila), `running` (em andamento), `ready` (concluída) ou `failed` (falhou)
`current` e `total`	Registro atual e total de registros
`percentage`	Percentual concluído
`message`	Mensagem de andamento
`error`	Mensagem de erro, quando houver

Enquanto o processamento não começou, a resposta traz status como pending.

Troca de status

POST `/comercial/online-students/change-status`

Altera o status de uma ou mais matrículas. A mesma regra vale para uma matrícula e para as selecionadas na lista (ação em lote Alterar status).

Corpo

Campo	Obrigatório	Tipo	Descrição
`students_uuid`	Sim	lista de `uuid`	`uuid` das matrículas
`status_id`	Sim	número	`id` do novo status, da lista `GET /comercial/online-students/statuses`

Regras

Aprovado, Reprovado e Não concluído exigem data de término na matrícula.
Aprovado exige CPF ou passaporte cadastrado para o aluno.
Cancelado, para aluno particular (sem empresa cliente), só é aceito sem pagamentos registrados.

Efeitos

Aprovado gera o certificado da matrícula, automaticamente.
Qualquer outro status cancela os certificados ativos da matrícula.
A solicitação de treinamento vinculada à matrícula, quando existe, acompanha o status.

Resposta

200, com {"message": "Status alterado com sucesso."}, quando todas as matrículas foram alteradas.
400, com {"errors": [...]}, quando alguma matrícula foi recusada. Cada item da lista descreve o motivo de uma recusa. As demais matrículas da chamada são alteradas normalmente.

Exemplo

curl -X POST "https://api.pedagogo.app/comercial/online-students/change-status" \
  -H "Authorization: Bearer <token-de-sessao>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "students_uuid": ["<uuid-da-matricula>"],
    "status_id": 2
  }'

Status do aluno

`status_id`	Status (como na tela)
1	Matriculado
4	Confirmado
2	Aprovado
3	Reprovado
7	Não concluído
6	Ausente
5	Cancelado

Cadastro para assinatura eletrônica

Os dois envios usam o uuid do cadastro do aluno (customer_vendor_student_uuid), não o da matrícula.

PATCH `/comercial/online-students/{uuid}/send-registration-link-by-email`

Envia ao aluno, por e-mail, um link para o cadastro da assinatura usada no certificado.

Resposta: 200, sem corpo.

PATCH `/comercial/online-students/{uuid}/send-registration-link-by-whatsapp`

Envia ao aluno, por WhatsApp, uma mensagem explicando que o cadastro é necessário para emitir o certificado, seguida do link. Só é enviada se o aluno tem celular cadastrado.

Resposta: 200, sem corpo.

Envio de certificados em lote

GET `/comercial/online-students/contacts`

Lista os contatos das empresas clientes dos certificados selecionados, para escolher os destinatários do envio.

Parâmetros de URL

Parâmetro	Obrigatório	Descrição
`certificates_ids`	Sim	Lista de `id` dos certificados

Resposta: 200, lista de contatos com id, name, email, phonenumber, cellphone, o nome da empresa (business_name) e o documento (business_document).

POST `/comercial/online-students/send-certificates`

Envia por e-mail os certificados selecionados, em arquivo compactado, para os contatos escolhidos. O envio roda em segundo plano.

Corpo

Campo	Obrigatório	Tipo	Descrição
`certificates_ids`	Sim	lista de números	`id` dos certificados a enviar
`contacts_ids`	Não	lista de números	`id` dos contatos que vão receber

Resposta: 200, sem dados. O envio segue em segundo plano.

Verificação de agenda

GET `/comercial/online-students/check-schedule`

Verifica se o cadastro do aluno já tem uma matrícula que coincide com o período informado. Devolve a matrícula encontrada mais recente, com o curso e a turma, ou null se não houver conflito.

Parâmetros de URL

Parâmetro	Obrigatório	Descrição
`customer_vendor_student_id`	Sim	`id` do cadastro do aluno
`start_date`	Sim	Data de início do período
`end_date`	Não	Data de término do período
`uuid`	Não	`uuid` da matrícula a desconsiderar (a própria matrícula, na alteração)

Resposta: 200, com a matrícula ou null.

Assinatura e foto

GET `/comercial/online-students/{uuid}/show-signature`

Devolve a assinatura cadastrada do aluno, como arquivo para download. Se não houver assinatura, a resposta é 200 com {"success": true, "message": "Assinatura não encontrada."}.

Na primeira consulta com assinatura encontrada, o cadastro do aluno é marcado como tendo assinatura.

POST `/comercial/online-students/{uuid}/photo`

Envia a foto do cadastro do aluno. A foto anterior é substituída.

Corpo (multipart/form-data)

Campo	Obrigatório	Tipo	Descrição
`file`	Sim	arquivo	Imagem da foto

Resposta: 200, com o cadastro do aluno.

Relatórios do aluno

GET `/comercial/online-students/report/training-confirmation-letter`

Gera a carta de confirmação de treinamento, em PDF, para os alunos informados. Usa o modelo de carta configurado para o cliente.

Parâmetros de URL

Parâmetro	Obrigatório	Descrição
`uuids`	Sim	Lista de `uuid` dos cadastros dos alunos (`customer_vendor_student_uuid`)

Resposta: 200, com o PDF. Sem alunos informados, a resposta é 400 com {"error": "Nenhum aluno selecionado"}.

GET `/comercial/online-students/{student_uuid}/contract`

Gera o contrato individual do aluno, em PDF. Usa o modelo de contrato configurado para o cliente e, quando não há modelo, o modelo padrão.

Resposta: 200, com o PDF.

GET `/comercial/online-students/{student_uuid}/attendance-record-report`

Gera o controle de presença do aluno, em PDF.

Resposta: 200, com o PDF.

GET `/comercial/online-students/{student_uuid}/document-delivery-protocol-report`

Gera o protocolo de entrega de documentos do aluno, em PDF.

Resposta: 200, com o PDF.

Listas auxiliares

Estas consultas alimentam os campos de seleção da tela. Todas respondem 200 com uma lista.

Caminho	Devolve
`/comercial/online-students/students`	Cadastros de alunos do cliente, com nome, documento, celular e e-mail. Aceita `search`, `per_page` e `page`
`/comercial/online-students/business`	Empresas clientes ativas do cliente, para o campo Empresa
`/comercial/online-students/business/{customer_vendor_uuid}/cost-centers`	Centros de custo da empresa cliente, com `id` e `cost_center`. Aceita `search`
`/comercial/online-students/business/{customer_vendor_uuid}/cost-centers/{id}`	Um centro de custo
`/comercial/online-students/companies`	Empresas cadastradas no cliente
`/comercial/online-students/statuses`	Status de matrícula, com `id` e `status`. Usados em `status_id`
`/comercial/online-students/integrations`	Catálogo de integrações, com `id` e `name`. Aceita `search`, `id`, `ids` e `client_id` (traz as integrações vinculadas ao cliente)
`/comercial/online-students/complements/users`	Usuários do cliente, com empresa e departamento

POST `/comercial/online-students/business/{customer_vendor_uuid}/cost-centers`

Cadastra um centro de custo para a empresa cliente.

Corpo

Campo	Obrigatório	Tipo	Descrição
`cost_center`	Sim	texto	Nome do centro de custo

Resposta: 201, com o centro de custo criado.

GET `/comercial/online-students/business/{customer_vendor_uuid}/cost-centers/{id}`

Devolve um centro de custo da empresa cliente.

Resposta: 200.

Demais recursos

Pagamentos, qualificações, certificados, complementos, datas e a matrícula na plataforma online/EAD estão nas páginas listadas no início desta página. Autenticação e formatos gerais estão em Autenticação e Convenções.

Identificadores​

Endpoints​

Listagem​

GET /comercial/online-students​

Cadastro​

POST /comercial/online-students​

Consulta, alteração e exclusão​

GET /comercial/online-students/{uuid}​

PUT /comercial/online-students/{uuid}​

DELETE /comercial/online-students/{uuid}​

Importação por planilha​

GET /comercial/online-students/import-template​

POST /comercial/online-students/import​

GET /comercial/online-students/import-progress/{token}​

Troca de status​

POST /comercial/online-students/change-status​

Status do aluno​

Cadastro para assinatura eletrônica​

PATCH /comercial/online-students/{uuid}/send-registration-link-by-email​

PATCH /comercial/online-students/{uuid}/send-registration-link-by-whatsapp​

Envio de certificados em lote​

GET /comercial/online-students/contacts​

POST /comercial/online-students/send-certificates​

Verificação de agenda​

GET /comercial/online-students/check-schedule​

Assinatura e foto​

GET /comercial/online-students/{uuid}/show-signature​

POST /comercial/online-students/{uuid}/photo​

Relatórios do aluno​

GET /comercial/online-students/report/training-confirmation-letter​

GET /comercial/online-students/{student_uuid}/contract​

GET /comercial/online-students/{student_uuid}/attendance-record-report​

GET /comercial/online-students/{student_uuid}/document-delivery-protocol-report​

Listas auxiliares​

POST /comercial/online-students/business/{customer_vendor_uuid}/cost-centers​

GET /comercial/online-students/business/{customer_vendor_uuid}/cost-centers/{id}​

Demais recursos​

Identificadores

Endpoints

Listagem

GET `/comercial/online-students`

Cadastro

POST `/comercial/online-students`

Consulta, alteração e exclusão

GET `/comercial/online-students/{uuid}`

PUT `/comercial/online-students/{uuid}`

DELETE `/comercial/online-students/{uuid}`

Importação por planilha

GET `/comercial/online-students/import-template`

POST `/comercial/online-students/import`

GET `/comercial/online-students/import-progress/{token}`

Troca de status

POST `/comercial/online-students/change-status`

Status do aluno

Cadastro para assinatura eletrônica

PATCH `/comercial/online-students/{uuid}/send-registration-link-by-email`

PATCH `/comercial/online-students/{uuid}/send-registration-link-by-whatsapp`

Envio de certificados em lote

GET `/comercial/online-students/contacts`

POST `/comercial/online-students/send-certificates`

Verificação de agenda

GET `/comercial/online-students/check-schedule`

Assinatura e foto

GET `/comercial/online-students/{uuid}/show-signature`

POST `/comercial/online-students/{uuid}/photo`

Relatórios do aluno

GET `/comercial/online-students/report/training-confirmation-letter`

GET `/comercial/online-students/{student_uuid}/contract`

GET `/comercial/online-students/{student_uuid}/attendance-record-report`

GET `/comercial/online-students/{student_uuid}/document-delivery-protocol-report`

Listas auxiliares

POST `/comercial/online-students/business/{customer_vendor_uuid}/cost-centers`

GET `/comercial/online-students/business/{customer_vendor_uuid}/cost-centers/{id}`

Demais recursos