API-Dokumentation

Integrieren Sie Rechnungsfunktionen direkt in Ihre Anwendung

Authentifizierung

Alle API-Anfragen erfordern einen API-Key im Request-Header:

x-api-key: YOUR_API_KEY

Pro-Tipp: API-Keys sind business-spezifisch. Jeder angemeldete Eigentuemer eines Unternehmens kann sie hier erstellen und verwalten:Unternehmen > Unternehmen auswaehlen > API-Keys.

POST

/api/v1/invoices/xrechnung

Dieser Endpunkt erzeugt ein XRechnung-XML aus einem JSON-Payload und validiert es vor der Rueckgabe. Er ist fuer deutsche und EN-16931-kompatible B2B- und B2G-Rechnungsprozesse gedacht.

Bei erfolgreicher Erstellung mit gueltiger Validierung liefert die API 201 Created. Ist das Request-Payload gueltig, aber das erzeugte Dokument faellt in der Validierung durch, liefert die API 422 Unprocessable Content und enthaelt das erzeugte XML inklusive Validierungsfehlern.

Request-Body (JSON)

Feld	Typ	Pflicht	Beschreibung
schema_version	string	Nein	Standardwert ist "1".
invoice_number	string	Ja	Eindeutige Rechnungs-ID.
buyer_reference	string	Nein	Optionaler Buyer- oder Routing-Referenzwert. Fuer PEPPOL dringend empfohlen.
order_reference	string	Nein	Optionale Bestellreferenz. Fuer PEPPOL dringend empfohlen.
issue_date	string	Ja	Format: YYYY-MM-DD.
due_date	string	Nein	Empfohlen fuer positive zahlbare Rechnungen. Format: YYYY-MM-DD.
currency	string	Ja	z. B. EUR, USD.
seller	object	Ja	Lieferantendaten. Unterstuetzte Felder siehe verschachtelte Objektreferenz.
buyer	object	Ja	Kundendaten. Unterstuetzte Felder siehe verschachtelte Objektreferenz.
line_items	array	Ja	Rechnungspositionen. Unterstuetzte Felder siehe verschachtelte Objektreferenz. Geldbetraege in Hauptwaehrungseinheiten, z. B. 150.00 EUR, nicht in Cent.
totals	object	Nein	Rechnungssummen. Unterstuetzte Felder siehe verschachtelte Objektreferenz. Geldbetraege in Hauptwaehrungseinheiten, z. B. 1785.00, nicht 178500.
payment	object	Nein	Zahlungsdaten. Unterstuetzte Felder siehe verschachtelte Objektreferenz.

Verschachtelte Objektreferenz

seller

Rechnungsaussteller. Diese Daten werden als Lieferantenpartei in der erzeugten eRechnung verwendet.

namestring

Rechtlicher Name oder Handelsname des Verkaeufers.

streetstring

Strasse und Hausnummer.

citystring

Stadt oder Ort.

postal_codestring

Postleitzahl.

countrystring

Zweistelliger ISO-Laendercode, z. B. DE oder FR.

vat_idstring

USt-ID fuer Steuer- und Parteienidentifikation.

endpoint_idstring

Optionale PEPPOL-Teilnehmerkennung des Verkaeufers.

endpoint_schemestring

Optionales PEPPOL-Schema, z. B. 9930.

emailstring

Kontakt-E-Mail des Verkaeufers. Fuer manche Formate erforderlich und als Fallback nuetzlich.

phonestring

Kontakt-Telefonnummer des Verkaeufers.

buyer

Rechnungsempfaenger oder Kunde. Diese Daten werden als Kundenpartei im erzeugten Dokument verwendet.

namestring

Rechtlicher Name oder Handelsname des Kaeufers.

streetstring

Strasse und Hausnummer.

citystring

Stadt oder Ort.

postal_codestring

Postleitzahl.

countrystring

Zweistelliger ISO-Laendercode.

vat_idstring

USt-ID, sofern vorhanden.

endpoint_idstring

Optionale PEPPOL-Teilnehmerkennung des Kaeufers.

endpoint_schemestring

Optionales PEPPOL-Schema des Kaeufers.

emailstring

E-Mail des Kaeufers, sofern vorhanden.

line_items[]

Jeder Eintrag repraesentiert eine Rechnungsposition. Betraege werden in Hauptwaehrungseinheiten uebergeben, nicht in Cent.

descriptionstring

Lesbare Artikel- oder Leistungsbeschreibung.

quantitynumber

Berechnete Menge der Position.

pricenumber

Einzelpreis in normaler Waehrung, z. B. 150.00.

totalnumber

Positionssumme in normaler Waehrung, meist quantity x price vor Rechnungsanpassungen.

vatRatenumber

MwSt-Prozentsatz der Position, z. B. 19 oder 0.

unitCodestring

UNECE-Einheitencode, z. B. HUR fuer Stunden oder C62 fuer Stueck.

totals

Rechnungssummen in Hauptwaehrungseinheiten. Diese sollten mit Positions- und Steuerwerten uebereinstimmen.

netnumber

Nettobetrag vor Steuern.

taxnumber

Gesamtsteuerbetrag.

grossnumber

Gesamtsumme inkl. Steuern.

payment

Optionale Zahlungsdaten, die in der erzeugten Rechnung dargestellt werden, falls vorhanden.

ibanstring

IBAN fuer den Zahlungseingang der Rechnung.

bicstring

BIC/SWIFT der empfangenden Bank.

Antwortstruktur

Feld	Beschreibung
id	Generierte lokale Kennung fuer die Antwort.
xml_base64	Base64-kodierte Version des erzeugten XRechnung-XML.
xml	Erzeugtes XRechnung-XML als Klartext.
format	eRechnungs-Formatkennung. Der oeffentliche XRechnung-Endpunkt liefert derzeit UBL.
schema_version	Schema-Version aus der Anfrage, standardmaessig 1.
validation	Validierungsobjekt mit valid, errors und warnings.
warnings	Top-Level-Warnungen, aus dem Validierungsergebnis gespiegelt.
code	Nur bei Validierungsfehler. Derzeit VALIDATION_FAILED.
message	Nur bei Validierungsfehler. Beschreibt den Grund der 422-Antwort.

Beispielanfrage (cURL)

Alle Geldfelder wie price, total, totals.net, totals.tax und totals.gross werden in normalen Waehrungseinheiten erwartet, nicht in Cent.

curl -X POST https://www.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"
  }
}'

Beispielantwort (201)

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

Beispielantwort (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

Dieser Endpunkt erzeugt eine PEPPOL BIS Billing 3.0 UBL-Rechnung und validiert sie vor der Rueckgabe von XML-Payload und Validierungsergebnis. Er ist fuer PEPPOL-kompatible Rechnungsprozesse gedacht, bei denen EN-16931-UBL-Ausgabe erforderlich ist.

Bei erfolgreicher Erstellung mit gueltiger Validierung liefert die API 201 Created. Ist das Request-Payload gueltig, aber das erzeugte Dokument faellt in der PEPPOL-Validierung durch, liefert die API 422 Unprocessable Content und enthaelt weiterhin XML und Validierungsfehler.

Request-Body (JSON)

Das Request-Payload ist identisch mit dem XRechnung-Endpunkt.

Fuer PEPPOL-Interoperabilitaet sollten buyer_reference oder order_reference gesetzt sein; payment.iban wird bei Zahlungsart Bankueberweisung empfohlen. Verwenden Sie gueltige PEPPOL-Endpunktkennungen und Schemas in seller.endpoint_id, seller.endpoint_scheme, buyer.endpoint_id und buyer.endpoint_scheme. Die API gibt ISO-Alpha-2-Laendercodes wie GB oder DE im XML aus.

Antwortstruktur

Feld	Beschreibung
id	Generierte lokale Kennung fuer die Antwort.
xml_base64	Base64-kodierte Version des erzeugten PEPPOL-UBL-XML.
xml	Erzeugtes PEPPOL BIS Billing 3.0 XML als Klartext.
format	eRechnungs-Formatkennung. Der oeffentliche PEPPOL-Endpunkt liefert PEPPOL.
schema_version	Schema-Version aus der Anfrage, standardmaessig 1.
validation	Validierungsobjekt mit valid, errors und warnings.
warnings	Top-Level-Warnungen, aus dem Validierungsergebnis gespiegelt.
filename	Empfohlener Dateiname fuer das erzeugte PEPPOL-XML.
code	Nur bei Validierungsfehler. Derzeit VALIDATION_FAILED.
message	Nur bei Validierungsfehler. Beschreibt den Grund der 422-Antwort.

Beispielantwort (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"
}

Beispielantwort (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

Dieser Endpunkt erzeugt ein hybrides ZUGFeRD (Factur-X)-PDF mit einem menschenlesbaren PDF und eingebettetem CII-XML. Das erzeugte CII-XML wird validiert und das Validierungsergebnis direkt mitgeliefert.

Request-Body (JSON)

Das Request-Payload ist identisch mit dem XRechnung-Endpunkt.

Fuer typische zahlbare Rechnungen sollte due_date gesetzt werden. Andernfalls kann die Validierung BR-CO-25 liefern; dann muss entweder ein Faelligkeitsdatum oder explizite Zahlungsbedingungen vorhanden sein.

Antwortstruktur

Feld	Beschreibung
pdf	Base64-kodierte hybride PDF/A-3-Datei.
xml	Erzeugter CII-XML-String.
validation	Validierungsergebnisse mit EN 16931 / CII Fehlern und Warnungen.
filename	Empfohlener Dateiname fuer das erzeugte hybride PDF.

Beispielantwort (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"
}

POST

/api/v1/validate

Dieser Endpunkt validiert ein vorhandenes XML-Dokument, ohne ein neues Rechnungsartefakt zu erzeugen. Er richtet sich an Integrationen mit bereits vorhandenem XML, die nur ein QuoteCash-Validierungsergebnis benoetigen.

Der reine Validierungsendpunkt liefert 200 OK, sobald XML zur Validierung akzeptiert wurde. Pruefen Sie validation.valid, um festzustellen, ob das uebergebene Dokument den gewaehlten Validator bestanden hat.

Request-Body (JSON)

Feld	Typ	Pflicht	Beschreibung
format	string	Ja	Einer von xrechnung, peppol oder zugferd. Die Aliase factur-x, facturx und cii werden fuer zugferd akzeptiert.
xml	string	Ja*	Rohes XML zur Validierung. Geben Sie entweder xml oder xml_base64 an.
xml_base64	string	Ja*	Base64-kodiertes XML. Nuetzlich fuer grosse XML-Inhalte oder binary-sichere Payloads.

Uebergeben Sie entweder xml oder xml_base64. Fuer PEPPOL nutzt der Endpunkt die konfigurierte PEPPOL-Validator-URL, sofern verfuegbar. Fuer ZUGFeRD muss das eingebettete CII-XML und nicht der PDF-Container gesendet werden.

Antwortstruktur

Feld	Beschreibung
format	Normalisiertes Zielformat des Validators: XRECHNUNG, PEPPOL oder ZUGFERD.
received_as	Zeigt, ob xml oder xml_base64 validiert wurde.
valid	Komfort-Boolean gespiegelt aus validation.valid.
validation	Validierungsobjekt mit valid, errors und warnings.

Beispielanfrage (cURL)

curl -X POST https://www.quotecash.io/api/v1/validate   -H "x-api-key: YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
  "format": "peppol",
  "xml": "<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">...</Invoice>"
}'

Beispielantwort (200)

{
  "format": "PEPPOL",
  "received_as": "xml",
  "valid": false,
  "validation": {
    "valid": false,
    "errors": [
      {
        "rule": "PEPPOL-EN16931-R001",
        "message": "Example validation rule failure returned for an uploaded XML document."
      }
    ],
    "warnings": []
  }
}

GET

/api/v1/cashflow/forecast

Mit diesem Endpunkt erhalten Sie eine business-spezifische Cashflow-Prognose mit Gesamtsummen, Perioden-Buckets und optionalen Rechnungsdetails fuer offene, teilweise bezahlte, bezahlte oder ueberfaellige Rechnungen.

Der oeffentliche Cashflow-Endpunkt liefert eine business-spezifische Prognose fuer den API-Key-Eigentuemer. Wenn business_id uebergeben wird, muss es dem Business des Schluessels entsprechen. Das invoices-Array wird nur bei include_invoices=true zurueckgegeben.

Query-Parameter

Feld	Typ	Pflicht	Beschreibung
from	string	Ja	Startdatum im ISO-Format YYYY-MM-DD.
to	string	Ja	Enddatum im ISO-Format YYYY-MM-DD.
groupBy	string	Nein	Aggregationsfenster. Unterstuetzte Werte: month oder week. Standard ist month.
payment_state	string	Nein	Optionaler Filter: open, partially_paid, paid oder overdue.
reminder_stage	string	Nein	Optionaler Filter: first, second, final, manual oder none.
include_invoices	boolean	Nein	Auf true setzen, um paginierte Rechnungszeilen in der Antwort zu erhalten.
sort_by	string	Nein	Optionale Sortierung fuer include_invoices=true. Werte: dueDate, open_amount, customer_name.
sort_direction	string	Nein	Optionale Sortierrichtung: asc oder desc.
page	number	Nein	Seitennummer fuer Pagination. Standard ist 1.
per_page	number	Nein	Eintraege pro Seite bei include_invoices=true. Standard 25, max. 100.
currency	string	Nein	Optionale Waehrungsueberschreibung. Standard ist die Waehrung des API-Key-Unternehmens.
business_id	string	Nein	Optionaler expliziter Business-Scope. Muss dem Business des API-Keys entsprechen.

Setzen Sie include_invoices=true, wenn Rechnungszeilen fuer Drill-down-Ansichten zurueckgegeben werden sollen. Ohne diesen Parameter enthaelt die Antwort nur range, filters, summary, periods und pagination.

Antwortstruktur

Feld	Beschreibung
range	Normalisiertes Zeitfenster inkl. Aggregation, Waehrung und generatedAt-Zeitstempel.
filters	Spiegelt aktive Payment/Reminder-Filter sowie Pagination-Einstellungen.
summary	Gesamtsummen inkl. openAmount, overdueAmount, paidAmountInRange, expectedIncomingInRange und Zaehler.
periods	Woechentliche oder monatliche Buckets mit expectedIncoming, paidAmount, overdueAmount, openAmount und invoiceCount.
invoices	Nur bei include_invoices=true. Enthaelt paginierte Rechnungszeilen mit paymentState, Overdue-Status und Reminder-Metadaten.
pagination	Pagination-Metadaten fuer invoices inkl. page, perPage, totalItems und totalPages.

Beispielanfrage (cURL)

curl -X GET "https://www.quotecash.io/api/v1/cashflow/forecast?from=2026-05-01&to=2026-06-30&groupBy=month&payment_state=overdue&include_invoices=true&per_page=10"   -H "x-api-key: YOUR_API_KEY"

Beispielantwort (200)

{
  "range": {
    "from": "2026-05-01T00:00:00.000Z",
    "to": "2026-06-30T23:59:59.999Z",
    "groupBy": "month",
    "currency": "EUR",
    "generatedAt": "2026-05-17T08:30:00.000Z"
  },
  "filters": {
    "paymentState": "overdue",
    "reminderStage": null,
    "includeInvoices": true,
    "sortBy": "dueDate",
    "sortDirection": "asc"
  },
  "summary": {
    "openAmount": 800,
    "overdueAmount": 800,
    "partiallyPaidAmount": 200,
    "paidAmountInRange": 200,
    "expectedIncomingInRange": 800,
    "invoiceCount": 1,
    "openInvoiceCount": 1,
    "overdueInvoiceCount": 1
  },
  "periods": [
    {
      "periodStart": "2026-05-01T00:00:00.000Z",
      "periodEnd": "2026-05-31T23:59:59.999Z",
      "label": "May 2026",
      "expectedIncoming": 800,
      "paidAmount": 200,
      "overdueAmount": 800,
      "openAmount": 800,
      "invoiceCount": 1
    }
  ],
  "invoices": [
    {
      "id": "inv-1",
      "invoiceNumber": "INV-001",
      "customerName": "Alpha GmbH",
      "date": "2026-05-01T00:00:00.000Z",
      "dueDate": "2026-05-10T00:00:00.000Z",
      "total": 1000,
      "paidAmount": 200,
      "openAmount": 800,
      "currency": "EUR",
      "status": "OVERDUE",
      "paymentState": "overdue",
      "isOverdue": true,
      "reminder": {
        "enabled": true,
        "lastStage": "first",
        "lastSentAt": "2026-05-11T00:00:00.000Z",
        "nextStage": null,
        "status": "sent",
        "nextScheduledFor": null
      }
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 10,
    "totalItems": 1,
    "totalPages": 1
  }
}

Integrationsbeispiele

Verwenden Sie diese Snippets als Copy-Paste-Startpunkte fuer die Integration von QuoteCash in Ihr Backend, Ihre Skripte oder API-Tools.

Oeffentliche API-Aufrufe unterliegen weiterhin den planbasierten Monatslimits. Wenn Stripe-Metered-Billing in der Umgebung aktiviert ist, werden erfolgreiche API-Key-Requests zusaetzlich als Usage Records an das aktive Stripe-Abonnement gemeldet.

Node.js Fetch-Beispiel

const response = await fetch('https://www.quotecash.io/api/v1/invoices/xrechnung', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.QUOTECASH_API_KEY,
  },
  body: JSON.stringify({
    schema_version: '1',
    invoice_number: 'INV-2026-001',
    issue_date: '2026-05-16',
    due_date: '2026-05-30',
    currency: 'EUR',
    seller: {
      name: 'Acme GmbH',
      street: 'Seller Street 1',
      city: 'Berlin',
      postal_code: '10115',
      country: 'DE',
      vat_id: 'DE123456789',
      email: 'billing@acme.test',
      phone: '+49 30 123456'
    },
    buyer: {
      name: 'Client GmbH',
      street: 'Buyer Street 5',
      city: 'Hamburg',
      postal_code: '20095',
      country: 'DE',
      vat_id: 'DE987654321'
    },
    line_items: [
      {
        description: 'Consulting',
        quantity: 8,
        price: 125,
        total: 1000,
        unitCode: 'HUR',
        vatRate: 19,
      },
    ],
    totals: {
      net: 1000,
      tax: 190,
      gross: 1190,
    },
    payment: {
      iban: 'DE12345678901234567890',
      bic: 'ABCDEFGHXXX',
    },
  }),
});

const data = await response.json();
console.log(response.status, data.validation?.valid, data.filename);