> ## Documentation Index
> Fetch the complete documentation index at: https://docs.invopop.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Export GOBL to a format

> Convert a GOBL Envelope or Object into an external format without persisting anything.
Send a JSON object with the GOBL document in "data", as with the other GOBL operations,
along with any attachments to embed, base64 encoded. JSON requests are limited to 8MB.
Larger documents and attachments may be sent instead as a multipart form, which is
streamed and accepted up to 100MB: its first part is named "data", followed by one
"attachment" file part per file. Each attachment part may set the standard "Content-ID"
and "Content-Description" MIME headers to provide the ID that identifies it in the
exported document, and its description; text that is not plain ASCII may use RFC 2047
encoded-words. Formats may be given in the query, or in a JSON request's "formats".
The response is the converted document as a raw download, with the key of the format
used in the "GOBL-Convert-Format" header.

Convert a [GOBL Envelope](https://docs.gobl.org/draft-0/envelope) or [GOBL Invoice](https://docs.gobl.org/draft-0/bill/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](https://docs.invopop.com/api-ref/silo/gobl/convert-formats.md) 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](https://docs.invopop.com/api-ref/silo/entries/export-an-entry.md) 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:

```json theme={"system"}
{
  "formats": ["ubl+peppol+bis-v3"],
  "data": {
    "$schema": "https://gobl.org/draft-0/bill/invoice",
    "...": "..."
  },
  "attachments": [
    {
      "id": "INV-1",
      "name": "invoice.pdf",
      "desc": "PDF copy of the invoice",
      "mime": "application/pdf",
      "data": "JVBERi0xLjcK..."
    }
  ]
}
```

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`:

```bash theme={"system"}
curl -X POST "https://api.invopop.com/silo/v1/gobl/convert/export?format=ubl%2Bpeppol%2Bbis-v3" \
  -H "Authorization: Bearer $INVOPOP_TOKEN" \
  -F "data=@invoice.json;type=application/json" \
  -F "attachment=@invoice.pdf;type=application/pdf;headers=\"Content-ID: INV-1\";headers=\"Content-Description: PDF copy of the invoice\"" \
  -o invoice.xml
```

An attachment's ID and description go in the standard `Content-ID` and `Content-Description` part headers, which are optional.


## OpenAPI

````yaml POST /silo/v1/gobl/convert/export
openapi: 3.0.0
info:
  contact:
    email: dev@invopop.com
    name: Invopop Developers
  description: >-
    Store and manage GOBL documents along with their attachments in "Silo
    Entries".
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: Silo Service API
  version: 1.0.0
servers:
  - description: production
    url: https://api.invopop.com
security:
  - authToken: []
paths:
  /silo/v1/gobl/convert/export:
    post:
      description: >-
        Convert a GOBL Envelope or Object into an external format without
        persisting anything.

        Send a JSON object with the GOBL document in "data", as with the other
        GOBL operations,

        along with any attachments to embed, base64 encoded. JSON requests are
        limited to 8MB.

        Larger documents and attachments may be sent instead as a multipart
        form, which is

        streamed and accepted up to 100MB: its first part is named "data",
        followed by one

        "attachment" file part per file. Each attachment part may set the
        standard "Content-ID"

        and "Content-Description" MIME headers to provide the ID that identifies
        it in the

        exported document, and its description; text that is not plain ASCII may
        use RFC 2047

        encoded-words. Formats may be given in the query, or in a JSON request's
        "formats".

        The response is the converted document as a raw download, with the key
        of the format

        used in the "GOBL-Convert-Format" header.
      parameters:
        - description: >-
            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.
          in: query
          name: format
          schema:
            description: >-
              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:
              - ubl+peppol+bis-v3
            items:
              type: string
            title: Format
            type: array
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SiloExportGOBL'
          multipart/form-data:
            schema:
              properties:
                attachment:
                  description: >-
                    Files to embed in the exported document, each with a file
                    name, and optionally Content-ID and Content-Description part
                    headers.
                  items:
                    $ref: '#/components/schemas/MultipartFileHeader'
                  type: array
                data:
                  $ref: '#/components/schemas/MultipartFileHeader'
              required:
                - data
              type: object
      responses:
        '200':
          content:
            application/octet-stream:
              schema:
                format: binary
                type: string
          description: >-
            The exported document. Content type and disposition are set
            according to the format.
components:
  schemas:
    SiloExportGOBL:
      properties:
        attachments:
          description: Files to embed in the exported document.
          items:
            $ref: '#/components/schemas/SiloExportAttachment'
          title: Attachments
          type: array
        data:
          description: GOBL Envelope or Object to export.
          title: Data
          type: object
        formats:
          description: >-
            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:
            - ubl+peppol+bis-v3
          items:
            type: string
          title: Formats
          type: array
      required:
        - data
      type: object
    MultipartFileHeader:
      format: binary
      type: string
    SiloExportAttachment:
      properties:
        data:
          $ref: '#/components/schemas/SiloBase64'
        desc:
          description: Description of the file.
          example: Payment receipt
          title: Description
          type: string
        id:
          description: >-
            Identifies the attachment in the exported document, such as the
            reference of a UBL or CII additional document.
          example: REC-1
          title: ID
          type: string
        mime:
          description: MIME type of the file, detected from the data when omitted.
          example: application/pdf
          title: MIME
          type: string
        name:
          description: Name of the file.
          example: receipt.pdf
          title: Name
          type: string
      required:
        - name
        - data
      type: object
    SiloBase64:
      description: Base64 encoded binary data.
      format: byte
      type: string
  securitySchemes:
    authToken:
      bearerFormat: JWT
      description: >-
        Use the `Bearer` scheme with a valid JWT token to authenticate requests.
        Example: `Authorization: Bearer <token>`
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.