Academic transcripts

The digital academic transcript (histórico escolar digital), defined by Portaria MEC 1095/2018, is a signed XML file plus its visual representation, the RVHE, a PDF built from a template. Digiploma creates both, collects the signatures in Lacuna Signer and publishes the transcript for validation.

A final transcript is also generated automatically with each diploma, in the issue and register and issue only modes. Use this API to issue the other transcripts, or a final transcript on its own.

Types

type	Meaning
Partial	Issued at any time while the student is enrolled, as proof of how much of the curriculum has been completed.
Final	Issued when the student's relationship with the institution ends, for the diploma or an external transfer.
Copy	Second copy (segunda via), in digital form, of a transcript originally issued on paper. The curriculum code and the admission data become optional.

A partial transcript is refused while the student has a final transcript for the same course that is not canceled. And when any transcript of a student and course is signed, Digiploma cancels the older partial transcripts of that student and course automatically, with the reason "Histórico escolar cancelado automaticamente pois um histórico escolar final ou um novo histórico escolar parcial foi emitido".

Before you start

• The organization must be an issuer (type Emissora or Emissora e Registradora). Otherwise the call fails with SubscriptionOperationNotAllowed.
• The Signer API key must be set in the organization's Configurações (Settings) (SignerApiKeyNotSet).
• You need an academic transcript template: a one-page, portrait PDF with the institution's header.
• You need the signers: a saved signature flow of type AcademicTranscript, or the signers inline in each request.

Create a transcript

POST /api/academic-transcripts creates one transcript. To create many from a JSON file, use a batch.

{
  "type": "Partial",
  "academicTranscriptTemplateId": "6a1d9e44-…",
  "documentFlow": {
    "academicTranscriptFlow": [
      { "order": 1, "requiredSignatures": 1, "isCompany": false,
        "signers": [ { "name": "Maria Souza", "email": "maria@ies.edu.br", "cpf": "12345678909" } ] },
      { "order": 2, "requiredSignatures": 1, "isCompany": true, "companyIdentifier": "12345678000195",
        "signers": [ { "name": "João Lima", "email": "joao@ies.edu.br", "cpf": "98765432100" } ] }
    ]
  },
  "academicTranscript": {
    "aluno": { … },
    "dadosCurso": { … },
    "iesEmissora": { … },
    "historicoEscolar": { "codigoCurriculo": "…", "elementosHistorico": [ … ], "situacaoAtualDiscente": { … }, … }
  }
}

Field	Required	Description
type	Yes	Partial, Final or Copy.
academicTranscriptTemplateId	Yes	The academic transcript template.
academicTranscript	Yes	The MEC data: the student (aluno), the course (dadosCurso), the issuing institution (iesEmissora) and the transcript itself (historicoEscolar). historicoEscolar.dataEmissaoHistorico and horaEmissaoHistorico default to the current date and time.
documentFlowId	One of the two	A saved signature flow of type AcademicTranscript.
documentFlow	One of the two	The signers inline. Only academicTranscriptFlow may be filled. Takes precedence over documentFlowId.
newFolderName	No	Creates a Signer folder with this name for the document. Takes precedence over signerFolderId.
signerFolderId	No	An existing Signer folder.

A complete example of the data is in the JSON sample file. The data is validated against the MEC XML schema.

Signers. The flow needs at least one institutional signature (isCompany: true, an e-CNPJ certificate), or the call fails with DocumentFlowIssuerInstitutionSignatureRequired. The representatives (e-CPF) sign first, in the order of their order values, in a step named Secretaria acadêmica; the institution signs last, in a step named Instituição. Only the first institutional rule is used. Final transcripts and second copies require A3 certificates, unless the instance disables that requirement.

The response is {success, academicTranscriptId, errors}:

Check success, not just the HTTP status

Failures that happen while the transcript is generated return HTTP 200 with "success": false, and the processing log in Portuguese in errors. That includes a duplicate validation code and a partial transcript refused because of an existing final one. See Creation results.

The validation code is computed from the student, the course, the institution and the issue date and time (to the minute), in the format {issuer MEC code}.{12 hexadecimal characters}. Two transcripts of the same student and course issued in the same minute get the same code, and the second one is refused as a duplicate.

Statuses

status	Meaning
Created	Created; waiting for signatures.
Active	Signed: the transcript is valid.
CanceledTemporarily	Temporarily canceled. Can be restored.
Canceled	Canceled.

Cancel, suspend or restore

POST /api/academic-transcripts/{id}/cancellation cancels a transcript, with a reason of up to 500 characters:

{ "reason": "Emitido com dados incorretos" }

If the transcript is not signed yet, its document is deleted from Signer and it can never be restored. A transcript that is already canceled fails with AcademicTranscriptAlreadyCanceled.

POST /api/academic-transcripts/{id}/status changes the status, with a required reason:

status	Allowed when
Canceled	The transcript is not canceled yet. Same effect as /cancellation.
CanceledTemporarily	The transcript is signed.
Active (restore)	The transcript is CanceledTemporarily and signed (AcademicTranscriptNotSignedCannotBeRestored).

Any other change fails with AcademicTranscriptInvalidStatus. Both operations require the UpdateAcademicTranscript permission.

Download the files

Document	Base64	Ticket	Direct download	Available when
Signed XML	GET /{id}/xml-b64	GET /{id}/xml-ticket	GET /{id}/xml	The transcript is Active (AcademicTranscriptNotValid). For a ticket, checked when it is downloaded.
RVHE	GET /{id}/visual-representation-b64	GET /{id}/visual-representation-ticket	—	Always.

All paths are relative to /api/academic-transcripts. See Downloads and tickets.

Replace the visual representation

POST /api/academic-transcripts/{id}/visual-representation replaces the RVHE of a transcript that is not canceled, from another academic transcript template (templateId) or from an uploaded PDF in portrait orientation (uploadId). The signed XML is not affected. It requires the UpdateDocumentVisualRepresentation permission (Administrador and Gerente roles).

Read and search

• GET /api/academic-transcripts/{id} returns the transcript, with degreeId when it was generated with a diploma.
• GET /api/academic-transcripts/{id}/history returns the status changes, newest first.
• GET /api/academic-transcripts returns a page of transcripts. Besides the paging parameters, it filters by Status, BatchId, creation date (StartDateUtc inclusive, EndDateUtc exclusive), IsSigned=true (signed transcripts, including canceled ones) and Q (student's CPF, name or social name, or course). Results are sorted by update date.

Validate a transcript

• GET /api/academic-transcripts/codes/{code} validates a transcript of your own organization, with the API key.
• GET /api/academic-transcripts/{code}/validation is the public validation. See Public validation.

Webhooks

Event	When
AcademicTranscriptCreated	The transcript was created (not sent when it is generated with POST /api/degrees/{id}/academic-transcript).
AcademicTranscriptConcluded	The transcript was signed, or restored.
AcademicTranscriptCanceled	The transcript was canceled, including the automatic cancellation of older partial transcripts.
AcademicTranscriptCanceledTemporarily	The transcript was suspended.

See Webhooks for the payloads.

Operation reference

Operation	Description
POST /api/academic-transcripts	Create a transcript
GET /api/academic-transcripts	List transcripts
GET /api/academic-transcripts/{id}	Get a transcript
GET /api/academic-transcripts/{id}/history	Get the status history
POST /api/academic-transcripts/{id}/cancellation	Cancel a transcript
POST /api/academic-transcripts/{id}/status	Cancel, suspend or restore a transcript
GET /api/academic-transcripts/{id}/xml, …/xml-b64, …/xml-ticket	Download the signed XML
GET /api/academic-transcripts/{id}/visual-representation-b64, …/visual-representation-ticket	Download the RVHE
POST /api/academic-transcripts/{id}/visual-representation	Replace the RVHE
GET /api/academic-transcripts/codes/{code}	Validate a transcript of your organization
GET /api/academic-transcripts/{code}/validation, …/validation/visual-representation, …/validation/xml	Public validation