Getting Started

This guide walks you through making your first xingen API call in under five minutes. You'll validate an XRechnung invoice and inspect the structured response.

Prerequisites

• A free xingen account — sign up here
• An API key (generated in your account dashboard)
• curl or any HTTP client

Step 1 — Get your API key

After signing up, navigate to Settings → API Keys and create a new key. Copy it somewhere safe — it won't be shown again.

Set it as an environment variable for convenience:

export XINGEN_API_KEY="xgn_live_your_key_here"

Step 2 — Prepare an invoice file

xingen accepts UBL 2.1 XML, CII XML, or a ZUGFeRD-embedded PDF/A-3. For this quickstart, save the minimal XRechnung skeleton below as invoice.xml:

<?xml version="1.0" encoding="UTF-8"?>
<ubl:Invoice xmlns:ubl="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
             xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
  <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0</cbc:CustomizationID>
  <cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>
  <cbc:ID>INV-2024-001</cbc:ID>
  <cbc:IssueDate>2024-03-01</cbc:IssueDate>
  <!-- ... remaining required fields ... -->
</ubl:Invoice>

Step 3 — Submit for validation

POST the file to /v1/invoices/validate as multipart/form-data, with the profile to validate against:

curl -X POST https://app.xingen.de/api/v1/invoices/validate \
  -H "Authorization: Bearer $XINGEN_API_KEY" \
  -F "file=@invoice.xml" \
  -F "profile=XRECHNUNG"

Validation runs asynchronously. This returns 202 Accepted immediately with an invoice ID — it doesn't contain the result yet:

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

Step 4 — Poll for the result

Poll GET /v1/invoices/{id} until status is no longer processing:

curl https://app.xingen.de/api/v1/invoices/3f9e2b7a-2c1d-4a6e-9b3f-8d1e2c4a6b7c \
  -H "Authorization: Bearer $XINGEN_API_KEY"

Once done, status is validated or failed_validation, and validationResult is populated:

{
  "id": "3f9e2b7a-2c1d-4a6e-9b3f-8d1e2c4a6b7c",
  "status": "failed_validation",
  "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>",
        "severity": "ERROR"
      }
    ]
  }
}

If you used an xgn_test_ sandbox key, this resolves instantly with a fixed, fake validated result instead of running real validation — see Authentication. Otherwise, errors contains structured error objects with field paths and fix suggestions. See the Error Reference for the full list.

Next steps

• Authentication — sandbox vs. live keys, plan-gated profiles, rotation
• Endpoints — every endpoint, including JSON and SAP submission
• Formats — supported input/output combinations
• SDKs — official client libraries for Java, Python, TypeScript, C#, PHP, and Go
• API Reference (Swagger UI) ↗ — interactive, try every endpoint live
• OpenAPI Spec (JSON) ↗ — raw spec, import directly into Postman or codegen tools