# zugferd.create

> Embed a ZUGFeRD / Factur-X invoice in a PDF.

> Coming soon. The hosted API is not live yet, and this page describes the planned service as of 16 November 2026. [Get notified](https://pdfluent.com/contact/?topic=hosted) when it opens.

Source: https://pdfluent.com/docs/api/reference/zugferd-create/

Embed a ZUGFeRD / Factur-X invoice in a PDF.

`POST /v1/zugferd/create`

| | |
|---|---|
| Input | one file, sent as `multipart/form-data`; the optional `options` part is a JSON object |
| Output | one PDF |
| Credits | [credit rate: no claim ID yet] |
| Limits | [size, page and time limits: no claim ID yet] |
| Reads or changes the document | returns a changed copy |
| Error statuses | 400, 413, 422, 500, 501, 504 (see [Errors](https://pdfluent.com/docs/api/errors/)) |

## Options

| Option | Type | Required | Default | Description |
|---|---|---|---|---|
| `invoice` | any | yes |  | The invoice: profile (`Minimum`, `BasicWL`, `Basic`, `EN16931`, `Extended`), invoice_number, type_code, issue_date (YYYY-MM-DD), seller and buyer (name, address, tax_id), line_items, currency, the totals and the optional payment fields, as in the SDK's `ZugferdInvoice`. |
| `password` | string | no |  | Password of an encrypted document. |
| `pdfa3` | boolean | no | `true` | Convert the document to PDF/A-3b first, as the e-invoicing standards require. Default true. |

## Example

### curl

```sh
curl -sS -f -X POST "$PDFLUENT_API_URL/v1/zugferd/create" \
  -H "x-api-key: $PDFLUENT_API_KEY" \
  -F file=@structured.pdf \
  -F 'options={"pdfa3":false,"invoice":{"profile":"Minimum","invoice_number":"INV-1","type_code":"380","issue_date":"2026-11-13","seller":{"name":"Seller B.V.","address":{"country_code":"NL"}},"buyer":{"name":"Buyer B.V.","address":{"country_code":"NL"}},"line_items":[],"currency":"EUR","tax_basis_total":100,"tax_total":21,"grand_total":121,"due_payable":121,"charge_total":0,"allowance_total":0}}' \
  -o result.pdf
```

### Python

```python
import json
import os

import requests

options = {"pdfa3": False, "invoice": {"profile": "Minimum", "invoice_number": "INV-1", "type_code": "380", "issue_date": "2026-11-13", "seller": {"name": "Seller B.V.", "address": {"country_code": "NL"}}, "buyer": {"name": "Buyer B.V.", "address": {"country_code": "NL"}}, "line_items": [], "currency": "EUR", "tax_basis_total": 100, "tax_total": 21, "grand_total": 121, "due_payable": 121, "charge_total": 0, "allowance_total": 0}}

parts = [
    ("file", ("structured.pdf", open("structured.pdf", "rb"))),
    ("options", (None, json.dumps(options))),
]

response = requests.post(
    os.environ["PDFLUENT_API_URL"] + "/v1/zugferd/create",
    headers={"x-api-key": os.environ["PDFLUENT_API_KEY"]},
    files=parts,
)
response.raise_for_status()

with open("result.pdf", "wb") as out:
    out.write(response.content)
```

### Node.js

```js
import { openAsBlob } from 'node:fs';
import { writeFile } from 'node:fs/promises';

const form = new FormData();
form.append('file', await openAsBlob("structured.pdf"), "structured.pdf");
form.append('options', JSON.stringify({"pdfa3":false,"invoice":{"profile":"Minimum","invoice_number":"INV-1","type_code":"380","issue_date":"2026-11-13","seller":{"name":"Seller B.V.","address":{"country_code":"NL"}},"buyer":{"name":"Buyer B.V.","address":{"country_code":"NL"}},"line_items":[],"currency":"EUR","tax_basis_total":100,"tax_total":21,"grand_total":121,"due_payable":121,"charge_total":0,"allowance_total":0}}));

const response = await fetch(process.env.PDFLUENT_API_URL + "/v1/zugferd/create", {
  method: 'POST',
  headers: { 'x-api-key': process.env.PDFLUENT_API_KEY },
  body: form,
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);

await writeFile("result.pdf", Buffer.from(await response.arrayBuffer()));
```

The key goes in the `x-api-key` header; see [Authentication](https://pdfluent.com/docs/api/authentication/). Every response carries `x-pdfluent-pages` and `x-pdfluent-credits`.
