Für Entwickler und Integrationsteams

Behalten Sie Ihr Abrechnungssystem. Verbinden Sie seine Rechnungen mit Peppol.

Erstellen Sie Rechnungen aus strukturierten Daten, senden Sie bestehende Rechnungen und Gutschriften über Peppol und rufen Sie Zustellstatus und eingegangene Belege ab. Jeder Schlüssel der öffentlichen REST-API handelt für genau ein OrdoGrid-Unternehmen. Ihr Team entwickelt und betreibt die Verbindung; die Referenz beschreibt die unterstützten Anfragen und Antworten.

API-Referenz ansehenTarife vergleichen

Die Integration an Ihrem tatsächlichen Ablauf ausrichten

Ein ERP oder Ihre eigene Abrechnungsanwendung

Erstellen Sie Kunden, Rechnungen und Gutschriften aus zugeordneten Feldern. Behalten Sie die Quellkennung, damit Wiederholungen denselben Beleg finden, statt eine zweite Rechnung auszustellen.

Ein System mit eigener PDF-Erstellung

Liefern Sie die strukturierten Rechnungsfelder und optional Ihre PDF-Darstellung. OrdoGrid erstellt daraus das UBL; diese API liest keine Rechnungsdaten aus einem PDF aus.

Rechnungseingang oder Abstimmung

Lesen Sie den Peppol-Eingang, laden Sie ausgetauschte XML- und PDF-Dateien herunter und stimmen Sie diese mit Ihrem System ab. Das Unternehmen muss über OrdoGrid empfangen, damit sich dieser Eingang füllt.

Vom Quelldatensatz zum überprüfbaren Ergebnis

  1. Einen begrenzten Unternehmensschlüssel erstellen

    Ein Inhaber oder Administrator erstellt den Schlüssel unter Unternehmen → API-Schlüssel. Wählen Sie eine stabile Integrations-ID und nur die benötigten Berechtigungen. Prüfen Sie zuerst mit GET /api/v1/me Unternehmen, Namensraum und wirksame Rechte.

  2. Die Rechnung erstellen und prüfen

    POST /api/v1/invoices nimmt eine vorhandene client_id oder eingebettete Kundendaten sowie strukturierte Rechnungspositionen an. Speichern Sie die zurückgegebene id und Nummer. Lassen Sie number weg, um die Unternehmensreihe zu nutzen; prüfen Sie Beträge, Kunde und MwSt.-Behandlung vor dem Versand.

  3. Den Empfänger prüfen und senden

    Prüfen Sie GET /api/v1/peppol/participants/{vat_number} und rufen Sie anschließend POST /api/v1/peppol/invoices/{id}/send auf. Erstellen benötigt invoices:write, Senden peppol:send. Gutschriften haben einen eigenen credit-notes-Versandpfad.

  4. Die Zustellung lesen und Dateien aufbewahren

    Rufen Sie GET /api/v1/peppol/invoices/{id}/status mit peppol:read ab. Speichern Sie document_id und peppol_document_id; letztere identifiziert das ausgetauschte XML. Übergabe an den Zugangspunkt, Netzzustellung, Kundenantwort und Zahlung sind getrennte Ergebnisse.

Drei getrennte Anfragen, eine Rechnung

Beispielhafte HTTP-Anfragen, keine interaktive Konsole. Ersetzen Sie jeden Platzhalter durch Ihren Unternehmensschlüssel, eine bestehende Kunden-ID und stabile Vorgangsschlüssel. Nutzen Sie die zurückgegebene Rechnungs-id für Versand und Status. Das Beispiel enthält zwei Einheiten zu 150 € netto und 21 % MwSt.; wählen Sie die Behandlung Ihres tatsächlichen Vorgangs.

Anfragen wirken auf echte Unternehmensdaten. Das Erstellen speichert einen echten Beleg und seine Nummer. Es gibt keine Sandbox: Senden Sie nur echte Rechnungen an einen vereinbarten Empfänger. Diese Seite führt keine Anfrage aus.

1. Die Rechnung erstellen

POST /api/v1/invoices
Authorization: Bearer <company-api-key>
Idempotency-Key: <stable-create-operation-key>
Content-Type: application/json

{
  "external_id": "your-source-order-id",
  "client_id": "<existing-client-id>",
  "currency": "EUR",
  "items": [
    {
      "description": "Beratungsleistung",
      "quantity": "2",
      "unit_price": "150.00",
      "vat_rate": 21
    }
  ]
}

2. Die geprüfte Rechnung senden

POST /api/v1/peppol/invoices/<invoice-id>/send
Authorization: Bearer <company-api-key>
Idempotency-Key: <stable-send-operation-key>
Content-Type: application/json

{ "include_pdf": true }

3. Den Peppol-Status lesen

GET /api/v1/peppol/invoices/<invoice-id>/status
Authorization: Bearer <company-api-key>

Die Erstellung liefert id und number. Versand und Status verwenden document_id für die Rechnung und peppol_document_id für ihren Peppol-Beleg, mit normalisierten Werten für status, lifecycle und transmission_state. Eine erfolgreiche Versandantwort belegt weder die Annahme durch den Kunden noch die Zahlung.

API-Referenz ansehen

Unternehmen und Berechtigungen unter Kontrolle

  • Der Schlüssel identifiziert ein Unternehmen; es gibt keinen Header zur Auswahl eines anderen Unternehmens. Sitzungscookies der App authentifizieren keine Geschäftsvorgänge der öffentlichen API.
  • Dieses Beispiel benötigt invoices:write, peppol:send und peppol:read. Ein write-Recht umfasst read derselben Ressource; peppol:send umfasst peppol:read nicht.
  • Kopieren Sie das Geheimnis einmal in Ihren serverseitigen Geheimnisspeicher. Halten Sie es aus Browsercode, URLs, Analysen und Protokollen heraus. Rotieren oder widerrufen Sie es bei Bedarf in der App.
  • Behalten Sie beim Schlüsselwechsel dieselbe Integrations-ID. Eine Rotation erhält sie; bei einem separat neu erstellten Schlüssel müssen Sie den ursprünglichen Namensraum erneut angeben.

Wiederherstellung in die Verbindung einbauen

Zwei Identitäten für Wiederholungen

Auf unterstützten POST-Pfaden gibt Idempotency-Key eine erfolgreiche Antwort 24 Stunden lang für denselben API-Schlüssel erneut zurück. Eine stabile external_id schützt die Belegerstellung je Unternehmen, Integrations-ID und Belegart darüber hinaus. Behalten Sie den ursprünglichen Anfrageinhalt unverändert.

Ein unbekanntes Ergebnis zuerst abstimmen

Suchen Sie nach einer Zeitüberschreitung die Rechnung über external_id und lesen Sie ihren Übertragungsstatus. Ein unklarer Versand kann schon im Netz sein: Halten Sie ihn an und stimmen Sie die archivierte Übertragung vor einem erneuten Versand ab. Erstellen Sie keine neue Rechnung, um einen Fehler zu umgehen.

Limits und Fehlercodes beachten

Lesen Sie die Limit-Header je Schlüssel und warten Sie bei HTTP 429 entsprechend Retry-After. Verzweigen Sie anhand des Fehlercodes, nicht des Nachrichtentexts. Lesen Sie Listen mit limit und offset vollständig aus.

Status abrufen und abstimmen

Ihre Integration liest die öffentlichen Status- und Belegpfade und übernimmt die Überwachung. Bewahren Sie das ausgetauschte XML auf und prüfen Sie Quellsummen, Zustellung und Zahlung getrennt. Die Integrationsleitfäden beschreiben Wiederherstellung und Abnahmekontrollen.

Diese Grenzen vor der Auswahl prüfen

  • Strukturierte Felder sind erforderlich. Die öffentliche API bietet weder eine Extraktion aus einem PDF allein noch einen Versand hochgeladener roher UBL-Dateien. Ein optionales PDF ist die Darstellung, nicht die Quelle für das UBL.
  • Peppol-Versand unterstützt Rechnungen und Gutschriften, keine Angebote oder Quittungen. Unternehmensvollmacht und geltendes Monatskontingent werden vor dem Versand geprüft.
  • POST /api/v1/peppol/send erstellt eine echte Rechnung, auch mit send: false. Diese Option ist keine Sandbox und prüft weiterhin Peppol-Vollmacht und Kontingent.
  • Die öffentliche API hat keinen Vorgang zum E-Mail-Versand von Belegen. Erfassen Sie Zahlungen erst nach dem tatsächlichen Geldfluss über Ihren eigenen Kanal; payments:write belastet keine Karte und überweist kein Geld.
  • Die Verbindung erfordert Feldzuordnung, Entwicklung und Betrieb. Sie ist kein fertiger Konnektor zu jedem ERP oder Steuerberater. Historie und Exporte benötigen einen eigenen Migrationsplan.

Fragen zur Rechnungsstellung über die API

Kann ich die Dokumentation ohne Konto lesen?
Ja. Die Referenz und GET /api/v1/openapi.json sind öffentlich. Geschäftsvorgänge erfordern Ihren eigenen Unternehmensschlüssel und die für den jeweiligen Vorgang angegebenen Rechte.
Kann ich die PDFs meines eigenen Systems behalten?
Ja. Liefern Sie Ihr PDF zusammen mit passenden strukturierten Daten oder laden Sie die Darstellung zur bestehenden Rechnung hoch. Die Referenz beschreibt die zulässigen Formate. Prüfen Sie vor dem Versand, dass Darstellung und strukturierte Beträge übereinstimmen.
Brauche ich die API für wenige Rechnungen pro Monat?
Meist reicht die App. Der dauerhaft kostenlose Tarif umfasst unbegrenzten Peppol-Empfang und eine versandte Rechnung pro Monat; Starter ergänzt unbegrenzten Versand. Wählen Sie Business, wenn Sie diese API oder weitere darin enthaltene Abläufe benötigen.
Kann ich Status nur mit peppol:send lesen?
Nein. Ergänzen Sie peppol:read für Empfängerprüfung, Zustellstatus, Eingang und ausgetauschte Belege. Erteilen Sie nur die für Ihre Integration benötigten Rechte.

Die Verbindung planen und umsetzen