---
title: "Emitir e registrar diplomas"
description: "Emissão e registro de diplomas na mesma organização do Digiploma (Emissora e Registradora): XMLs, assinaturas no Lacuna Signer, RVDD e histórico final."
canonical: "https://docs.lacunasoftware.com/articles/digiploma/api/degrees"
locale: "pt-BR"
product: "Digiploma"
last_updated: "2026-10-11"
---

# 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](https://docs.lacunasoftware.com/articles/digiploma/api/emissions) ou [Apenas registro](https://docs.lacunasoftware.com/articles/digiploma/api/registrations).

## 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](https://docs.lacunasoftware.com/articles/digiploma/api/templates-and-flows#modelos). 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](https://docs.lacunasoftware.com/articles/digiploma/api/academic-transcripts). 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](https://docs.lacunasoftware.com/articles/digiploma/api/templates-and-flows#modelos).
* Você precisa dos signatários: um [fluxo de assinatura](https://docs.lacunasoftware.com/articles/digiploma/api/templates-and-flows#fluxos-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](https://docs.lacunasoftware.com/articles/digiploma/api/batches).

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

```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](https://docs.lacunasoftware.com/articles/digiploma/api/degrees#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](https://www.digiploma.com.br/assets/files/json-template5.json), e o schema completo
está na [referência da API](https://www.digiploma.com.br/swagger/). 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](https://docs.lacunasoftware.com/articles/digiploma/api/templates-and-flows#fluxos-de-assinatura), e
[Assinaturas e o Lacuna Signer](https://docs.lacunasoftware.com/articles/digiploma/signatures) mostra quem assina o quê, com diagramas.

### A resposta

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

> **Aviso: 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](https://docs.lacunasoftware.com/articles/digiploma/api#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](https://docs.lacunasoftware.com/articles/digiploma/api/webhooks) `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](https://docs.lacunasoftware.com/articles/digiploma/api/restamps) 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](https://docs.lacunasoftware.com/articles/digiploma/api#permissões).

```json
{ "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.

> **Aviso: 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](https://docs.lacunasoftware.com/articles/digiploma/api/academic-transcripts#anular-ou-restaurar). Os diplomas anulados aparecem na
[lista de diplomas anulados](https://docs.lacunasoftware.com/articles/digiploma/api/cancellation-lists) 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](https://docs.lacunasoftware.com/articles/digiploma/api#paginação):

| Parâmetro | Filtro |
|---|---|
| `Status` | Diplomas neste status. |
| `BatchId` | Diplomas criados por este [lote](https://docs.lacunasoftware.com/articles/digiploma/api/batches). |
| `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](https://docs.lacunasoftware.com/articles/digiploma/api#downloads-e-tickets), 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](https://docs.lacunasoftware.com/articles/digiploma/api#uploads), 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](https://docs.lacunasoftware.com/articles/digiploma/api/validation).

## 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](https://docs.lacunasoftware.com/articles/digiploma/api/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](https://docs.lacunasoftware.com/articles/digiploma/api/validation) |