Históricos escolares

O histórico escolar digital, definido pela Portaria MEC nº 1.095/2018, é um arquivo XML assinado acompanhado da sua representação visual, a RVHE, um PDF gerado a partir de um modelo. O Digiploma gera os dois, coleta as assinaturas no Lacuna Signer e publica o histórico para validação.

Um histórico final também é gerado automaticamente com cada diploma, nos modos emitir e registrar e apenas emitir. Use esta API para emitir os demais históricos, ou um histórico final avulso.

Tipos

type	Significado
Partial	Emitido a qualquer momento enquanto o aluno está matriculado, como comprovante da parte do currículo já integralizada.
Final	Emitido quando o vínculo do aluno com a instituição termina, para o diploma ou para uma transferência externa.
Copy	Segunda via, em formato digital, de um histórico emitido originalmente em papel. O código do currículo e os dados de ingresso passam a ser opcionais.

Um histórico parcial é recusado enquanto o aluno tiver, no mesmo curso, um histórico final que não esteja anulado. Além disso, quando qualquer histórico de um aluno e curso é assinado, o Digiploma anula automaticamente os históricos parciais mais antigos desse aluno e curso, com o motivo "Histórico escolar cancelado automaticamente pois um histórico escolar final ou um novo histórico escolar parcial foi emitido".

Antes de começar

• A organização precisa ser emissora (tipo Emissora ou Emissora e Registradora). Caso contrário, a chamada falha com SubscriptionOperationNotAllowed.
• A chave de API do Signer precisa estar definida nas Configurações da organização (SignerApiKeyNotSet).
• É preciso ter um modelo de histórico escolar: um PDF de uma página, em orientação retrato, com o cabeçalho da instituição.
• É preciso ter os signatários: um fluxo de assinatura salvo, do tipo AcademicTranscript, ou os signatários informados diretamente em cada requisição.

Criar um histórico escolar

POST /api/academic-transcripts cria um histórico. Para criar vários a partir de um arquivo JSON, use um lote.

{
  "type": "Partial",
  "academicTranscriptTemplateId": "6a1d9e44-…",
  "documentFlow": {
    "academicTranscriptFlow": [
      { "order": 1, "requiredSignatures": 1, "isCompany": false,
        "signers": [ { "name": "Maria Souza", "email": "maria@ies.edu.br", "cpf": "12345678909" } ] },
      { "order": 2, "requiredSignatures": 1, "isCompany": true, "companyIdentifier": "12345678000195",
        "signers": [ { "name": "João Lima", "email": "joao@ies.edu.br", "cpf": "98765432100" } ] }
    ]
  },
  "academicTranscript": {
    "aluno": { … },
    "dadosCurso": { … },
    "iesEmissora": { … },
    "historicoEscolar": { "codigoCurriculo": "…", "elementosHistorico": [ … ], "situacaoAtualDiscente": { … }, … }
  }
}

Campo	Obrigatório	Descrição
type	Sim	Partial, Final ou Copy.
academicTranscriptTemplateId	Sim	O modelo de histórico escolar.
academicTranscript	Sim	Os dados do MEC: o aluno (aluno), o curso (dadosCurso), a instituição emissora (iesEmissora) e o próprio histórico (historicoEscolar). Quando omitidos, historicoEscolar.dataEmissaoHistorico e horaEmissaoHistorico recebem a data e a hora atuais.
documentFlowId	Um dos dois	Um fluxo de assinatura salvo, do tipo AcademicTranscript.
documentFlow	Um dos dois	Os signatários, informados na própria requisição. Só academicTranscriptFlow pode ser preenchido. Tem precedência sobre documentFlowId.
newFolderName	Não	Cria no Signer uma pasta com esse nome para o documento. Tem precedência sobre signerFolderId.
signerFolderId	Não	Uma pasta já existente no Signer.

Há um exemplo completo dos dados no arquivo JSON de exemplo. Os dados são validados pelo esquema XML do MEC.

Signatários. O fluxo precisa de pelo menos uma assinatura institucional (isCompany: true, com certificado e-CNPJ); caso contrário, a chamada falha com DocumentFlowIssuerInstitutionSignatureRequired. Os representantes (e-CPF) assinam primeiro, na ordem dos valores de order, numa etapa chamada Secretaria acadêmica; a instituição assina por último, numa etapa chamada Instituição. Só a primeira regra institucional é usada. Históricos finais e segundas vias exigem certificados A3, a menos que a instância desative essa exigência.

A resposta é {success, academicTranscriptId, errors}:

Verifique success, não só o código de status HTTP

Falhas que acontecem durante a geração do histórico retornam HTTP 200 com "success": false e o log de processamento, em português, em errors. Isso inclui um código de validação duplicado e um histórico parcial recusado porque já existe um histórico final. Veja Resultado da criação.

O código de validação é calculado a partir do aluno, do curso, da instituição e da data e hora de emissão (até o minuto), no formato {código MEC da emissora}.{12 caracteres hexadecimais}. Dois históricos do mesmo aluno e curso emitidos no mesmo minuto recebem o mesmo código, e o segundo é recusado como duplicado.

Status

status	Significado
Created	Criado; aguardando assinaturas.
Active	Assinado: o histórico é válido.
CanceledTemporarily	Anulado temporariamente. Pode ser restaurado.
Canceled	Anulado.

Anular ou restaurar

POST /api/academic-transcripts/{id}/cancellation anula um histórico, com um motivo (reason) de até 500 caracteres:

{ "reason": "Emitido com dados incorretos" }

Se o histórico ainda não foi assinado, o documento dele é excluído do Signer e o histórico nunca mais pode ser restaurado. Se o histórico já estiver anulado, a chamada falha com AcademicTranscriptAlreadyCanceled.

POST /api/academic-transcripts/{id}/status muda o status, com um motivo (reason) obrigatório:

status	Permitido quando
Canceled	O histórico ainda não está anulado. Mesmo efeito de /cancellation.
CanceledTemporarily	O histórico está assinado.
Active (restaurar)	O histórico está CanceledTemporarily e assinado (AcademicTranscriptNotSignedCannotBeRestored).

Qualquer outra mudança falha com AcademicTranscriptInvalidStatus. As duas operações exigem a permissão UpdateAcademicTranscript.

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 histórico está Active (AcademicTranscriptNotValid). Com ticket, a verificação é feita no momento do download.
RVHE	GET /{id}/visual-representation-b64	GET /{id}/visual-representation-ticket	—	Sempre.

Todos os caminhos são relativos a /api/academic-transcripts. Veja Downloads e tickets.

Substituir a representação visual

POST /api/academic-transcripts/{id}/visual-representation substitui o RVHE de um histórico que não esteja anulado, a partir de outro modelo de histórico escolar (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/academic-transcripts/{id} retorna o histórico, com degreeId quando ele foi gerado junto com um diploma.
• GET /api/academic-transcripts/{id}/history retorna as mudanças de status, da mais recente para a mais antiga.
• GET /api/academic-transcripts retorna uma página de históricos. Além dos parâmetros de paginação, filtra por Status, BatchId, data de criação (de StartDateUtc, inclusive, até EndDateUtc, exclusive), IsSigned=true (históricos assinados, inclusive os anulados) e Q (CPF, nome ou nome social do aluno, ou curso). Os resultados são ordenados pela data de atualização.

Validar um histórico escolar

• GET /api/academic-transcripts/codes/{code} valida um histórico da sua própria organização, com a chave de API.
• GET /api/academic-transcripts/{code}/validation é a validação pública. Veja Validação pública.

Webhooks

Evento	Quando
AcademicTranscriptCreated	O histórico foi criado (não é enviado quando ele é gerado com POST /api/degrees/{id}/academic-transcript).
AcademicTranscriptConcluded	O histórico foi assinado ou restaurado.
AcademicTranscriptCanceled	O histórico foi anulado, inclusive na anulação automática dos históricos parciais mais antigos.
AcademicTranscriptCanceledTemporarily	O histórico foi anulado temporariamente.

Veja os dados de cada evento em Webhooks.

Referência das operações

Operação	Descrição
POST /api/academic-transcripts	Criar um histórico
GET /api/academic-transcripts	Listar históricos
GET /api/academic-transcripts/{id}	Consultar um histórico
GET /api/academic-transcripts/{id}/history	Consultar as mudanças de status
POST /api/academic-transcripts/{id}/cancellation	Anular um histórico
POST /api/academic-transcripts/{id}/status	Anular, anular temporariamente ou restaurar um histórico
GET /api/academic-transcripts/{id}/xml, …/xml-b64, …/xml-ticket	Baixar o XML assinado
GET /api/academic-transcripts/{id}/visual-representation-b64, …/visual-representation-ticket	Baixar o RVHE
POST /api/academic-transcripts/{id}/visual-representation	Substituir o RVHE
GET /api/academic-transcripts/codes/{code}	Validar um histórico da sua organização
GET /api/academic-transcripts/{code}/validation, …/validation/visual-representation, …/validation/xml	Validação pública