Batch

Overview

Batch

The Batch resource allows bulk document processing in a single request.

It is designed for high-volume operational flows where multiple fiscal documents must be validated and submitted together under a shared country, purpose, and flow context. Using batch submission reduces repetitive API calls and improves consistency in large-scale integrations.

Supported document types:

INVOICE
CREDIT_NOTE
DEBIT_NOTE

Endpoints

POST - /v1.1/batch
POST - /v1.1/batch/importer
POST - /v1.1/documents/create/batch

Processing Model

Batch requests are validated and processed according to the selected endpoint and input format.

/v1.1/batch accepts structured JSON or UBL/XML payloads.
/v1.1/batch/importer accepts template-based file uploads (CSV/Excel).
/v1.1/documents/create/batch generates batch template files from existing documents that match filters.

Depending on endpoint parameters, processing can be synchronous or asynchronous.

Batch Lifecycle

The batch flow follows a predictable sequence:

Input validation The API verifies query parameters, authorization context, and payload format.
Document parsing Each document or row is parsed according to the selected endpoint and content type.
Business validation Tax and country rules are applied before integration processing.
Registration and processing Accepted entries are stored and pushed into the platform processing pipeline.

Synchronous vs Asynchronous Mode

Batch processing can complete in two execution modes:

Synchronous The API returns the processing output directly in the response.
Asynchronous The API acknowledges the request and sends the final result by email after background processing.

This behavior is explicit in /v1.1/batch/importer through the sync parameter and may vary by country context.

Typical Use Cases

High-volume invoice submission from ERP systems.
Monthly or periodic tax reporting uploads.
Bulk migration of legacy records.
Spreadsheet-driven operational imports without custom JSON integration.

Endpoints

Process document batch (JSON or UBL/XML)

POST - /v1.1/batch

Creates documents from a batch payload in JSON or UBL/XML format.

This endpoint is designed for direct system-to-system integrations where documents are already available in structured payloads. It is the preferred choice for automation pipelines that generate invoice data programmatically.

Query Parameters

Required parameters

Name	Type	Required	Description
`countryIso`	string	Yes	Country code in ISO 3166-1 alpha-2 format (e.g., `ES`).
`vatNumber`	string	Yes	Company VAT number.
`purpose`	string	Yes	Allowed values: `EINVOICING`, `EREPORTING`, `RETURNS`.
`flow`	string	Yes	Allowed values: `ISSUED`, `RECEIVED`.

Optional parameters

Name	Type	Required	Description
`period`	object	No	Relevance period, for example `{ "from": "2024-01", "to": "2024-07" }`.

Request Body

Required. Supported media types:

application/json (array of CreateJsonDocumentRequest)
application/xml (DocumentListType)

For JSON submissions, each array item represents one document with its own metadata, counterparty, and line details. For XML submissions, the request must contain a <Documents> root with one or more UBL document nodes.

Example Request (JSON)

POST /v1.1/batch?countryIso=ES&vatNumber=B27835560&purpose=EINVOICING&flow=ISSUED
Authorization: Bearer $ACCESS_TOKEN
Content-Type: application/json

[
  {
    "schemaVersion": "1.0",
    "documentType": "INVOICE",
    "documentDate": "2025-04-12",
    "documentNumber": "2025/0004",
    "counterparty": {
      "name": "CUSTOMER S.L.",
      "vatNumber": "ESB12345678",
      "address": {
        "streetName": "RUA POLICARPO SANZ",
        "houseAndOfficeNo": "36",
        "city": "VIGO",
        "countrySubdivision": "PONTEVEDRA",
        "countryCode": "ES"
      }
    },
    "lines": [
      {
        "taxCode": "DSGS",
        "number": 1,
        "description": "Supply of services",
        "quantity": 1,
        "unitPrice": 100,
        "netAmount": 100,
        "vatRate": 21,
        "vatAmount": 21,
        "grossAmount": 121
      }
    ],
    "totalNet": 100,
    "totalVat": 21,
    "totalGross": 121,
    "currencyCode": "EUR"
  }
]

Responses

Status	Description	Content-Type
`201`	Batch created	`/` (`BatchResponse`)
`400`	Invalid input	`/` (`ApiError`)

Success Response

{
  "id": "96d7cd9a-6259-4ff1-9e75-ce16f10d0b67"
}

Load batch file (CSV/Excel template)

POST - /v1.1/batch/importer

Creates documents from an uploaded batch file in Marosa template format.

This endpoint is intended for operational and template-based imports where data is prepared in spreadsheet files instead of JSON/XML payloads.

Query Parameters

Required parameters

Name	Type	Required	Description
`countryIso`	string	Yes	Country code in ISO 3166-1 alpha-2 format (e.g., `ES`).
`vatNumber`	string	Yes	Company VAT number.
`purpose`	string	Yes	Allowed values: `EINVOICING`, `EREPORTING`, `RETURNS`.

Optional parameters

Name	Type	Required	Default	Description
`sync`	boolean	No	`false`	If `true` and `countryIso=ES`, processing is synchronous. Otherwise, asynchronous.

Request Body

Required. Media type: multipart/form-data

Field	Type	Required	Description
`file`	binary	Yes	Batch file in CSV or Excel format, according to Marosa template.

The uploaded file must follow Marosa's template structure. If the template schema is not respected, the API returns a validation error response.

Example Request

POST /v1.1/batch/importer?countryIso=ES&vatNumber=B27835560&purpose=EREPORTING&sync=true
Authorization: Bearer $ACCESS_TOKEN
Content-Type: multipart/form-data

[email protected]

Responses

Status	Description	Content-Type
`200`	Batch created successfully	`application/json`
`400`	Invalid input	`/` (`ApiError`)

In synchronous mode (sync=true with countryIso=ES), the result is returned immediately. In asynchronous mode, the response indicates that processing continues in background and the final output is delivered by email.

Build batch file from document filters

POST - /v1.1/documents/create/batch

Builds a Spanish batch file in Marosa template format using documents that match the provided filter.

This endpoint is typically used for extraction, reconciliation, and reporting workflows where a generated batch file is required from documents already registered in the platform.

Request Body

Required. Media type: application/json (InvoiceBatchGeneratorApi).

Main fields:

Name	Type	Required	Description
`invoiceFilter`	object	Yes	Document filter criteria (purpose, flow, country, period, statuses, etc.).
`batchInformation`	object	No	Metadata used in generated batch output.
`withAuditInformation`	boolean	No	Includes audit information in the generated output when enabled.
`async`	boolean	No	`true` generates file asynchronously by email; `false` returns file synchronously (up to 100K docs).

Example Request

POST /v1.1/documents/create/batch
Authorization: Bearer $ACCESS_TOKEN
Content-Type: application/json

{
  "invoiceFilter": {
    "purpose": "EREPORTING",
    "flow": "ISSUED",
    "countryIso": "ES",
    "companyVatNumbers": ["B27835560"],
    "period": [
      {
        "from": "2024-01",
        "to": "2024-04"
      }
    ],
    "year": "2024",
    "statuses": ["CORRECTO", "INCORRECTO:3000", "ACEPTADO_CON_ERRORES:2025"],
    "documentNumber": "myInvoice",
    "batchNumber": "1234",
    "batchReference": "BATCH-REF-001"
  },
  "batchInformation": {
    "returnType": "A0",
    "reportingEntityTIN": "B27835560",
    "surnamesAndNameOrCompanyName": "Marosa",
    "legalRepresentativeTIN": "",
    "financialYear": 2024,
    "externalReference": "myExternalReference"
  },
  "withAuditInformation": true,
  "async": false
}

Responses

Status	Description	Content-Type
`200`	Invoices exported successfully	`text/csv` (sync) or `text/plain` (async message)
`400`	Invalid input	`/` (`ApiError`)

When async=false, the response contains the generated CSV/template file. When async=true, the response contains an acknowledgment message and the file is sent by email.