API Documentation

Integrate invoicing capabilities directly into your application using our REST API.

Authentication

All API requests require an API key to be included in the header of the request:

x-api-key: YOUR_API_KEY

Pro-tip: Admin users can generate and manage API keys via theAdmin Dashboard > API Keys section.

POST

/api/v1/invoices/xrechnung

This endpoint generates an XRechnung XML document from a JSON payload and validates it before returning the result. It is intended for German and EN 16931 compatible B2B and B2G invoicing flows.

Successful generation with valid validation returns 201 Created. If the request payload is valid but the generated document fails validation, the API returns 422 Unprocessable Content and includes the generated XML together with validation errors.

Request Body (JSON)

Field	Type	Required	Description
schema_version	string	No	Default is "1".
invoice_number	string	Yes	Unique invoice ID.
buyer_reference	string	No	Optional buyer or routing reference. Strongly recommended for PEPPOL.
order_reference	string	No	Optional order or purchase order reference. Strongly recommended for PEPPOL.
issue_date	string	Yes	Format: YYYY-MM-DD.
due_date	string	No	Recommended for positive-payable invoices. Format: YYYY-MM-DD.
currency	string	Yes	e.g. EUR, USD.
seller	object	Yes	Supplier information. See nested object reference below for supported fields.
buyer	object	Yes	Customer information. See nested object reference below for supported fields.
line_items	array	Yes	Invoice lines. See nested object reference below for supported fields. Monetary values use major currency units, e.g. 150.00 EUR, not cents.
totals	object	No	Invoice totals. See nested object reference below. Monetary values use major currency units, e.g. 1785.00, not 178500.
payment	object	No	Payment account details. See nested object reference below for supported fields.

Nested Object Reference

seller

Issuer of the invoice. This data is used for supplier party information in the generated e-invoice.

namestring

Legal or trading name of the seller.

streetstring

Street and house number.

citystring

City or locality.

postal_codestring

Postal or ZIP code.

countrystring

Two-letter ISO country code, for example DE or FR.

vat_idstring

VAT identifier used for tax and party identification.

endpoint_idstring

Optional PEPPOL participant identifier for the seller.

endpoint_schemestring

Optional PEPPOL participant scheme identifier, for example 9930.

emailstring

Seller contact email. Required for some formats and useful fallback endpoint data.

phonestring

Seller contact phone number.

buyer

Invoice recipient or customer. This becomes the customer party in the generated document.

namestring

Legal or trading name of the buyer.

streetstring

Street and house number.

citystring

City or locality.

postal_codestring

Postal or ZIP code.

countrystring

Two-letter ISO country code.

vat_idstring

VAT identifier when available.

endpoint_idstring

Optional PEPPOL participant identifier for the buyer.

endpoint_schemestring

Optional PEPPOL participant scheme identifier for the buyer.

emailstring

Buyer email when available.

line_items[]

Each array entry represents one invoice line. Amounts are passed in major currency units, not cents.

descriptionstring

Human-readable item or service description.

quantitynumber

Billed quantity for the line item.

pricenumber

Unit price in normal currency units, for example 150.00.

totalnumber

Line total in normal currency units, usually quantity multiplied by price before invoice-level adjustments.

vatRatenumber

VAT percentage for the line, for example 19 or 0.

unitCodestring

UNECE unit code such as HUR for hours or C62 for pieces.

totals

Invoice totals in major currency units. These should match the sum of your line items and taxes.

netnumber

Net amount before tax.

taxnumber

Total tax amount.

grossnumber

Grand total including tax.

payment

Optional payment account details shown in the generated invoice when available.

ibanstring

Bank account IBAN for invoice payment.

bicstring

BIC or SWIFT code for the receiving bank.

Response Structure

Field	Description
id	Generated local identifier for the response payload.
xml_base64	Base64-encoded version of the generated XRechnung XML.
xml	Generated XRechnung XML as a plain string.
format	E-invoice format identifier. The public XRechnung endpoint currently returns UBL.
schema_version	Schema version echoed back from the request, defaulting to 1.
validation	Validation result object containing valid, errors, and warnings.
warnings	Top-level warnings array mirrored from the validation result for convenience.
code	Present only on validation failure. Currently returned as VALIDATION_FAILED.
message	Present only on validation failure and describes why the document received a 422 response.

Example Request (cURL)

All monetary fields such as price, total, totals.net, totals.tax, and totals.gross are expected in normal currency units, not cents.

curl -X POST https://quotecash.io/api/v1/invoices/xrechnung \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schema_version": "1",
  "invoice_number": "INV-2024-001",
  "issue_date": "2024-03-14",
  "due_date": "2024-03-28",
  "currency": "EUR",
  "seller": {
    "name": "Acme Corp",
    "street": "123 Seller St",
    "city": "Berlin",
    "postal_code": "10115",
    "country": "DE",
    "vat_id": "DE123456789"
  },
  "buyer": {
    "name": "Global Client",
    "street": "456 Buyer Rd",
    "city": "Munich",
    "postal_code": "80331",
    "country": "DE",
    "vat_id": "DE987654321"
  },
  "line_items": [
    {
      "description": "API Consulting",
      "quantity": 10,
      "price": 150,
      "total": 1500,
      "unitCode": "HUR",
      "vatRate": 19
    }
  ],
  "totals": {
    "net": 1500,
    "tax": 285,
    "gross": 1785
  },
  "payment": {
    "iban": "DE12345678901234567890",
    "bic": "ABCDEFGHXXX"
  }
}'

Example Response (201)

{
  "id": "local-1710412800000",
  "xml_base64": "PEludm9pY2UgLi4uPg==",
  "xml": "<Invoice ...>",
  "format": "UBL",
  "schema_version": "1",
  "validation": {
    "valid": true,
    "errors": [],
    "warnings": []
  },
  "warnings": []
}

Example Response (422)

{
  "code": "VALIDATION_FAILED",
  "message": "Generated document failed KoSIT validation",
  "id": "local-1710412800000",
  "xml_base64": "PEludm9pY2UgLi4uPg==",
  "xml": "<Invoice ...>",
  "format": "UBL",
  "schema_version": "1",
  "validation": {
    "valid": false,
    "errors": [
      {
        "rule": "BR-DE-1",
        "message": "Example validation rule failure returned for an invalid XRechnung payload or generated document."
      }
    ],
    "warnings": []
  },
  "warnings": []
}

POST

/api/v1/invoices/peppol

This endpoint generates a PEPPOL BIS Billing 3.0 UBL invoice and validates it before returning the XML payload and validation result. It is intended for PEPPOL-compatible invoicing flows where EN 16931 UBL output is required.

Successful generation with valid validation returns 201 Created. If the request payload is valid but the generated document fails PEPPOL validation, the API returns 422 Unprocessable Content and still includes the generated XML and validation errors.

Request Body (JSON)

The request payload is identical to the XRechnung endpoint.

For PEPPOL interoperability, buyer_reference or order_reference should be supplied, and payment.iban is recommended whenever the payment means is bank transfer. Use valid PEPPOL endpoint identifiers and schemes in seller.endpoint_id, seller.endpoint_scheme, buyer.endpoint_id, and buyer.endpoint_scheme. The API emits ISO alpha-2 country codes such as GB or DE in the XML.

Response Structure

Field	Description
id	Generated local identifier for the response payload.
xml_base64	Base64-encoded version of the generated PEPPOL UBL XML.
xml	Generated PEPPOL BIS Billing 3.0 XML as a plain string.
format	E-invoice format identifier. The public PEPPOL endpoint returns PEPPOL.
schema_version	Schema version echoed back from the request, defaulting to 1.
validation	Validation result object containing valid, errors, and warnings.
warnings	Top-level warnings array mirrored from the validation result for convenience.
filename	Suggested filename for the generated PEPPOL XML document.
code	Present only on validation failure. Currently returned as VALIDATION_FAILED.
message	Present only on validation failure and describes why the document received a 422 response.

Example Response (201)

{
  "id": "local-1710412800000",
  "xml_base64": "PEludm9pY2UgLi4uPg==",
  "xml": "<Invoice ...>",
  "format": "PEPPOL",
  "schema_version": "1",
  "validation": {
    "valid": true,
    "errors": [],
    "warnings": []
  },
  "warnings": [],
  "filename": "invoice-GB-INV-2024-001-peppol.xml"
}

Example Response (422)

{
  "code": "VALIDATION_FAILED",
  "message": "Generated document failed PEPPOL validation",
  "id": "local-1710412800000",
  "xml_base64": "PEludm9pY2UgLi4uPg==",
  "xml": "<Invoice ...>",
  "format": "PEPPOL",
  "schema_version": "1",
  "validation": {
    "valid": false,
    "errors": [
      {
        "rule": "PEPPOL-EN16931-R001",
        "message": "Example PEPPOL validation rule failure returned for an invalid document."
      }
    ],
    "warnings": []
  },
  "warnings": [],
  "filename": "invoice-GB-INV-2024-001-peppol.xml"
}

POST

/api/v1/invoices/zugferd

This endpoint generates a ZUGFeRD (Factur-X) hybrid PDF containing both a human-readable PDF and a machine-readable CII XML. It validates the generated CII XML and returns the validation result inline.

Successful generation with valid validation returns 201 Created. If the request payload is valid but the generated document fails validation, the API returns 422 Unprocessable Content and still includes the generated PDF, XML, and validation errors.

Request Body (JSON)

The request payload is identical to the XRechnung endpoint.

For common positive-payable invoices, include due_date. Otherwise validation can return BR-CO-25, which means either a payment due date or explicit payment terms must be present.

Response Structure

Field	Description
pdf	Base64 encoded hybrid PDF/A-3 file.
xml	The generated CII XML string.
validation	Validation results with EN 16931 / CII rule errors and warnings.
filename	Suggested filename for the generated hybrid PDF.

Example Response (422)

{
  "code": "VALIDATION_FAILED",
  "message": "Generated document failed validation",
  "pdf": "JVBERi0xLjQKJ...",
  "xml": "<rsm:CrossIndustryInvoice ...>",
  "validation": {
    "valid": false,
    "errors": [
      {
        "rule": "BR-CO-25",
        "message": "[BR-CO-25]-In case the Amount due for payment (BT-115) is positive, either the Payment due date (BT-9) or the Payment terms (BT-20) shall be present."
      }
    ],
    "warnings": []
  },
  "filename": "invoice-INV-2024-001-zugferd.pdf"
}

Need Help?

Check out our GitHub issues or contact our support lab.

View Documentation on GitHub