Currículos escolares

O currículo escolar digital, definido pela Instrução Normativa SESU nº 2, descreve a estrutura curricular de um curso: as unidades curriculares, as etiquetas, as áreas e os critérios de integralização. O Digiploma gera o XML assinado e a sua representação visual, a RVCE, coleta as assinaturas no Lacuna Signer e publica o currículo para validação. Os históricos escolares fazem referência a um currículo pelo código dele (historicoEscolar.codigoCurriculo).

Antes de começar

• A organização precisa ser emissora (tipo Emissora ou Emissora e Registradora) (SubscriptionOperationNotAllowed).
• A chave de API do Signer precisa estar definida nas Configurações da organização (SignerApiKeyNotSet).
• É preciso ter um modelo de currículo.
• É preciso ter os signatários: um fluxo de assinatura salvo, do tipo Curriculum, ou os signatários informados diretamente em cada requisição.

Criar um currículo

POST /api/curriculums cria um currículo. Para criar vários a partir de um arquivo JSON, use um lote.

{
  "templateId": "b3e1…",
  "documentFlowId": "e90d…",
  "curriculum": {
    "codigo": "ADM-2024",
    "dataCurriculo": "2024-01-15",
    "minutosRelogioDaHoraAula": 50,
    "dadosCurso": { … },
    "iesEmissora": { … },
    "etiquetas": [ { "codigo": "ob", "nome": "Obrigatória" } ],
    "areas": [ … ],
    "estruturaCurricular": { … },
    "criteriosIntegralizacao": [ … ]
  }
}

Campo	Obrigatório	Descrição
templateId	Sim	O modelo de currículo.
curriculum	Sim	Os dados: o código do currículo na instituição (codigo), a data de aprovação (dataCurriculo; por padrão, a data de hoje), a duração da hora-aula em minutos (minutosRelogioDaHoraAula), o curso (dadosCurso), a instituição (iesEmissora), pelo menos uma etiqueta (etiquetas), as áreas, a estrutura curricular (estruturaCurricular), pelo menos um critério de integralização (criteriosIntegralizacao) e, opcionalmente, as atividades complementares e as informações adicionais.
documentFlowId / documentFlow	Um dos dois	Os signatários. Só curriculumFlow pode ser preenchido, com exatamente uma assinatura institucional (e-CNPJ) (DocumentFlowCurriculumOnlyOneCompanySignatureAllowed).
newFolderName / signerFolderId	Não	A pasta do Signer para o documento, nova ou já existente.

Há um exemplo completo dos dados no arquivo JSON de exemplo.

Os coordenadores do curso (e-CPF) assinam primeiro, numa etapa chamada Coordenação do curso, e a instituição assina por último, numa etapa chamada Instituição.

A resposta é {success, id, errors}. Falhas na geração retornam HTTP 200 com "success": false e o log de processamento em errors; isso inclui CurriculumCodeAlreadyExists, quando outro currículo não cancelado da organização tem o mesmo codigo. Veja Resultado da criação.

Status e cancelamento

status	Significado
Created	Criado; aguardando assinaturas.
Active	Assinado: o currículo é válido.
Canceled	Cancelado (na interface, Anulado).

POST /api/curriculums/{id}/cancellation, com um motivo (reason) de até 500 caracteres, cancela um currículo. O cancelamento é definitivo: não há anulação temporária nem restauração. Se o currículo ainda não foi assinado, o documento dele é excluído do Signer. Depois do cancelamento, o mesmo codigo pode ser usado por um novo currículo.

Baixar os arquivos

Documento	Base64	Ticket	Download direto	Disponível quando
XML assinado	GET /{id}/xml-b64	GET /{id}/xml-ticket	GET /{id}/xml	O currículo está Active (CurriculumNotValid). Com ticket, a verificação é feita no momento do download.
RVCE	GET /{id}/visual-representation-b64	GET /{id}/visual-representation-ticket	—	Sempre.

Todos os caminhos são relativos a /api/curriculums. Veja Downloads e tickets.

Substituir a representação visual

POST /api/curriculums/{id}/visual-representation substitui o RVCE de um currículo que não esteja cancelado, a partir de outro modelo de currículo (templateId) ou de um PDF em orientação retrato enviado por upload (uploadId). O XML assinado não é alterado. A operação exige a permissão UpdateDocumentVisualRepresentation (papéis Administrador e Gerente).

Consultar e pesquisar

• GET /api/curriculums/{id} retorna o currículo; GET /api/curriculums/{id}/history retorna as mudanças de status dele, da mais recente para a mais antiga.
• GET /api/curriculums retorna uma página de currículos. Além dos parâmetros de paginação, filtra por Status, BatchId, data de criação (de StartDateUtc, inclusive, até EndDateUtc, exclusive) e Q (código do currículo, nome do curso ou nome da instituição). Os resultados são ordenados pela data de atualização.

Validar um currículo

• GET /api/curriculums/codes/{code} valida um currículo da sua própria organização, com a chave de API.
• GET /api/curriculums/{code}/validation é a validação pública. Veja Validação pública.

Webhooks

Evento	Quando
CurriculumCreated	O currículo foi criado.
CurriculumConcluded	O currículo foi assinado.
CurriculumCanceled	O currículo foi cancelado.

Veja os dados de cada evento em Webhooks.

Referência das operações

Operação	Descrição
POST /api/curriculums	Criar um currículo
GET /api/curriculums	Listar currículos
GET /api/curriculums/{id}	Consultar um currículo
GET /api/curriculums/{id}/history	Consultar as mudanças de status
POST /api/curriculums/{id}/cancellation	Cancelar um currículo
GET /api/curriculums/{id}/xml, …/xml-b64, …/xml-ticket	Baixar o XML assinado
GET /api/curriculums/{id}/visual-representation-b64, …/visual-representation-ticket	Baixar o RVCE
POST /api/curriculums/{id}/visual-representation	Substituir o RVCE
GET /api/curriculums/codes/{code}	Validar um currículo da sua organização
GET /api/curriculums/{code}/validation, …/validation/visual-representation, …/validation/xml	Validação pública