---
title: "Modelos e fluxos de assinatura"
description: "Modelos de representação visual (RVDD, RVHE e RVCE) e fluxos de assinatura da API do Digiploma, reutilizáveis nas requisições de criação de documentos."
canonical: "https://docs.lacunasoftware.com/articles/digiploma/api/templates-and-flows"
locale: "pt-BR"
product: "Digiploma"
last_updated: "2026-10-11"
---

# Modelos e fluxos de assinatura

Antes de criar documentos, a organização normalmente cadastra dois tipos de recurso, que reutiliza em várias requisições:

* **Modelos**, que definem a representação visual de cada documento: o RVDD do diploma, o RVHE do histórico escolar e o RVCE do
  currículo.
* **Fluxos de assinatura**, que definem quem assina cada documento. Salvar um fluxo é opcional, já que toda requisição de criação também
  aceita os signatários na própria requisição, mas cada requisição precisa de um ou de outro.

## Modelos

| `type` | Usado para | Requisitos do PDF |
|---|---|---|
| `Degree` | O RVDD do diploma | Um formulário PDF com exatamente **duas páginas** (frente e verso), em **paisagem**. |
| `AcademicTranscript` | O RVHE do histórico escolar | Um PDF com **uma página**, em **retrato**, com o cabeçalho da instituição (nome, endereço, atos regulatórios e, opcionalmente, o logotipo), conforme o art. 17 da Portaria MEC 1095/2018. |
| `Curriculum` | O RVCE do currículo | Um PDF com **uma página**, em **retrato**. |

Exemplos: [modelo de diploma](https://www.digiploma.com.br/assets/files/template_v2.pdf),
[modelo de histórico escolar](https://www.digiploma.com.br/assets/files/academic_transcript_template.pdf) e
[modelo de currículo](https://www.digiploma.com.br/assets/files/curriculum_template.pdf).

### Como o modelo de diploma é preenchido

O modelo de diploma é um formulário PDF. O Digiploma preenche os campos de texto com os dados do diploma e depois achata o formulário
(*flatten*):

* Um campo com o nome de uma informação, como `Diploma.Diplomado.Nome`, recebe o valor dela.
* Num campo cujo texto contém tags entre chaves, como `Conferido a {Diploma.Diplomado.Nome}`, cada tag é substituída. Um mesmo campo pode
  misturar texto e várias tags.

Os nomes das informações são os mesmos das colunas do [arquivo CSV de lote](https://docs.lacunasoftware.com/articles/digiploma/api/batches#formatos-de-arquivo), como
`Diploma.Diplomado.CPF` ou `Registro.LivroRegistro.NumeroRegistro`, além de valores derivados, como `Diploma.DataConclusaoExtenso`. A
página de criação de modelos, no Digiploma, lista todos eles.

Dois nomes de campo são especiais:

* `VerificationCode` recebe o endereço e o código de validação. Sem esse campo, eles são impressos no canto inferior direito da primeira
  página.
* `QrCode` marca onde fica o QR code que leva à página de validação. Sem esse campo, o QR code é colocado no canto inferior direito da
  última página.

Um modelo de diploma também pode ter uma **versão para papel timbrado**: um segundo formulário PDF, com os mesmos campos e sem imagem de
fundo, para imprimir o diploma em papel timbrado. Ele também precisa ter exatamente duas páginas. Nesse caso, cada diploma ganha um
segundo RVDD, baixado com `GET /api/degrees/{id}/letterhead-visual-representation-ticket`.

### Como os modelos de histórico e de currículo são usados

Nos históricos escolares e nos currículos, o PDF é um **fundo** aplicado a todas as páginas de um documento que o próprio Digiploma
diagrama, com as tabelas de dados do aluno, do curso, das disciplinas etc. As margens (`marginTopInCentimeters` etc.) mantêm o conteúdo
afastado do cabeçalho: a margem superior deve corresponder à altura do cabeçalho no PDF. Os campos de texto podem usar tags como
`{Historico.IesEmissora.Nome}` ou `{Curriculo.IesEmissora.CNPJ}`. Um QR code que leva à página de validação é colocado no canto inferior
esquerdo da última página.

### O endereço de validação

Por padrão, o QR code e o endereço impresso apontam para a página de validação da instância, `/validar/{code}`. Para usar uma página de
validação própria, defina `baseUrl` (por exemplo, `https://diplomas.example.edu.br`) e, opcionalmente, `validationPath`, em que `{code}` é
substituído pelo código de validação (por exemplo, `/diploma/{code}`).

### Criar um modelo

1. Faça o [upload](https://docs.lacunasoftware.com/articles/digiploma/api#uploads) do PDF.
1. Se quiser, visualize o modelo preenchido com dados de demonstração: `POST /api/templates/preview-ticket` recebe o upload (`id`,
   `contentType`) e as configurações do modelo (`type`, margens, `baseUrl`, `validationPath`) e retorna um
   [ticket](https://docs.lacunasoftware.com/articles/digiploma/api#downloads-e-tickets) para baixar o PDF preenchido.
1. Crie o modelo com `POST /api/templates`:

    ```json
    {
      "name": "Diploma de graduação 2026",
      "type": "Degree",
      "upload": { "id": "5d3b…", "name": "diploma.pdf", "contentType": "application/pdf" },
      "letterheadUpload": { "id": "8a1f…", "name": "diploma-timbrado.pdf", "contentType": "application/pdf" }
    }
    ```

| Campo | Descrição |
|---|---|
| `name` | Obrigatório, até 200 caracteres. |
| `type` | `Degree` (padrão), `AcademicTranscript` ou `Curriculum`. |
| `upload` | O PDF. O `contentType` precisa ser `application/pdf` (`ContentTypeNotSupported`). |
| `letterheadUpload` | Só para `Degree`: a versão para papel timbrado. |
| `baseUrl`, `validationPath` | O endereço de validação (veja acima). |
| `marginTopInCentimeters`, `marginBottomInCentimeters`, `marginLeftInCentimeters`, `marginRightInCentimeters` | Não se aplicam a `Degree`. Na página A4, as margens superior e inferior somadas não podem passar de 27,5 cm, e as margens esquerda e direita somadas precisam ficar abaixo de 21 cm (`InvalidTemplateDimensions`). |
| `settings.academicTranscript` | Só para `AcademicTranscript`: exibir o reconhecimento do curso junto com a renovação, ocultar o documento de identidade de alunos brasileiros e definir títulos personalizados para as tabelas de dados. |

Um PDF com o número de páginas ou a orientação errados falha com `InvalidNumberOfPages` ou `InvalidPageOrientation`.

### Outras operações

| Operação | Descrição |
|---|---|
| `GET /api/templates` | Uma página de modelos. Filtra por `Type`; `Q` busca no nome. |
| `GET /api/templates/{id}` | Um modelo, com as configurações, e tickets para baixar o PDF (`file`) e a versão para papel timbrado (`letterheadFile`). |
| `PUT /api/templates/{id}` | Altera o nome, o endereço de validação, as margens e as configurações. O PDF e o tipo não podem ser alterados: crie um novo modelo. |
| `DELETE /api/templates/{id}` | Exclui um modelo. Falha com `TemplateIsLinked` enquanto uma emissão usar o modelo. Os documentos já criados mantêm a representação visual. |

## Fluxos de assinatura

Um fluxo de assinatura lista os signatários de cada **etapa** de um documento. Cada tipo de documento usa algumas das etapas:

| `type` do fluxo | Usado em | Etapas |
|---|---|---|
| `EmissionRegistration` | [Emissão e registro](https://docs.lacunasoftware.com/articles/digiploma/api/degrees) | `issuingFlow`, `registrationFlow`, `storageFlow`, `academicTranscriptFlow` |
| `Emission` | [Apenas emissão](https://docs.lacunasoftware.com/articles/digiploma/api/emissions) | `issuingFlow`, `academicTranscriptFlow` |
| `Registration` | [Apenas registro](https://docs.lacunasoftware.com/articles/digiploma/api/registrations) | `registrationFlow`, `storageFlow` |
| `AcademicTranscript` | [Históricos escolares](https://docs.lacunasoftware.com/articles/digiploma/api/academic-transcripts) | `academicTranscriptFlow` |
| `Curriculum` | [Currículos](https://docs.lacunasoftware.com/articles/digiploma/api/curriculums) | `curriculumFlow` |

As etapas listadas precisam ser preenchidas, e as demais precisam ficar vazias.

### Regras de cada etapa

Cada etapa é uma lista de **regras**. Uma regra é a assinatura de uma pessoa, com certificado e-CPF, ou a assinatura da instituição, com
certificado e-CNPJ (`isCompany: true`):

| Etapa | O que assina | Regras |
|---|---|---|
| `issuingFlow` (**Emissão**) | `DadosDiploma`, no XML do diploma e no XML da documentação acadêmica | Pelo menos um representante da emissora (e-CPF) e a emissora (e-CNPJ). A primeira regra e-CNPJ também assina o XML da documentação acadêmica inteiro. |
| `registrationFlow` (**Registro**) | `DadosRegistro`, no XML do diploma | Apenas representantes da registradora (e-CPF). |
| `storageFlow` (**Armazenamento**) | O XML do diploma inteiro | Exatamente uma regra, do e-CNPJ da registradora, com `requiredSignatures` = 1. |
| `academicTranscriptFlow` | O XML do histórico escolar | Pelo menos uma regra e-CNPJ. Os representantes (e-CPF) assinam primeiro; depois, a primeira regra e-CNPJ. |
| `curriculumFlow` | O XML do currículo | Exatamente uma regra e-CNPJ. Os coordenadores de curso (e-CPF) assinam primeiro. |

Um fluxo que viola essas regras falha com um erro `DocumentFlow…`, como `DocumentFlowStorageInstitutionSignatureRequired`.

```json
{
  "name": "Diplomas — graduação",
  "type": "EmissionRegistration",
  "issuingFlow": [
    { "order": 1, "isCompany": false, "requiredSignatures": 1,
      "signers": [ { "name": "Reitora", "email": "reitoria@ies.edu.br", "cpf": "12345678909" } ] },
    { "order": 2, "isCompany": true, "companyIdentifier": "12345678000195", "requiredSignatures": 1,
      "signers": [ { "name": "Secretaria Geral", "email": "secretaria@ies.edu.br", "cpf": "98765432100" } ] }
  ],
  "registrationFlow": [ … ],
  "storageFlow": [ … ],
  "academicTranscriptFlow": [ … ]
}
```

| Campo da regra | Descrição |
|---|---|
| `order` | Numa etapa, as regras com o mesmo `order` são assinadas em paralelo; valores diferentes são assinados em sequência. As etapas se sucedem na ordem da tabela acima. |
| `isCompany` | `true` para uma assinatura institucional (e-CNPJ), `false` para uma pessoa (e-CPF). |
| `companyIdentifier` | Com `isCompany`, o CNPJ que o certificado precisa ter. |
| `signers` | As pessoas que assinam, cada uma com `name`, `email` e `cpf` (todos obrigatórios). Numa regra institucional, a pessoa que assina com o certificado e-CNPJ. |
| `requiredSignatures` | Quando uma regra lista vários signatários, quantos deles precisam assinar. |
| `ruleName` | O nome de uma regra com vários signatários. |

Os certificados precisam ser do tipo A3, a menos que a instância desative essa exigência. Os históricos escolares parciais aceitam
certificados A1.

### Operações

| Operação | Descrição |
|---|---|
| `POST /api/flows` | Cria um fluxo, com `name`, `type` e as etapas. |
| `POST /api/flows/validate` | Verifica um fluxo contra as regras do seu `type`, sem salvá-lo. |
| `GET /api/flows` | Uma página de fluxos. Filtra por `type`; `Q` busca no nome. |
| `GET /api/flows/{id}` | Um fluxo, com as etapas. |
| `PUT /api/flows/{id}` | Substitui um fluxo. |
| `DELETE /api/flows/{id}` | Exclui um fluxo. |

Lotes e documentos guardam uma cópia do fluxo com que foram criados: alterar ou excluir um fluxo não os afeta.

Numa requisição de criação, envie `documentFlowId` com o id de um fluxo salvo, ou `documentFlow` com as etapas na própria requisição (sem
`name` e `type`). Quando os dois são enviados, vale o `documentFlow`.