XRechnung - Electronic Invoicing support in Mobilitybox Invoice API

Invoices are now available as XRechnung XML files in addition to the existing PDF download. Both UBL and CII formats are generated asynchronously when an invoice is created for a customer with complete electronic invoicing details.

Prepare Customer for XRechnung generation

When creating a customer with POST /v9/ticketing/customers.json, include an electronic_invoicing object inside customer.

{
  "customer": {
    "address_lines": [
      "Example GmbH",
      "Musterstraße 12",
      "10115 Berlin"
    ],
    "electronic_invoicing": {
      "electronic_address": "[email protected]",
      "electronic_address_scheme_id": "EM",
      "buyer_reference": "PURCHASING-123",
      "address": {
        "name": "Example GmbH",
        "street_with_number": "Musterstraße 12",
        "postal_code": "10115",
        "city": "Berlin",
        "country_code": "DE"
      }
    }
  }
}

All fields below are required when electronic_invoicing is supplied. Paths are relative to that object.

Field	Description
electronic_address	The buyer's electronic address, such as an invoice email address.
electronic_address_scheme_id	The address scheme matching that value, such as "EM" for email or "0204" for a Leitweg-ID. Send codes as strings to preserve leading zeros.
buyer_reference	The reference supplied by the buyer for routing the invoice internally.
address.name	The buyer's name or company name.
address.street_with_number	Street and building number.
address.postal_code	Postal code, supplied as a string.
address.city	City.
address.country_code	Two-letter country code, such as "DE".

The fields address.addition_address_line_one and address.addition_address_line_two are optional.

Field	Description
address.addition_address_line_one	Additional address line one (optional).
address.addition_address_line_two	Additional address line two (optional).

Keep supplying the existing address_lines field; the structured address currently does not replace it in Invoicing V1. Customer responses return electronic invoicing details in the same nested structure.

If a required field is missing, empty, or whitespace-only, the API returns HTTP 422 with a message identifying the field. An explicitly empty or null electronic_invoicing object is also rejected. Omitting the object entirely remains valid, but does not enable automatic XRechnung generation for that customer.

Customers cannot be changed after they have been created. Therefore, the electronic invoicing details cannot be added or corrected after an invoice has been created. Existing invoices are not processed retroactively and will not receive an XRechnung later.

UBL and CII

UBL (Universal Business Language) and CII (Cross Industry Invoice) are two XML syntaxes supported by XRechnung for invoices and invoice cancellations. They represent invoice information using different XML structures. Choose the format supported by the recipient's accounting software; both are machine-readable XML files, rather than PDF documents. See the official XRechnung overview.

Format	Download suffix
PDF	.pdf
UBL XML	.ubl.xml
CII XML	.cii.xml

Downloading an XRechnung

The invoice JSON response contains invoice_pdf_url and invoice_xrechnung_url. The latter points to the UBL file. To download CII, replace its final .ubl.xml suffix with .cii.xml.

The download works like the existing PDF download: send a GET request and preserve the invoice ID and identifier embedded in the URL. No new identifier is needed.

GET /v9/ticketing/invoices/{invoice_id}/{identifier}.pdf
GET /v9/ticketing/invoices/{invoice_id}/{identifier}.ubl.xml
GET /v9/ticketing/invoices/{invoice_id}/{identifier}.cii.xml

A ready file is returned as an attachment with HTTP 200. XML generation runs asynchronously, so a file may not be available immediately after the invoice is created. If generation has not finished, the endpoint returns HTTP 202 with a JSON message asking you to retry in a few seconds. Check the response status before treating the response body as an XML file.

Zahlungsaufforderungen - Payment Notices

Payment notices are exported in the same UBL and CII XML structures as invoices. The generated files are intended to follow the relevant XRechnung XML schemas and to be compatible with XRechnung XML importers.

They do not claim conformance with the XRechnung or EN 16931 standards, because a payment notice is not an invoice in the legal and business sense. Recipients should therefore agree in advance that they accept this document type and syntax.