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, academic transcript template and curriculum template.

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, 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 the PDF.

2. 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 to download the filled PDF.

3. Create it with POST /api/templates:

   {
     "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	issuingFlow, registrationFlow, storageFlow, academicTranscriptFlow
Emission	Issue only	issuingFlow, academicTranscriptFlow
Registration	Register only	registrationFlow, storageFlow
AcademicTranscript	Academic transcripts	academicTranscriptFlow
Curriculum	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.

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