Certificados da turma
Os certificados de treinamento dos alunos aprovados da turma. Na tela, ficam na aba Turmas > Certificados da página da turma. As ações de certificado só aparecem com a turma Concluída. Cada certificado tem número, datas de envio, retorno e entrega, protocolo, arquivo armazenado e situação da assinatura digital.
Nas rotas desta página, {class_uuid} é o uuid da turma e {id} é o identificador numérico do certificado.
Atenção aos verbos. A geração de certificados é um PATCH na raiz da rota. A edição em lote é um POST na mesma raiz. O verbo não segue o nome da ação, então confira a tabela abaixo.
Endpoints
| Método | Caminho | Descrição |
|---|---|---|
GET | /comercial/classes/{class_uuid}/certificates | Lista os certificados da turma |
PATCH | /comercial/classes/{class_uuid}/certificates | Gera os certificados dos alunos aprovados |
POST | /comercial/classes/{class_uuid}/certificates | Edita em lote os números e as datas de certificados |
GET | /comercial/classes/{class_uuid}/certificates/contacts | Lista os contatos das empresas dos alunos (lista de apoio) |
GET | /comercial/classes/{class_uuid}/certificates/download-certificates | Baixa os certificados em um pacote ZIP |
POST | /comercial/classes/{class_uuid}/certificates/exports | Inicia a exportação dos certificados em segundo plano |
GET | /comercial/classes/{class_uuid}/certificates/exports/{uuid} | Consulta o andamento de uma exportação |
GET | /comercial/classes/{class_uuid}/certificates/exports/{uuid}/download | Baixa o pacote de uma exportação pronta |
GET | /comercial/classes/{class_uuid}/certificates/generate-certificates | Gera o PDF dos certificados selecionados |
GET | /comercial/classes/{class_uuid}/certificates/generate-completion-cards | Gera a carteirinha dos certificados selecionados |
GET | /comercial/classes/{class_uuid}/certificates/generate-individual-certificates | Gera o PDF de cada certificado e grava nos arquivos da turma |
POST | /comercial/classes/{class_uuid}/certificates/save-certificates | Grava nos arquivos da turma os certificados que ainda não têm arquivo |
POST | /comercial/classes/{class_uuid}/certificates/send-certificates | Envia os certificados por e-mail às empresas |
POST | /comercial/classes/{class_uuid}/certificates/send-certificates-to-sign | Grava e envia os certificados para assinatura digital |
GET | /comercial/classes/{class_uuid}/certificates/sign-progress/{token} | Consulta o andamento de um processo em segundo plano |
DELETE | /comercial/classes/{class_uuid}/certificates/{id} | Remove um certificado |
PUT | /comercial/classes/{class_uuid}/certificates/{id} | Altera um certificado |
POST | /comercial/classes/{class_uuid}/certificates/{id}/cancel | Cancela um certificado |
PATCH | /comercial/classes/{class_uuid}/certificates/{id}/signature | Marca ou desmarca o certificado como sem assinatura |
Listar e gerar
GET /comercial/classes/{class_uuid}/certificates
Lista os certificados dos alunos aprovados da turma informada na URL.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
search | Texto livre para buscar pelo nome do aluno, pelo documento, pelo curso, pela empresa, pelo número do certificado, pelo protocolo ou pelo código da turma |
cancelled | 1 mostra só os cancelados. 0 mostra só os não cancelados |
certificateIds | Lista de ids de certificados |
protocol_number | Busca parcial pelo número de protocolo |
service_approval_proposal | Busca parcial pela proposta de aprovação do serviço |
start_date_send e end_date_send | Intervalo de datas de envio |
start_date_return e end_date_return | Intervalo de datas de retorno |
start_date_delivery e end_date_delivery | Intervalo de datas de entrega |
stored_certificate | 1 mostra os certificados armazenados. 0 mostra os não armazenados |
digital_signature_status_id | Filtra pela situação da assinatura digital |
column e order | Ordena pela coluna informada, em asc ou desc |
per_page e page | Paginação. Sem per_page, a resposta é a lista completa |
Resposta: 200. Cada item traz o aluno, a empresa, o curso, a turma, o número do certificado e os números externos, as datas de envio, retorno e entrega, o status, o arquivo armazenado, a situação da assinatura digital e a observação.
PATCH /comercial/classes/{class_uuid}/certificates
Gera os certificados dos alunos aprovados da turma. Na tela, é a ação Gerar certificados.
Regras e efeitos:
- Só gera para turma Concluída.
- Gera para os alunos Aprovados que não têm certificado ativo.
- Se o aluno tinha um certificado cancelado sem motivo, o mesmo certificado volta a valer.
- Se o cancelamento teve motivo, é emitido um certificado novo, com novo número.
- O número do certificado é sequencial para a empresa cliente.
Não há corpo na chamada.
Resposta: 200, com corpo null.
POST /comercial/classes/{class_uuid}/certificates
Edita em lote os números e as datas dos certificados informados. Na tela, é a ação Editar certificados em lote. Esta rota não gera certificados: para gerar, use o PATCH acima.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
ids | Sim | Lista ou texto | Ids dos certificados a alterar. Aceita uma lista ou os ids separados por vírgula |
certificate_number | Não | Número inteiro | Número do certificado |
external_certificate_number | Não | Texto | Número do certificado externo |
protocol_number | Não | Texto | Número do protocolo |
service_approval_proposal | Não | Texto | Proposta de aprovação do serviç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 |
card_number | Não | Texto | Número da carteirinha |
card_delivery_date | Não | Data | Data de entrega da carteirinha |
observations | Não | Texto | Observações |
Os mesmos campos valem para a alteração de um certificado (PUT), descrita mais abaixo. Certificados cancelados não são alterados.
Resposta: 200 com uma lista, com um item para cada id. Cada item é o certificado alterado ou, quando ele está cancelado, {"message": "Não é possível alterar um certificado cancelado"}.
Listas auxiliares
GET /comercial/classes/{class_uuid}/certificates/contacts
Lista os contatos das empresas dos alunos com certificado, para escolher os destinatários do envio por e-mail. Os contatos aparecem agrupados por empresa.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
certificates_ids | Lista de ids de certificados. Restringe a lista aos contatos desses certificados |
student_uuid | uuid do aluno. Restringe a lista ao aluno |
Resposta: 200. Cada item traz o nome da empresa, o documento da empresa e os dados do contato (id, name, email, phonenumber e cellphone).
Consultar, alterar e cancelar
PUT /comercial/classes/{class_uuid}/certificates/{id}
Altera um certificado. Os campos são os mesmos da edição em lote acima, e todos são opcionais.
O status do certificado acompanha a data mais avançada preenchida: entrega, depois retorno, depois envio.
Resposta: 200 com o certificado alterado. Para certificado cancelado, 200 com {"message": "Não é possível alterar um certificado cancelado"}.
DELETE /comercial/classes/{class_uuid}/certificates/{id}
Remove um certificado. A remoção é lógica.
Resposta: 200, com corpo null.
POST /comercial/classes/{class_uuid}/certificates/{id}/cancel
Cancela um certificado. Ao cancelar, o arquivo armazenado é removido e o documento de assinatura digital vinculado, se houver, também é removido.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
cancel_reason | Sim | Texto | Motivo do cancelamento. Na tela, o campo é obrigatório |
Resposta: 200 com o certificado cancelado.
PATCH /comercial/classes/{class_uuid}/certificates/{id}/signature
Marca ou desmarca o certificado como sem assinatura. Na tela, é a ação Assinatura. A chamada alterna o valor atual, sem corpo.
Resposta: 200 com true ou false, conforme o novo estado.
Impressão e download
GET /comercial/classes/{class_uuid}/certificates/download-certificates
Gera um pacote ZIP com os PDFs dos certificados informados, que não estão cancelados, e devolve para download.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
certificateIds | Lista de ids de certificados |
certificate_keys | Lista de chaves dos certificados |
Resposta: 200 com o arquivo ZIP para download.
POST /comercial/classes/{class_uuid}/certificates/exports
Inicia a exportação dos certificados em segundo plano. Na tela, é o download em lote com acompanhamento de progresso, indicado para turmas grandes. A exportação fica disponível por 30 minutos.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
certificateIds | Não | Lista | Ids dos certificados a exportar |
certificate_keys | Não | Lista | Chaves dos certificados a exportar |
Resposta: 202 com uuid e status (queued, na fila).
GET /comercial/classes/{class_uuid}/certificates/exports/{uuid}
Consulta o andamento de uma exportação.
Resposta: 200 com uuid, status, progress (andamento da exportação), expires_at, error_message e download_url_if_ready, que traz o caminho do download quando a exportação está pronta. Os valores de status incluem queued (na fila), ready (pronta) e failed (falhou). Se a exportação não existe, 404 com {"error": "Export não encontrado."}.
GET /comercial/classes/{class_uuid}/certificates/exports/{uuid}/download
Baixa o pacote de uma exportação pronta.
Resposta: 200 com o arquivo ZIP para download. Enquanto a exportação não está pronta, 409, com o status atual. Se a exportação não existe, ou se o arquivo não foi encontrado, 404.
GET /comercial/classes/{class_uuid}/certificates/generate-certificates
Gera o PDF dos certificados selecionados, sem os cancelados. Na tela, é a impressão do certificado.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
certificateIds | Lista de ids de certificados |
Resposta: 200 com o arquivo PDF para download.
GET /comercial/classes/{class_uuid}/certificates/generate-completion-cards
Gera a carteirinha dos certificados selecionados, em PDF. Na tela, é a impressão da carteirinha.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
certificateIds | Lista de ids de certificados |
Resposta: 200 com o arquivo PDF para download.
Armazenar e enviar
GET /comercial/classes/{class_uuid}/certificates/generate-individual-certificates
Gera o PDF de cada certificado e grava o arquivo nos arquivos da turma, na pasta de certificados, vinculado ao certificado. Sem certificateIds, a rota usa todos os certificados ativos da turma.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
certificateIds | Lista de ids de certificados. Opcional |
Resposta: 200, com corpo null.
POST /comercial/classes/{class_uuid}/certificates/save-certificates
Grava nos arquivos da turma os certificados que ainda não têm arquivo. Na tela, é a ação Armazenar certificados. O processamento acontece em segundo plano.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
certificateIds | Não | Lista | Ids dos certificados a armazenar. Sem ela, a rota usa os certificados da turma que ainda não têm arquivo |
Resposta: 202 com token e channel. Use o token na rota de andamento, descrita abaixo.
POST /comercial/classes/{class_uuid}/certificates/send-certificates
Envia os certificados por e-mail às empresas, em um arquivo compactado. O envio acontece em segundo plano.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
certificates_ids | Não | Lista | Ids dos certificados a enviar |
contacts_ids | Não | Lista | Ids dos contatos que vão receber, como retornados pela lista de contatos |
Resposta: 200, com corpo null.
POST /comercial/classes/{class_uuid}/certificates/send-certificates-to-sign
Grava os certificados que ainda não têm arquivo e os envia para assinatura digital. Na tela, é a ação Enviar certificados para assinatura digital. O processamento acontece em segundo plano.
Esta rota só funciona para empresas com plano de assinatura digital. Sem ele, a resposta é 403 com {"message": "Sua empresa não possui um plano de assinatura digital."}.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
certificateIds | Não | Lista | Ids dos certificados a enviar |
observer | Não | Booleano | Inclui o usuário logado como observador do processo, para receber as notificações |
instructors | Não | Booleano | Exige a assinatura dos instrutores da turma |
send_company_copy | Não | Booleano | Envia uma cópia à empresa ao final |
remove_drawn_signature | Não | Booleano | Remove a assinatura desenhada do certificado |
Resposta: 202 com token e channel. Use o token na rota de andamento.
GET /comercial/classes/{class_uuid}/certificates/sign-progress/{token}
Consulta o andamento de um processo em segundo plano iniciado pelas rotas de armazenamento ou de envio para assinatura. Use esta rota para acompanhar o processo, pelo token recebido.
Resposta: 200 com status, stage (etapa atual), stage_index e stage_total, current e total (itens processados), percentage, failed (itens com falha), message e error. Enquanto o processo não começou, a resposta é status igual a pending, com a mensagem Na fila.... Quando o processo termina, status indica o resultado.