Arbeitsanleitung22 Min. Lesezeit

Öffentliche API anbinden: Schlüssel, Berechtigungen, Felder, Abnahme

ERP oder Kasse an die öffentliche API von OrdoGrid anbinden: Schlüssel und Integrations-ID, Berechtigungen, Bruttopreise, Peppol, sichere Wiederholungen, Abnahme.

Aktualisiert
Inhaltsverantwortung
Integrationsteam
Für
Integrationsentwicklung · Lösungsarchitektur · Finanzverantwortliche einer Integration

Auf einen Blick

Legen Sie je Integration einen unternehmensgebundenen Schlüssel mit den minimal nötigen Berechtigungen und einer stabilen Integrations-ID an, ordnen Sie die Felder so zu, dass die Beträge centgenau mit Ihrer Quelle übereinstimmen (Bruttopreise eingeschlossen), prüfen Sie jeden Empfänger vor dem Peppol-Versand und weisen Sie Wiederholungen, Zahlungsausgleich und Zustellung mit echten Rechnungen vor dem Produktivstart nach. Eine Sandbox gibt es nicht: Jeder Aufruf wirkt auf echte Daten.

Bevor Sie beginnen

  • Ein Business-Tarif mit Zugang zur öffentlichen API
  • Die Rolle Inhaber oder Administrator im OrdoGrid-Unternehmen, für das die Integration handelt
  • Eine unterzeichnete Autorisation Peppol für die belgische MwSt.-Nummer des Unternehmens, wenn die Integration über Peppol sendet
  • Eine stabile Quellkennung für jede Rechnung, Gutschrift und Zahlung
  • Erwartete Beträge für repräsentative Fälle, abgestimmt mit Ihrem Controlling oder Steuerberater

Erwartete Ergebnisse

  • Ein Schlüssel mit minimalen Berechtigungen und eine dokumentierte Integrations-ID
  • Eine Feldzuordnung, die Ihre Beträge centgenau wiedergibt, Rundung eingeschlossen
  • Ein bestandenes Abnahmepaket für Wiederholungen, Peppol-Zustellung und Zahlungsausgleich
Auf dieser Seite

Über die öffentliche API von OrdoGrid (/api/v1) legt ein ERP, eine Kasse oder ein Fakturierungssystem Rechnungen, Gutschriften und Zahlungen in einem OrdoGrid-Unternehmen an und sendet sie über Peppol. Dieses Playbook führt Sie vom Schlüssel bis zum Produktivstart: Berechtigungen, centgenaue Feldzuordnung, Peppol-Versand, Wiederholungen ohne Duplikate und die Tests, die vorher bestanden sein müssen.

Es richtet sich an die Integrationsentwicklung und an die Finanzverantwortlichen, die die Beträge freigeben. Jeder Endpunkt ist in der API-Referenz beschrieben, ohne Anmeldung lesbar, zusammen mit der OpenAPI-Datei. Die Richtlinie für Wiederholungen und Störungen im Betrieb steht in Zuverlässige Integrationen.

Was das Gesetz verlangt, was wir empfehlen, was OrdoGrid tut

Was das Gesetz verlangt. Seit dem 1. Januar 2026 müssen in Belgien niedergelassene Unternehmen für Lieferungen und Dienstleistungen an belgische, mehrwertsteuerpflichtige Geschäftskunden strukturierte elektronische Rechnungen ausstellen, grundsätzlich im Format Peppol BIS über das Peppol-Netz (die Pflicht im Detail). Diese strukturierte Rechnung ist die rechtsgültige Rechnung; eine PDF-Kopie ist freiwillig. Eine Gutschrift (Kreditnote, Rechnungskorrektur), die eine strukturierte Rechnung berichtigt, muss ebenfalls über Peppol gehen. Kann der Kunde nicht empfangen, müssen Sie die Rechnung trotzdem in anderer Form ausstellen, etwa als PDF. Der FÖD Finanzen weist darauf hin, dass Peppol keine Duplikate erkennt: Diese zu vermeiden, ist Ihre Aufgabe.

Was OrdoGrid tut. Die API erzeugt das UBL-XML aus den gesendeten Feldern, prüft es vor der Zustellung gegen EN 16931 und Peppol BIS Billing 3.0.21 und archiviert das exakt übertragene XML und PDF. OrdoGrid ist über einen zertifizierten Zugangspunkt mit Peppol verbunden, und nur Unternehmen mit belgischer (BE) MwSt.-Nummer können senden. Es gibt keine Sandbox, keinen Endpunkt, der ein PDF in eine Rechnung umwandelt, und keinen API-Vorgang, der ein Dokument per E-Mail versendet.

Was wir empfehlen. Ein Schlüssel je Integration, minimale Berechtigungen, eine dauerhafte Identität für jeden Geschäftsvorfall, eine Empfängerprüfung vor jedem Peppol-Versand und vor dem Produktivstart freigegebene Sollbeträge.

Muster und Berechtigungen wählen

Ihre SituationWichtigste AufrufeBerechtigungen (Scopes)
ERP stellt Rechnungen aus und sendet sie über PeppolPOST /api/v1/invoices, danach POST /api/v1/peppol/invoices/{id}/send; oder ein Aufruf von POST /api/v1/peppol/send, mit eigenem pdf, falls Sie eines erzeugeninvoices:write, peppol:send, peppol:read
Kasse mit Anzahlungen, späteren Zahlungen und ErstattungenPOST /api/v1/invoices mit prepayments, danach .../payments und .../refundsdie vorigen, dazu credit_notes:write und payments:write
GutschriftenPOST /api/v1/credit-notes, danach POST /api/v1/peppol/credit-notes/{id}/sendcredit_notes:write, peppol:send
Reporting oder AbstimmungGET /api/v1/invoices, GET .../payments, GET /api/v1/peppol/documentsinvoices:read, peppol:read
Lieferantenrechnungen in Ihr SystemGET /api/v1/peppol/inbox, GET /api/v1/peppol/documents/{id}/xmlpeppol:read
  • Eine write-Berechtigung schließt read auf derselben Ressource ein und sonst nichts: peppol:send schließt peppol:read nicht ein, das Sie für die Empfängerprüfung, den Zustellstatus und das ausgetauschte XML brauchen.
  • POST /api/v1/peppol/send verlangt sowohl invoices:write als auch peppol:send. prepayments auf einer neuen Rechnung verlangen zusätzlich payments:write, sonst folgt 403 INSUFFICIENT_SCOPE.
  • Zahlungsverlauf und Suche nach einer Bewegung verlangen invoices:read, nicht payments:read.
  • Der Posteingang füllt sich nur, wenn das Unternehmen über OrdoGrid empfängt (Réception Peppol → Activer la réception, Empfang aktivieren).

Schlüssel erstellen und Integrations-ID festhalten

Integrations-ID

Der Namensraum eines Schlüssels, integration_id in der API. OrdoGrid speichert jede external_id je Unternehmen, Integrations-ID und Belegart, sodass Suche und Duplikatschutz nur Datensätze sehen, die unter derselben Integrations-ID angelegt wurden. Sie wird beim Erstellen festgelegt, kann nicht geändert werden und bleibt beim Rotieren erhalten.

  1. Öffnen Sie im Profilmenü API-Schlüssel und klicken Sie auf Schlüssel erstellen. Das ist den Rollen Inhaber und Administrator vorbehalten.
  2. Füllen Sie Name so aus, dass das System erkennbar ist, zum Beispiel Kasse Namur.
  3. Ersetzen Sie in Integrations-ID den Standardwert default durch einen stabilen Wert wie pos-namur (1 bis 80 Buchstaben, Ziffern, _, . oder -).
  4. Haken Sie nur die Berechtigungen aus der Tabelle oben an. Lassen Sie Läuft ab am leer für einen Schlüssel ohne Ablauf, oder richten Sie das Datum nach Ihrer Rotationsrichtlinie.
  5. Klicken Sie auf Schlüssel erstellen, kopieren Sie das Geheimnis unter Kopieren Sie diesen Schlüssel jetzt in Ihre Geheimnisverwaltung und klicken Sie auf Ich habe ihn gespeichert. Das Geheimnis beginnt mit ik_live_ und wird nur einmal angezeigt.
  6. Rufen Sie GET /api/v1/me auf und prüfen Sie Name und MwSt.-Nummer des Unternehmens, api_key.integration_id, effective_scopes, Währungen, Zahlungsmethoden und rate_limit_per_minute. Bewahren Sie die bereinigte Antwort bei Ihrer Feldzuordnung auf.
curl https://ordogrid.com/api/v1/me -H "Authorization: Bearer ik_live_..."

Der Schlüssel funktioniert auch im Header X-Api-Key. Sitzungscookies der Anwendung wirken auf dieser API nicht, und der Schlüssel selbst bestimmt das Unternehmen: Es gibt also keinen Unternehmensheader und keinen Weg zu einem anderen Unternehmen. Die Liste API-Schlüssel zeigt die Integrations-ID nach dem Erstellen nicht mehr an, und die Seite bietet keine Bearbeitung: Um Berechtigungen zu ändern, erstellen Sie einen neuen Schlüssel mit derselben Integrations-ID, stellen den Connector um und widerrufen danach den alten mit Widerrufen.

SituationWas OrdoGrid tutIntegrations-IDWas Sie tun
RotierenNeues Geheimnis mit gleichem Namen, gleichen Berechtigungen, gleichem Ablaufdatum und gleicher Integrations-ID; das alte Geheimnis funktioniert sofort nicht mehrBleibt erhaltenSetzen Sie das neue Geheimnis sofort ein
Widerrufen, dann Schlüssel erstellenDer alte Schlüssel funktioniert sofort nicht mehrdefault, sofern Sie sie nicht neu eingebenGeben Sie exakt dieselbe Integrations-ID ein
Kennzeichen Abgelaufen oder WiderrufenAufrufe liefern 401 API_KEY_EXPIRED oder 401 API_KEY_REVOKEDBleibt am alten SchlüsselErstellen Sie einen neuen Schlüssel mit derselben Integrations-ID; Rotieren übernimmt ein vergangenes Ablaufdatum

Jedes Feld ausdrücklich zuordnen

GeschäftsdatenAPI-FeldRegel
Ihre Auftrags-, Bon- oder Vertragsnummerexternal_id1 bis 200 Zeichen; nie für einen anderen Geschäftsvorfall wiederverwendet
Kundeclient (inline) oder client_idEines von beiden; für Peppol vat_number und eine vollständige address
Adressestreet, city, postal_code, countryAlle vier sind erforderlich. Verwenden Sie vorzugsweise einen zweistelligen ISO-Code wie BE. Bekannte Ländernamen auf Französisch, Niederländisch, Englisch oder Deutsch werden in diesen Code umgewandelt; ein unbekannter Wert wird beim Erstellen mit 400 INVALID_COUNTRY abgewiesen
RechnungsnummernumberWeglassen: OrdoGrid vergibt die nächste Nummer aus dem Nummernkreis des Unternehmens; eine bereits vergebene Nummer liefert 409 DOCUMENT_NUMBER_TAKEN
Bestellnummer des Kundenpurchase_orderWird zur UBL-BuyerReference
ZahlungsreferenzcommunicationWird zur UBL-PaymentID und zur BuyerReference, wenn keine Bestellnummer vorliegt
Positionenitems[]: description, quantity, unit_price, vat_rate, vat_type, unit, discountunit_price ist ein Preis ohne MwSt.
Bruttopreisprice_basis: "gross", source_unit_priceSiehe unten
MwSt.-Regelungitems[].vat_type, je Positionstandard, reverse_charge, cocontractant, intracommunity, exempt (Kleinunternehmerregelung), exempt_art44 (Befreiung nach Art. 44), zero_rated, export, margin; andere Werte liefern UNKNOWN_VAT_TYPE, und ein vat_type auf Belegebene wird als unbekanntes Feld abgelehnt
Bei Erstellung erhaltenes Geldprepayments[]Nur Rechnungen; verlangt payments:write
Ihr eigenes PDFpdf bei POST /api/v1/peppol/send oder PUT /api/v1/invoices/{id}/pdfWird byteweise übertragen und muss daher dieselben Beträge zeigen wie die Daten
Gutgeschriebene Rechnung (Gutschriften)credit_for_invoice_id oder credit_for_invoice_number für eine außerhalb von OrdoGrid ausgestellte RechnungPflicht bei POST /api/v1/credit-notes; verknüpft die Gutschrift mit der Rechnung, die sie berichtigt

Weil die BuyerReference auf die Zahlungsreferenz und dann auf die Rechnungsnummer zurückgreift, ist die Peppol-Regel, die eine Käufer- oder Bestellreferenz verlangt (PEPPOL-EN16931-R003), immer erfüllt; senden Sie die Bestellnummer des Kunden trotzdem mit, wenn Sie sie haben. Die API wählt die MwSt.-Regelung nicht: Das tut Ihr Quellsystem oder Ihr Steuerberater, nach den MwSt.-Regelungen in der Rechnungsstellung.

  • Nur zugeordnete Felder senden. Unbekannte Felder, auch in client, address und items, werden mit einem 400 abgelehnt, das sie benennt: Ein 200 oder 201 bedeutet also, dass alles Gesendete übernommen wurde.
  • Beträge sind Dezimalzeichenfolgen. EUR, USD und GBP haben zwei Nachkommastellen, JPY keine. Zu viele Nachkommastellen bei einer Bewegung werden abgelehnt (INVALID_AMOUNT_PRECISION), nie abgeschnitten. Einzelpreise und Mengen behalten ihre Genauigkeit.
  • Zeitpunkte tragen eine Zeitzone. occurred_at braucht einen ISO-8601-Versatz wie 2026-10-02T10:15:00+02:00, sonst folgt INVALID_OCCURRENCE_TIME. Belgien liegt bis zum 25. Oktober 2026 bei UTC+2, danach bei UTC+1. Antworten schreiben jeden Zeitpunkt in UTC, mit Millisekunden und Z: Diese Zahlung kommt als 2026-10-02T08:15:00.000Z zurück. Rechnen Sie für die Anzeige in Ortszeit um; Tage (issue_date, due_date) bleiben JJJJ-MM-TT.
  • Keine Währungsumrechnung. Eine Bewegung muss in der Rechnungswährung erfolgen (CURRENCY_MISMATCH). Die belgischen MwSt.-Regeln verlangen den MwSt.-Gesamtbetrag in Euro, auch bei einer Rechnung in anderer Währung: Stimmen Sie das Vorgehen mit Ihrem Steuerberater ab, bevor Sie solche Rechnungen automatisieren.
  • Eine Zahlung ist eine Bewegung, kein Etikett. Ein Bezahlt-Status ohne passende Bewegung wird mit PAYMENT_MOVEMENT_REQUIRED abgelehnt.

Bruttopreise: den Preis senden, den der Kunde gesehen hat

unit_price ist immer ein Nettopreis, und prices_include_vat ändert nur die Anzeige der Preise. Eine Kasse, die "unit_price": "12.50" mit "prices_include_vat": true sendet, berechnet also 12,50 € zuzüglich 21 % MwSt.

Senden Sie stattdessen "price_basis": "gross" und "source_unit_price": "12.50"; unit_price ist dann ein Platzhalter, der die Quelle nicht überschreibt. OrdoGrid berechnet den Nettobetrag jeder Zeile als Menge × Preis inkl. MwSt. ÷ (1 + MwSt.-Satz), auf den Cent gerundet, und danach die MwSt. einmal je Satz auf die Nettosumme. Die Differenz zwischen Ihrer Bruttosumme und Netto plus MwSt. ist totals.rounding und geht über Peppol als Rundungsbetrag (BT-114). totals.gross bleibt Netto plus MwSt.; totals.payable ist der vom Kunden geschuldete Betrag vor Anzahlungen. Feste Rabatte akzeptieren amount_basis: "net" (Standard) oder "gross". Antworten weisen die Rabatte ohne MwSt. getrennt aus: totals.line_discounts, totals.global_discount und ihre Summe totals.discounts, die auf dem PDF gedruckte Rabattsumme; global_discount gibt den erfassten Gesamtrabatt zurück. Auf Zeilen mit 0 % (Reverse Charge, innergemeinschaftliche Lieferungen, Ausfuhren) ist der Bruttopreis gleich dem Nettopreis: Senden Sie dort Nettopreise. Einzelheiten: Bruttopreise, Rabatte und Rundung.

Über Peppol senden: prüfen, senden, Ergebnis lesen

Zuerst muss ein Benutzer im Menü Peppol die Autorisation Peppol (Peppol-Vollmacht) für die MwSt.-Nummer des Unternehmens unterzeichnen (Peppol in OrdoGrid einrichten); sonst schlägt der Versand mit 403 PEPPOL_APPROVAL_REQUIRED fehl. Jeder Versand wird auf das monatliche Peppol-Kontingent des Tarifs angerechnet (403 PEPPOL_LIMIT_REACHED, Zähler und Grenze in details). Der Empfang über OrdoGrid ist für das Senden nicht nötig, doch das belgische Recht verlangt, dass Ihr Unternehmen auch Peppol-Rechnungen empfangen kann, über OrdoGrid oder einen anderen Anbieter.

  1. Empfänger prüfen. GET /api/v1/peppol/participants/BE0123456749 liefert registered und, falls gefunden, eine participant_id wie 0208:0123456749. Belgische Unternehmen sind unter ihrer Unternehmensnummer der ZDU (Zentrale Datenbank der Unternehmen, Schema 0208) registriert: Fragen Sie Kunden nicht nach einer eigenen Peppol-ID. registered: false bedeutet, dass keine Registrierung bestätigt werden konnte, weil der Kunde nicht bei Peppol registriert ist oder die Suche fehlgeschlagen ist; wiederholen Sie sie und suchen Sie bei Bedarf 0208: mit der Unternehmensnummer auf lookup.peppol.org.
  2. Senden mit POST /api/v1/peppol/invoices/{id}/send. Optional: include_pdf (Standard true), attachments (neue Dateien in Base64), attachment_ids (Dateien, die schon an der Rechnung hängen).
  3. peppol_document_id speichern, aus der Antwort, neben document_id und transmission_state.
  4. Ergebnis lesen mit GET /api/v1/peppol/invoices/{id}/status (status, lifecycle, transmission_state). In der Anwendung erscheint der Beleg unter Peppol → Outbox, wo das Kennzeichen Traité (Verarbeitet) die Zustellung im Netz bedeutet, nicht die Annahme. Die meisten Belege kommen innerhalb von Minuten bis wenigen Stunden an; dauert es länger als einen Werktag, wenden Sie sich an den OrdoGrid-Support.
  5. Archivieren Sie das ausgetauschte UBL mit GET /api/v1/peppol/documents/{peppol_document_id}/xml und das übertragene PDF mit .../pdf. Die Rechnungs-ID funktioniert dort nicht.

Ist der Kunde nicht auf Peppol, legen Sie die Rechnung mit POST /api/v1/invoices an, holen ihr PDF mit GET /api/v1/invoices/{id}/pdf und stellen es über Ihren eigenen Kanal zu, oder ein Benutzer sendet sie in der Anwendung mit Envoyer (Senden). Kann der Kunde später empfangen, senden Sie alte Rechnungen nicht erneut über Peppol; siehe Kunde nicht auf Peppol.

RouteZweckAchtung
POST /api/v1/peppol/sendAnlegen und senden in einem Aufruf"send": false legt eine echte nummerierte Rechnung an, ohne zu senden, und verlangt trotzdem die Vollmacht und freies Kontingent
POST /api/v1/peppol/invoices/{id}/sendEine bestehende Rechnung sendenEine Gutschrift-ID liefert 404
POST /api/v1/peppol/credit-notes/{id}/sendEine Gutschrift sendenGeht als UBL CreditNote (Typ 381) hinaus; eine Rechnungs-ID liefert 404
Angebote, QuittungenKeineKeine Peppol-Belege

Peppol BIS akzeptiert sechs Anhangstypen: PDF, PNG, JPEG, CSV, XLSX und ODS, und der FÖD Finanzen hält fest, dass Anhänge mit der Rechnung reisen, nicht getrennt per E-Mail. Übernehmen Sie die attachment_ids aus attachments[] von GET /api/v1/invoices/{id}; lassen Sie das Feld weg, um alle Dateien anzuhängen, oder senden Sie [] für keine. Eine ID ohne Treffer wird stillschweigend ignoriert.

Wiederholungen absichern

MechanismusGeltungsbereichDauerIdentische WiederholungAbweichender Inhalt
Header Idempotency-KeyEin API-Schlüssel; POST-Vorgänge, die ihn dokumentieren24 StundenUrsprüngliche Antwort, Header Idempotent-Replay: true409 IDEMPOTENCY_KEY_REUSED
external_id bei Rechnungen und GutschriftenUnternehmen, Integrations-ID, BelegartLäuft nicht ab; übersteht die RotationErste vollständige Antwort409 EXTERNAL_ID_REUSED
external_id bei Anzahlungen, Zahlungen, ErstattungenUnternehmen und Integrations-ID, über alle RechnungenLäuft nicht ab; übersteht die RotationUrsprüngliche Bewegung, 200, "replayed": true409 EXTERNAL_ID_REUSED

Nutzen Sie beide. PATCH, PUT und DELETE wiederholen keine Antwort. Für Belege bildet OrdoGrid einen Fingerabdruck des gesamten Erstellungsinhalts, wie gesendet: Eine geänderte Notiz oder E-Mail-Adresse, ein zusätzliches optionales Feld oder 8 statt "8" sind abweichender Inhalt. Bewahren Sie also den gesendeten Inhalt auf und wiederholen Sie ihn unverändert. Bei Bewegungen zählen Betrag, Währung, Methode, occurred_at (in UTC verglichen) und reference.

Nach einer Zeitüberschreitung oder einer verlorenen Antwort:

  1. Suchen Sie die Identität mit GET /api/v1/invoices/lookup?external_id=..., GET /api/v1/credit-notes/lookup?external_id=... oder GET /api/v1/invoices/payments/lookup?external_id=....
  2. Gefunden: Verwenden Sie diesen Datensatz. 404: Wiederholen Sie den identischen Inhalt.
  3. 409 EXTERNAL_OPERATION_IN_PROGRESS: Eine andere Anfrage legt ihn gerade an; warten Sie und wiederholen Sie danach den identischen Inhalt (die Sperre eines abgebrochenen Versuchs endet nach zwei Minuten).
  4. 502 DOCUMENT_CREATED: Der Beleg ist gespeichert, aber PDF oder Anhänge wurden nicht fertiggestellt; wiederholen Sie mit derselben external_id und demselben Inhalt.
  5. Wechseln Sie nie zu einer neuen external_id, nur weil eine Antwort verloren ging.

PEPPOL_TRANSMISSION_UNCERTAIN bedeutet, dass OrdoGrid nicht bestätigen kann, ob der Beleg hinausging: Lesen Sie den Status und klären Sie das Ergebnis mit dem OrdoGrid-Support, bevor Sie erneut senden, denn eine Zeitüberschreitung beweist keinen Fehlschlag, und Peppol kennzeichnet eine zweite Kopie nicht als Duplikat, sodass die Software des Kunden sie womöglich zweimal bucht.

Ratenbegrenzungen gelten je Schlüssel und Minute: Lesen Sie X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset, und warten Sie bei 429 RATE_LIMITED die Zeit aus Retry-After ab. Blättern Sie Listen mit limit (höchstens 100) und offset durch, bis Sie jede Zeile haben. Verzweigen Sie nach dem Fehlerfeld code, nie nach message.

Rechenbeispiel: ein Thekenverkauf mit Kartenanzahlung

Bureau Plus SRL, ein Bürobedarfsgeschäft in Namur, bindet seine Kasse mit dem Schlüssel Kasse Namur (Integrations-ID pos-namur) an. Am Freitag, dem 2. Oktober 2026, um 10:15 Uhr nimmt das Steuerbüro Cabinet Lemaire SRL, mehrwertsteuerpflichtig unter BE0123456749, 8 Tintenpatronen zu je 12,50 € inkl. 21 % MwSt. mit, zahlt 40,00 € mit Karte und überweist den Rest.

1. GET /api/v1/peppol/participants/BE0123456749 liefert "registered": true und "participant_id": "0208:0123456749".

2. Die Kasse legt die Rechnung mit dem Kassenbon als Identität an:

POST /api/v1/invoices
Authorization: Bearer ik_live_...
Idempotency-Key: pos-ticket-2026-0187-create
Content-Type: application/json

{
  "external_id": "pos-ticket-2026-0187",
  "client": {"name": "Cabinet Lemaire SRL", "vat_number": "BE0123456749",
    "address": {"street": "Rue de Fer 12", "city": "Namur", "postal_code": "5000", "country": "BE"}},
  "currency": "EUR", "issue_date": "2026-10-02", "due_date": "2026-11-02",
  "purchase_order": "LEM-2026-118",
  "items": [{"description": "Cartouche d'encre XL noire", "quantity": "8", "unit_price": "0",
    "price_basis": "gross", "source_unit_price": "12.50", "vat_rate": 21}],
  "prepayments": [{"external_id": "pos-tender-2026-0187-1", "amount": "40.00", "currency": "EUR",
    "method": "card", "occurred_at": "2026-10-02T10:15:00+02:00", "reference": "Caisse 2 / ticket 0187"}]
}

3. OrdoGrid berechnet:

SchrittBerechnungErgebnis
Vereinbarter Betrag8 × 12,50 €100,00 €
Nettobetrag100,00 € ÷ 1,21 = 82,6446… €, gerundet82,64 €
MwSt. zu 21 %82,64 € × 21 % = 17,3544 €, gerundet17,35 €
Gesetzliche Summe (totals.gross)82,64 € + 17,35 €99,99 €
Rundung (totals.rounding, BT-114)100,00 € − 99,99 €+0,01 €
Geschuldet vor der Anzahlung (totals.payable, document_total)99,99 € + 0,01 €100,00 €
Zahlbetrag (BT-115, outstanding)99,99 € − 40,00 € + 0,01 €60,00 €

Die Antwort 201 enthält die vergebene Nummer, etwa F-2026-0412, und:

{
  "external_id": "pos-ticket-2026-0187", "integration_id": "pos-namur",
  "totals": {"net": 82.64, "vat": 17.35, "gross": 99.99, "rounding": 0.01, "payable": 100.0},
  "settlement": {"document_total": "100.00", "prepayments": "40.00", "payments": "40.00",
    "credits": "0.00", "outstanding": "60.00", "refund_due": "0.00", "status": "partial"}
}

totals sind JSON-Zahlen, die Werte in settlement Dezimalzeichenfolgen: Vergleichen Sie beide als Dezimalwerte. Die Anzahlung ist bereits in payments enthalten; addieren Sie prepayments nie hinzu. In der Anwendung zeigt der Bereich Abrechnung Rechnungssumme 100,00 €, Vorauszahlungen 40,00 €, Zahlungen (inklusive Vorauszahlungen) 40,00 € und Offen 60,00 €. Die Patronen werden an der Kasse übergeben, die 40,00 € sind also eine Teilzahlung. Eine Anzahlung, die vor der Lieferung eingeht, macht die MwSt. bei Vereinnahmung fällig und muss spätestens am 15. des Folgemonats in Rechnung gestellt werden (Anzahlungsrechnung).

4. POST /api/v1/peppol/invoices/{id}/send mit leerem Inhalt. Das UBL enthält 0,01 € als Rundung (BT-114) und 60,00 € als Zahlbetrag (BT-115), wie es die Regel BR-CO-16 verlangt. Bureau Plus speichert die peppol_document_id.

5. Am Montag, dem 12. Oktober 2026, zeigt die Bank 60,00 € von Cabinet Lemaire. POST /api/v1/invoices/{id}/payments mit external_id bank-2026-10-12-07, amount "60.00", method bank_transfer, occurred_at 2026-10-12T09:30:00+02:00 liefert 201, outstanding "0.00" und status "settled".

6. Die Kasse ist wieder online und sendet die Anzahlung pos-tender-2026-0187-1 mit identischen Feldern erneut an dieselbe Zahlungsroute: OrdoGrid liefert die ursprüngliche Anzahlung mit 200 und "replayed": true zurück, und payments bleibt bei "100.00".

Fehler bei diesem VerkaufErgebnisKorrektur
"unit_price": "12.50" mit "prices_include_vat": true, ohne price_basis100,00 € netto + 21,00 € MwSt. = 121,00 €, also 21,00 € zu vielSenden Sie price_basis und source_unit_price
Anzahlung "40.004" oder occurred_at ohne VersatzINVALID_AMOUNT_PRECISION, INVALID_OCCURRENCE_TIMEAuf den Cent runden; +02:00 ergänzen
Überweisung von 60,50 € voll erfasstOVERPAYMENT, nichts erfasst60,00 € erfassen; die 0,50 € außerhalb dieser Rechnung regeln
Wiederholung neu aufgebaut mit "quantity": 8 statt "8"409 EXTERNAL_ID_REUSEDDen gespeicherten Inhalt wiederholen

Ein Abnahmepaket vor dem Produktivstart aufbauen

Jeder Aufruf legt echte, nummerierte Belege an, und jeder Versand erreicht das echte Netz. Führen Sie das Paket mit echten Geschäftsvorfällen und einem informierten Pilotkunden durch, halten Sie die Beträge klein und berichtigen Sie Fehler per Gutschrift, über Peppol, wenn die Rechnung über Peppol ging.

Nr.FallErwartetes Ergebnis
1Nettopreise zu jedem MwSt.-Satz, den Sie verwendenNetto, MwSt. und Summe centgenau wie in Ihrer Quelle; Nummer aus dem Nummernkreis des Unternehmens
2Bruttopreise (das Rechenbeispiel)rounding 0,01 und payable 100,00
3Negative Rundung: 10 × 12,50 € inkl. 21 % MwSt.Netto 103,31 €, MwSt. 21,70 €, gesetzliche Summe 125,01 €, Rundung −0,01 €, Zahlbetrag 125,00 €
4TeilgutschriftAls UBL CreditNote gesendet; outstanding sinkt; mehr als den Rest gutzuschreiben liefert CREDIT_CAPACITY_EXCEEDED
5Gutschrift auf eine bezahlte Rechnung, dann die Erstattungrefund_due erscheint und fällt danach auf null
6Anzahlung, Zahlung, wiederholte AnzahlungDie Anzahlung zählt nie doppelt
7Erstellung innerhalb von 24 Stunden und danach wiederholt; Antwort nach dem Speichern verlorenJedes Mal dieselbe Rechnung und Nummer; die Suche findet sie
8Geänderter Inhalt unter einer bestehenden external_id409 EXTERNAL_ID_REUSED; nichts angelegt
9Kunde nicht auf Peppolregistered: false; Ersatzkanal genutzt; kein Peppol-Versuch
10Zustellung und NachweiseStatus bis zur Zustellung gelesen; XML mit peppol_document_id abgerufen
11Schlüssel mit derselben Integrations-ID ersetztDie Suche findet die früheren Rechnungen
12Fehlende Berechtigung, unvollständige Adresse, unbekanntes Feld403 INSUFFICIENT_SCOPE; 400 mit dem Feldnamen

Lassen Sie das Controlling die Sollbeträge vor dem Test freigeben und gehen Sie erst live, wenn jede Abweichung erklärt ist.

Sonderfälle und häufige Fehler

FehlerFolgeRichtiges Vorgehen
Zahlungsnummern der Kasse, die jeden Tag wieder bei 1 beginnen, als external_id409 EXTERNAL_ID_REUSED ab dem zweiten Tag, denn Bewegungs-IDs sind über alle Rechnungen eindeutigIDs bilden, die sich nie wiederholen, etwa Jahr plus Bonnummer wie im Beispiel
ERP-Nummern in number, während Benutzer auch in der Anwendung Rechnungen anlegenLücken oder 409 DOCUMENT_NUMBER_TAKEN im selben NummernkreisNur ein System führt den Rechnungsnummernkreis; number weglassen
Beträge per PATCH nach einer Zahlung oder einem Peppol-Versand geändertDOCUMENT_FINANCIAL_CONTENTS_LOCKEDGutschrift und bei Bedarf eine neue Rechnung
Gutschrift zu einer Peppol-Rechnung nur als PDF versandtNicht das gesetzlich verlangte strukturierte FormatMit POST /api/v1/peppol/credit-notes/{id}/send senden
Traité oder „zugestellt“ als Freigabe gelesenZahlung einer Rechnung angemahnt, die der Käufer abgelehnt hatInvoice Responses auf der Seite Peppol verfolgen; sie erreichen OrdoGrid nur, wenn das Unternehmen dort empfängt (Activer la réception), und Käufer sind nicht verpflichtet, eine zu senden
PDF zusätzlich zum Peppol-Versand gemailtDer Kunde bucht die Rechnung womöglich zweimalNur Peppol, wenn der Kunde dort empfängt; belgische Peppol-Dienstleister raten vom Doppelversand ab

Aufzubewahrende Nachweise

  • Schlüsselverzeichnis: Name, Integrations-ID, Berechtigungen, Verantwortliche, Datum von Erstellung und Rotation; nie das Geheimnis.
  • Momentaufnahme des Vertrags: die bereinigte /me-Antwort mit Datum und contract_version, dazu die versionierte Feldzuordnung und die freigegebenen Sollbeträge.
  • Je Geschäftsvorfall: external_id, OrdoGrid-id und -Nummer, peppol_document_id, der exakt gesendete Inhalt, der Antwortcode und der code jeder Ablehnung.
  • Ablehnungskatalog: für jeden in der Abnahme aufgetretenen Code eine bereinigte Anfrage, der code und die gewählte Wiederherstellung. Testen Sie nach einer Änderung der Feldzuordnung die Wiederholungsfälle erneut: Ein neues Feld ändert den Inhalt von Belegen, die noch auf eine Wiederholung warten.
  • Belege und Zahlungen: das ausgetauschte XML und PDF, das ausgestellte PDF (GET /api/v1/invoices/{id}/pdf?view=original), bei Bedarf eine datierte Aufstellung (?view=current) und der Bewegungsverlauf (GET /api/v1/invoices/{id}/payments).

Das belgische Recht verlangt, Rechnungen 7 Jahre ab dem 1. Januar des auf die Ausstellung folgenden Jahres aufzubewahren (Art. 60 MwSt.-Gesetzbuch, geändert durch das Gesetz vom 18. Dezember 2025), und der FÖD Finanzen empfiehlt nachdrücklich, das ursprüngliche XML aufzubewahren. OrdoGrid archiviert das exakte XML und PDF jeder Übertragung mit ihren Hashwerten, ist aber kein gesetzlicher Archivierungsdienst: Bewahren Sie eigene Kopien auf.

Häufige Fragen

Gibt es eine Sandbox oder einen Testmodus?

Nein. Jeder Aufruf wirkt auf echte Unternehmensdaten, und jeder Versand erreicht das echte Peppol-Netz; auch "send": false legt eine echte nummerierte Rechnung an. Testen Sie mit echten Geschäftsvorfällen und einem Pilotkunden und berichtigen Sie Fehler per Gutschrift.

Was passiert mit meiner Integration, wenn ich einen Schlüssel rotiere?

Das alte Geheimnis funktioniert sofort nicht mehr; setzen Sie das neue also umgehend ein. Die Rotation behält Integrations-ID, Berechtigungen und Ablaufdatum bei, sodass Suche und Duplikatschutz weiter funktionieren.

Warum erhalte ich EXTERNAL_ID_REUSED, obwohl ich nur eine Notiz geändert habe?

OrdoGrid bildet den Fingerabdruck des gesamten Erstellungsinhalts, nicht nur der Beträge. Wiederholen Sie den gespeicherten Inhalt. Hat sich der Geschäftsvorfall tatsächlich geändert, behandeln Sie das als Berichtigung: eine Gutschrift und bei Bedarf eine neue Rechnung mit neuer external_id.

Kann die API eine Rechnung an einen Kunden ohne Peppol per E-Mail senden?

Nein, die öffentliche API hat keinen E-Mail-Vorgang. Holen Sie das PDF mit GET /api/v1/invoices/{id}/pdf und senden Sie es über Ihren eigenen Kanal, oder ein Benutzer sendet es in der Anwendung mit Envoyer.

Bedeutet ein Zustellstatus, dass der Kunde die Rechnung angenommen hat?

Nein, er bedeutet die Zustellung im Netz. Annahme oder Ablehnung kommt nur über eine Invoice Response, zu der Käufer nicht verpflichtet sind, und eine Zahlung nur über eine erfasste Bewegung.

Kann mein System Lieferantenrechnungen über die API empfangen?

Ja, mit peppol:read, über GET /api/v1/peppol/inbox und die XML-Route, sofern das Unternehmen über OrdoGrid empfängt. OrdoGrid bucht oder genehmigt Lieferantenrechnungen nicht; das bleibt in Ihrer Buchhaltungssoftware.

Quellen und Referenzen