---
title: "Batches"
description: "Digiploma batches: create many diplomas, emissions, registration requests, academic transcripts or curriculums from one file, generated in the background."
canonical: "https://docs.lacunasoftware.com/en-us/articles/digiploma/api/batches"
locale: "en"
product: "Digiploma"
last_updated: "2026-10-11"
---

# 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](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/degrees)) | JSON or CSV file | Emissora e Registradora |
| `Emission` | Emissions ([Issue only](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/emissions)) | JSON file | Emissora, Emissora e Registradora |
| `Registration` | Registration requests ([Register only](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/registrations)) | Signed academic documentation XML files, one per request | Registradora, Emissora e Registradora |
| `AcademicTranscript` | [Academic transcripts](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/academic-transcripts) | JSON file | Emissora, Emissora e Registradora |
| `Curriculum` | [Curriculums](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/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](https://www.digiploma.com.br/assets/files/json-template5.json), [CSV](https://www.digiploma.com.br/assets/files/csv-template6.csv) |
| `Emission` | [JSON](https://www.digiploma.com.br/assets/files/emission-json-template3.json) |
| `AcademicTranscript` | [JSON](https://www.digiploma.com.br/assets/files/academic-transcript-template2.json) |
| `Curriculum` | [JSON](https://www.digiploma.com.br/assets/files/curriculum-template.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](https://docs.lacunasoftware.com/en-us/articles/digiploma/api#uploads) the file. For a JSON file, send `contentType` `application/json`; for a CSV file, `text/csv`.
1. Validate the file (recommended, see [Validate a file](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/batches#validate-a-file)).
1. Create the batch with `POST /api/batches`:

```json
{
  "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](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/templates-and-flows#signature-flows) 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](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/emissions#create-an-emission). 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](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/registrations#register-the-diploma), 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](https://docs.lacunasoftware.com/en-us/articles/digiploma/api#downloads-and-tickets) 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](https://docs.lacunasoftware.com/en-us/articles/digiploma/api#pagination). 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` |

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

```json
{
  "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 |