Certificados do aluno online
Certificados de uma matrícula online. Na tela, o certificado aparece na área de certificado do aluno, em Alunos online, e as impressões ficam no menu de ações da linha, em Impressões. O certificado é gerado automaticamente quando a matrícula passa a Aprovado (ver Troca de status).
Na listagem, aparecem apenas os certificados de matrículas Aprovado.
Nas rotas desta página, {student_uuid} é o uuid da matrícula. As exportações de certificados por turma usam o mesmo controlador e estão em Certificados das turmas.
Endpoints
| Método | Caminho | Descrição |
|---|---|---|
GET | /comercial/online-students/certificates/external-statuses | Lista os status de certificado externo (lista de apoio) |
GET | /comercial/online-students/{student_uuid}/certificates | Lista os certificados da matrícula |
PUT | /comercial/online-students/{student_uuid}/certificates/{id} | Altera as datas de envio, retorno e entrega |
POST | /comercial/online-students/{student_uuid}/certificates/{id}/cancel | Cancela um certificado |
PATCH | /comercial/online-students/{student_uuid}/certificates/{id}/signature | Marca ou desmarca o certificado como sem assinatura |
GET | /comercial/online-students/{student_uuid}/certificates/generate-certificates | Gera o PDF do certificado (impressão) |
GET | /comercial/online-students/{student_uuid}/certificates/generate-completion-cards | Gera a carteirinha de conclusão (PDF) |
GET | /comercial/online-students/{student_uuid}/certificates/training-completion-statement | Gera o documento de conclusão de treinamento (PDF) |
POST | /comercial/online-students/{student_uuid}/certificates/save-certificates | Armazena os certificados da matrícula, em segundo plano |
POST | /comercial/online-students/{student_uuid}/certificates/send-certificates-to-sign | Armazena e envia os certificados para assinatura digital, em segundo plano |
GET | /comercial/online-students/{student_uuid}/certificates/sign-progress/{token} | Consulta o andamento do armazenamento ou do envio para assinatura |
Lista de apoio
GET /comercial/online-students/certificates/external-statuses
Lista os status de certificado externo, com id e status. Aceita per_page e page.
Resposta: 200, lista de status.
Consulta
GET /comercial/online-students/{student_uuid}/certificates
Lista os certificados da matrícula, com os dados do aluno, do curso e da matrícula.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
search | Busca pelo nome, celular ou documento do aluno, pelo curso, pela empresa, pelo número do certificado, pelo número de protocolo e pela proposta de aprovação |
id | id do certificado |
cancelled | 1 para cancelados, 0 para não cancelados |
external | Filtra cursos com certificação externa |
student_name e course_name | Texto do nome do aluno e do nome do curso |
course_code | Código do curso |
protocol_number | Número de protocolo |
service_approval_proposal | Proposta de aprovação do serviço |
customer_vendor_student_uuid | uuid do cadastro do aluno |
start_date_send e end_date_send | Período da data de envio |
start_date_return e end_date_return | Período da data de retorno |
start_date_delivery e end_date_delivery | Período da data de entrega do certificado |
digital_signature_status_id | id do status da assinatura digital |
column e order | Coluna e sentido da ordenação |
per_page e page | Paginação |
Resposta: 200. Sem per_page, a resposta é uma lista simples. Com per_page, a resposta é paginada. Cada item traz id, certificate_number, external_certificate_number, protocol_number, service_approval_proposal, send_date, return_date, certificate_delivery_date, card_number, card_delivery_date, cancelled, cancel_reason, without_signature, dados do aluno e do curso, status_name, file (arquivo armazenado, quando houver) e o status da assinatura digital.
Alteração
PUT /comercial/online-students/{student_uuid}/certificates/{id}
Altera as datas do certificado. O status do certificado é calculado pelas datas: com data de entrega, o certificado fica como entregue; sem ela, mas com data de retorno, como retornado; sem as duas, mas com data de envio, como enviado.
Certificado cancelado não pode ser alterado. Nesse caso, a resposta é 200 com {"message": "Não é possível alterar um certificado cancelado"}, e nada é gravado.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
send_date | Não | data | Data de envio |
return_date | Não | data | Data de retorno |
certificate_delivery_date | Não | data | Data de entrega do certificado |
Resposta: 200, com o certificado alterado, ou com a mensagem de certificado cancelado.
PATCH /comercial/online-students/{student_uuid}/certificates/{id}/signature
Marca ou desmarca o certificado como sem assinatura. A chamada inverte o valor atual. Não tem corpo.
Resposta: 200, com true quando o certificado foi salvo.
POST /comercial/online-students/{student_uuid}/certificates/{id}/cancel
Cancela o certificado. O arquivo armazenado do certificado é removido.
Na tela, o motivo do cancelamento é obrigatório. Certificado cancelado com motivo não volta a valer: uma nova aprovação da matrícula gera um certificado novo, com novo número. Certificado cancelado não pode ser alterado.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
cancel_reason | Sim | texto | Motivo do cancelamento |
Resposta: 200, com o certificado cancelado.
Impressões
GET /comercial/online-students/{student_uuid}/certificates/generate-certificates
Gera o PDF do certificado da matrícula. Considera os certificados não cancelados da matrícula. Se o certificado já está armazenado, o arquivo não é renderizado de novo.
Resposta: 200, com o PDF.
GET /comercial/online-students/{student_uuid}/certificates/generate-completion-cards
Gera a carteirinha de conclusão do aluno, em PDF, a partir do modelo configurado para o cliente.
Resposta: 200, com o PDF.
GET /comercial/online-students/{student_uuid}/certificates/training-completion-statement
Gera o documento de conclusão de treinamento, em PDF, a partir do modelo configurado para o cliente.
Resposta: 200, com o PDF.
Armazenamento e assinatura digital
Armazenar e enviar para assinatura rodam em segundo plano. A resposta devolve um token para acompanhar o andamento em sign-progress.
Entram no processamento os certificados da matrícula que ainda não têm arquivo armazenado e não estão cancelados. Se certificateIds for informado, entram apenas os certificados listados.
POST /comercial/online-students/{student_uuid}/certificates/save-certificates
Armazena os certificados da matrícula nos arquivos do aluno.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
certificateIds | Não | lista de números | id dos certificados a armazenar |
Resposta: 202
| Campo | Descrição |
|---|---|
token | Identificador do processamento, usado em sign-progress |
channel | Nome do canal de acompanhamento em tempo real. O acompanhamento por consulta usa o token |
POST /comercial/online-students/{student_uuid}/certificates/send-certificates-to-sign
Armazena os certificados da matrícula e os envia para assinatura digital. Exige que o cliente tenha o plano de assinatura digital.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
certificateIds | Não | lista de números | id dos certificados a enviar |
send_company_copy | Não | booleano | Quando true e o aluno tem empresa cliente, envia cópia à empresa |
remove_drawn_signature | Não | booleano | Quando true, remove a assinatura desenhada do certificado |
Resposta
202, comtokenechannel, como emsave-certificates.403, com{"message": "Sua empresa não possui um plano de assinatura digital."}, quando o cliente não tem o plano.
GET /comercial/online-students/{student_uuid}/certificates/sign-progress/{token}
Devolve o andamento do processamento. Enquanto o processamento não começou, a resposta traz status como pending.
Resposta: 200
| Campo | Descrição |
|---|---|
status | pending (na fila), running (em andamento), ready (concluído) ou failed (falhou) |
stage | Etapa atual do processamento. Começa em queued e termina em done, ou em error quando falha |
stage_index e stage_total | Posição da etapa atual e total de etapas |
current e total | Certificado atual e total de certificados |
percentage | Percentual concluído |
failed | Quantidade de certificados com falha |
message | Mensagem de andamento |
error | Mensagem de erro, quando houver |