Embed a generated e-invoice XML into YOUR carrier PDF

curl -X POST https://service.invoice-api.xhub.io/api/v1/invoice/DE/facturx/embed \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "pdf": "JVBERi0xLjcKJeLjz9MK...",
  "invoice": {
    "invoiceNumber": "INV-2026-0042",
    "type": "invoice",
    "issueDate": "2026-03-20",
    "seller": {
      "name": "Muster GmbH",
      "countryCode": "DE"
    },
    "buyer": {
      "name": "Muster GmbH",
      "countryCode": "DE"
    },
    "items": [
      {
        "description": "Software Development Services — March 2026",
        "quantity": 40,
        "unit": "HUR",
        "unitPrice": 120,
        "netAmount": 4800,
        "taxAmount": 912
      }
    ],
    "currency": "EUR",
    "subtotal": 4800,
    "total": 5712,
    "taxSummary": [
      {
        "netAmount": 4800,
        "taxAmount": 912
      }
    ]
  }
}'

{
  "success": true,
  "format": "zugferd",
  "filename": "INV-2026-0042_zugferd.pdf",
  "mimeType": "application/pdf",
  "hash": "a1b2c3d4e5f6...",
  "data": "JVBERi0xLjcKJeLjz9MK...",
  "payloadHash": "3d80b2995c1f...",
  "embeddedXml": "embeddedXml",
  "carrier": {
    "pdfA3Declared": true,
    "checks": [
      {
        "code": "PDF-001",
        "severity": "warning",
        "passed": true
      }
    ],
    "warnings": [
      {
        "code": "CARRIER_FONTS_NOT_EMBEDDED",
        "message": "message"
      }
    ]
  },
  "validation": {
    "valid": false,
    "results": [
      {
        "format": "zugferd-2.4-en16931",
        "valid": null,
        "errors": [
          {
            "ruleId": "BR-DE-6",
            "message": "message"
          }
        ],
        "skipped": "not entitled"
      }
    ],
    "status": "passed",
    "errors": [
      {
        "code": "BR-O-08",
        "message": "message"
      }
    ],
    "reason": "missing"
  },
  "appliedFormatOptions": {
    "version": "1.0",
    "profile": "MINIMUM"
  },
  "errors": [
    {
      "code": "DE_AC_001",
      "message": "message",
      "rule": "rule",
      "field": "field"
    }
  ],
  "complianceErrors": [
    {
      "code": "DE_AC_001",
      "message": "message",
      "rule": "rule",
      "field": "field"
    }
  ],
  "warnings": [
    {
      "code": "DE_AC_001",
      "message": "message",
      "rule": "rule",
      "field": "field"
    }
  ]
}

Takes your finished invoice PDF plus the invoice data and returns that same PDF with the generated CII XML embedded — PDF/A-3 marker, AFRelationship=Alternative, factur-x.xml. Same invoice data, same validation chain and same entitlement as /{countryCode}/{format}/generate; only the visual page comes from you instead of from a template.

Available for the hybrid formats only — DE/zugferd, CH/zugferd, FR/facturx, BE/facturx. An XML-only format (xrechnung, ubl, …) or plain pdf returns a 400.

🔴 No template here: templateId and formatOptions.template do not exist on this route — the request body is strict and rejects them with a 400 rather than ignoring them.

⚪ PDF/A-3 is declared, not converted. The marker is set on the carrier you sent; the carrier itself is not rewritten. What we actually measured is reported in the carrier block — including CARRIER_FONTS_NOT_EMBEDDED when your PDF uses fonts without an embedded font file. Nothing is rejected because of it; a full PDF/A-3b proof (veraPDF) does not take place.

Takes your finished invoice PDF plus the invoice data and returns **that same PDF** with the generated CII XML embedded — PDF/A-3 marker, `AFRelationship=Alternative`, `factur-x.xml`. Same invoice data, same validation chain and same entitlement as `/{countryCode}/{format}/generate`; only the visual page comes from you instead of from a template. Available for the hybrid formats only — `DE/zugferd`, `CH/zugferd`, `FR/facturx`, `BE/facturx`. An XML-only format (`xrechnung`, `ubl`, …) or plain `pdf` returns a 400. 🔴 **No template here**: `templateId` and `formatOptions.template` do not exist on this route — the request body is strict and rejects them with a 400 rather than ignoring them. ⚪ **PDF/A-3 is declared, not converted.** The marker is set on the carrier you sent; the carrier itself is not rewritten. What we actually measured is reported in the `carrier` block — including `CARRIER_FONTS_NOT_EMBEDDED` when your PDF uses fonts without an embedded font file. Nothing is rejected because of it; a full PDF/A-3b proof (veraPDF) does not take place.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

countryCodeenumRequired

Country of the hybrid format (DE, CH, FR, BE)

Allowed values:

formatenumRequired

Hybrid format token

Allowed values:

Request

This endpoint expects an object.

pdfstringRequired>=1 character

Base64-encoded carrier PDF — your layout. It becomes the visual page of the hybrid document; the generated CII XML is embedded into it as factur-x.xml (AFRelationship=Alternative). PDF/A-3 is declared, not converted — the marker is set on the carrier you sent, the carrier itself is not rewritten. What we actually measured is reported in carrier; nothing is rejected because of it. A full PDF/A-3b proof (veraPDF) does not take place.

Base64-encoded carrier PDF — **your** layout. It becomes the visual page of the hybrid document; the generated CII XML is embedded into it as `factur-x.xml` (AFRelationship=Alternative). PDF/A-3 is **declared, not converted** — the marker is set on the carrier you sent, the carrier itself is not rewritten. What we actually measured is reported in `carrier`; nothing is rejected because of it. A full PDF/A-3b proof (veraPDF) does not take place.

invoiceobjectRequired

Invoice data the embedded XML is generated from — the same shape as /{countryCode}/{format}/generate.

validatebooleanOptional

Run the same XSD + Schematron check as /validate on the generated XML and return the verdict in an additional validation block. This call then counts as 2 units on the format’s create entitlement — same rule as /generate. The block is fed from the self-check of the same run, with status: 'not_run' and a reason when the check did not run completely.

Run the same XSD + Schematron check as `/validate` on the generated XML and return the verdict in an additional `validation` block. **This call then counts as 2 units** on the format's `create` entitlement — same rule as `/generate`. The block is fed from the self-check of the same run, with `status: 'not_run'` and a `reason` when the check did not run completely.

formatOptionsobjectOptional

🔴 No template here. Unlike /generate this object is strict and carries only profile and version: the visual page comes from YOUR pdf, so template and templateId have nothing to select. Sending either returns a 400 rather than being silently ignored.

🔴 **No template here.** Unlike `/generate` this object is strict and carries only `profile` and `version`: the visual page comes from YOUR `pdf`, so `template` and `templateId` have nothing to select. Sending either returns a 400 rather than being silently ignored.

Response

Hybrid document produced — YOUR layout carrying the generated XML. The carrier block reports what we measured on it.

successboolean

Whether the hybrid document was produced

formatstring

Output format used

filenamestring

Suggested filename

mimeTypestring

MIME type

hashstring

Hex-encoded SHA-256 of the returned document bytes. Not stable across calls (the PDF carries a creation timestamp); use payloadHash for idempotent names.

datastring

Base64-encoded hybrid PDF: YOUR layout with the generated XML embedded

payloadHashstringOptional

Hex-encoded SHA-256 of the canonical JSON of the invoice you sent.

embeddedXmlstringOptional

The CII XML that was embedded, for convenient inspection

carrierobjectOptional

What we measured on the document we produced from your carrier

validationobjectOptional

Spec-conformance verdict — present only when the request set validate: true.

appliedFormatOptionsobjectOptional

The ZUGFeRD / Factur-X version and profile the document was actually written in — the requested ones, or the defaults (2.4 / 1.08, EN16931) when none was sent. Absent for formats without a version selector (XRechnung, UBL, …).

errorslist of objectsOptional

Generation errors (if any)

complianceErrorslist of objectsOptional

Spec violations found in the generated XML (422)

warningslist of objectsOptional

Generation warnings (if any). SELF_CHECK_INCOMPLETE means a rulebook of our conformance self-check could not be applied: the document was not fully checked against it.

Errors

400

Embed Invoices Request Bad Request Error

401

Embed Invoices Request Unauthorized Error

403

Embed Invoices Request Forbidden Error

413

Embed Invoices Request Content Too Large Error

422

Embed Invoices Request Unprocessable Entity Error

429

Embed Invoices Request Too Many Requests Error

500

Embed Invoices Request Internal Server Error

Available for the hybrid formats only — DE/zugferd, CH/zugferd, FR/facturx, BE/facturx. An XML-only format (xrechnung, ubl, …) or plain pdf returns a 400.

🔴 No template here: templateId and formatOptions.template do not exist on this route — the request body is strict and rejects them with a 400 rather than ignoring them.