Alunos
O módulo Alunos guarda o cadastro das pessoas que fazem treinamentos no cliente: dados pessoais, endereço, dados complementares, foto, arquivos e o histórico de treinamentos. Corresponde à tela Alunos do módulo Administrativo. Cada aluno tem um responsável, o usuário que acompanha aquele aluno.
Um aluno pode ser, ao mesmo tempo, colaborador ou instrutor, porque esses cadastros compartilham a mesma base de pessoas e o mesmo CPF.
O aluno é identificado pelo uuid do cadastro de aluno, uuid nas rotas
abaixo. Os sub-recursos têm páginas próprias:
- Arquivos: documentos anexados ao aluno.
- Treinamentos: histórico de treinamentos, recibo e certificados.
- Endereços: endereço do aluno, pelo cadastro da pessoa.
Endpoints
| Método | Caminho | Descrição |
|---|---|---|
| GET | /administrative/students | Lista os alunos |
| POST | /administrative/students | Cadastra um aluno |
| GET | /administrative/students/export | Exporta a lista de alunos em planilha |
| POST | /administrative/students/import | Importa alunos a partir de uma planilha |
| GET | /administrative/students/import-template | Baixa o modelo de planilha para importação |
| POST | /administrative/students/change-responsible | Altera o responsável de vários alunos |
| GET | /administrative/students/users | Lista de apoio: usuários para escolher o responsável |
| GET | /administrative/students/file-types | Lista de apoio: categorias de arquivo |
| GET | /administrative/students/{uuid} | Consulta um aluno |
| PUT | /administrative/students/{uuid} | Altera um aluno |
| DELETE | /administrative/students/{uuid} | Apaga um aluno |
| POST | /administrative/students/{uuid}/photo | Envia a foto do aluno |
| POST | /administrative/students/{uuid}/merge | Mescla cadastros duplicados neste aluno |
| PATCH | /administrative/students/{uuid}/send-registration-link-by-email | Envia por e-mail o link para cadastrar a assinatura |
| PATCH | /administrative/students/{uuid}/send-registration-link-by-whatsapp | Envia por WhatsApp o link para cadastrar a assinatura |
| GET | /administrative/students/{uuid}/show-signature | Visualiza a assinatura do aluno |
GET /administrative/students
Lista os alunos do cliente, em ordem alfabética pelo nome, salvo se columnName
e orderData forem informados.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
| search | Texto livre: busca pelo nome, CPF, celular, e-mail e código do aluno (uuid), e pelo nome ou CNPJ da empresa vinculada |
| mt | Filtra pelo indicador de assinatura cadastrada: 1 para sim, 0 para não |
| customer_vendor_business_id | Traz só os alunos vinculados à empresa com esse id |
| columnName | Coluna para ordenar |
| orderData | Sentido da ordenação: asc ou desc |
| per_page | Quantidade de registros por página |
| page | Número da página, quando per_page é informado |
Resposta (200): lista de alunos, direta ou paginada. Campos principais:
uuid, customer_vendor_uuid, name, document, birth_date, email,
phonenumber, cellphone, responsible_id, responsible, business_uuid,
business_name, business_document, mt, photo_url, zip_code, street,
number, complement, neighborhood, city, state, user_create_name e
user_update_name.
Exemplo:
curl "https://api.pedagogo.app/administrative/students?search=Ana&per_page=15" \
-H "Accept: application/json" \
-H "Authorization: Bearer <token-de-sessao>"
POST /administrative/students
Cadastra um aluno. O cadastro de pessoa e o endereço são criados junto com o
aluno. Se o CPF informado pertencer a um aluno apagado, o cadastro antigo é
reativado, com o histórico dele. Se o CPF já pertencer a um aluno ativo, a
resposta é 422 com a mensagem O CPF já está cadastrado..
Corpo (JSON)
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| name | Sim | Texto | Nome do aluno |
| document | Não | Texto | CPF ou CNPJ válido |
| birth_date | Não | Data (AAAA-MM-DD) | Data de nascimento |
| Não | E-mail do aluno. Se já pertencer a outro cadastro do cliente, o aluno é salvo sem e-mail | ||
| phonenumber | Não | Texto | Telefone fixo |
| cellphone | Não | Texto | Celular |
| observation | Não | Texto | Observações sobre o aluno |
| responsible_id | Não | Número inteiro | id do usuário responsável pelo aluno |
| customer_vendor_business_id | Não | Número inteiro | id da empresa vinculada ao aluno |
| passport | Não | Texto | Número do passaporte, para alunos estrangeiros |
| nid_number | Não | Texto | Número do RG |
| nid_issuer | Não | Texto | Órgão emissor do RG |
| nid_issuing_state | Não | Texto | Estado de emissão do RG |
| nid_issuing_expiration_date | Não | Data (AAAA-MM-DD) | Data de validade do RG |
| nationality | Não | Texto | Nacionalidade |
| naturalness | Não | Texto | Naturalidade (cidade ou país de nascimento) |
| shoe_size | Não | Texto | Tamanho do calçado |
| overalls | Não | Texto | Tamanho do macacão |
| external_password | Não | Texto | Campo de texto livre do cadastro |
| zip_code, street, number, complement, neighborhood, city, state | Não | Texto | Endereço do aluno |
Resposta (201): o registro do aluno criado, com o uuid.
Exemplo:
curl -X POST https://api.pedagogo.app/administrative/students \
-H "Accept: application/json" \
-H "Authorization: Bearer <token-de-sessao>" \
-H "Content-Type: application/json" \
-d '{"name": "Aluno exemplo", "cellphone": "11999990000"}'
GET /administrative/students/{uuid}
Devolve um aluno pelo uuid, com os dados pessoais, o responsável e o endereço.
PUT /administrative/students/{uuid}
Altera um aluno. Aceita os mesmos campos do cadastro. O endereço informado aqui é gravado no endereço principal da pessoa; para gerenciar vários endereços, use Endereços.
Corpo (JSON)
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| name | Sim | Texto | Nome do aluno |
| document | Não | Texto | CPF ou CNPJ válido. Não pode pertencer a outro aluno do cliente |
Os demais campos são os mesmos do cadastro de aluno (POST), descritos acima nesta página.
Resposta (200): o aluno alterado.
DELETE /administrative/students/{uuid}
Apaga o cadastro de aluno. A exclusão é lógica e não é bloqueada por treinamentos ou arquivos vinculados. A pessoa continua cadastrada para outros papéis, como colaborador ou instrutor.
Resposta (200): sem conteúdo relevante (null).
POST /administrative/students/{uuid}/photo
Envia a foto do aluno. Substitui a foto anterior.
Corpo (multipart/form-data)
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| file | Sim | Imagem | Foto do aluno |
Resposta (200): o aluno.
POST /administrative/students/{uuid}/merge
Junta cadastros duplicados de um mesmo aluno a este cadastro. Os treinamentos e
os arquivos dos cadastros informados em ids passam para este aluno. Depois, os
cadastros duplicados são apagados. Os dados pessoais deste aluno não são alterados.
Não há desfazer: confira os cadastros antes de mesclar.
Corpo (JSON)
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| ids | Sim | Lista de uuids | uuid dos cadastros de aluno duplicados |
Resposta (200):
{
"message": "Alunos mesclados com sucesso",
"success": true
}
POST /administrative/students/change-responsible
Troca o responsável de vários alunos. A troca vale para o cadastro de cada aluno e
para os treinamentos dele que não são vinculados a uma empresa. Se start_date
for informada, só mudam os treinamentos que começam nessa data ou depois.
Corpo (JSON)
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| uuids | Sim | Lista de uuids | uuid dos alunos |
| responsible_id | Sim | Número inteiro | id do novo usuário responsável |
| start_date | Não | Data (AAAA-MM-DD) | Data a partir da qual os treinamentos são alterados |
Resposta (200):
{
"message": "Responsável alterado com sucesso."
}
PATCH /administrative/students/{uuid}/send-registration-link-by-email
Envia ao e-mail do aluno o link para cadastrar a assinatura eletrônica no certificado. Não recebe corpo.
Resposta (200): sem conteúdo relevante (null).
PATCH /administrative/students/{uuid}/send-registration-link-by-whatsapp
Envia ao celular do aluno, por WhatsApp, a mensagem com o link para cadastrar a assinatura eletrônica. Não recebe corpo. Se o aluno não tiver celular cadastrado, nada é enviado e a resposta traz a mensagem indicada abaixo.
A resposta confirma o envio ao serviço de mensagens, não a entrega ao aparelho.
Resposta (200): sem conteúdo relevante (null) quando o envio é feito. Sem
celular cadastrado:
{
"message": "Número de celular não encontrado."
}
GET /administrative/students/{uuid}/show-signature
Mostra a assinatura eletrônica que o aluno cadastrou no aplicativo Meus
Treinamentos. Ao encontrar a assinatura, o indicador mt do aluno passa a 1.
Se não encontrar, passa a 0.
Resposta (200): o arquivo da assinatura para download, quando encontrada. Se não houver assinatura:
{
"success": true,
"message": "Assinatura não encontrada."
}
GET /administrative/students/export
Baixa uma planilha Excel (.xlsx) com os alunos. Aceita os mesmos parâmetros da
listagem GET /administrative/students e exporta o resultado da busca.
Resposta (200): arquivo .xlsx para download. O nome do arquivo começa com
um trecho aleatório.
POST /administrative/students/import
Importa alunos a partir de uma planilha. A importação roda em segundo plano: a resposta confirma apenas o início. Quem importou recebe um e-mail com o total de registros, o total de alunos importados e as linhas que não entraram, com o motivo.
Use o modelo baixado em GET /administrative/students/import-template.
Só a primeira aba da planilha é lida.
Corpo (multipart/form-data)
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| file | Sim | Arquivo (.xlsx) | Planilha com os alunos, no formato do modelo |
Resposta (200):
{
"message": "Importação iniciada com sucesso."
}
GET /administrative/students/import-template
Baixa o modelo de planilha para importação de alunos.
Resposta (200): arquivo .xlsx para download.
Listas de apoio
GET /administrative/students/users
Lista os usuários do cliente, para escolher o responsável de um aluno. Devolve a mesma resposta de GET /administrative/users.
GET /administrative/students/file-types
Lista as categorias de arquivo do cliente, para classificar os arquivos do aluno.
Campos principais: id, uuid e file_type. As categorias são cadastradas em
Configurações.