Öffentliche API anbinden: Unternehmensumfang, Finanzzuordnung und Abnahme

Die öffentliche API ist eine Schnittstelle für finanzielle Geschäftsvorfälle. Entwickeln Sie anhand ihres aktuellen Vertrags und erhalten Sie die Quellidentitäten bereits ab dem ersten Prototyp. Eine erfolgreiche HTTP-Anfrage ist ein nützlicher Nachweis. Eine Unternehmensintegration muss zusätzlich erklären können, was sie erstellt hat, welchem Unternehmen es gehört und wie die Wiederherstellung Duplikate vermeidet.

Vertrag und Unternehmen ermitteln

Rufen Sie GET /api/v1/openapi.json für die tatsächliche Beschreibung der Endpunkte ab. Beginnen Sie authentifizierte Aufrufe mit GET /api/v1/me. Prüfen Sie Unternehmensidentität, Integrationsnamensraum, unterstützte Vorgänge, Zahlungsmethoden, Währungen und steuerliche Fähigkeiten. Bewahren Sie Vertragsversion und Abrufdatum zusammen mit Ihrer Zuordnung auf.

Erstellen Sie den Schlüssel über Unternehmen → API-Schlüssel mit einer berechtigten Eigentümer- oder Administratorrolle. Das Geheimnis wird nur einmal angezeigt; speichern Sie es in Ihrer freigegebenen Geheimnisverwaltung. Schlüssel sind an ein Unternehmen gebunden. Ein Unternehmensheader kann den Aufruf daher nicht zu einem anderen Mandanten umleiten. Sitzungscookies der Anwendung und Zugangsdaten der öffentlichen API sind getrennte Verfahren.

Nur die erforderlichen Vorgänge erlauben

Verwenden Sie Authorization: Bearer … oder den unterstützten Header X-Api-Key. Ermitteln Sie Berechtigungsbereiche über GET /api/v1/scopes. Schreibvorgänge für Belege benötigen den passenden Schreibbereich. payments:write ist für Geldbewegungen und bei Erstellung erfasste Anzahlungen erforderlich. Peppol-Versand und Peppol-Lesezugriff sind voneinander unabhängig.

POST /api/v1/peppol/send erstellt eine Rechnung und kann sie übertragen; deshalb sind invoices:write und peppol:send notwendig. Für das Lesen von Übertragungsnachweisen wird peppol:read benötigt. Prüfen Sie die genehmigte Unternehmensregistrierung und das Tarifkontingent getrennt von den Schlüsselberechtigungen.

Daten mit klarer Zuständigkeit zuordnen

Führen Sie eine Zuordnungstabelle mit Quellfeld, API-Feld, Typ, Umwandlung, maßgeblicher Quelle und Behandlung einer Ablehnung. Adressen benötigen Straße, Ort, Postleitzahl und Land. Unbekannte Felder werden abgelehnt; senden Sie daher nicht das vollständige Objekt des Quellsystems. Lassen Sie number bei Rechnungen weg, wenn die Unternehmenssequenz die Nummer vergeben soll.

Verwenden Sie für Zahlungsbeträge Dezimalzeichenfolgen mit der unterstützten Währungspräzision. Erfassen Sie Währung und tatsächlichen Zeitpunkt einschließlich Zeitzone bei Geldbewegungen. Schneiden Sie Werte nicht stillschweigend ab, rechnen Sie Währungen nicht unbemerkt um und leiten Sie ohne bestätigte Bewegung keine Zahlung aus einer Quellkennzeichnung „bezahlt“ ab.

Beispiel für eine Quellidentität: Ein ERP-Auftrag order-4711 wird zur Rechnung mit external_id: order-4711 im Integrationsnamensraum erp. Eine bestätigte Anzahlung erhält die eigene Bewegungsidentität tender-4711-1. Diese Werte bleiben bei wiederholten Anfragen und beim Schlüsselaustausch stabil.

Erstellung und Austausch bei Bedarf trennen

POST /api/v1/invoices erstellt den Beleg. Eine bestehende Rechnung senden Sie über POST /api/v1/peppol/invoices/{invoice_id}/send; Gutschriften verwenden den separaten Gutschriftpfad. Angebote und Quittungen haben keinen Peppol-Versandendpunkt.

Der kombinierte Endpunkt /peppol/send akzeptiert strukturierte Rechnungsfelder und optional ein mitgeliefertes PDF. Mit send: false wird ohne Netzwerkübertragung erstellt; dies eignet sich für eine kontrollierte Erstellungsprüfung. Es handelt sich dennoch um eine echte Rechnung, nicht um eine Sandbox.

Peppol überträgt strukturiertes UBL. Ein mitgeliefertes PDF ist ein Begleitdokument, keine Quelle für die Datenextraktion. BIS Billing 3.0 veröffentlicht die Syntax von Rechnungen und Gutschriften. Auf dieser öffentlichen Schnittstelle bietet das Produkt keinen OCR-Endpunkt zur Umwandlung eines PDFs in eine Rechnung.

Dauerhafte Wiederherstellung umsetzen

Senden Sie stabile external_id-Werte für Belege und Bewegungen sowie einen separaten Idempotency-Key für wiederholbare Schreibvorgänge. HTTP-Idempotenz gilt 24 Stunden und ist an den API-Schlüssel gebunden. Dauerhafte finanzielle Identitäten bleiben über dieses Zeitfenster und eine Schlüsselrotation hinaus erhalten.

Nach einer unklaren Erstellungsantwort nutzen Sie die externe Suche oder wiederholen exakt denselben Inhalt. EXTERNAL_ID_REUSED bedeutet, dass eine Identität mit abweichenden Erstellungsdaten wiederverwendet wurde; auch nichtfinanzielle Felder können betroffen sein. Bei Bewegungen betrifft der Konflikt abweichende Bewegungsinhalte. Untersuchen Sie den Konflikt und verwenden Sie den passenden Berichtigungsweg, statt eine beliebige neue ID zu erzeugen. Ein unklarer Peppol-Versand benötigt vor erneuter Übertragung einen Anbieterabgleich.

Lesen Sie Listen vollständig über alle Seiten und anhand des dokumentierten Antwortformats. Verzweigen Sie anhand des Fehlerfelds code, nicht anhand des Beschreibungstextes. Beachten Sie Rate-Limit-Header und Retry-After bei Antworten mit Status 429.

Die Abnahme mit Finanzbeispielen nachweisen

Prüfen Sie gewöhnliche Rechnung, Gutschrift, Anzahlung, Teilzahlung, ausgeführte Rückerstattung, wiederholte Erstellung, wiederholte Bewegung und verlorene Antwort. Vergleichen Sie Summen, Quell-IDs, vergebene Nummer, Zahlungsausgleich, Übertragung und archivierte XML- beziehungsweise PDF-Dateien getrennt.

Bei einer Rechnung über 121 € mit einer Anzahlung von 40 € erwarten Sie Zahlungen von 40 € und einen offenen Betrag von 81 €. Eine spätere Zahlung von 81 € gleicht die Rechnung aus. Die Wiederholung der ursprünglichen Anzahlung muss dieselbe Bewegung zurückgeben und die Zahlungen bei 121 € belassen. Addieren Sie Anzahlungen niemals erneut zu den Zahlungen.

Rufen Sie ausgestellte und aktuelle PDF-Ansichten bewusst auf: Die aktuelle Ansicht ist eine datierte Aufstellung des Zahlungsausgleichs; die ausgestellte beziehungsweise ursprüngliche Ansicht erhält die ursprüngliche Darstellung. Die Peppol-Dokumentkennung dient dem Abruf der ausgetauschten XML- und PDF-Dateien und unterscheidet sich von Rechnungs- und Anbieter-IDs.

Übergeben Sie Zuordnung, Schlüsselverantwortung, externe IDs, Überwachung, Abstimmungsverfahren und bereinigte Fehlerbeispiele. Geben Sie erst frei, wenn ungeklärte finanzielle Differenzen behoben sind. Fahren Sie mit Zuverlässige Integrationen und Monatsabschluss und Abstimmung fort.