Endpoints

Base URL: https://app.xingen.de/api — every path below is relative to it (e.g. POST /v1/invoices/validate is POST https://app.xingen.de/api/v1/invoices/validate).

Validation is asynchronous. Every submit endpoint returns 202 Accepted immediately with an invoice id; poll GET /v1/invoices/{id} until status leaves processing. Sandbox keys (xgn_test_) are the exception — they resolve instantly with a canned result. See Authentication.

POST /v1/invoices/validate

Upload a UBL XML, CII XML, or ZUGFeRD PDF/A-3 file for validation.

Request

Field	In	Type	Description
Content-Type	header	string	`multipart/form-data`
file	form field	file	The invoice file (`.xml` or `.pdf`)
profile	form field	string	Required. One of `EN16931`, `PEPPOL`, `XRECHNUNG`, `FRANCE`, `ITALY`. `XRECHNUNG`/`FRANCE`/`ITALY` require Pro.

Response

{
  "id": "3f9e2b7a-2c1d-4a6e-9b3f-8d1e2c4a6b7c",
  "status": "processing"
}

POST /v1/invoices/validate/idoc

Upload a SAP IDoc XML file. It's converted to xingen's canonical invoice model before EN 16931 rules run. Same request/response shape as above (file + profile form fields, 202 with {id, status}).

POST /v1/invoices/validate/odata

Submit a SAP S/4HANA OData SupplierInvoice payload directly — useful if you're reading invoices out of SAP via OData rather than exporting files.

Request

Field	In	Type	Description
profile	query param	string	Required. Same values as above.
(body)	body	JSON	SAP OData `SupplierInvoice` entity payload

Response

{
  "id": "8b1a4c2e-...",
  "status": "processing"
}

POST /v1/invoices

Submit invoice data as structured JSON instead of generating XML yourself — useful if your system already has the invoice as data rather than a document.

Request body

{
  "invoiceNumber": "INV-2024-0042",
  "issueDate": "2024-03-15",
  "currency": "EUR",
  "buyerReference": "991-12345-06",
  "validationProfile": "XRECHNUNG",
  "supplier": { "name": "Acme GmbH", "vatId": "DE123456789", "leitwegId": null },
  "buyer": { "name": "Contoso AG", "vatId": "DE987654321", "leitwegId": "991-12345-06" },
  "lines": [
    { "description": "Software License Q1", "quantity": 5, "unit": "C62", "price": 199.00, "taxRate": 19 }
  ]
}

Response

{
  "id": "9c2d5e1a-...",
  "status": "processing"
}

POST /v1/invoices/extract

Upload a plain (non-XRechnung/UBL/CII) invoice PDF — including scanned/image-based PDFs — for AI-based field extraction with Claude. The extracted invoice is validated and converted to a ZUGFeRD/Factur-X hybrid PDF, downloadable via GET /v1/invoices/{id}/download once processing completes. This is the same conversion the dashboard UI uses under the hood, so this endpoint lets you automate it.

Request

Field	In	Type	Description
Content-Type	header	string	`multipart/form-data`
file	form field	file	Plain invoice PDF
profile	form field	string	Optional, default `EN16931`. One of `EN16931`, `PEPPOL`, `XRECHNUNG`, `FRANCE`, `ITALY`.
tier	form field	string	Optional, default `FAST`. `FAST` or `ACCURATE` — `ACCURATE` requires Pro.

Response

{
  "id": "1a2b3c4d-...",
  "status": "processing"
}

Returns 403 if tier=ACCURATE is requested on a Free plan.

GET /v1/invoices/{id}

Poll this to retrieve the validation result. status is one of processing, validated, or failed_validation.

Response

{
  "id": "3f9e2b7a-2c1d-4a6e-9b3f-8d1e2c4a6b7c",
  "status": "failed_validation",
  "validationProfile": "XRECHNUNG",
  "invoiceFormat": "UBL",
  "sandbox": false,
  "createdAt": "2024-03-01T10:00:00Z",
  "canonicalJson": { "invoiceNumber": "INV-2024-0042", "issueDate": "2024-03-15", "..." : "..." },
  "validationResult": {
    "valid": false,
    "errors": [
      {
        "code": "BR-01",
        "message": "An Invoice shall have a Specification identifier.",
        "field": "/Invoice/CustomizationID",
        "suggestion": "Add <cbc:CustomizationID>urn:cen.eu:en16931...</cbc:CustomizationID>",
        "documentationUrl": "https://...",
        "layer": "CORE",
        "severity": "ERROR"
      }
    ],
    "kositResult": { "valid": false, "errors": [] }
  }
}

Note there is no line number in errors — field gives the affected path instead. See the Error Reference for the full error shape and common codes.

GET /v1/invoices

Paginated list of your own invoices (all invoices, if you're a super-admin).

Param	In	Type	Description
page, size	query	int	Standard pagination, default size 20
sort	query	string	Default `createdAt,desc`

GET /v1/invoices/{id}/download

Exports a validated invoice as a ZUGFeRD-compliant PDF with embedded XML (application/pdf).

GET /v1/invoices/{id}/download/idoc

Exports a validated invoice as a SAP IDoc XML file (application/xml).

API key management

POST /v1/api-keys, GET /v1/api-keys, DELETE /v1/api-keys/{id} — see Authentication for request/response details.