Multipart Upload

Uploads a document using a multipart request. This endpoint supports three upload flows:

	Flow A1 — XML + separate files	Flow A2 — self-contained XML	Flow B — ZUGFeRD / Factur-X PDF
`document`	`application/xml`	`application/xml` (image & attachments embedded as Base64)	`application/pdf` (PDF/A-3 with embedded XML)
`image`	required	must not be provided	must not be provided
`attachment`	optional	must not be provided	must not be provided

Flow A1 — The classic flow. Supply the invoice XML, a separate PDF image, and any optional attachment files as individual multipart parts.

Flow A2 — A self-contained variant. Supply only the XML; the PDF image and any attachments are Base64-encoded and embedded directly inside the XML document. No separate image or attachment parts are needed or accepted.

Flow B — For ZUGFeRD and Factur-X invoices. The invoice is a PDF/A-3 file that contains the XML embedded inside. All content is contained within the single PDF — no separate image or attachment parts are accepted.

Endpoint

Method: - POST
Path: /v3/documents/{documentType}/{direction}/multipart

Full URLs

Test: https://apitest.4exchange.app/v3/documents/{documentType}/{direction}/multipart
Production: https://api.4exchange.app/v3/documents/{documentType}/{direction}/multipart

Request

Request size limit

The maximum request size is 6 MB (after Base64 encoding and headers). Requests over this limit are rejected with 413 - Request Entity Too Large response.

Encoding requirement

Please ensure that the XML document is UTF-8 encoded for correct handling.

Path parameters

documentType (string, required): Type of document, allowed values are: invoice, applicationresponse, ereport
direction (string, required): Direction of document, allowed values are: send or receive.

Example: POST /v3/documents/invoice/send/multipart

Headers

Authorization: Bearer token (requires 4Exchange/send scope).
Content-Type: multipart/form-data
documentId (string, optional): Client-provided identifier for tracking. Any non-empty string; does not need to be a UUID. If omitted, the system generates one.

Multipart form fields

document — required in all flows

Content-Type: application/xml (Flow A1, A2) or application/pdf (Flow B)
The invoice document. See flow details below.

image — Flow A1 only

Content-Type: application/pdf
The PDF rendering of the invoice. Required in Flow A1. Must not be provided in Flow A2 or Flow B.

attachment — Flow A1 only, optional

Content-Type: application/pdf, image/png, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, etc.
Additional files. Multiple entries are accepted. Must not be provided in Flow A2 or Flow B.

Upload flows

Flow A1 — XML with separate image and attachments

Use this flow when you have a standalone XML invoice, a separate PDF rendering, and optionally additional attachment files to upload as separate multipart parts.

document: the XML invoice file (application/xml), required.
image: the PDF rendering of the invoice (application/pdf), required.
attachment: additional files, optional. Multiple entries are accepted.

POST /v3/documents/invoice/send/multipart HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="document"; filename="invoice.xml"
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<Invoice>
    <cbc:ID>123</cbc:ID>
    <cbc:IssueDate>2025-02-28</cbc:IssueDate>
    .......
    <cac:LegalMonetaryTotal>
        <cbc:LineExtensionAmount currencyID="EUR">100.00</cbc:LineExtensionAmount>
        <cbc:TaxExclusiveAmount currencyID="EUR">100.00</cbc:TaxExclusiveAmount>
        <cbc:TaxInclusiveAmount currencyID="EUR">121.00</cbc:TaxInclusiveAmount>
        <cbc:PayableAmount currencyID="EUR">121.00</cbc:PayableAmount>
    </cac:LegalMonetaryTotal>
</Invoice>
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="image"; filename="invoice.pdf"
Content-Type: application/pdf

(binary content of invoice.pdf)
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="attachment"; filename="supporting-document.pdf"
Content-Type: application/pdf

(binary content of supporting-document.pdf)
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Flow A2 — Self-contained XML (image and attachments embedded)

Use this flow when the PDF image and any attachments are Base64-encoded and embedded directly inside the XML document. Only the document part is uploaded; no separate image or attachment multipart parts are accepted.

document: the XML invoice file (application/xml), required. Must contain the PDF image and any attachments as Base64-encoded elements within the XML structure.
image: must not be provided.
attachment: must not be provided.

POST /v3/documents/invoice/send/multipart HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="document"; filename="invoice.xml"
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<Invoice>
  <Details>...</Details>
  <EmbeddedPDF encoding="Base64">JVBERi0xLjQK...</EmbeddedPDF>
  <Attachment filename="annex.pdf" encoding="Base64">JVBERi0xLjQK...</Attachment>
</Invoice>

<?xml version="1.0" encoding="utf-8"?>
<Invoice>
    <cbc:ID>123</cbc:ID>
    <cbc:IssueDate>2025-02-28</cbc:IssueDate>
    <cac:AdditionalDocumentReference>
      <cbc:ID>123</cbc:ID>
      <cac:Attachment>
        <cbc:EmbeddedDocumentBinaryObject mimeCode="application/pdf" filename="123.pdf">
          JVBERi0xLjQK...
        </cbc:EmbeddedDocumentBinaryObject>
      </cac:Attachment>
    </cac:AdditionalDocumentReference>
    .......
    <cac:LegalMonetaryTotal>
        <cbc:LineExtensionAmount currencyID="EUR">100.00</cbc:LineExtensionAmount>
        <cbc:TaxExclusiveAmount currencyID="EUR">100.00</cbc:TaxExclusiveAmount>
        <cbc:TaxInclusiveAmount currencyID="EUR">121.00</cbc:TaxInclusiveAmount>
        <cbc:PayableAmount currencyID="EUR">121.00</cbc:PayableAmount>
    </cac:LegalMonetaryTotal>
</Invoice>
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Flow B — ZUGFeRD / Factur-X PDF

Use this flow when your invoice is a PDF/A-3 file with an embedded XML payload (ZUGFeRD or Factur-X format). The PDF is the single self-contained document — all content is inside it. No separate image or attachment parts are accepted.

document: the PDF/A-3 invoice file (application/pdf), required. Must contain the embedded XML.
image: must not be provided.
attachment: must not be provided.

The service will:

Validate that the PDF is parseable and contains a valid embedded XML payload.
Extract the embedded XML from the PDF.
Store the original PDF as the primary document representation.
Use the extracted XML as the canonical invoice payload for processing and validation.
Continue with the same processing pipeline as a standard XML invoice.

POST /v3/documents/invoice/send/multipart HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="document"; filename="invoice-zugferd.pdf"
Content-Type: application/pdf

(binary content of ZUGFeRD/Factur-X PDF/A-3 file)
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Responses

200 OK

{
    "message": "Successfully received the document",
    "documentId": "8e6e870e-854b-46ef-a4d5-dfe5a5799cf8"
}

400 Bad Request

Returned when the request is malformed or the combination of fields is invalid. The response body contains an error field with a message describing the problem.

Error message	Cause
`Content-Type must be multipart/form-data`	The `Content-Type` header does not contain `multipart/form-data`.
`Invalid direction: {x}. Must be "send" or "receive"`	The `direction` path parameter is not `send` or `receive`.
`Failed to parse multipart request: {details}`	The request body cannot be decoded as valid multipart/form-data (e.g. missing or corrupt boundary).
`document field is required`	No `document` field found in the multipart body.
`Only one document file is allowed`	More than one `document` field is present.
`XML parsing failed: {details}`	The `document` field contains syntactically invalid XML.
`image field is required`	Flow A1: no `image` field found alongside the XML document.
`Only one image file is allowed, please mark others as attachment`	More than one `image` field is present.
`{Image\|Attachment} filename is required` / `{Image\|Attachment} content is missing or invalid`	An uploaded file is missing its filename or has empty content.
`Filenames need to be unique`	Two or more uploaded files share the same filename (case-insensitive).
`image field must not be provided when document is a PDF. …`	Flow B: an `image` field was included alongside a PDF document.
`attachment fields must not be provided when document is a PDF. …`	Flow B: `attachment` fields were sent — they must be embedded inside the PDF instead.

{
    "Error": "image field must not be provided when document is a PDF. For ZUGFeRD/Factur-X uploads the PDF is the primary document; the XML is extracted automatically."
}

401 Unauthorized

{
    "message": "Unauthorized"
}

413 Request Entity Too Large

{
    "message": "Request Too Long"
}

422 Unprocessable Entity

Returned when the Flow B PDF document cannot be processed. The response body contains an error field with a message from the extractor.

Cause	Description
PDF contains no embedded XML	The uploaded PDF is valid but has no embedded XML invoice attachment.
PDF cannot be parsed or XML is corrupt	The PDF cannot be parsed at all, or the embedded XML content is corrupt or not valid XML.

{
    "Error": "No XML invoice attachment found in the PDF."
}