Emitir e registrar diplomas

Esta página é para instituições que emitem e registram os próprios diplomas na mesma organização do Digiploma, do tipo Emissora e Registradora. O Digiploma pressupõe que a instituição já concluiu as duas etapas internamente e usa a API para formalizá-las como o MEC exige: gera os arquivos XML, coleta as assinaturas no Lacuna Signer e produz a representação visual e o histórico escolar final.

Se a sua instituição apenas emite ou apenas registra diplomas, veja Apenas emissão ou Apenas registro.

O que compõe um diploma

Parte	O que é
XML do diploma	Os dados públicos do diploma (DadosDiploma e DadosRegistro), assinados em três etapas: emissão, registro e armazenamento. É o arquivo que a validação pública retorna.
XML da documentação acadêmica	Os dados privados usados para registrar o diploma: os dados pessoais do aluno, o histórico acadêmico e a documentação comprobatória (documentacaoComprobatoria). É assinado pela emissora.
RVDD	A representação visual do diploma digital, um PDF preenchido a partir de um modelo de diploma. Se o modelo também tiver uma versão para papel timbrado, é gerado um segundo PDF, para impressão em papel timbrado.
Histórico escolar final	Um documento à parte, gerado junto com o diploma. Veja Históricos escolares. Não é gerado para segunda via nem para diploma emitido por decisão judicial.

Antes de começar

• A organização precisa ser do tipo 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. Caso contrário, a chamada falha com SignerApiKeyNotSet.
• Você precisa de um modelo de diploma e de um modelo de histórico escolar. Veja Modelos.
• Você precisa dos signatários: um fluxo de assinatura salvo, do tipo EmissionRegistration, ou os signatários informados na própria requisição.

Criar um diploma

POST /api/degrees cria um diploma. Para criar vários de uma vez a partir de um arquivo JSON ou CSV, use um lote.

curl -X POST https://www.digiploma.com.br/api/degrees \
  -H "X-Api-Key: $API_KEY" -H "Content-Type: application/json" \
  -d @degree.json

{
  "templateId": "0f8b1c2e-…",
  "academicTranscriptTemplateId": "6a1d9e44-…",
  "documentFlowId": "c2f0e7a1-…",
  "newFolderName": "Formandos 2026-1",
  "degree": {
    "degreeType": "Default",
    "diploma": {
      "dadosDiploma": { "diplomado": { … }, "dadosCurso": { … }, "iesEmissora": { … }, "dataConclusao": "2026-06-30", … },
      "dadosRegistro": { "iesRegistradora": { … }, "livroRegistro": { … }, … }
    },
    "documentacaoAcademica": {
      "registro": { "dadosPrivadosDiplomado": { … }, "documentacaoComprobatoria": [ … ], "isSegundaVia": false }
    }
  }
}

Campo	Obrigatório	Descrição
templateId	Sim	O modelo de diploma usado para gerar o RVDD.
academicTranscriptTemplateId	Sim	O modelo de histórico escolar usado para gerar a representação visual do histórico. Obrigatório mesmo para segunda via ou diploma por decisão judicial, que não geram histórico.
degree	Sim	Os dados do diploma exigidos pelo MEC (veja abaixo).
documentFlowId	Um dos dois	Um fluxo de assinatura salvo, do tipo EmissionRegistration.
documentFlow	Um dos dois	Os signatários informados na própria requisição (veja Signatários). Tem precedência sobre documentFlowId.
newFolderName	Não	Cria no Signer uma pasta com este nome para os documentos. Tem precedência sobre signerFolderId.
signerFolderId	Não	Uma pasta existente do Signer para os documentos. Sem nenhum dos dois campos de pasta, os documentos vão para a raiz da organização no Signer.

O objeto degree segue o schema XML do MEC, com os nomes de elementos em português da Portaria MEC 554/2019:

• diploma.dadosDiploma: o diplomado (diplomado), o curso (dadosCurso), a instituição emissora (iesEmissora), a data de conclusão e, quando for o caso, as declarações da decisão judicial e a instituição de origem de uma transferência assistida.
• diploma.dadosRegistro: a instituição registradora (iesRegistradora), os dados do livro de registro (livroRegistro: livro, números de folha, de sequência e de registro, datas e responsável) e informações adicionais.
• documentacaoAcademica.registro: os dados privados do diplomado, incluindo a filiação e o histórico acadêmico (historico), que também alimenta o histórico escolar final; o termo de responsabilidade (termoResponsabilidade); a documentação comprobatória (documentacaoComprobatoria, cada documento um PDF/A em Base64); e isSegundaVia, para segunda via.
• degreeType: Default, Nsf (a variante do schema do MEC para o layout NSF) ou JudicialDecision (diploma emitido por decisão judicial). isNsf está obsoleto; use degreeType.
• visualRepresentationFieldsContent: textos opcionais que substituem os valores de campos de formulário do RVDD, identificados pelo nome.

Há um exemplo completo no arquivo JSON de exemplo, e o schema completo está na referência da API. Os dados são validados contra os schemas XML do MEC antes de os documentos serem criados.

Signatários

Cada diploma passa por quatro etapas de assinatura. Quando você envia documentFlow em vez de um fluxo salvo, as quatro precisam estar preenchidas; caso contrário, a chamada falha com DocumentFlowInvalidEmissionRegistrationData:

Etapa	Campo	Regras
Emissão	issuingFlow	Pelo menos um representante da emissora (e-CPF) e a própria emissora (e-CNPJ).
Registro	registrationFlow	Apenas representantes da registradora (e-CPF).
Armazenamento	storageFlow	Exatamente uma assinatura institucional (e-CNPJ), com requiredSignatures = 1.
Histórico escolar	academicTranscriptFlow	Pelo menos uma assinatura institucional (e-CNPJ).

O XML do diploma é assinado pelas etapas de emissão, registro e armazenamento, nessa ordem. O XML da documentação acadêmica é assinado pela etapa de emissão, seguida de uma assinatura com o e-CNPJ da emissora. O histórico escolar é um documento à parte no Signer, assinado por uma etapa própria. A estrutura de cada etapa está descrita em Fluxos de assinatura, e Assinaturas e o Lacuna Signer mostra quem assina o quê, com diagramas.

A resposta

{ "success": true, "id": "9b0f…", "academicTranscriptId": "2c4e…", "errors": null }

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

Falhas que acontecem durante a geração dos documentos, como dados rejeitados pelo schema XML do MEC ou um erro no Signer, retornam HTTP 200 com "success": false. Nesse caso, errors traz o log de processamento em português, incluindo os erros de schema. Só as verificações feitas antes da geração (tipo da organização, chave do Signer, modelos, fluxo) e um código de validação duplicado retornam um código de status de erro. Veja Resultado da criação.

Se o histórico escolar não puder ser gerado, o diploma é criado mesmo assim: success é true e academicTranscriptId é null. O motivo vem no campo academicTranscriptCreationError do webhook DegreeCreated.

O código de validação

O Digiploma calcula o código de validação do diploma a partir dos dados dele, no formato {código MEC da emissora}.{código MEC da registradora}.{12 caracteres hexadecimais}, e o grava no XML do diploma. Não é possível informá-lo. Um segundo diploma com o mesmo código é recusado com ValidationCodeDuplicated enquanto o primeiro não estiver anulado.

Assinatura e status

Depois que o diploma é criado, o Signer coleta as assinaturas e notifica o Digiploma à medida que cada documento é concluído.

status	Significado
Created	Criado; aguardando as assinaturas.
Active	O XML do diploma está assinado: o diploma é válido.
CanceledTemporarily	Anulado temporariamente. Pode ser restaurado.
Canceled	Anulado.

Duas flags completam o status: isSigned (XML do diploma assinado) e isAcademicDocumentationSigned (XML da documentação acadêmica assinado). O diploma passa a Active assim que o XML do diploma é assinado, e é concluído quando os dois arquivos XML estão assinados, em qualquer ordem. Só então o Digiploma envia o webhook DegreeConcluded e agenda a renotarização dos dois arquivos.

observação

Entre esses dois momentos, GET /api/degrees/{id}/xml já retorna o XML do diploma, mas a validação pública ainda informa que o diploma não é válido, porque exige os dois arquivos assinados.

Anular ou restaurar um diploma

POST /api/degrees/{id}/status altera o status de um diploma. A operação exige a permissão UpdateDegree, que os papéis Operador e Monitor não têm. Veja Permissões.

{ "status": "Canceled", "cancellationReason": "ErroDeFato", "reason": "Nome do diplomado grafado incorretamente" }

Campo	Descrição
status	Canceled, CanceledTemporarily ou Active (restaurar).
cancellationReason	O motivo da anulação, obrigatório ao anular um diploma cujos dois arquivos XML estão assinados: ErroDeFato, ErroDeDireito, DecisaoJudicial, ReemissaoParaComplementoDeInformacao, ReemissaoParaInclusaoDeHabilitacao ou ReemissaoParaAnotacaoDeRegistro.
reason	Uma observação em texto livre, de até 500 caracteres.

De	Para	O que acontece
Created	Canceled	Os documentos pendentes são excluídos do Signer. O diploma nunca mais poderá ser restaurado.
Active	Canceled	O diploma é anulado. cancellationReason é obrigatório se os dois arquivos XML estiverem assinados.
Active	CanceledTemporarily	O diploma é anulado temporariamente. Nada muda no Signer.
CanceledTemporarily	Active	O diploma é restaurado. Os dois arquivos XML precisam estar assinados (DegreeNotSignedCannotBeRestored), e nenhum outro diploma válido pode ter o mesmo código de validação (DegreeCannotRestoreValidAlreadyExists).
CanceledTemporarily	Canceled	O diploma é anulado.

Qualquer outra mudança falha com DegreeInvalidStatus. Um diploma Canceled não pode ser restaurado diretamente.

Sempre envie reason

O webhook de mudança de status (DegreeCanceled, DegreeCanceledTemporarily ou DegreeRestored) só é enviado quando a mudança tem um texto de motivo. A anulação de um diploma assinado sempre tem um, montado a partir de cancellationReason. Uma anulação temporária, uma restauração ou uma anulação feita antes de as assinaturas estarem completas não envia webhook, a menos que você preencha reason.

Alterar o status de um diploma não altera o histórico escolar dele, que tem as próprias operações de status. Os diplomas anulados aparecem na lista de diplomas anulados da instituição.

Consultar diplomas

Operação	Retorna
GET /api/degrees/{id}	Os metadados do diploma: aluno, curso, instituições, status, flags de assinatura, código de validação, ids e links dos documentos no Signer e o histórico escolar vinculado. É a chamada mais leve.
GET /api/degrees/{id}/information	Os dados públicos (dadosDiploma, dadosRegistro) lidos do XML do diploma. Funciona em qualquer status.
GET /api/degrees/{id}/academic-documentation	A documentação acadêmica lida do XML assinado, incluindo a documentação comprobatória em PDFs em Base64; por isso, a resposta pode ser grande. Falha com DegreeAcademicDocumentationNotSigned até esse XML ser assinado.
GET /api/degrees/{id}/history	As mudanças de status, da mais recente para a mais antiga, no formato {status, reason, date}.
GET /api/degrees	Uma página de diplomas com o modelo completo.
GET /api/v2/degrees	Uma página de diplomas só com id, studentName, studentSocialName, studentCpf, course, creationDate, updateDate e status. Mais rápida para grandes volumes.

As duas operações de listagem aceitam os mesmos parâmetros, além dos parâmetros de paginação:

Parâmetro	Filtro
Status	Diplomas neste status.
BatchId	Diplomas criados por este lote.
StartDateUtc, EndDateUtc	Diplomas criados de StartDateUtc (inclusive) até EndDateUtc (exclusive).
IsSigned	true retorna diplomas com pelo menos um arquivo XML assinado, em qualquer status exceto Created. false não filtra.
Q	Texto no CPF, no nome ou no nome social do aluno, ou no nome do curso. A pontuação é ignorada, então um CPF formatado também é encontrado. Não pesquisa o código de validação.

Os resultados são ordenados pela data de atualização (Order: Asc por padrão, ou Desc).

Baixar os arquivos

Cada arquivo pode ser baixado de três formas: o próprio arquivo, um JSON com o conteúdo em Base64 ({bytes, name, contentType}) ou um ticket, uma URL temporária que dispensa a chave de API.

Documento	Download direto	Base64	Ticket	Disponível quando
XML do diploma	GET /{id}/xml	GET /{id}/xml-b64	GET /{id}/xml-ticket	O diploma está Active (caso contrário, DegreeNotValid). No caso do ticket, a verificação é feita no download.
XML da documentação acadêmica	GET /{id}/academic-documentation-xml	GET /{id}/academic-documentation-xml-b64	GET /{id}/academic-documentation-ticket	Esse XML está assinado, em qualquer status.
RVDD	—	GET /{id}/visual-representation-b64	GET /{id}/visual-representation-ticket	Sempre.
RVDD para papel timbrado	—	—	GET /{id}/letterhead-visual-representation-ticket	O modelo tem versão para papel timbrado (hasLetterhead). Caso contrário, o download falha com LetterheadNotFound.

Todos os caminhos são relativos a /api/degrees.

Substituir a representação visual

POST /api/degrees/{id}/visual-representation substitui o RVDD de um diploma Created ou Active. Os arquivos XML assinados não são afetados. A operação exige a permissão UpdateDocumentVisualRepresentation (papéis Administrador e Gerente).

Campo	Descrição
templateId	Gera o RVDD novamente a partir de outro modelo de diploma. Tem precedência sobre uploadId.
fieldsContent	Com templateId, textos que substituem os valores de campos de formulário identificados pelo nome.
uploadId	Substitui o RVDD por um PDF enviado por upload, que precisa ter exatamente duas páginas, a primeira em orientação paisagem (InvalidNumberOfPages, InvalidPageOrientation).

Gerar o histórico escolar depois

Se um diploma não tem histórico escolar, POST /api/degrees/{id}/academic-transcript gera o histórico escolar final dele a partir dos dados do diploma. O corpo recebe academicTranscriptTemplateId, os signatários (documentFlow com academicTranscriptFlow, ou documentFlowId) e, opcionalmente, signerFolderId ou newFolderName. A operação retorna o histórico e falha com DegreeAlreadyHasLinkedAcademicTranscript se o diploma já tiver um, ou com DegreeTypeNotSupported para segunda via ou diploma por decisão judicial. Ao contrário das outras formas de criar um histórico, esta não envia o webhook AcademicTranscriptCreated.

Validar um diploma

• GET /api/degrees/codes/{code} valida um diploma da sua própria organização pelo código de validação, com a chave de API, e retorna o CPF sem máscara.
• GET /api/degrees/{code}/validation é a validação pública, que dispensa a chave de API. Veja Validação pública.

Webhooks

Evento	Quando
DegreeCreated	O diploma foi criado. Traz academicTranscriptCreationError quando o histórico escolar não pôde ser gerado.
DegreeConcluded	Os dois arquivos XML estão assinados.
DegreeCanceled, DegreeCanceledTemporarily, DegreeRestored	O status mudou, com um motivo (veja acima).

Os dados de cada evento estão em Webhooks.

Referência das operações

Operação	Descrição
POST /api/degrees	Criar um diploma
GET /api/degrees	Listar diplomas
GET /api/v2/degrees	Listar diplomas (modelo compacto, para grandes volumes)
GET /api/degrees/{id}	Obter um diploma
GET /api/degrees/{id}/information	Obter os dados públicos de um diploma
GET /api/degrees/{id}/academic-documentation	Obter os dados da documentação acadêmica
GET /api/degrees/{id}/history	Obter o histórico de status
POST /api/degrees/{id}/status	Anular, anular temporariamente ou restaurar um diploma
GET /api/degrees/{id}/xml, …/xml-b64, …/xml-ticket	Baixar o XML do diploma
GET /api/degrees/{id}/academic-documentation-xml, …/academic-documentation-xml-b64, …/academic-documentation-ticket	Baixar o XML da documentação acadêmica
GET /api/degrees/{id}/visual-representation-b64, …/visual-representation-ticket	Baixar o RVDD
GET /api/degrees/{id}/letterhead-visual-representation-ticket	Baixar o RVDD para papel timbrado
POST /api/degrees/{id}/visual-representation	Substituir o RVDD
POST /api/degrees/{id}/academic-transcript	Gerar o histórico escolar final de um diploma
GET /api/degrees/codes/{code}	Validar um diploma da sua organização
GET /api/degrees/{code}/validation, …/validation/visual-representation, …/validation/xml	Validação pública