Ganz gleich, ob Sie ein kleines Unternehmen, ein Großunternehmen oder ein Softwareanbieter sind, die API von Qvalia bietet Ihnen einen einzigen, standardbasierten Weg zur Integration mit dem Peppol-Netzwerk, mit optionaler Unterstützung für zusätzliche EDI-Flows, intelligente Dokumentenverarbeitung und Datenanreicherung.
Über den Service Invoicing API können Sie mit rechnungsbezogenen Peppol-Nachrichten wie BIS Billing (Rechnung), BIS Billing Credit Note (Gutschrift), BIS Self-Billing Invoice, BIS Self-Billing Credit Note und BIS Invoice Response arbeiten und diese bei Bedarf durch Message Level Response für technische Bestätigungen im Zusammenhang mit Rechnungen und anderen Peppol-Nachrichten ergänzen.
Die API kann:
- Helfen Sie einem kleinen Unternehmen, Peppol-Rechnungen schnell zu versenden
- Unterstützung eines großen Unternehmens mit strukturierten, umfangreichen Nachrichtenflüssen
- Leistungsfähige Fakturierungssoftware und ERP-Systeme, die eine mandantenfähige Konnektivität für viele Kunden benötigen
In diesem Leitfaden erfahren Sie, wie Sie:
- Richten Sie Qvalias Transaktions-API als Ihren Peppol- und EDI-Hub ein
- Tauschen Sie Ihre erste Peppol-Rechnung über API aus
- Erweitern Sie Ihr Angebot über Rechnungen hinaus auf Bestellungen, Kataloge und mehr
- Ermöglicht skalierbare, mehrmandantenfähige Modelle für Software-Anbieter
- Hinzufügen von erweiterten KI-gesteuerten Datenfunktionen zur Datenanreicherung und PDF-Extraktion
Überblick: API für Peppol und EDI
Die Peppol API bietet eine einheitliche Schnittstelle für elektronische Geschäftsnachrichten über Peppol und EDI. Sie wurde entwickelt, um Kernszenarien zu unterstützen, wie z.B.:
- Rechnungen und Gutschriften
- Bestellungen und Bestellungsantworten
- Auftragsänderungen und -stornierungen
- Kataloge und Artikelaktualisierungen
- Versandhinweise
- Antworten auf Nachrichtenebene und Statusaktualisierungen
Für alle Endpunkte wird ein gemeinsames Gestaltungsprinzip verwendet:
- REST-basierte HTTP-Endpunkte
- Unterstützung für JSON und XML
- UBL 2.1 als das zugrunde liegende Datenmodell
- Fehlerbehandlung mit Standard-HTTP-Statuscodes
Für Sie bedeutet das, dass Sie in Begriffen von Geschäftsnachrichten denken können, anstatt in Netzwerken und Protokollen. Sie erstellen gültige UBL-basierte Dokumente; Qvalia übernimmt die Peppol- und EDI-Schicht im Hintergrund.
Erste Schritte: Voraussetzungen und Einrichtung
Für den Einstieg in die Peppol-API von Qvalia sind nur wenige Grundlagen erforderlich:
Qvalia-Konto
Ihre Organisation wird als Qvalia-Kunde aufgenommen. Sie erhalten eine Kontoregistrierungsnummer, die Ihr Konto bei allen Transaktionsaufrufen eindeutig identifiziert.
API-Schlüssel
Die Authentifizierung erfolgt über einen API-Schlüssel, mit separaten Schlüsseln für Test- und Produktionsumgebungen. Alle Aufrufe erfolgen über HTTPS mit modernem TLS.
Kontoregistrierungsnummer im URL-Pfad
Transaktionsaufrufe enthalten Ihre accountRegNo im Pfad. Zum Beispiel:
POST /transaction/{accountRegNo}/invoices/outgoingWahl des Formats: JSON oder XML
Sie können JSON oder XML über Standard-HTTP-Header (Content-Type und Accept) auswählen. JSON ist der Standard, wenn keine ausdrückliche Wahl getroffen wird.
Sobald diese Elemente vorhanden sind, können Sie damit beginnen, den Peppol-Verkehr mit Qvalia zu testen.
Schritt für Schritt: Integration Ihres ersten Peppol-Rechnungsflusses (Senden und Empfangen)
In diesem Abschnitt wird eine typische erste Integration zwischen Ihrem System und der Transaktions-API von Qvalia beschrieben, die sowohl den Versand als auch den Empfang von Peppol-Rechnungen umfasst.
Schritt 1: Beginnen Sie in der Sandbox
Beginnen Sie mit der Integration in die Sandbox-Umgebung:
- Basis-URL (Beispiel): https://api-qa.qvalia.com
- Gleiches Authentifizierungsmodell, gleiche Endpunkte und gleiche Struktur wie in der Produktion
Auf diese Weise können Sie entwickeln und testen, ohne echte Kunden oder Finanzströme zu beeinträchtigen.
Schritt 2: Verwenden Sie Ihren API-Schlüssel und Ihre AccountRegNo
Speichern Sie in Ihrer Konfiguration:
- Ihr API-Schlüssel (für die Sandbox)
- Ihre KontoRegNummer
Jeder Antrag sollte Folgendes enthalten:
- Autorisierungskopf mit dem API-Schlüssel
- accountRegNo im Endpunktpfad, zum Beispiel:
Ausgehende Rechnungen:/transaction/{accountRegNo}/invoices/outgoing
Eingehende Rechnungen (Pull):/transaction/{accountRegNo}/invoices/incoming
Schritt 3: Wählen Sie JSON oder XML (UBL-basiert)
Alle Transaktionen verwenden UBL 2.1 als zugrunde liegenden Standard.
Sie können entweder:
- Erzeugen von UBL 2.1 XML, oder
- Verwendung der UBL-JSON-Darstellung, die dieselbe Struktur in JSON-Felder abbildet
Kopfzeilen steuern das Format:
JSON (Standard)
Content-Type: application/jsonAccept: application/jsonXML
Content-Type: application/xmlAccept: application/xmlDiese Flexibilität ermöglicht es Ihnen, die Peppol-API sowohl in JSON-first- als auch in XML-first-Umgebungen zu integrieren.
Schritt 4: Zuordnung Ihrer Rechnung zu UBL
Als nächstes bilden Sie Ihr internes Rechnungsmodell auf UBL-Elemente ab. Es stehen sowohl UBL JSON als auch UBL XML zur Verfügung.
- Kopfdaten (Rechnung, Ausstellungsdatum, InvoiceTypeCode)
- Parteien (AccountingSupplierParty, AccountingCustomerParty)
- Summen (TaxTotal, LegalMonetaryTotal)
- Zeilen (RechnungsZeile, Artikel, Preis, SteuerKategorie)
Das Ziel ist es, dies zu gewährleisten:
- Alle Pflichtfelder sind vorhanden
- Die Werte entsprechen dem jeweiligen Peppol-Profil (z.B., BIS Billing)
- Ihre eigenen geschäftlichen Anforderungen (Referenzen, Kostenstellen, Projektcodes) werden erfüllt
Anschließend serialisieren Sie diese Daten je nach gewähltem Format entweder als JSON oder XML. Für Eingangsrechnungen verwenden Sie dieselbe UBL-Struktur beim Lesen, Validieren und Zuordnen von Daten aus Qvalia in Ihr internes Modell.
Schritt 5a: Versenden einer Peppol-Ausgangsrechnung
Schritt 5.1: Versenden einer Peppol-Ausgangsrechnung
Wenn Ihre ausgehende Nutzlast bereit ist, Beispiel Endpunkt:
POST https://api-qa.qvalia.com/transaction/{accountRegNo}/invoices/outgoingEinschließen:
- Autorisierungs-Header mit Ihrem API-Schlüssel
- Korrekter Content-Type-Header (JSON oder XML)
- Die UBL-basierte Rechnungsnutzlast im Anfragekörper
Qvalia validiert die Rechnung, leitet sie über das Peppol-Netzwerk oder VAN weiter und sendet eine Antwort mit Kennungen und Status zurück.
Schritt 5.2: Empfang der eingehenden Peppol-Rechnungen
Um Eingangsrechnungen von Qvalia über die API abzurufen, müssen Sie typischerweise:
Rufen Sie z. B. den eingehenden Endpunkt an:
GET https://api-qa.qvalia.com/transaction/{accountRegNo}/invoices/incomingOptional können Sie das auch tun:
- Filter oder Seitenergebnisse (je nach Einstellung)
- Verwendung von "Lese"-Endpunkten zur Unterscheidung zwischen neuen und bereits verarbeiteten Rechnungen
Das zurückgegebene UBL JSON oder XML wird dann in Ihr internes Datenmodell zur Buchung, Genehmigung oder weiteren Verarbeitung eingefügt.
Schritt 6: Überwachung, Antworten und Fehler handhaben
Die Transaktions-API verwendet vorhersehbare HTTP-Statuscodes, die Sie Protokollen, Überwachungs- und Benutzermeldungen zuordnen können. Typische Muster:
- 200 OK - Die Anfrage war erfolgreich, und die Daten werden zurückgegeben
- 204 No Content - Erfolgreiche Anfrage, kein Body vorhanden
- 400 / 422 - Ungültige Daten oder ungültiges Schema; passen Sie Ihre Nutzdaten oder das Parsing an
- 401 / 403 - Authentifizierungs- oder Berechtigungsprobleme
- 404 - Ressource nicht gefunden (oft ein Pfad- oder ID-Problem)
- 409 - Konflikte, wie z. B. Duplikate
- 429 - Ratenlimit erreicht; verlangsamen Sie Ihre Anfragen
- 500 - Interner Fehler; wiederholen Sie den Versuch oder benachrichtigen Sie den Support, falls er bestehen bleibt
Die gleichen Muster gelten sowohl für den Versand als auch für den Empfang von Rechnungen.
Verwenden Sie das Transaktionsprotokoll für die operative Nachbereitung
Zusätzlich zu den API-Antworten können Sie sich jederzeit bei Qvalia anmelden und die Aktivitäten im Transaktionsprotokoll überprüfen. Dadurch erhalten Sie eine UI-basierte Ansicht dessen, was in Ihrer Integration geschieht, z. B.:
- Versendung und Empfang von Rechnungen
- Status für einzelne Transaktionen
- Fehlerdetails und Validierungsrückmeldungen
- Zeitstempel auf technischer und geschäftlicher Ebene
Das Transaktionsprotokoll ist nützlich für:
- First-Line-Support und operative Teams, die nicht direkt mit der API arbeiten
- Behebung spezifischer Probleme, die von Kunden oder internen Nutzern gemeldet werden
- Überprüfung, ob sich Änderungen an Ihrer Integration in der Produktion wie erwartet verhalten
Zusammen ergeben die HTTP-Statuscodes und das Transaktionsprotokoll ein vollständiges Bild: Ihr System kann programmatisch auf Antworten reagieren, während Ihr Team bei Bedarf direkt in Qvalia Untersuchungen und Folgemaßnahmen durchführen kann.
Jenseits von Rechnungen: Erweitern Sie Ihren Peppol API Anwendungsfall
Sobald Sie über Rechnungen verfügen, können Sie Ihre Integration problemlos auf ein vollständiges Peppol-Nachrichtenportfolio ausweiten.
Typische Erweiterungen sind:
Aufträge. Empfangen und senden Sie strukturierte Bestellungen elektronisch
Antworten und Änderungen von Bestellungen. Bestätigen, Ändern oder Stornieren von Bestellungen
Kataloge. Pflegen Sie Produkt- und Preisinformationen in elektronischen Katalogen
Versandanzeigen. Übermittlung von Versandinformationen
Antworten auf Nachrichtenebene. Verfolgen von Bestätigungen auf technischer und geschäftlicher Ebene
Da für all dies dasselbe API-Design, Authentifizierungsmodell und UBL 2.1-Datenmodell verwendet wird, benötigen Sie keine separaten Projekte oder Gateways für jeden Dokumententyp. Sie ermöglichen neue Anwendungsfälle, wenn sich Ihr Unternehmen oder die Anforderungen Ihrer Kunden weiterentwickeln.
Hier wird das Versprechen "eine Peppol-API für jeden Bedarf" greifbar: dieselbe Integration dient kleinen Anbietern, großen Unternehmen und komplexen Plattformszenarien.
Partner-API für Fakturierungssoftware und ERPs
Wenn Sie ein Software-Anbieter sind, der eine Rechnungsstellungsplattform, ein ERP, eine Buchhaltungslösung oder eine Integrationsplattform betreibt, sind Ihre Anforderungen etwas anders. Mit der Partner-API von Qvalia können Sie eine mandantenfähige Konfiguration für den Austausch von Nachrichten für Endnutzer einrichten, einschließlich der Verwaltung von Peppol ID .
Die Partner-API für Peppol wird benötigt, wenn Sie es brauchen:
- Bedienen Sie viele Endkunden von einer Plattform aus
- Eine klare Trennung zwischen den Daten und Transaktionen der einzelnen Kunden aufrechterhalten
- Vermeiden Sie den Betrieb eines eigenen Peppol-Zugangspunkts oder EDI-Gateways
Das partnerorientierte Modell von Qvalia ist speziell für diesen Zweck konzipiert.
Wie die Partnereinrichtung funktioniert
- Ihr Unternehmen wird als Partner aufgenommen und erhält eine Partner-Kennung.
- Sie können zwischen zwei Methoden für die Verwaltung von Endbenutzernachrichten wählen: 1) ein konsolidiertes gemeinsames Benutzerkonto oder 2) individuelle Qvalia-Konten für jeden Endbenutzer, jedes mit einer eigenen accountRegNo.
- API-Aufrufe umfassen sowohl Ihren Partnerkontext als auch das spezifische Kundenkonto, so dass Sie in dessen Namen Nachrichten senden und empfangen können.
Beispiel: Implementierung durch Partner
Onboarding
- Ihr Unternehmen erhält Partneranmeldedaten und eine Konfiguration, einschließlich einer PartnerRegNo und eines API-Schlüssels.
- Sie richten eine einzelne Integration in die API von Qvalia ein, indem Sie die
/partner/{partnerRegNo}Präfix für alle partnerbezogenen Anrufe.
Onboarding von Kunden in Ihr Produkt
- Wenn ein Kunde Peppol/e-invoicing in Ihrer Benutzeroberfläche aktiviert, wird ein Qvalia-Konto für diesen Kunden erstellt oder verknüpft.
- Sie speichern die accountRegNo des Kunden zusammen mit Ihrer eigenen Kunden-ID, so dass Sie Transaktionen pro Kunde adressieren können.
Senden und Empfangen von Transaktionen pro Kunde
Ihre Anwendung generiert oder konsumiert UBL-Payloads (Rechnungen, Bestellungen usw.) auf die gleiche Weise wie die Standard-Transaktions-API. Um Transaktionen im Namen eines bestimmten Kunden zu senden oder zu empfangen, rufen Sie die Transaktions-API über das URI-Muster mit Partnerpräfix auf:
/partner/{partnerRegNo}/transaction/{accountRegNo}/{message-type}/{direction}Zum Beispiel:
- Versenden einer Ausgangsrechnung:
/partner/{partnerRegNo}/transaction/{accountRegNo}/invoices/outgoing(POST) - Abruf von Eingangsrechnungen:
/partner/{partnerRegNo}/transaction/{accountRegNo}/invoices/incoming(GET) - Verwendung von
readVarianten gegebenenfalls durch Hinzufügen vonreadauf dem Weg.
Qvalia leitet und empfängt Nachrichten so, als ob sie direkt vom Kunden gesendet oder empfangen würden, mit vollständiger Rückverfolgbarkeit pro Konto.
Vorteile für Software-Anbieter
- Eine technische Integration, viele Kunden, die ein einheitliches Partner- und Kontomodell verwenden.
- Sie müssen kein eigenes Peppol- oder EDI-Backbone betreiben und warten.
- Einfache Skalierung auf neue Märkte, Mandate und Nachrichtentypen durch Wiederverwendung desselben Partnerintegrationsmusters.
Zusätzliche Funktionalität: KI-Agentenanreicherung
Neben Transport und Konnektivität bietet Qvalia auch die Enrichment-API, die Transaktionen mit Positionsklassifizierung, Vor- und Nachbearbeitung von Transaktionen und vielem mehr anreichern kann und PDF-Dokumente mit minimalem Aufwand in reichhaltige, strukturierte und validierte Daten extrahieren und umwandeln kann.
Die Anreicherungs-API ist als asynchroner Dienst konzipiert:
- Sie übermitteln eine Rechnungsdatei (z. B. PDF oder XML) über die API.
- Sie erhalten eine pollingId in der Antwort.
- Sie fragen den Status ab, bis die Anreicherung abgeschlossen ist.
- Sie rufen ein strukturiertes JSON-Ergebnis mit angereicherten Informationen ab.
Dieses Ergebnis kann Folgendes beinhalten:
- Geparster Rechnungsinhalt, extrahiert aus der Originaldatei
- Validierung gegen Peppol oder andere Geschäftsregeln
- Normalisierte Felder, die sich für Analysen, Automatisierung und KI-Workflows eignen
Umsetzungsmuster
Eine typische Integration sieht wie folgt aus:
Einreichen einer Rechnung zur Anreicherung
Rufen Sie einen Endpunkt auf, fügen Sie die Rechnungsdatei und alle relevanten Metadaten an, und
Speichern Sie die zurückgegebene pollingId.
POST /enrichment/{accountRegNo}/invoiceAbfrage nach Abschluss
Aufruf in sicheren Abständen. Während der Verarbeitung bestätigt die API, dass der Auftrag noch läuft. Nach Beendigung gibt sie einen Status zurück und verweist auf das Anreicherungsergebnis.
GET /enrichment/{accountRegNo}/{pollingId}Abrufen bestimmter Anreicherungstypen
Rufen Sie eine bestimmte Anreicherungsausgabe ab, z. B. detaillierte Rechnungsdaten oder Peppol-Validierungsergebnisse. Geben Sie diese in Ihre Buchhaltungs-Engine, Ihren Analyse-Stack oder Ihre Automatisierungslogik ein.
GET /enrichment/{accountRegNo}/{pollingId}/{enrichmentType}Anwendungsfälle
- Kleine Unternehmen
können von der intelligenten Dokumentenverarbeitung auf Unternehmensebene profitieren; saubere, strukturierte Daten ohne Investitionen in komplexe OCR- oder Validierungstools. - Large Unternehmen
können Rechnungs- und Dokumentendaten über alle Einheiten, Systeme und Regionen hinweg standardisieren und eine bessere Datenkontrolle, Analyse und Automatisierung der Buchhaltung ermöglichen. - Softwareanbieter und Partner
können erweiterte Anreicherungsfunktionen direkt in ihre Produkte einbetten, ohne eigene Parsing- und Regel-Engines entwickeln zu müssen.
In allen Fällen ist der Zugang zu dieser Technologie einfach: dasselbe Konten- und Sicherheitsmodell wie bei der Transaktions-API und eine kleine Anzahl klar definierter Endpunkte.
Peppol API-Zugang für jedes Unternehmen
Qvalias API wurde entwickelt, um Ihnen einen vereinfachten, skalierbaren Zugangspunkt zum Peppol-Netzwerk zu bieten, unabhängig von der Art Ihres Unternehmens:
- Ein kleines Unternehmen, das konforme elektronische Rechnungen austauschen muss
- Ein großes Unternehmen, das große Mengen an Datenströmen mit mehreren Einheiten verwaltet
- Ein Softwareanbieter, der Rechnungs-, ERP- oder Finanzlösungen für viele Kunden anbietet
Ihr nächster Schritt ist einfach: Verbinden Sie sich mit der Sandbox, senden Sie Ihre erste Testrechnung und beginnen Sie mit der Planung, wie Peppol, EDI und Enrichment ein integrierter Bestandteil Ihrer Abläufe oder Ihres Produkts werden können - und nicht ein separates, komplexes Projekt.
