Ö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 Situation | Wichtigste Aufrufe | Berechtigungen (Scopes) |
|---|---|---|
| ERP stellt Rechnungen aus und sendet sie über Peppol | POST /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 erzeugen | invoices:write, peppol:send, peppol:read |
| Kasse mit Anzahlungen, späteren Zahlungen und Erstattungen | POST /api/v1/invoices mit prepayments, danach .../payments und .../refunds | die vorigen, dazu credit_notes:write und payments:write |
| Gutschriften | POST /api/v1/credit-notes, danach POST /api/v1/peppol/credit-notes/{id}/send | credit_notes:write, peppol:send |
| Reporting oder Abstimmung | GET /api/v1/invoices, GET .../payments, GET /api/v1/peppol/documents | invoices:read, peppol:read |
| Lieferantenrechnungen in Ihr System | GET /api/v1/peppol/inbox, GET /api/v1/peppol/documents/{id}/xml | peppol:read |
- Eine
write-Berechtigung schließtreadauf derselben Ressource ein und sonst nichts:peppol:sendschließtpeppol:readnicht ein, das Sie für die Empfängerprüfung, den Zustellstatus und das ausgetauschte XML brauchen. POST /api/v1/peppol/sendverlangt sowohlinvoices:writeals auchpeppol:send.prepaymentsauf einer neuen Rechnung verlangen zusätzlichpayments:write, sonst folgt403 INSUFFICIENT_SCOPE.- Zahlungsverlauf und Suche nach einer Bewegung verlangen
invoices:read, nichtpayments: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_idin der API. OrdoGrid speichert jedeexternal_idje 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.
- Öffnen Sie im Profilmenü API-Schlüssel und klicken Sie auf Schlüssel erstellen. Das ist den Rollen Inhaber und Administrator vorbehalten.
- Füllen Sie Name so aus, dass das System erkennbar ist, zum Beispiel
Kasse Namur. - Ersetzen Sie in Integrations-ID den Standardwert
defaultdurch einen stabilen Wert wiepos-namur(1 bis 80 Buchstaben, Ziffern,_,.oder-). - 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.
- 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. - Rufen Sie
GET /api/v1/meauf und prüfen Sie Name und MwSt.-Nummer des Unternehmens,api_key.integration_id,effective_scopes, Währungen, Zahlungsmethoden undrate_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.
| Situation | Was OrdoGrid tut | Integrations-ID | Was Sie tun |
|---|---|---|---|
| Rotieren | Neues Geheimnis mit gleichem Namen, gleichen Berechtigungen, gleichem Ablaufdatum und gleicher Integrations-ID; das alte Geheimnis funktioniert sofort nicht mehr | Bleibt erhalten | Setzen Sie das neue Geheimnis sofort ein |
| Widerrufen, dann Schlüssel erstellen | Der alte Schlüssel funktioniert sofort nicht mehr | default, sofern Sie sie nicht neu eingeben | Geben Sie exakt dieselbe Integrations-ID ein |
| Kennzeichen Abgelaufen oder Widerrufen | Aufrufe liefern 401 API_KEY_EXPIRED oder 401 API_KEY_REVOKED | Bleibt am alten Schlüssel | Erstellen Sie einen neuen Schlüssel mit derselben Integrations-ID; Rotieren übernimmt ein vergangenes Ablaufdatum |
Jedes Feld ausdrücklich zuordnen
| Geschäftsdaten | API-Feld | Regel |
|---|---|---|
| Ihre Auftrags-, Bon- oder Vertragsnummer | external_id | 1 bis 200 Zeichen; nie für einen anderen Geschäftsvorfall wiederverwendet |
| Kunde | client (inline) oder client_id | Eines von beiden; für Peppol vat_number und eine vollständige address |
| Adresse | street, city, postal_code, country | Alle 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 |
| Rechnungsnummer | number | Weglassen: OrdoGrid vergibt die nächste Nummer aus dem Nummernkreis des Unternehmens; eine bereits vergebene Nummer liefert 409 DOCUMENT_NUMBER_TAKEN |
| Bestellnummer des Kunden | purchase_order | Wird zur UBL-BuyerReference |
| Zahlungsreferenz | communication | Wird zur UBL-PaymentID und zur BuyerReference, wenn keine Bestellnummer vorliegt |
| Positionen | items[]: description, quantity, unit_price, vat_rate, vat_type, unit, discount | unit_price ist ein Preis ohne MwSt. |
| Bruttopreis | price_basis: "gross", source_unit_price | Siehe unten |
| MwSt.-Regelung | items[].vat_type, je Position | standard, 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 Geld | prepayments[] | Nur Rechnungen; verlangt payments:write |
| Ihr eigenes PDF | pdf bei POST /api/v1/peppol/send oder PUT /api/v1/invoices/{id}/pdf | Wird 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 Rechnung | Pflicht 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,addressunditems, werden mit einem400abgelehnt, das sie benennt: Ein200oder201bedeutet 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_atbraucht einen ISO-8601-Versatz wie2026-10-02T10:15:00+02:00, sonst folgtINVALID_OCCURRENCE_TIME. Belgien liegt bis zum 25. Oktober 2026 bei UTC+2, danach bei UTC+1. Antworten schreiben jeden Zeitpunkt in UTC, mit Millisekunden undZ: Diese Zahlung kommt als2026-10-02T08:15:00.000Zzurück. Rechnen Sie für die Anzeige in Ortszeit um; Tage (issue_date,due_date) bleibenJJJJ-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_REQUIREDabgelehnt.
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.
- Empfänger prüfen.
GET /api/v1/peppol/participants/BE0123456749liefertregisteredund, falls gefunden, eineparticipant_idwie0208: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: falsebedeutet, 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 Bedarf0208:mit der Unternehmensnummer auf lookup.peppol.org. - Senden mit
POST /api/v1/peppol/invoices/{id}/send. Optional:include_pdf(Standardtrue),attachments(neue Dateien in Base64),attachment_ids(Dateien, die schon an der Rechnung hängen). peppol_document_idspeichern, aus der Antwort, nebendocument_idundtransmission_state.- 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. - Archivieren Sie das ausgetauschte UBL mit
GET /api/v1/peppol/documents/{peppol_document_id}/xmlund 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.
| Route | Zweck | Achtung |
|---|---|---|
POST /api/v1/peppol/send | Anlegen 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}/send | Eine bestehende Rechnung senden | Eine Gutschrift-ID liefert 404 |
POST /api/v1/peppol/credit-notes/{id}/send | Eine Gutschrift senden | Geht als UBL CreditNote (Typ 381) hinaus; eine Rechnungs-ID liefert 404 |
| Angebote, Quittungen | Keine | Keine 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
| Mechanismus | Geltungsbereich | Dauer | Identische Wiederholung | Abweichender Inhalt |
|---|---|---|---|---|
Header Idempotency-Key | Ein API-Schlüssel; POST-Vorgänge, die ihn dokumentieren | 24 Stunden | Ursprüngliche Antwort, Header Idempotent-Replay: true | 409 IDEMPOTENCY_KEY_REUSED |
external_id bei Rechnungen und Gutschriften | Unternehmen, Integrations-ID, Belegart | Läuft nicht ab; übersteht die Rotation | Erste vollständige Antwort | 409 EXTERNAL_ID_REUSED |
external_id bei Anzahlungen, Zahlungen, Erstattungen | Unternehmen und Integrations-ID, über alle Rechnungen | Läuft nicht ab; übersteht die Rotation | Ursprüngliche Bewegung, 200, "replayed": true | 409 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:
- Suchen Sie die Identität mit
GET /api/v1/invoices/lookup?external_id=...,GET /api/v1/credit-notes/lookup?external_id=...oderGET /api/v1/invoices/payments/lookup?external_id=.... - Gefunden: Verwenden Sie diesen Datensatz.
404: Wiederholen Sie den identischen Inhalt. 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).502 DOCUMENT_CREATED: Der Beleg ist gespeichert, aber PDF oder Anhänge wurden nicht fertiggestellt; wiederholen Sie mit derselbenexternal_idund demselben Inhalt.- 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:
| Schritt | Berechnung | Ergebnis |
|---|---|---|
| Vereinbarter Betrag | 8 × 12,50 € | 100,00 € |
| Nettobetrag | 100,00 € ÷ 1,21 = 82,6446… €, gerundet | 82,64 € |
| MwSt. zu 21 % | 82,64 € × 21 % = 17,3544 €, gerundet | 17,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 Verkauf | Ergebnis | Korrektur |
|---|---|---|
"unit_price": "12.50" mit "prices_include_vat": true, ohne price_basis | 100,00 € netto + 21,00 € MwSt. = 121,00 €, also 21,00 € zu viel | Senden Sie price_basis und source_unit_price |
Anzahlung "40.004" oder occurred_at ohne Versatz | INVALID_AMOUNT_PRECISION, INVALID_OCCURRENCE_TIME | Auf den Cent runden; +02:00 ergänzen |
| Überweisung von 60,50 € voll erfasst | OVERPAYMENT, nichts erfasst | 60,00 € erfassen; die 0,50 € außerhalb dieser Rechnung regeln |
Wiederholung neu aufgebaut mit "quantity": 8 statt "8" | 409 EXTERNAL_ID_REUSED | Den 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. | Fall | Erwartetes Ergebnis |
|---|---|---|
| 1 | Nettopreise zu jedem MwSt.-Satz, den Sie verwenden | Netto, MwSt. und Summe centgenau wie in Ihrer Quelle; Nummer aus dem Nummernkreis des Unternehmens |
| 2 | Bruttopreise (das Rechenbeispiel) | rounding 0,01 und payable 100,00 |
| 3 | Negative Rundung: 10 × 12,50 € inkl. 21 % MwSt. | Netto 103,31 €, MwSt. 21,70 €, gesetzliche Summe 125,01 €, Rundung −0,01 €, Zahlbetrag 125,00 € |
| 4 | Teilgutschrift | Als UBL CreditNote gesendet; outstanding sinkt; mehr als den Rest gutzuschreiben liefert CREDIT_CAPACITY_EXCEEDED |
| 5 | Gutschrift auf eine bezahlte Rechnung, dann die Erstattung | refund_due erscheint und fällt danach auf null |
| 6 | Anzahlung, Zahlung, wiederholte Anzahlung | Die Anzahlung zählt nie doppelt |
| 7 | Erstellung innerhalb von 24 Stunden und danach wiederholt; Antwort nach dem Speichern verloren | Jedes Mal dieselbe Rechnung und Nummer; die Suche findet sie |
| 8 | Geänderter Inhalt unter einer bestehenden external_id | 409 EXTERNAL_ID_REUSED; nichts angelegt |
| 9 | Kunde nicht auf Peppol | registered: false; Ersatzkanal genutzt; kein Peppol-Versuch |
| 10 | Zustellung und Nachweise | Status bis zur Zustellung gelesen; XML mit peppol_document_id abgerufen |
| 11 | Schlüssel mit derselben Integrations-ID ersetzt | Die Suche findet die früheren Rechnungen |
| 12 | Fehlende Berechtigung, unvollständige Adresse, unbekanntes Feld | 403 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
| Fehler | Folge | Richtiges Vorgehen |
|---|---|---|
Zahlungsnummern der Kasse, die jeden Tag wieder bei 1 beginnen, als external_id | 409 EXTERNAL_ID_REUSED ab dem zweiten Tag, denn Bewegungs-IDs sind über alle Rechnungen eindeutig | IDs bilden, die sich nie wiederholen, etwa Jahr plus Bonnummer wie im Beispiel |
ERP-Nummern in number, während Benutzer auch in der Anwendung Rechnungen anlegen | Lücken oder 409 DOCUMENT_NUMBER_TAKEN im selben Nummernkreis | Nur ein System führt den Rechnungsnummernkreis; number weglassen |
Beträge per PATCH nach einer Zahlung oder einem Peppol-Versand geändert | DOCUMENT_FINANCIAL_CONTENTS_LOCKED | Gutschrift und bei Bedarf eine neue Rechnung |
| Gutschrift zu einer Peppol-Rechnung nur als PDF versandt | Nicht das gesetzlich verlangte strukturierte Format | Mit POST /api/v1/peppol/credit-notes/{id}/send senden |
| Traité oder „zugestellt“ als Freigabe gelesen | Zahlung einer Rechnung angemahnt, die der Käufer abgelehnt hat | Invoice 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 gemailt | Der Kunde bucht die Rechnung womöglich zweimal | Nur 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 undcontract_version, dazu die versionierte Feldzuordnung und die freigegebenen Sollbeträge. - Je Geschäftsvorfall:
external_id, OrdoGrid-idund -Nummer,peppol_document_id, der exakt gesendete Inhalt, der Antwortcode und dercodejeder Ablehnung. - Ablehnungskatalog: für jeden in der Abnahme aufgetretenen Code eine bereinigte Anfrage, der
codeund 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
- OrdoGrid – Referenz der öffentlichen API
- OpenPeppol – Peppol BIS Billing 3.0
- FÖD Finanzen – FAQ Allgemeine Fragen zu Peppol (0208-ID, Suche, Verzögerungen)
- FÖD Finanzen – FAQ Allgemeine Fragen zur B2B-Pflicht (Kunde nicht bereit, PDF, Anhänge)
- FÖD Finanzen – FAQ Spezifische Fragen zur E-Rechnung (Gutschriften, Duplikate)
- FÖD Finanzen – Wie bewahre ich elektronisch empfangene Rechnungen auf?