---
title: "Templates and signature flows"
description: "Templates for the visual representations of diplomas, transcripts and curriculums, and signature flows that define who signs each Digiploma document."
canonical: "https://docs.lacunasoftware.com/en-us/articles/digiploma/api/templates-and-flows"
locale: "en"
product: "Digiploma"
last_updated: "2026-10-11"
---

# Templates and signature flows

Before creating documents, an organization usually registers two kinds of resource that it reuses across requests:

* **Templates**, which define the visual representation of each document: the RVDD of a diploma, the RVHE of an academic transcript and
  the RVCE of a curriculum.
* **Signature flows**, which define who signs each document. Saving a flow is optional, since every creation request also accepts the
  signers inline, but each request needs one or the other.

## Templates

| `type` | Used for | PDF requirements |
|---|---|---|
| `Degree` | The diploma's RVDD | A PDF form with exactly **two pages** (front and back), in **landscape**. |
| `AcademicTranscript` | The academic transcript's RVHE | A PDF with **one page**, in **portrait**, with the institution's header (name, address, regulatory acts and, optionally, the logo), as in Art. 17 of Portaria MEC 1095/2018. |
| `Curriculum` | The curriculum's RVCE | A PDF with **one page**, in **portrait**. |

Examples: [diploma template](https://www.digiploma.com.br/assets/files/template_v2.pdf),
[academic transcript template](https://www.digiploma.com.br/assets/files/academic_transcript_template.pdf) and
[curriculum template](https://www.digiploma.com.br/assets/files/curriculum_template.pdf).

### How the diploma template is filled

The diploma template is a PDF form. Digiploma fills its text fields with the diploma's data, and then flattens the form:

* A field named after a piece of information, such as `Diploma.Diplomado.Nome`, receives its value.
* A field whose text contains tags in braces, such as `Conferido a {Diploma.Diplomado.Nome}`, has each tag replaced. One field can mix text
  and several tags.

The names of the information are the same as the column names of the [CSV batch file](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/batches#file-formats), such as
`Diploma.Diplomado.CPF` or `Registro.LivroRegistro.NumeroRegistro`, plus derived values such as `Diploma.DataConclusaoExtenso`. The
template creation page, in Digiploma, lists them.

Two field names are special:

* `VerificationCode` receives the validation address and code. Without it, they are printed at the bottom right of the first page.
* `QrCode` marks where the QR code to the validation page goes. Without it, the QR code is placed at the bottom right of the last page.

A diploma template can also have a **letterhead** version (*timbrado*): a second PDF form, with the same fields and no background image, for
printing the diploma on letterhead paper. It must also have exactly two pages. Each diploma then gets a second RVDD, downloaded with
`GET /api/degrees/{id}/letterhead-visual-representation-ticket`.

### How the transcript and curriculum templates are used

For academic transcripts and curriculums, the PDF is a **background** applied to every page of a document that Digiploma lays out itself,
with the tables of the student's data, the course, the subjects, and so on. The margins (`marginTopInCentimeters`, and so on) keep the
content clear of the header: the top margin should match the height of the header on the PDF. Text fields can use tags such as
`{Historico.IesEmissora.Nome}` or `{Curriculo.IesEmissora.CNPJ}`. A QR code to the validation page is placed at the bottom left of the last
page.

### The validation address

By default, the QR code and the printed address point to the instance's validation page, `/validar/{code}`. To use your own validation page,
set `baseUrl` (for example `https://diplomas.example.edu.br`) and, optionally, `validationPath`, where `{code}` is replaced by the
validation code (for example `/diploma/{code}`).

### Create a template

1. [Upload](https://docs.lacunasoftware.com/en-us/articles/digiploma/api#uploads) the PDF.
1. Optionally, preview it with demonstration data: `POST /api/templates/preview-ticket` takes the upload (`id`, `contentType`) and the
   template settings (`type`, margins, `baseUrl`, `validationPath`), and returns a [ticket](https://docs.lacunasoftware.com/en-us/articles/digiploma/api#downloads-and-tickets) to download
   the filled PDF.
1. Create it with `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" }
    }
    ```

| Field | Description |
|---|---|
| `name` | Required, up to 200 characters. |
| `type` | `Degree` (default), `AcademicTranscript` or `Curriculum`. |
| `upload` | The PDF. Its `contentType` must be `application/pdf` (`ContentTypeNotSupported`). |
| `letterheadUpload` | `Degree` only: the letterhead version. |
| `baseUrl`, `validationPath` | The validation address (see above). |
| `marginTopInCentimeters`, `marginBottomInCentimeters`, `marginLeftInCentimeters`, `marginRightInCentimeters` | Not for `Degree`. On the A4 page, top and bottom together must not exceed 27.5 cm, and left and right together must stay under 21 cm (`InvalidTemplateDimensions`). |
| `settings.academicTranscript` | `AcademicTranscript` only: show the course recognition along with its renewal, hide the identity document of Brazilian students, and custom titles for the data tables. |

A PDF with the wrong number of pages or orientation fails with `InvalidNumberOfPages` or `InvalidPageOrientation`.

### Other operations

| Operation | Description |
|---|---|
| `GET /api/templates` | A page of templates. Filters by `Type`; `Q` matches the name. |
| `GET /api/templates/{id}` | A template, with its settings, and tickets to download its PDF (`file`) and letterhead (`letterheadFile`). |
| `PUT /api/templates/{id}` | Changes the name, the validation address, the margins and the settings. The PDF and the type cannot be changed: create a new template. |
| `DELETE /api/templates/{id}` | Deletes a template. Fails with `TemplateIsLinked` while an emission uses it. Documents already created keep their visual representation. |

## Signature flows

A signature flow lists the signers of each **stage** of a document. Each document type uses some stages:

| Flow `type` | Used by | Stages |
|---|---|---|
| `EmissionRegistration` | [Issue and register](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/degrees) | `issuingFlow`, `registrationFlow`, `storageFlow`, `academicTranscriptFlow` |
| `Emission` | [Issue only](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/emissions) | `issuingFlow`, `academicTranscriptFlow` |
| `Registration` | [Register only](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/registrations) | `registrationFlow`, `storageFlow` |
| `AcademicTranscript` | [Academic transcripts](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/academic-transcripts) | `academicTranscriptFlow` |
| `Curriculum` | [Curriculums](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/curriculums) | `curriculumFlow` |

The stages listed must be filled, and the others must be empty.

### Rules of each stage

Each stage is a list of **rules**. A rule is either a signature of a person, with an e-CPF certificate, or a signature of the institution,
with an e-CNPJ certificate (`isCompany: true`):

| Stage | What it signs | Rules |
|---|---|---|
| `issuingFlow` (*Emissão*) | `DadosDiploma`, in the diploma XML and in the academic documentation XML | At least one representative of the issuer (e-CPF) and the issuer (e-CNPJ). The first e-CNPJ rule also signs the whole academic documentation XML. |
| `registrationFlow` (*Registro*) | `DadosRegistro`, in the diploma XML | Representatives of the registrar only (e-CPF). |
| `storageFlow` (*Armazenamento*) | The whole diploma XML | Exactly one rule, of the registrar's e-CNPJ, with `requiredSignatures` = 1. |
| `academicTranscriptFlow` | The academic transcript XML | At least one e-CNPJ rule. Representatives (e-CPF) sign first; then the first e-CNPJ rule. |
| `curriculumFlow` | The curriculum XML | Exactly one e-CNPJ rule. Course coordinators (e-CPF) sign first. |

A flow that breaks these rules fails with a `DocumentFlow…` error, such as `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": [ … ]
}
```

| Rule field | Description |
|---|---|
| `order` | Rules with the same `order` in a stage are signed in parallel; different values are signed in sequence. Stages follow each other in the order of the table above. |
| `isCompany` | `true` for an institutional signature (e-CNPJ), `false` for a person (e-CPF). |
| `companyIdentifier` | For `isCompany`, the CNPJ the certificate must have. |
| `signers` | The people who sign, each with `name`, `email` and `cpf` (all required). For an institutional rule, the person who signs with the e-CNPJ certificate. |
| `requiredSignatures` | When a rule lists several signers, how many of them must sign. |
| `ruleName` | The name of a rule with several signers. |

The certificates must be of type A3, unless the instance disables that requirement. Partial academic transcripts accept A1 certificates.

### Operations

| Operation | Description |
|---|---|
| `POST /api/flows` | Create a flow, with a `name`, a `type` and its stages. |
| `POST /api/flows/validate` | Check a flow against the rules of its `type`, without saving it. |
| `GET /api/flows` | A page of flows. Filters by `type`; `Q` matches the name. |
| `GET /api/flows/{id}` | A flow, with its stages. |
| `PUT /api/flows/{id}` | Replace a flow. |
| `DELETE /api/flows/{id}` | Delete a flow. |

Batches and documents keep a copy of the flow they were created with: changing or deleting a flow does not affect them.

In a creation request, send `documentFlowId` with the id of a saved flow, or `documentFlow` with the stages inline (without `name` and
`type`). When both are sent, `documentFlow` is used.