Document

Overview

Document

The Document entity constitutes the primary resource within the API and models a structured electronic document.

Three document implementations are available:

INVOICE
CREDIT_NOTE
DEBIT_NOTE

Endpoints

GET - /v1.1/documents.
GET - /v1.1/document.
POST - /v1.1/document.
POST - /v1.1/document/validate.
POST - /v1.1/document/convert.

Document status lifecycle

Upon submission, a document progresses through a controlled sequence of internal processing phases. Each phase evaluates specific conditions that determine the subsequent transition.

stateDiagram-v2

    [*] --> CREATED

    CREATED --> DUPLICATED : [isDuplicate]
    CREATED --> VALIDATING : [!isDuplicate]

    VALIDATING --> ERROR : [validationFailed]
    VALIDATING --> PROCESSING : [validationPassed]

    PROCESSING --> OK : [integrationSuccess]
    PROCESSING --> ERROR : [integrationFailed]

    DUPLICATED --> [*]
    ERROR --> [*]
    OK --> [*]

    %% --- Styles ---
    classDef processing fill:#2196F3,stroke:#0D47A1,color:#ffffff
    classDef success fill:#4CAF50,stroke:#1B5E20,color:#ffffff
    classDef error fill:#F44336,stroke:#B71C1C,color:#ffffff
    classDef duplicate fill:#FF9800,stroke:#E65100,color:#ffffff
		classDef internal fill:#9E9E9E,stroke:#616161,color:#ffffff
    
    class CREATED internal
		class VALIDATING internal
    class PROCESSING processing
    class OK success
    class ERROR error
    class DUPLICATED duplicate

The lifecycle follows the sequence below:

Duplicate Verification
- The system evaluates whether the document has already been processed.
- If a duplicate is detected, the document transitions directly to the DUPLICATED status.
- If no duplicate is found, processing continues to validation.
Validation Phase
- The document is validated against structural, syntactic, and business rules.
- If validation fails, the document transitions to the ERROR status (validation error).
- If validation succeeds, the document proceeds to processing.
Processing and Country Integration
- The document is transmitted to the corresponding country integration service.
- If the integration completes successfully, the document transitions to the OK status.
- If the integration fails, the document transitions to the ERROR status (integration error).

Terminal Statuses

A document lifecycle concludes in one of the following terminal statuses:

Status	Description
`PROCESSING`	The document was successfully validated and send to country connector
`OK`	The document was successfully validated, processed, and sended.
`ERROR`	The document failed during validation or external integration.
`DUPLICATED`	The document was identified as a duplicate and was not processed further.

These statuses represent stable and externally queryable states.

Internal Processing Phases

The lifecycle diagram may reference intermediate phases such as CREATED and VALIDATING.

It is important to clarify that:

CREATED represents the intake event of a document.
VALIDATING represents an internal evaluation phase.

These phases are internal processing representations and do not constitute persistent business states. They are not externally exposed nor stored as final document statuses.

Examples

UBL format

JSON format

Endpoints

Paginated list of documents

GET - /v1.1/documents

Retrieves a paginated list of documents that match the specified filtering criteria.

This endpoint allows clients to query documents using multiple filters, including document status, purpose, flow (issued or received), document number, company or supplier information, batch number, and several date ranges such as issue date, due date, submission date, or received date.
Filters may be combined to refine the search results according to business needs (for example, retrieving all issued invoices in OK status within a specific date range).

Results are returned in a paginated format to ensure efficient handling of large datasets.

Query Parameters

Required parameters

Name	Type	Required	Description
`countryIso`	string	Yes	Country code of the company in ISO 3166-1 alpha-2 format (e.g., `ES`).
`purpose`	string	Yes	Defines the purpose of the documents. Allowed values: `EINVOICING`, `EREPORTING`, `RETURNS`.
`flow`	string	Yes	Indicates whether the documents belong to the issued or received flow. Allowed values: `ISSUED`, `RECEIVED`.

Optional Filtering Parameters

Name	Type	Required	Description
`documentNumber`	string	No	Document number as defined in the client system (e.g., `A/1234`).
`issuedDateFrom`	string (`yyyy-MM-dd`)	No	Filters documents issued on or after the specified date.
`issuedDateTo`	string (`yyyy-MM-dd`)	No	Filters documents issued on or before the specified date.
`dueDateFrom`	string (`yyyy-MM-dd`)	No	Filters documents with a due date on or after the specified date.
`dueDateTo`	string (`yyyy-MM-dd`)	No	Filters documents with a due date on or before the specified date.
`submissionDateFrom`	string (`yyyy-MM-dd`)	No	Filters documents submitted on or after the specified date.
`submissionDateTo`	string (`yyyy-MM-dd`)	No	Filters documents submitted on or before the specified date.
`receivedDateFrom`	string (`yyyy-MM-dd`)	No	Filters documents received on or after the specified date.
`receivedDateTo`	string (`yyyy-MM-dd`)	No	Filters documents received on or before the specified date.
`status`	string	No	Filters documents by processing status. Allowed values: `CREATED`, `PROCESSING`, `OK`, `ERROR`, `DUPLICATED`.
`companyVatNumbers`	string	No	Comma-separated list of company VAT numbers.
`companyName`	string	No	Company name (e.g., `MAROSAVAT SLU`).
`batchNumber`	string	No	Batch identifier (UUID format).
`supplierName`	string	No	Supplier name.
`supplierVatNumber`	string	No	Supplier VAT number.

Pagination Parameters

Name	Type	Required	Default	Allowed Values	Description
`page`	integer	No	`0`	—	Zero-based page index.
`size`	integer	No	`20`	`20`, `50`, `100`, `500`	Number of records per page.

Get document by ID

GET - /v1.1/document

Retrieves a specific document by its unique identifier (documentId).

This endpoint allows clients to obtain the document in different representations depending on their needs.
The response format is determined by the required Accept header and may return the document in structured format (JSON or XML/UBL), as a human-readable PDF, or as a QR code image.

The document must belong to the specified country and purpose context. Access control validations are applied based on the provided parameters and the authentication token.

Query Parameters

Required parameters

Name	Type	Required	Description
`countryIso`	string	Yes	Country code of the company in ISO 3166-1 alpha-2 format (e.g., `ES`).
`purpose`	string	Yes	Purpose of the document. Allowed values: `EINVOICING`, `EREPORTING`, `RETURNS`.
`documentId`	string	Yes	Unique identifier of the document (UUID format).

Required Header

Name	Type	Required	Allowed Values
`Accept`	string	Yes	`application/json`, `application/xml`, `application/pdf`, `image/png`

The Accept header determines the format of the returned document:

application/json → Document in JSON format
application/xml → Document in XML/UBL format
application/pdf → Human-readable PDF representation
image/png → QR code image representation

Responses

Status	Description	Content-Type
`200`	Document successfully retrieved	Depends on `Accept` header
`400`	Invalid input parameters	Returns an `ApiError` object

A successful response returns the document as a binary or structured payload according to the requested format.

Example Request (JSON)

GET /v1.1/document?countryIso=ES&purpose=EINVOICING&documentId=f10d0b67-f10d-ce16-0d0b-ce16f10d0b67
Authorization: Bearer $ACCESS_TOKEN
Accept: application/json

Example Request (PDF)

  GET /v1.1/document?countryIso=ES&purpose=EINVOICING&documentId=f10d0b67-f10d-ce16-0d0b-ce16f10d0b67
  Authorization: Bearer $ACCESS_TOKEN
  Accept: application/pdf

Process document file

POST - /v1.1/document

Creates a new document by submitting its content in either JSON or UBL (XML) format.

This endpoint is used to initiate document processing within Marosa. After the request is accepted, the document is registered in the platform and continues through the corresponding processing workflow according to the selected country, purpose, and flow (issued or received).
The submitted payload is validated to ensure that the document is well-formed and complies with the API requirements. If validation succeeds, the API returns a response containing the newly created document reference and related metadata.

The optional period parameter may be provided when the document is relevant for a specific tax period (for example, in reporting or returns scenarios).

Query Parameters

Required parameters

Name	Type	Required	Description
`countryIso`	string	Yes	Country code of the company in ISO 3166-1 alpha-2 format (e.g., `ES`).
`vatNumber`	string	Yes	VAT number of the company (e.g., `B27835560`).
`purpose`	string	Yes	Defines the purpose of the document. Allowed values: `EINVOICING`, `EREPORTING`, `RETURNS`.
`flow`	string	Yes	Indicates whether the document belongs to the issued or received flow. Allowed values: `ISSUED`, `RECEIVED`.

Optional parameters

Name	Type	Required	Description
`period`	`TaxPeriod`	No	Tax relevance period of the document (e.g., `{ "from": "2025-01", "to": "2025-01" }`).

Request Body

The request body must contain the document content in one of the supported formats below.

Content-Type	Description	Schema
`application/json`	Document in JSON format	`CreateJsonDocumentRequest`
`application/xml`	Document in UBL (XML) format	One of: `InvoiceType`, `CreditNoteType`, `DebitNoteType`

Responses

Status	Description	Content-Type	Schema
`201`	Document created successfully	`application/json`	`DocumentResponse`
`400`	Invalid input	`application/json`	`ApiError`

Validate document (UBL 2.1)

POST - /v1.1/document/validate

Validates whether a document is compliant with the UBL 2.1 specification.

This endpoint is intended to help clients verify that an invoice document is structurally correct and conforms to the expected UBL 2.1 schema before it is submitted for processing.
The validation focuses on UBL compliance (structure and schema-level constraints). A successful validation response indicates that the document is well-formed and compatible with the UBL 2.1 format, reducing the likelihood of downstream processing errors.

The request body must contain the document in UBL (XML) format.

Request Body

Content-Type	Description	Supported Schemas
`application/xml`	Document in UBL 2.1 format	One of: `InvoiceType`, `CreditNoteType`, `DebitNoteType`

Responses

Status	Description	Content-Type	Schema
`200`	Document validated	`application/json`	`UBLValidationResult`

Convert document to PDF

POST - /v1.1/document/convert

Transforms a structured electronic document into a PDF file and returns the generated PDF synchronously (in the same response).

This endpoint is intended for scenarios where the client already has an invoice document in a supported e-invoicing format and needs a human-readable representation for archiving, sharing, or manual review.
The input document is provided as a file upload (multipart/form-data). The service validates the file format and content before conversion. If the input is valid, the resulting PDF is returned directly as application/pdf.

Supported input formats include UBL, CII, and ZUGFeRD.

Request

Required form-data fields

Name	Type	Required	Description
`file`	binary	Yes	Document file to be converted (UBL, CII, or ZUGFeRD).

Content-Type

The request must be sent using multipart/form-data.

Responses

Status	Description	Content-Type	Notes
`200`	PDF generated successfully	`application/pdf`	Returns the PDF as a binary payload.
`400`	Invalid file format or content	`application/json`	Returns an `ApiError` object.
`500`	Internal server error while processing the invoice	`application/json`	Returns an `ApiError` object.

Example Request

curl -X POST "<BASE_URL>/v1.1/document/convert" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: multipart/form-data" \
-F "[email protected]"

Example Response

A successful response returns a PDF file (application/pdf) as a binary payload.