Batches

A batch (lote) creates many documents from one file: diplomas, emissions, registration requests, academic transcripts or curriculums. The batch is created synchronously, after its file is validated, and its documents are generated in the background.

Batch types

type	Creates	Input	Organization type
EmissionRegistration (default)	Diplomas, each with its final academic transcript (Issue and register)	JSON or CSV file	Emissora e Registradora
Emission	Emissions (Issue only)	JSON file	Emissora, Emissora e Registradora
Registration	Registration requests (Register only)	Signed academic documentation XML files, one per request	Registradora, Emissora e Registradora
AcademicTranscript	Academic transcripts	JSON file	Emissora, Emissora e Registradora
Curriculum	Curriculums	JSON file	Emissora, Emissora e Registradora

Always send type: when omitted, it defaults to EmissionRegistration.

File formats

A JSON file is an array with one object per document, with the same data as the single-creation request of that document type. Sample files:

type	Sample
EmissionRegistration	JSON, CSV
Emission	JSON
AcademicTranscript	JSON
Curriculum	JSON

The CSV file, accepted for diplomas only, has one line per diploma and a header line with the names of the information, as dotted paths such as Diploma.Diplomado.Nome. Repeated elements take a numbered suffix, as in Diploma.Curso.Habilitacao_1.NomeHabilitacao. The separator is the one declared on a first line SEP=, (as Excel writes it), or otherwise the comma or the semicolon, whichever is more frequent in the header. The default encoding is ISO-8859-1 (Latin-1); a file with a byte order mark is read as UTF-8.

In JSON files, a decimal comma is accepted, and texts are trimmed. JSON entries are validated against the MEC XML schema; CSV lines are validated against the data rules only.

Create a batch

1. Upload the file. For a JSON file, send contentType application/json; for a CSV file, text/csv.
2. Validate the file (recommended, see Validate a file).
3. Create the batch with POST /api/batches:

{
  "type": "EmissionRegistration",
  "fileType": "Csv",
  "batchFile": { "id": "5d3b…", "name": "formandos-2026-1.csv", "contentType": "text/csv" },
  "templateId": "0f8b…",
  "academicTranscriptTemplateId": "6a1d…",
  "documentFlowId": "c2f0…",
  "newFolderName": "Formandos 2026-1"
}

Field	Description
type	The batch type.
fileType	Json or Csv. Csv only for EmissionRegistration (BatchTypeRequiresJson).
batchFile	The uploaded file. Not used for Registration. (degreesFile is an obsolete name of the same field.)
templateId	The diploma template: required for EmissionRegistration, optional for Emission.
academicTranscriptTemplateId	The academic transcript template: required for EmissionRegistration, Emission and AcademicTranscript.
curriculumTemplateId	The curriculum template: required for Curriculum.
documentFlowId / documentFlow	The signers, required: a saved signature flow whose type matches the batch, or the stages inline.
newFolderName / signerFolderId	The Signer folder for the documents: a new folder with this name, or an existing folder.
academicTranscriptType	For AcademicTranscript: Partial, Final or Copy.
emission	For Emission: registrationType and, for Subscription, registryId, as in Issue only. It can also attach the supporting documents and the designation act of each entry as uploads, in files (with the 0-based position of the entry in index).
registration	For Registration: academicDocumentationFiles, the list of uploaded XML files (at least one).

The response is the batch id: { "id": "…" }.

The whole file is validated during this call, which can take a while for a large file. If any entry is invalid, the batch is not created, and the call fails with DegreesFileIsInvalid, AcademicTranscriptFileIsInvalid, CurriculumFileIsInvalid or BatchRegistrationInvalidFiles, with no detail per entry. To find the problems, validate the file first.

For Registration batches, the XML files and their signatures are validated, and the requests are created, but nothing is sent to Signer: the signing starts when each request is registered, with the flow and the folder of the batch.

Follow the batch

The documents are generated in the background, in groups of 50. GET /api/batches/{id} returns the batch's progress:

Field	Description
status	Created (waiting), Started (generating) or Completed.
totalDegrees	The number of entries in the file (for every batch type, despite the name).
totalDegreesCreated	The number of documents created so far.
totalDegreesWithError	The number of entries that failed so far.

Poll it until status is Completed. There are no batch webhooks, but each document created sends its own creation webhook, such as DegreeCreated.

An entry can fail during generation even after the file was validated, for example when another document with the same validation code already exists, or when Signer refuses a group of documents. Failed entries are not created, and the reasons are only in the batch log: GET /api/batches/{id}/log-ticket returns a ticket to download it as a text file, in Portuguese, one line per step, with the entry number and the student's CPF. The log exists only after the batch is Completed (BatchLogFileNotFound before).

To list what a batch created, use GET /api/batches/{id}/degrees, …/emissions, …/registrations, …/academic-transcripts or …/curriculums, with the paging parameters. An EmissionRegistration batch lists its diplomas and their transcripts.

GET /api/batches returns a page of the organization's batches, sorted by creation date.

Validate a file

Before creating a batch, validate its file with the operation for its type. It returns the result of each entry, and creates nothing:

type	Operation
EmissionRegistration	POST /api/batches/degrees-file (JSON or CSV)
Emission	POST /api/batches/emissions-file
AcademicTranscript	POST /api/batches/academic-transcripts-file (with academicTranscriptType)
Curriculum	POST /api/batches/curriculums-file

{ "id": "5d3b…", "name": "formandos-2026-1.csv", "contentType": "text/csv", "fileType": "Csv" }

{
  "isValid": false,
  "totalErrors": 2,
  "generalError": null,
  "result": [
    { "entryNumber": 1, "isValid": true, "errors": [], "structureErrors": [], "information": { … } },
    { "entryNumber": 2, "isValid": false, "errors": [ "Diploma.Diplomado.CPF: …" ], "structureErrors": [ … ], "information": { … } }
  ]
}

The response is always HTTP 200. Problems with the file as a whole, such as a CSV file without a header, come in generalError, with no result. Each entry of result has its number in the file (from 1), its errors in the data (errors, as "field: message", in Portuguese), its errors against the MEC XML schema (structureErrors) and the data read from the file (information).

Operation reference

Operation	Description
POST /api/batches	Create a batch
GET /api/batches	List batches
GET /api/batches/{id}	Get a batch
GET /api/batches/{id}/log-ticket	Download the batch log
GET /api/batches/{id}/degrees, …/emissions, …/registrations, …/academic-transcripts, …/curriculums	List the documents of a batch
POST /api/batches/degrees-file	Validate a diploma file
POST /api/batches/emissions-file	Validate an emission file
POST /api/batches/academic-transcripts-file	Validate an academic transcript file
POST /api/batches/curriculums-file	Validate a curriculum file