API-Dokumentation

Integrieren Sie Rechnungsfunktionen direkt in Ihre Anwendung

QuoteCash positioniert die API als kanonischen Invoice-Lifecycle: ein JSON-Payload hinein, automatisch validieren, benoetigte Artefakte erzeugen, optional speichern und die Rechnung bis zum Zahlungseingang verfolgen.

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.

POSTGET

/api/v1/invoices

Dies ist der kanonische QuoteCash-Endpunkt fuer den Developer-Quickstart. Senden Sie ein Invoice-JSON einmal an POST /api/v1/invoices, lassen Sie QuoteCash validieren, erzeugen Sie die benoetigten Artefakte, speichern Sie die Rechnung im Business des API-Keys und verfolgen Sie sie anschliessend bis zur Zahlung.

Empfohlener Integrationspfad

POST /api/v1/invoices mit einem kanonischen Invoice-Payload senden.
options.validate aktiv lassen und unter options.generate die benoetigten Formate anfordern.
validation und artifacts direkt aus der Antwort lesen.
Spaeter dieselbe gespeicherte Rechnung fuer Zahlungsstatus, Receivables, Cashflow und weitere Artefakte wiederverwenden.

Kompatibilitaet: Bestehende Stored-Invoice-Requests funktionieren weiter. Fuer den kanonischen Lifecycle verwenden neue Integrationen denselben Endpunkt mit options.mode, options.generate, options.validate und options.artifact_failure_mode.

Verwenden Sie diesen Endpunkt, wenn per API uebermittelte Rechnungen als normale QuoteCash-Rechnungen im Business des API-Keys gespeichert werden sollen. Der buyer wird per E-Mail, USt-ID oder Name einem Kunden zugeordnet oder automatisch erstellt.

Artefakte fuer gespeicherte Rechnungen koennen spaeter ueber POST /api/v1/invoices/{id}/artifacts erzeugt, ueber GET /api/v1/invoices/{id}/artifacts gelistet und kanonisch ueber GET /api/v1/artifacts/{artifact_id} abgerufen werden. Fuer create-and-forget-Flows ohne Speicherung stehen POST /api/v1/artifacts/xrechnung, /peppol, /zugferd und /pdf bereit.

POST 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	Muss EUR sein. QuoteCash lehnt derzeit jede andere Rechnungswaehrung ab.
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.
options	object	Nein	Steuert, ob die Rechnung gespeichert oder temporaer verarbeitet wird, welche Artefakte erzeugt werden und wie auf Artefaktfehler reagiert wird.
options.mode	string	Nein	stored oder temporary. Fuer neue Integrationen ist stored der Standard.
options.validate	boolean	Nein	Standard ist true. Validiert erzeugte XML-basierte Artefakte automatisch.
options.artifact_failure_mode	string	Nein	Die API akzeptiert partial oder strict. partial entspricht weiterlaufen; strict entspricht Request fehlschlagen lassen.
options.generate	array<object>	Nein	Liste der anzufordernden Artefakte. Jedes Element beschreibt ein Format wie xrechnung, zugferd, peppol oder pdf.
status	string	Nein	Optionaler gespeicherter Rechnungsstatus. Standard ist SENT.

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.

options

Lifecycle-Optionen fuer den kanonischen POST /api/v1/invoices Flow.

modestring

stored oder temporary. stored ist der Standardpfad fuer neue Integrationen.

validateboolean

Standard ist true. Validiert erzeugte XML-basierte Artefakte automatisch.

artifact_failure_modestring

Die API akzeptiert derzeit partial oder strict. partial bedeutet weiterlaufen und erfolgreiche Artefakte zurueckgeben; strict bedeutet den Request fehlschlagen lassen, sobald ein Artefakt scheitert.

strict_schemaboolean

Optional. Wenn true, lehnt die API unbekannte Felder im Request ab.

generate[]array<object>

Liste der anzufordernden Artefakte. Jedes Element beschreibt ein Format wie xrechnung, zugferd, peppol oder pdf.

options.generate[]

Jeder Eintrag fordert ein konkretes Ausgabeformat an.

formatstring

Pflichtfeld. Einer von xrechnung, zugferd, peppol oder pdf.

syntaxstring

Optional fuer xrechnung. Verwenden Sie ubl fuer die aktuell unterstuetzte Ausgabe.

profilestring

Optionaler Profilhinweis, zum Beispiel EN16931 fuer zugferd.

templatestring

Optionales Template, zum Beispiel default fuer pdf.

transportboolean

Reserviertes optionales Flag fuer transportbezogene Flows.

POST Antwortstruktur

Feld	Beschreibung
id	ID der gespeicherten Rechnung.
invoice_number	Eindeutige Rechnungsnummer.
customer_id	Kunden-ID, aus den buyer-Daten gefunden oder erstellt.
status	Rechnungsstatus: DRAFT, READY, SENT, PARTIALLY_PAID, PAID, OVERDUE oder CANCELLED.
currency	Waehrungscode der Rechnung.
total	Bruttosumme in Hauptwaehrungseinheiten.
open_amount	Offener Betrag. Bei Status PAID auf 0 gesetzt.
paid_amount	Bezahlter Betrag. Bei Status PAID auf total gesetzt.
cashflow_visible	Immer true fuer Rechnungen, die ueber diesen Endpunkt gespeichert wurden.
validation	Aggregiertes Validierungsergebnis ueber alle angeforderten Artefakte.
artifacts	Array der erzeugten Artefaktobjekte mit Format, Status, Validierung und Dateiinhalt.
request_id	Serverseitige Request-ID fuer Support, Logs und Idempotenz-Debugging.

GET Query-Parameter

Feld	Typ	Pflicht	Beschreibung
page	number	Nein	Seitennummer. Standard ist 1.
per_page	number	Nein	Eintraege pro Seite. Standard 25, max. 100.
status	string	Nein	Filter nach DRAFT, READY, SENT, PARTIALLY_PAID, PAID, OVERDUE oder CANCELLED.
customer_id	string	Nein	Filter nach gespeicherter Kunden-ID.
invoice_number	string	Nein	Filter nach exakter Rechnungsnummer.

GET Antwortstruktur

Feld	Beschreibung
invoices	Paginierte Rechnungszeilen inkl. Kunde, Summen, Zahlungsfelder, Zeitstempel und Positionen.
pagination	Pagination-Metadaten: page, per_page, total_items und total_pages.

POST Beispielanfrage (cURL)

curl -X POST https://www.quotecash.io/api/v1/invoices   -H "x-api-key: YOUR_API_KEY"   -H "Idempotency-Key: invoice-inv-api-001-v1"   -H "Content-Type: application/json"   -d '{
  "schema_version": "1",
  "invoice_number": "INV-API-001",
  "issue_date": "2026-07-01",
  "due_date": "2026-07-15",
  "currency": "EUR",
  "status": "SENT",
  "seller": {
    "name": "Acme GmbH",
    "street": "Alexanderplatz 1",
    "city": "Berlin",
    "postal_code": "10178",
    "country": "DE",
    "vat_id": "DE123456789",
    "email": "billing@acme.example",
    "phone": "+49 30 123456"
  },
  "buyer": {
    "name": "Alpha GmbH",
    "vat_id": "DE987654321",
    "email": "finance@alpha.example",
    "street": "Main Str 1",
    "city": "Berlin",
    "postal_code": "10115",
    "country": "DE"
  },
  "line_items": [
    {
      "description": "Consulting",
      "quantity": 2,
      "price": 500,
      "total": 1000,
      "unitCode": "HUR",
      "vatRate": 19
    }
  ],
  "totals": {
    "net": 1000,
    "tax": 190,
    "gross": 1190
  },
  "payment": {
    "iban": "DE12345678901234567890",
    "bic": "ABCDEFGHXXX"
  },
  "options": {
    "mode": "stored",
    "validate": true,
    "artifact_failure_mode": "partial",
    "generate": [
      { "format": "xrechnung", "syntax": "ubl" },
      { "format": "pdf", "template": "default" }
    ]
  }
}'

POST Beispielantwort (201)

{
  "id": "invoice-1",
  "invoice_number": "INV-API-001",
  "customer_id": "customer-1",
  "status": "SENT",
  "currency": "EUR",
  "total": 1190,
  "open_amount": 1190,
  "paid_amount": 0,
  "cashflow_visible": true,
  "validation": {
    "valid": true,
    "errors": [],
    "warnings": []
  },
  "artifacts": [
    {
      "id": "artifact-1",
      "invoice_id": "invoice-1",
      "format": "xrechnung",
      "syntax": "ubl",
      "profile": null,
      "template": null,
      "filename": "invoice-INV-API-001-xrechnung.xml",
      "mime_type": "application/xml",
      "status": "GENERATED",
      "validation": {
        "valid": true,
        "errors": [],
        "warnings": []
      },
      "error": null,
      "content_base64": "PEludm9pY2UgLi4uPg==",
      "created_at": "2026-07-01T09:00:00.000Z",
      "expires_at": null
    },
    {
      "id": "artifact-2",
      "invoice_id": "invoice-1",
      "format": "pdf",
      "syntax": null,
      "profile": null,
      "template": "default",
      "filename": "invoice-INV-API-001.pdf",
      "mime_type": "application/pdf",
      "status": "GENERATED",
      "validation": null,
      "error": null,
      "content_base64": "JVBERi0xLjQKJ...",
      "created_at": "2026-07-01T09:00:00.000Z",
      "expires_at": null
    }
  ],
  "request_id": "req_01J0QC8A7SZ3V8X6Z4M2VK0QWK"
}

GET Beispielanfrage (cURL)

curl -X GET "https://www.quotecash.io/api/v1/invoices?status=SENT&per_page=10"   -H "x-api-key: YOUR_API_KEY"

GET Beispielantwort (200)

{
  "invoices": [
    {
      "id": "invoice-1",
      "invoice_number": "INV-API-001",
      "customer_id": "customer-1",
      "customer_name": "Alpha GmbH",
      "customer_email": "finance@alpha.example",
      "date": "2026-07-01T00:00:00.000Z",
      "due_date": "2026-07-15T00:00:00.000Z",
      "status": "SENT",
      "currency": "EUR",
      "subtotal": 1000,
      "tax": 190,
      "total": 1190,
      "paid_amount": 0,
      "open_amount": 1190,
      "last_paid_at": null,
      "created_at": "2026-07-01T00:00:00.000Z",
      "items": [
        {
          "id": "item-1",
          "description": "Consulting",
          "quantity": 2,
          "price": 500,
          "tax_rate": 19,
          "total": 1000,
          "unit_code": "HUR"
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total_items": 1,
    "total_pages": 1
  }
}

Artifacts API

Artefakte sind die Ausgabeobjekte rund um den kanonischen Invoice-Lifecycle. Sie koennen an gespeicherte Rechnungen angehaengt, spaeter per artifact_id erneut geladen oder in temporaeren create-and-forget-Flows direkt erzeugt werden.

Gespeicherte Rechnungsartefakte

Verwenden Sie diesen Pfad, wenn POST /api/v1/invoices die Rechnung bereits gespeichert hat und Sie spaeter weitere Formate erzeugen, auflisten oder erneut abrufen wollen.

POST /api/v1/invoices/{id}/artifacts

GET /api/v1/invoices/{id}/artifacts

GET /api/v1/artifacts/{artifact_id}

Temporare create-and-forget-Artefakte

Verwenden Sie diese Routen nur, wenn Sie kein gespeichertes QuoteCash-Invoice-Objekt brauchen. Die Antwort enthaelt das erzeugte Artefakt direkt inline; temporaere Artefakte laufen nach etwa 24 Stunden ab.

POST /api/v1/artifacts/xrechnung

POST /api/v1/artifacts/zugferd

POST /api/v1/artifacts/peppol

POST /api/v1/artifacts/pdf

Empfohlener Pfad fuer neue Integrationen: 1) POST /api/v1/invoices mit options.generate, 2) bei Bedarf spaeter POST /api/v1/invoices/{id}/artifacts fuer weitere Formate, 3) GET /api/v1/artifacts/{artifact_id} fuer erneutes Abrufen eines konkreten Artefakts.

POST /api/v1/invoices/{id}/artifacts Request-Body

Feld	Typ	Pflicht	Beschreibung
validate	boolean	Nein	Standard ist true. Wenn true, validiert QuoteCash XML-basierte Artefakte vor der Rueckgabe.
artifact_failure_mode	string	Nein	Die API akzeptiert derzeit partial oder strict. partial bedeutet weiterlaufen und erfolgreiche Artefakte zurueckgeben; strict bedeutet Request abbrechen, sobald ein angefordertes Artefakt fehlschlaegt.
generate	array<object>	Ja	Liste der Artefakt-Requests, die fuer die gespeicherte Rechnung erzeugt werden sollen.

Artefakt-Request Referenz

generate[]

Jeder Array-Eintrag fordert genau ein Artefakt fuer eine bereits gespeicherte Rechnung an.

formatstring

Pflichtfeld. Einer von xrechnung, zugferd, peppol oder pdf.

syntaxstring

Optional fuer xrechnung. Verwenden Sie ubl fuer die derzeit unterstuetzte Ausgabe.

profilestring

Optionaler Profilhinweis, z. B. EN16931 fuer zugferd.

templatestring

Optionales Rendering-Template, z. B. default fuer pdf.

transportboolean

Reserviertes optionales Flag fuer transportbezogene Generierungsfluesse.

Artefaktobjekt Antwortstruktur

Feld	Beschreibung
id	Artefaktobjekt-ID.
invoice_id	ID der gespeicherten Rechnung, wenn das Artefakt zu einer persistierten Rechnung gehoert. Bei temporaeren Flows null.
format	Artefaktformat wie xrechnung, zugferd, peppol oder pdf.
syntax	Optionale Syntaxangabe, z. B. ubl.
profile	Optionale Profilmetadaten, z. B. EN16931.
template	Optionale Template-Metadaten fuer gerenderte Dateien wie pdf.
filename	Empfohlener Dateiname.
mime_type	Content-Type des Artefakts.
status	Artefaktstatus. Persistierte Eintraege sind typischerweise GENERATED oder FAILED.
validation	Validierungsdetails fuer XML-basierte Artefakte, wenn Validierung gelaufen ist.
error	Fehlerobjekt, wenn Generierung oder Validierung fehlgeschlagen ist.
content_base64	Base64-kodierter Dateiinhalt fuer direkte Weiterverarbeitung oder Debugging.
created_at	Zeitpunkt der Artefakterstellung.
expires_at	Ablaufzeitpunkt fuer temporaere Artefakte, sonst null.

POST Beispielanfrage

curl -X POST https://www.quotecash.io/api/v1/invoices/invoice-1/artifacts   -H "x-api-key: YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
  "validate": true,
  "artifact_failure_mode": "partial",
  "generate": [
    { "format": "zugferd", "profile": "EN16931" },
    { "format": "pdf", "template": "default" }
  ]
}'

POST Beispielantwort

{
  "artifacts": [
    {
      "id": "artifact-3",
      "invoice_id": "invoice-1",
      "format": "zugferd",
      "syntax": null,
      "profile": "EN16931",
      "template": null,
      "filename": "invoice-INV-API-001-zugferd.pdf",
      "mime_type": "application/pdf",
      "status": "GENERATED",
      "validation": {
        "valid": true,
        "errors": [],
        "warnings": []
      },
      "error": null,
      "content_base64": "JVBERi0xLjQKJ...",
      "created_at": "2026-07-01T09:05:00.000Z",
      "expires_at": null
    }
  ],
  "request_id": "req_01J0QCCS5BM8XQ3P8K5H6C4MZN"
}

GET Liste Beispiel

curl -X GET https://www.quotecash.io/api/v1/invoices/invoice-1/artifacts   -H "x-api-key: YOUR_API_KEY"

{
  "artifacts": [
    {
      "id": "artifact-1",
      "invoice_id": "invoice-1",
      "format": "xrechnung",
      "syntax": "ubl",
      "profile": null,
      "template": null,
      "filename": "invoice-INV-API-001-xrechnung.xml",
      "mime_type": "application/xml",
      "status": "GENERATED",
      "validation": {
        "valid": true,
        "errors": [],
        "warnings": []
      },
      "error": null,
      "content_base64": "PEludm9pY2UgLi4uPg==",
      "created_at": "2026-07-01T09:00:00.000Z",
      "expires_at": null
    },
    {
      "id": "artifact-2",
      "invoice_id": "invoice-1",
      "format": "pdf",
      "syntax": null,
      "profile": null,
      "template": "default",
      "filename": "invoice-INV-API-001.pdf",
      "mime_type": "application/pdf",
      "status": "GENERATED",
      "validation": null,
      "error": null,
      "content_base64": "JVBERi0xLjQKJ...",
      "created_at": "2026-07-01T09:00:00.000Z",
      "expires_at": null
    }
  ],
  "request_id": "req_01J0QCFD4E0NNQY0DGB03BNNZT"
}

GET /api/v1/artifacts/{artifact_id}

curl -X GET https://www.quotecash.io/api/v1/artifacts/artifact-1   -H "x-api-key: YOUR_API_KEY"

{
  "artifact": {
    "id": "artifact-1",
    "invoice_id": "invoice-1",
    "format": "xrechnung",
    "syntax": "ubl",
    "profile": null,
    "template": null,
    "filename": "invoice-INV-API-001-xrechnung.xml",
    "mime_type": "application/xml",
    "status": "GENERATED",
    "validation": {
      "valid": true,
      "errors": [],
      "warnings": []
    },
    "error": null,
    "content_base64": "PEludm9pY2UgLi4uPg==",
    "created_at": "2026-07-01T09:00:00.000Z",
    "expires_at": null
  },
  "request_id": "req_01J0QCG3PTWR6XK73TSN6G7TVT"
}

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

Dieser Endpunkt liefert eine business-spezifische Zahlungseingangsprognose aus gespeicherten Rechnungen: offene und ueberfaellige Forderungen, erfasste Zahlungen, nach Woche oder Monat gruppierte Zeitraeume und optionale Rechnungsdetails.

Der oeffentliche Endpoint liefert eine EUR-only rechnungsbasierte Zahlungseingangsprognose fuer den API-Key-Eigentuemer. Alle Betraege werden in Euro (EUR) verarbeitet und ausgegeben. Waehrungsumrechnung und konsolidierte Mehrwaehrungsberichte werden nicht unterstuetzt; historische Nicht-EUR-Datensaetze bleiben ausgeschlossen. Aktuelle und zukuenftige Werte gruppieren verbleibende offene Betraege nach Rechnungsfaelligkeit. Jeder API-Key gehoert zu einem Business; ein optionales business_id muss dazu passen. Das invoices-Array wird nur bei include_invoices=true zurueckgegeben. Die Vorschau enthaelt keine zukuenftigen Ausgaben oder Bankkontostaende und ist keine vollstaendige Liquiditaetsplanung.

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.
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.

Weitere v1-Helfer: GET /api/v1/invoices/open und GET /api/v1/invoices/overdue sind Convenience-Aliase fuer gefilterte Rechnungslisten, waehrend GET /api/v1/receivables/summary eine kompakte Forderungszusammenfassung liefert.

Antwortstruktur

Feld	Beschreibung
range	Normalisiertes Zeitfenster inkl. Aggregation, Waehrung und generatedAt-Zeitstempel.
filters	Spiegelt aktive Payment/Reminder-Filter sowie Pagination-Einstellungen.
summary	Gesamtsummen in range.currency inkl. openAmount, overdueAmount, paidAmountInRange, expectedIncomingInRange und Zaehler.
periods	Nach Woche oder Monat gruppierte Zeitraeume in range.currency 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 neue Integrationen. Alle Beispiele beginnen mit dem kanonischen POST /api/v1/invoices Flow und lesen danach Validierung sowie erzeugte Artefakte aus der Antwort.

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', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.QUOTECASH_API_KEY,
    'Idempotency-Key': 'invoice-inv-2026-001-v1',
  },
  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',
    },
    options: {
      mode: 'stored',
      validate: true,
      artifact_failure_mode: 'partial',
      generate: [
        { format: 'xrechnung', syntax: 'ubl' },
        { format: 'pdf', template: 'default' },
      ],
    },
  }),
});

const data = await response.json();
console.log(response.status, data.id, data.validation?.valid, data.artifacts?.[0]?.id);

LEGACY

Legacy- und create-and-forget-Generatoren

Die folgenden Einzelformat-Endpunkte bleiben fuer bestehende Integrationen dokumentiert. Fuer neue Integrationen ist POST /api/v1/invoices mit options.generate der Standardpfad. Wenn Sie wirklich keinen gespeicherten Invoice-Lifecycle benoetigen, bevorzugen Sie die temporaeren /api/v1/artifacts/*-Routen gegenueber den alten /api/v1/invoices/*-Generatoren.

LEGACYPOST

/api/v1/invoices/xrechnung

Dieser Endpunkt prueft erforderliche Request-Felder, erzeugt UBL-2.1-XML mit dem XRechnung-3.0-Customization-Identifier und validiert das Ergebnis ueber den konfigurierten externen Dienst vor der Rueckgabe. Das konkrete 3.0.x-Validator-Bundle ist nicht im Repository fixiert.

Fuer neue Integrationen: bevorzugen Sie POST /api/v1/invoices mit options.generate oder, falls keine Speicherung gewuenscht ist, POST /api/v1/artifacts/xrechnung. /api/v1/invoices/xrechnung bleibt nur aus Kompatibilitaetsgruenden erhalten.

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	Muss EUR sein. QuoteCash lehnt derzeit jede andere Rechnungswaehrung ab.
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 verwenden normale Waehrungseinheiten, nicht Cent. Positions-, Steuer- und Zahlbetraege im XRechnung-XML werden aus quantity, price und vatRate neu berechnet; uebermittelte total- und totals-Felder werden nicht in das XML kopiert.

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": "RE-2026-1042",
  "issue_date": "2026-07-24",
  "due_date": "2026-08-07",
  "currency": "EUR",
  "buyer_reference": "04011000-12345-03",
  "seller": {
    "name": "Muster GmbH",
    "vat_id": "DE123456789",
    "street": "Musterstraße 1",
    "city": "Berlin",
    "postal_code": "10115",
    "country": "DE",
    "email": "rechnung@muster.example",
    "phone": "+49 30 123456",
    "endpoint_id": "rechnung@muster.example",
    "endpoint_scheme": "EM"
  },
  "buyer": {
    "name": "Beispielkunde GmbH",
    "vat_id": "DE987654321",
    "street": "Kundenweg 2",
    "city": "Hamburg",
    "postal_code": "20095",
    "country": "DE",
    "endpoint_id": "buchhaltung@kunde.example",
    "endpoint_scheme": "EM"
  },
  "line_items": [
    {
      "description": "Implementierung E-Rechnung",
      "quantity": 1,
      "price": 1200,
      "total": 1200,
      "vatRate": 19,
      "unitCode": "C62"
    }
  ],
  "totals": {
    "net": 1200,
    "tax": 228,
    "gross": 1428
  },
  "payment": {
    "iban": "DE02120300000000202051",
    "bic": "BYLADEM1001"
  }
}'

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": "UNKNOWN",
        "message": "The configured validator marked the document invalid but returned no specific rule."
      }
    ],
    "warnings": []
  },
  "warnings": []
}

LEGACYPOST

/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 bleibt fuer kompatible Legacy-Integrationen verfuegbar, ist aber nicht mehr der primaere Developer-Pfad.

Fuer neue Integrationen: bevorzugen Sie POST /api/v1/invoices mit options.generate oder, falls keine Speicherung noetig ist, POST /api/v1/artifacts/peppol. /api/v1/invoices/peppol bleibt fuer bestehende Integrationen erhalten.

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

LEGACYPOST

/api/v1/invoices/zugferd

Dieser Endpunkt erzeugt generisches EN-16931-CII-XML, validiert das XML und haengt es bei Erfolg als factur-x.xml an ein lesbares PDF. Er beansprucht derzeit keine konkrete ZUGFeRD-/Factur-X-Version und prueft die PDF/A-Konformitaet nicht unabhaengig. Fuer neue Integrationen ist dies nur noch ein Legacy-Kompatibilitaetspfad.

Fuer neue Integrationen: bevorzugen Sie POST /api/v1/invoices mit options.generate oder, falls keine Speicherung gewuenscht ist, POST /api/v1/artifacts/zugferd. /api/v1/invoices/zugferd bleibt fuer Legacy-Clients dokumentiert.

Besteht das erzeugte CII-XML die Validierung, haengt die API factur-x.xml an und liefert 201 Created mit PDF, XML und Validierungsdetails. Schlaegt die XML-Validierung fehl, liefert sie 422 Unprocessable Content mit Diagnose-XML und Fehlern; ein PDF wird nicht zusammengebaut. Ein fehlgeschlagenes Ergebnis darf nicht als gueltige Rechnung versendet oder archiviert werden.

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-kodiertes Hybrid-PDF mit angehängter factur-x.xml. Nur nach erfolgreicher XML-Validierung; PDF/A-Konformität wird nicht unabhängig geprüft.
xml	Erzeugtes generisches EN-16931-CII-XML. Wird bei einer 422-Antwort auch zur Diagnose zurückgegeben.
validation	XML-Validierungsergebnis mit Fehlern und Warnungen des konfigurierten Validators.
filename	Empfohlener Dateiname fuer das erzeugte hybride PDF.
code	Bei Validierungsfehler als VALIDATION_FAILED vorhanden.
message	Bei Validierungsfehler vorhanden und erklaert die 422-Antwort.

Beispielantwort (422)

{
  "code": "VALIDATION_FAILED",
  "message": "Generated document failed KoSIT validation",
  "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"
}