Skip to main content
POST
cURL
Convert a GOBL Envelope or GOBL Invoice into an external format, such as UBL or CII, without storing anything. The response is the converted document itself, with its content type and file name set according to the format. Choose formats by their key from the conversion formats endpoint, filtered by direction=export. List several in order of preference and the first that accepts the document is used. The GOBL-Convert-Format response header names the format chosen. Use specific keys such as ubl+en16931-v2017 or ubl+peppol+bis-v3: generic keys such as ubl and cii are only used to recognise documents on import, and cannot be exported to. To export an invoice that is already stored, use export an entry instead.

JSON requests

Send the document in data, as with the other GOBL endpoints. Formats go in formats, or in the format query parameter. Any attachments to embed, such as a PDF copy of the invoice, are included with their contents base64 encoded:
The attachment id is used as the document reference in the exported file, such as a UBL or CII additional document reference. The mime type is detected from the data when omitted. JSON requests are limited to 8MB.

Multipart requests

For larger documents or attachments, send a multipart/form-data form instead, which is streamed and accepted up to 100MB. The first part must be named data and hold the GOBL JSON, followed by one attachment part per file. The format keys go in the format query parameter, escaping each + as %2B:
An attachment’s ID and description go in the standard Content-ID and Content-Description part headers, which are optional.

Authorizations

Authorization
string
header
required

Use the Bearer scheme with a valid JWT token to authenticate requests. Example: Authorization: Bearer <token>

Query Parameters

format
string[]

Key of the format to export to, as listed by /gobl/convert/formats. Repeat the parameter, or separate keys with commas, to offer several in order of preference: the first that accepts the document is used. Required unless given as formats in a JSON request.

Example:

Body

data
Data · object
required

GOBL Envelope or Object to export.

attachments
Attachments · object[]

Files to embed in the exported document.

formats
string[]

Keys of the formats to export to, in order of preference, after any given in the query: the first that accepts the document is used.

Example:

Response

200 - application/octet-stream

The exported document. Content type and disposition are set according to the format.

The response is of type file.