Download the PHP package xingen/xingen-sdk without Composer

xingen-sdk

PHP client SDK for the Xingen e-invoice validation API — submit UBL, CII, ZUGFeRD, and SAP IDoc/OData invoices for validation against EN16931, XRechnung, and Peppol.

Requires PHP 8.1+ with the curl and json extensions (both bundled with PHP by default). No third-party runtime dependencies.

Status: v1, covering invoice submission/validation and API key management. Contacts and dashboard/user endpoints are not exposed (they're Firebase-auth-only on the backend).

Install

Authentication

Every request needs an API key (xgn_live_... for production, xgn_test_... for sandbox — sandbox requests never count toward quota). Create one from the Xingen dashboard or via $client->apiKeys.

XingenClient holds one connection-pooled curl handle — construct it once and reuse it, don't rebuild it per request. baseUrl: overrides the default https://app.xingen.de/api, useful for self-hosted or local (./gradlew bootRun, port 10001) testing.

Validate a file

Every validate/submit endpoint is asynchronous — the backend queues the invoice and returns immediately. Use a *AndWait helper to submit and poll for the result in one call:

PollOptions controls the backoff (initialInterval, maxInterval, backoffMultiplier), the overall timeout, and an optional cancellationCheck. A failed validation is not an exception — it's a completed API call that found the invoice invalid, so *AndWait returns normally with validationResult->valid === false. Only a transport failure, cancellation, or timeout throws.

If you'd rather manage polling yourself, use the low-level pair:

validateIdoc / validateIdocAndWait work the same way for SAP IDoc XML files. Both, and validateFile/validateFileAndWait, also accept a [$filename, $content] array if you already hold the file bytes in memory instead of a path.

Submit a structured invoice (JSON)

InvoiceSubmission has full parity with the backend's domain model — every invoice type it can validate, it can also submit, including non-standard VAT categories (exempt/reverse-charge/export via LineInput::$taxCategoryCode + $exemptionReason/$exemptionReasonCode), payee/ taxRepresentative, delivery, invoicePeriod, precedingInvoiceReferences (for credit notes), and the full BT-11..BT-19 document reference fields. See the constructor parameters on InvoiceSubmission and its nested value objects for the complete set.

SAP S/4HANA OData supplier-invoice payloads are supported as a thin passthrough — pass a raw JSON string or a plain array rather than a fully typed model:

Extract an invoice from a PDF (AI)

Upload a plain invoice PDF — including scanned/image-based PDFs — and let the backend extract structured fields with Claude. Works exactly like the other submit endpoints: async, so use extractInvoiceAndWait or the low-level extractInvoice/get pair.

If the extraction missed a field or validation flagged something, correct it with a JSON merge-patch (RFC 7386) and re-validate synchronously — only invoices that finished processing (VALIDATED or FAILED_VALIDATION) can be corrected. Array fields (lines, paymentMeans, allowanceCharges, taxBreakdowns) are replaced wholesale when present in the patch:

To find out which fields the backend fills in automatically per profile (so you know what not to prompt the user for):

List and retrieve invoices

Download results

API keys

Error handling

All SDK exceptions extend Xingen\Sdk\Error\XingenException. HTTP errors map to typed subclasses of ApiException:

Design notes

• No automatic retries. Retrying a submit() after a client-side timeout is unsafe without idempotency keys, which the API doesn't support yet — a retried submit could create a duplicate invoice. Handle retries at the call site if you need them.
• Monetary and quantity fields are string, never float. PHP has no native arbitrary-precision decimal type, so float would silently lose precision on large or exact-decimal amounts. Response bodies are parsed through a small dependency-free JSON decoder (Xingen\Sdk\Internal\Json) that preserves every numeric literal as its exact source-text string instead of routing it through PHP's json_decode() (which, like most JSON parsers, converts numbers through a float64 intermediate). Request bodies send these same fields as plain PHP strings, which the backend's Jackson-based deserializer accepts for its BigDecimal fields without issue.
• No third-party dependencies. HTTP is handled via ext-curl (bundled with PHP), reusing a single connection-pooled handle across requests rather than a Composer HTTP client package.

Contributing

Tests run against a real (loopback) php -S server subprocess, not a mocking framework — no network calls leave the machine, and no external test-server dependency is required.

License

MIT — see LICENSE.