E-invoice API

Status: Public API contract. Last updated: 2026-06-20T14:32:32-07:00

POST /api/v1/e-invoice/render produces a PDF/A-3b document with a CII XML attachment, packaged according to the Factur-X or ZUGFeRD standard.

There are four endpoints in this family:

Endpoint	Auth	Purpose
`GET /api/v1/e-invoice/capabilities`	None	Static capability registry.
`POST /api/v1/e-invoice/render`	Required	Render. Returns either inline PDF or a job descriptor.
`GET /api/v1/e-invoice/jobs/{job_id}`	Required	Poll an object-mode job.
`GET /api/v1/e-invoice/jobs/{job_id}/artifacts/{artifact}`	Required	Download a job artifact.

For the underlying DocumentRequest shape (pages, elements, fonts), see the JSON Render API reference. Token / quota / 4xx codes shared across endpoints live in the same document’s §6.

1. Capabilities

GET /api/v1/e-invoice/capabilities returns the static product capability registry. Authentication is not required — this advertises what the platform supports, not what your token is allowed to do. Per-token authorisation is checked at render time.

Property	Value
Method	`GET`
Path	`/api/v1/e-invoice/capabilities`
Auth	None
Response	`200`, `Content-Type: application/json`

curl "https://api.gpdf.com/api/v1/e-invoice/capabilities"

Sample response:

{
  "schema_version": 1,
  "package": "pdfa3_embedded_xml",
  "pdfa_profile": "pdfa-3b",
  "standards": [
    {
      "standard": "factur_x",
      "standard_id": "factur_x",
      "name": "Factur-X",
      "profile": "en16931",
      "document_type": "invoice",
      "xml_format": "cii",
      "embedded_file_name": "factur-x.xml"
    },
    {
      "standard": "zugferd",
      "standard_id": "zugferd",
      "name": "ZUGFeRD",
      "profile": "en16931",
      "document_type": "invoice",
      "xml_format": "cii",
      "embedded_file_name": "zugferd-invoice.xml"
    }
  ],
  "delivery_modes": ["inline_pdf", "object"],
  "data_residency_modes": ["auto", "eu", "global"]
}

2. Render

Property	Value
Method	`POST`
Path	`/api/v1/e-invoice/render`
Auth	Required — `Authorization: Bearer YOUR_TOKEN`
Request `Content-Type`	`application/json`
Success (`inline_pdf`)	`200`, `Content-Type: application/pdf`
Success (`object`)	`200`, `Content-Type: application/json` (job descriptor; see §5)

The request body is a DocumentRequest (same shape as JSON Render) plus a required settings.e_invoice block. The PDF/A profile is fixed:

If settings.profile is omitted or empty, gPdf uses pdfa-3b.
If settings.profile is set, it must be pdfa-3b. Anything else returns API-002.
Sending settings.e_invoice to POST /api/v1/pdf/render returns API-002 — the field is route-specific.

Minimum request:

{
  "settings": {
    "profile": "pdfa-3b",
    "e_invoice": {
      "standard": "factur_x",
      "profile": "en16931",
      "document_type": "invoice",
      "xml": {
        "format": "cii",
        "encoding": "utf8",
        "content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>"
      }
    }
  },
  "pages": [
    { "size": "a4", "elements": [] }
  ]
}

curl -X POST "https://api.gpdf.com/api/v1/e-invoice/render" \
  -H "Authorization: Bearer $GPDF_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @einvoice.json \
  --output invoice.pdf

3. `settings.e_invoice` fields

{
  "standard": "factur_x",
  "profile": "en16931",
  "document_type": "invoice",
  "xml": {
    "format": "cii",
    "encoding": "utf8",
    "content": "<?xml version=\"1.0\" ... ?>"
  },
  "validation": {
    "level": "basic",
    "execution": "sync",
    "fail_on_warnings": false
  },
  "delivery": {
    "mode": "inline_pdf",
    "url_ttl_seconds": 900
  },
  "report": {
    "enabled": false
  },
  "retention": {
    "ttl_hours": 23,
    "store_request": false
  },
  "data_residency": {
    "mode": "auto",
    "country": "DE",
    "strict": false
  },
  "job_id": "0190f0e8-2b8a-7ad4-9b3e-1234567890ab"
}

Top-level fields:

Field	Type	Required	Notes
`standard`	`"factur_x" \| "zugferd"`	Yes	Envelope standard.
`profile`	`"en16931"`	Yes	Semantic profile. Currently `en16931` only.
`document_type`	`"invoice"`	Yes	Currently invoice only.
`xml`	`EInvoiceXmlPayload`	Yes	The CII XML payload.
`validation`	`EInvoiceValidationSettings`	No	Validation policy. Default basic + sync.
`delivery`	`EInvoiceDeliverySettings`	No	Response shape. Default `inline_pdf`.
`report`	`EInvoiceReportSettings`	No	Whether to produce a validation report artifact.
`retention`	`EInvoiceRetentionSettings`	No	Retention for object-mode artifacts.
`data_residency`	`EInvoiceDataResidencySettings`	No	Storage residency profile.
`job_id`	`string`	No	Idempotency ID for object delivery. UUID v7 recommended.

3.1 `EInvoiceXmlPayload`

Field	Type	Required	Notes
`format`	`"cii"`	Yes	Currently CII only.
`encoding`	`"utf8"`	No	Default `utf8`.
`content`	`string`	Yes	UTF-8 XML content. Non-empty. Max `2 MiB`.

xml.content is checked for basic structural sanity. Full EN 16931 Schematron is not run on the inline path; request strict validation via validation.level = "strict" to schedule full checking.

3.2 `EInvoiceValidationSettings`

Field	Type	Default	Notes
`level`	`"basic" \| "strict"`	`basic`	`basic` = lightweight request-level checks. `strict` = full third-party validation.
`execution`	`"sync" \| "async"`	`sync`	`async` requires `level = strict` and `delivery.mode = object`.
`fail_on_warnings`	`boolean`	`false`	When `true`, any warning in the strict report fails the job.

Rules:

level = strict requires delivery.mode = object. Strict validation does not return inline.
execution = async requires level = strict and delivery.mode = object. The job is queued and updated when validation completes.

3.3 `EInvoiceDeliverySettings`

Field	Type	Default	Notes
`mode`	`"inline_pdf" \| "object"`	`inline_pdf`	`inline_pdf` returns PDF bytes inline. `object` returns JSON + stores artifacts retrievable via the job API.
`url_ttl_seconds`	`integer`	`900`	Range `1..900`. TTL of artifact download URLs.

When mode = inline_pdf:

The render endpoint returns application/pdf immediately.
No job is created.
No artifacts are stored.

When mode = object:

The render endpoint returns application/json describing the job (see §5).
Artifacts are accessible via the artifact API (see §6) until they expire.

3.4 `EInvoiceReportSettings`

Field	Type	Default	Notes
`enabled`	`boolean`	`false`	When `true`, produces a `report.json` artifact alongside the PDF/XML. Requires `delivery.mode = object`.

The report is produced asynchronously by the validator. It is added to the job’s artifacts once available. Until then artifacts.report.available = false.

3.5 `EInvoiceRetentionSettings`

Field	Type	Default	Notes
`ttl_hours`	`integer`	`23`	Range `1..23`. Retention for object-mode artifacts and job metadata.
`store_request`	`boolean`	`false`	When `true`, the original request body is also stored as an artifact.

After ttl_hours elapses, artifact downloads return 404 and the job lookup returns metadata only (no usable artifact URLs).

3.6 `EInvoiceDataResidencySettings`

Field	Type	Default	Notes
`mode`	`"auto" \| "eu" \| "global"`	`auto`	Storage residency profile for artifacts and job metadata.
`country`	`string`	—	ISO 3166-1 alpha-2 country code. Used by `auto` and `strict` mode.
`strict`	`boolean`	`false`	When `true` and the country cannot be resolved to a residency profile, returns `API-002`.

Behaviour:

auto resolves residency from country (e.g. DE → eu, US → global).
eu forces EU residency regardless of country.
global forces global residency.
strict = true makes ambiguous or missing country a hard error rather than a fallback.

4. Standard mapping

`standard`	Embedded file	XMP namespace	XMP version	XMP conformance	XMP document type	AFRelationship
`factur_x`	`factur-x.xml`	`urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0#`	`1.0`	`EN 16931`	`INVOICE`	`Alternative`
`zugferd`	`zugferd-invoice.xml`	`urn:zugferd:pdfa:CrossIndustryDocument:invoice:2p0#`	`2p0`	`EN 16931`	`INVOICE`	`Alternative`

Both standards embed CII XML conforming to EN 16931 and use the Alternative AFRelationship per the Factur-X / ZUGFeRD baseline.

5. Job lookup

GET /api/v1/e-invoice/jobs/{job_id} returns the current state of an object-mode job, including artifact URLs.

Property	Value
Method	`GET`
Path	`/api/v1/e-invoice/jobs/{job_id}`
Auth	Required — same token that created the job.
Response	`200`, `Content-Type: application/json`

curl "https://api.gpdf.com/api/v1/e-invoice/jobs/$JOB_ID" \
  -H "Authorization: Bearer $GPDF_TOKEN"

Sample response:

{
  "job_id": "0190f0e8-2b8a-7ad4-9b3e-1234567890ab",
  "status": "completed",
  "delivery": "object",
  "data_residency": "eu",
  "created_at_ms": "1715140800000",
  "expires_at_ms": "1715223600000",
  "artifacts": {
    "pdf": {
      "available": true,
      "content_type": "application/pdf",
      "bytes": 184231,
      "expires_at_ms": "1715141700000",
      "url": "https://api.gpdf.com/api/v1/e-invoice/jobs/0190f0.../artifacts/pdf"
    },
    "xml": {
      "available": true,
      "content_type": "application/xml",
      "bytes": 8421,
      "expires_at_ms": "1715141700000",
      "url": "https://api.gpdf.com/api/v1/e-invoice/jobs/0190f0.../artifacts/xml"
    },
    "report": {
      "available": false,
      "content_type": "application/json",
      "bytes": 0,
      "expires_at_ms": "1715141700000",
      "url": "https://api.gpdf.com/api/v1/e-invoice/jobs/0190f0.../artifacts/report"
    }
  },
  "validation": {
    "level": "strict",
    "execution": "async",
    "status": "pending",
    "report_requested": true
  }
}

Field	Type	Notes
`job_id`	`string`	Echoes the request’s `job_id` if supplied; otherwise generated.
`status`	`string`	`pending`, `completed`, `failed`.
`delivery`	`string`	`object` (this endpoint only exists for object jobs).
`data_residency`	`string`	`eu` or `global`.
`created_at_ms`, `expires_at_ms`	`string`	Unix milliseconds as decimal strings.
`artifacts`	object	Per-artifact descriptor. Each entry has `available`, `content_type`, `bytes`, `expires_at_ms`, `url`.
`artifacts.pdf`	object	The signed PDF/A-3b. Always present.
`artifacts.xml`	object	The embedded CII XML, also exposed as a separate artifact. Always present.
`artifacts.request`	object (optional)	Original request body. Present only when `retention.store_request = true`.
`artifacts.report`	object (optional)	Validation report. Present only when `report.enabled = true`.
`validation.status`	`string`	`pending`, `completed`, `failed`. `completed` means the report was produced — it does not mean the invoice is valid. Read `report.valid` inside the report artifact for that.

Notes:

Artifact URLs always point to the gPdf job API. Authenticate URL fetches with the same Bearer token.
validation.status = "failed" indicates the validator pipeline failed to produce a clean report; the report artifact, if any, contains a failure envelope.
expires_at_ms on the job and on each artifact may differ because each artifact URL has its own short TTL (url_ttl_seconds, default 900).

6. Artifact download

GET /api/v1/e-invoice/jobs/{job_id}/artifacts/{artifact} returns the raw artifact bytes.

Property	Value
Method	`GET`
Path	`/api/v1/e-invoice/jobs/{job_id}/artifacts/{artifact}`
Auth	Required — same token that created the job.
Response	`200`, `Content-Type` matches the artifact (`application/pdf`, `application/xml`, `application/json`).

{artifact} is one of:

pdf
xml
report (only when report.enabled = true)
request (only when retention.store_request = true)

curl "https://api.gpdf.com/api/v1/e-invoice/jobs/$JOB_ID/artifacts/pdf" \
  -H "Authorization: Bearer $GPDF_TOKEN" \
  --output invoice.pdf

If the artifact has expired or is not yet available, the response is 404.

7. Validation flows

There are two distinct end-to-end flows depending on validation.level and delivery.mode. Pick by what the caller needs to see at request time.

7.1 Inline flow — basic validation, sync, PDF returned immediately

Default. Use this when you only need request-level XML structure checks and want the PDF in the same HTTP round-trip.

       client                              gPdf
         │                                  │
    1    │  POST /api/v1/e-invoice/render   │
         │ ────────────────────────────────>│
         │                                  │ ─┐
         │                                  │  │ basic XML structure check
         │                                  │  │ embed CII as attachment
         │                                  │  │ render PDF/A-3b
         │                                  │ <─┘
    2    │  200 application/pdf             │
         │<──────────────────────────────── │
         │                                  │

Settings: validation.level = "basic", validation.execution = "sync", delivery.mode = "inline_pdf" (all defaults).

Properties:

One round-trip. Total time typically 200–800 ms.
No job is created. No artifacts are stored.
xml.content only goes through structural sanity checks; full EN 16931 Schematron is not run on this path.

7.2 Object-delivery flow — strict validation, async, polled job

Use this when you need full third-party validation (e.g. a verifiable EN 16931 report alongside the PDF) and you can tolerate eventual delivery.

       client                              gPdf
         │                                  │
    1    │  POST /api/v1/e-invoice/render   │
         │ ────────────────────────────────>│
         │                                  │ ─┐
         │                                  │  │ embed CII, render PDF/A-3b
         │                                  │  │ store pdf + xml artifacts
         │                                  │  │ schedule strict validator
         │                                  │ <─┘
    2    │  200 application/json (pending)  │
         │<──────────────────────────────── │
         │                                  │
         │           (background validator runs out-of-band)
         │                                  │
    3    │  GET /api/v1/e-invoice/jobs/{id} │   ←── poll
         │ ────────────────────────────────>│
         │  200 application/json (pending)  │
         │<──────────────────────────────── │
         │           ...                    │
         │  GET /api/v1/e-invoice/jobs/{id} │   ←── eventually
         │ ────────────────────────────────>│
         │  200 application/json (completed,│
         │     report.json now available)   │
         │<──────────────────────────────── │
         │                                  │
    4    │  GET .../artifacts/pdf           │
         │ ────────────────────────────────>│
         │  200 application/pdf             │
         │<──────────────────────────────── │

Settings: validation.level = "strict", validation.execution = "async", delivery.mode = "object", optional report.enabled = true.

Properties:

Step 2 returns immediately (< 1s) with a job descriptor — see §5.
pdf and xml artifacts are typically available before validation completes — you can download the PDF as soon as Step 2 returns; the report is what takes time.
Step 3 returns validation.status = "completed" once the validator pipeline produces a report; that does not mean the invoice is valid — read report.valid inside the report artifact for that.
validation.status = "failed" means the validator pipeline itself failed; the report artifact, if any, contains a failure envelope rather than a clean EN 16931 report.

7.3 Polling cadence

Recommended back-off schedule for Step 3 above:

Poll	Wait since previous poll	Cumulative time
1st	5 s after Step 2	5 s
2nd	10 s	15 s
3rd	20 s	35 s
4th	30 s	65 s
5th+	60 s	125 s, 185 s, …

Most strict jobs reach completed within 60 s. A job still pending after 5 minutes is unusual — capture the job_id and report it.

8. Errors specific to e-invoice

In addition to the codes in the JSON Render reference’s §6.1, the e-invoice endpoint surfaces:

Trigger	Code	Note
Token policy disallows `document.e_invoice`	`API-002`	Contact your account contact to add the entitlement.
Disallowed `standard`, `profile`, or `document_type`	`API-002`	Use only standards listed in `/api/v1/e-invoice/capabilities` and allowed by your token.
`xml.content` exceeds `2 MiB`	`API-002`	Reduce the XML or split the document.
`data_residency.strict = true` with unresolved country	`API-002`	Provide an explicit `mode` or a known `country`.
Artifact / job not found or expired	HTTP `404` with `API-002` envelope	The retention window has passed.