Dokumente
Rechnungen und Gutschriften
Plus Selbstabrechnung und Rechnungsantworten
Formate
JSON oder UBL-XML
Basierend auf UBL 2.1, ein Dokument pro Anfrage
Veranstaltungen
Signierte Webhooks
Erhalten, zugestellt, verspätet und fehlgeschlagen
Verfügbarkeit
99,8 % pro Monat
Vertraglich, mit Leistungsgutschriften
Eine Rechnung mit einer Anfrage versenden
Senden Sie die Rechnung als JSON- oder UBL-XML-Datei an den Ausgangsendpunkt Ihres Kontos. Qvalia überprüft sie, sucht den Empfänger in Peppol und stellt sie zu. Gutschriften, Selbstabrechnungsbelege und Rechnungsantworten folgen dem gleichen Muster.
- Sandbox unter api-test.qvalia.com, Produktionsumgebung unter api.qvalia.com
- API-Schlüssel im „Authorization“-Header oder ein kurzlebiges Token (JWT)
- Ein „Idempotency-Key“-Header sorgt für sichere Wiederholungsversuche
● ● ●
Sandbox-Anfrage: Rechnung versenden
curl -X POST \
"https://api-test.qvalia.com/transaction/$ACCOUNT_REG_NO/invoices/outgoing" \
-H "Authorization: $QVALIA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d @invoice.jsonWie eine Rechnung die API durchläuft
Ihr System arbeitet mit einer API. Qvalia betreibt den dahinterstehenden Peppol-Zugangspunkt.
1. Absenden
Veröffentlichen Sie pro Anfrage ein Dokument. Sind die Daten ungültig oder ist der Empfänger nicht bei Peppol registriert, gibt die API den stabilen Fehlercode 422 zurück, bevor überhaupt etwas gesendet wird.
2. Überprüfen und bereitstellen
Qvalia prüft das Dokument anhand der geltenden Peppol-Regeln, ermittelt den Access Point des Empfängers und übermittelt das Dokument über AS4.
3. Den Status verfolgen
Webhooks melden die Zustellung, laufende Wiederholungsversuche und Fehler. Der Status-Endpunkt gibt den aktuellen Status jedes Dokuments ohne die Dokumentdaten zurück.
4. Empfangen
Eingehende Rechnungen und Antworten werden an den Endpunkten für den Eingang abgeholt. Der Lese-Endpunkt gibt ungelesene Dokumente zurück und markiert sie als gelesen, sodass beim nächsten Aufruf nur noch neue Dokumente zurückgegeben werden.
Rechnungsdokumente und Endpunkte
Jeder Weg beginnt mit /transaction/{accountRegNo}, die Registrierungsnummer Ihres Kontos. Jeder Dokumenttyp verfügt über Endpunkte für ausgehende und eingehende Daten, einen Lese-Endpunkt für ungelesene Dokumente sowie einen Status-Endpunkt.
| Dokument | Endpunkt | Peppol-Spezifikation |
| Rechnung | /invoices | Peppol BIS Billing 3.0 |
| Gutschrift | /creditnotes | Peppol BIS Billing 3.0 |
| Rechnung auf eigene Rechnung | /selfbillinginvoices | Peppol BIS – Selbstabrechnung |
| Gutschrift aus Eigenfakturierung | /selfbillingcreditnotes | Peppol BIS – Selbstabrechnung |
| Rechnungsantwort | /invoiceresponses | Peppol BIS Invoice Response |
| Antwort auf Nachrichtenebene | /messagelevelresponses | Peppol BIS Message Level Response |
Welche Dokumenttypen Ihr Konto verwendet, hängt vom jeweiligen Dienst und Tarif ab. Die Schemata für Anfragen und Antworten finden Sie in den Referenzdokumenten zur Rechnungs-API und zur Gutschrifts-API. Informationen zu allen APIs von Qvalia finden Sie unter „Peppol-APIs und Entwicklertools“.
Überprüfen Sie den Empfänger, bevor Sie die Nachricht versenden
Rufen Sie vor dem Versenden der Rechnung die „ Peppol ID “ ab. Die Antwort gibt Auskunft darüber, ob der Teilnehmer bei Peppol registriert ist und welche Dokumenttypen er empfangen kann, sodass Ihr System eine fehlende oder falsche ID kennzeichnen kann, bevor das Netzwerk die Rechnung ablehnt.
- Beschränken Sie die Suche auf einen Dokumenttyp mit
docTypeRoot, zum BeispielInvoiceoderCreditNote - „ Peppol ID “ ist das Schema und die Kennung, zum Beispiel
0007:1234567890 - Gleiche Basis-URLs und Authentifizierung wie bei der Transaktions-API
● ● ●
Sandbox-Anfrage: Empfänger suchen
curl \
"https://api-test.qvalia.com/account/$ACCOUNT_REG_NO/action/lookup/peppol/0007:1234567890?docTypeRoot=Invoice" \
-H "Authorization: $QVALIA_API_KEY"Entwickelt für die Integration in Produktionsumgebungen
Die Details, die darüber entscheiden, ob eine Integration auch bei hohem Datenaufkommen stabil läuft, sind alle in der API-Referenz dokumentiert.
- Sichere Wiederholungsversuche
Senden Sie einen Idempotenz-Schlüssel, und bei einer wiederholten Anfrage wird die ursprüngliche Antwort zurückgegeben, anstatt eine zweite Rechnung zu erstellen. - Signierte Webhooks
Jedes Ereignis verfügt über eine Ereignis-ID und – sobald Sie ein Signaturgeheimnis festgelegt haben – über eine Signatur, die Sie überprüfen können. - Ereigniswiedergabe für 30 Tage
Rufen Sie jedes zugestellte Ereignis anhand seiner ID erneut ab, beispielsweise nach einem Ausfall auf Ihrer Seite. - Status ohne Nutzdaten
Massenabgleich mit schlanken Statusdatensätzen, gefiltert nach Datum, Dokument-ID oder Aktualisierungszeit. - Ratenbegrenzungen zurücksetzen
Die Begrenzungen werden pro Konto gezählt, und eine 429-Antwort gibt an, wie lange Sie warten müssen. - Anhänge
Fügen Sie PDF-Dateien und Bilder in die Nachricht ein. Die gesamte Anfrage, einschließlich der Anhänge und der Base64-Kodierung, darf die von Peppol festgelegte Obergrenze von 100 MB nicht überschreiten.
Eine Rechnung, das Format, das jeder Empfänger benötigt
Senden Sie die Rechnung einmal. Qvalia prüft sie, ermittelt den Empfänger und übermittelt sie über das Peppol-Netzwerk als „Peppol BIS Billing “ 3.0 oder „Peppol PINT“. Ist der Empfänger nicht bei Peppol registriert, kann Qvalia die Rechnung in ausgewählten Märkten per EDI, als PDF per E-Mail, in gedruckter Form oder über B2C-Online-Banking übermitteln. Hierbei handelt es sich um zusätzliche Übermittlungskanäle, nicht um Peppol-Spezifikationen. Informieren Sie sich, welche Geschäftsnachrichtenformate Qvalia unterstützt.
Falls Ihr System keine Peppol-BIS-Rechnungen erstellen kann, laden Sie die Rechnung in dem Format hoch, in dem sie bereits erstellt wird: Svefaktura 1.0, EDIFACT INVOIC, cXML, Finvoice 3.0, XRechnung, CII oder das XML-Format in ZUGFeRD und Factur-X. Qvalia konvertiert sie in Peppol- BIS Billing 3.0, überprüft sie auf Gültigkeit und versendet sie. Siehe „Rechnungen in Ihrem bestehenden Format versenden“.
Wählen Sie Ihren Ausgangspunkt
Softwareplattformen
Integriertes Peppol
Bieten Sie Ihren eigenen Kunden die elektronische Rechnungsstellung an. Die Partner-API legt deren Konten und Peppol-IDs an, und die Rechnungsstellungs-API übermittelt deren Dokumente.
ERP- und Finanzteams
Peppol Zugangspunkt
Verbinden Sie Ihr ERP- oder Finanzsystem über die API, SFTP oder einen vorgefertigten Konnektor mit Peppol.
Entwickler
Schnellstartanleitung
Erstellen Sie Schritt für Schritt – vom API-Schlüssel bis zu Ihrer ersten Sandbox-Rechnung – mit Beispielanfragen.
Häufig gestellte Fragen zur Rechnungs-API
Was ist eine E-Invoicing-API?
Mithilfe einer E-Invoicing-API kann Ihre Software strukturierte elektronische Rechnungen senden und empfangen, ohne selbst eine Netzwerkverbindung herstellen zu müssen. Mit der Invoicing-API von Qvalia übermittelt Ihr System Rechnungen im JSON- oder UBL-XML-Format, woraufhin Qvalia diese validiert und über das Peppol-Netzwerk weiterleitet.
Welche Rechnungsdokumente kann ich versenden und empfangen?
Rechnungen, Gutschriften, Selbstrechnungen und Selbstgutschriften sowie Rechnungsantworten, jeweils mit Endpunkten für den Ausgang und den Eingang. Welche Dokumenttypen Ihr Konto verwendet, hängt vom Dienst und vom Tarif ab.
Muss ich mich mit Peppol BIS auskennen, um die API nutzen zu können?
Ihre Dokumente entsprechen dem Peppol- BIS Billing s 3.0 und liegen im UBL 2.1-basierten JSON- oder XML-Format vor. Die Beispieldaten auf api.qvalia.io zeigen eine vollständige Rechnung, und Validierungsfehler verweisen auf die zu behebende Regel. Siehe „So funktioniert die Peppol-Validierung“.
Gibt es eine Sandkiste?
Ja. Die Sandbox unter api-test.qvalia.com verwendet einen eigenen API-Schlüssel, sodass Sie Tests mit Ihren eigenen Systemen durchführen können, ohne dass echte Kunden davon betroffen sind. Der Zugriff auf die API und die Sandbox ist ab dem „Connect“- Medium -Tarif enthalten.
Wie kann ich vermeiden, dass dieselbe Rechnung zweimal versendet wird?
Senden Sie bei jeder Übermittlung einen „Idempotency-Key“-Header mit. Wenn Sie die Anfrage wiederholen, beispielsweise nach Ablauf einer Zeitüberschreitung, gibt die API die ursprüngliche Antwort zurück, anstatt ein zweites Dokument zu erstellen. Eine neue Übermittlung mit derselben Dokument-ID und demselben Empfänger führt zu einem 409-Conflict-Fehler, es sei denn, Sie wählen die Option zum Überschreiben.
Woran erkenne ich, dass eine Rechnung zugestellt wurde?
Abonnieren Sie Webhooks für Zustell- und Fehlerereignisse oder rufen Sie den Status-Endpunkt ab. Ein Webhook, den Ihr Endpunkt nicht akzeptiert, wird nicht erneut gesendet. Führen Sie daher als Sicherheitsmaßnahme regelmäßig eine Statusprüfung durch. Jedes zugestellte Ereignis kann 30 Tage lang erneut abgerufen werden.
Wie erhalte ich eingehende Rechnungen?
Abonnieren Sie den Webhook für neue Dokumente und rufen Sie anschließend die Rechnung über den Endpunkt für eingehende Daten ab. Der Lese-Endpunkt gibt ungelesene Rechnungen zurück und markiert diese als gelesen.
Was kostet die Rechnungs-API?
Der API-Zugriff ist ab dem „Connect Medium “-Tarif enthalten. Die Preise für Partner und Unternehmen richten sich nach dem Volumen und dem Bereitstellungsmodell. Siehe „Tarife und Preise“.
