Zuverlässige Integrationen: Wiederholung, unklarer Versand, Abgleich
OrdoGrid-API-Aufrufe ohne doppelte Rechnung oder Zahlung wiederholen: stabile external_id, Integrations-ID, Idempotency-Key, Fehlercodes, unklarer Peppol-Versand.
- Aktualisiert
- Inhaltsverantwortung
- Integrationsbetrieb
- Für
- Integrationsentwicklung · Integrationsbetrieb · Finanzcontrolling
Auf einen Blick
Geben Sie jedem Geschäftsereignis eine stabile external_id unter einer festen Integrations-ID, ordnen Sie jede Antwort vor einer Wiederholung anhand ihres Codes ein und suchen Sie das Ereignis nach jeder Zeitüberschreitung. Verwenden Sie nach einer verlorenen Antwort nie eine neue ID, und halten Sie einen unklaren Peppol-Versand an, bis OrdoGrid das Ergebnis bestätigt hat.
Bevor Sie beginnen
- Ein Business-Tarif mit Zugang zur öffentlichen API
- Ein OrdoGrid-API-Schlüssel mit nur den nötigen Berechtigungen und einer bekannten Integrations-ID
- Ein Quellsystem, das je Rechnung, Gutschrift und Zahlung eine stabile ID ableiten kann
- Bereinigte Protokolle der Anfragen und Antworten sowie eine benannte Verantwortung für die Wiederholungswarteschlange
Erwartete Ergebnisse
- Eine Wiederholungsstrategie auf Basis der Fehlercodes, mit getesteten Grenzen und Wartezeiten
- Keine doppelte Rechnung, Gutschrift oder Zahlung nach Zeitüberschreitung, Absturz oder Schlüsselrotation
- Eine überwachte Warteschlange, in der jeder angehaltene Eintrag eine Verantwortung und eine Entscheidung hat
Auf dieser Seite
Eine Integration ist zuverlässig, wenn sie einen Geschäftsvorfall nach einer verlorenen HTTP-Antwort, einer abgebrochenen Verarbeitung oder einer unklaren Übergabe an Peppol wiederherstellen kann, ohne eine zweite Rechnung, Zahlung oder Übertragung zu erzeugen. „Dreimal wiederholen“ reicht dafür nicht: Manche Anfragen werden abgelehnt, bevor etwas gespeichert ist, andere scheitern, nachdem OrdoGrid die Rechnung bereits nummeriert oder die Zahlung bereits erfasst hat. Dieses Playbook legt fest, welche Identitäten Sie behalten, wie Sie jede Antwort einordnen, wann Sie wiederholen, wann Sie anhalten und was Sie überwachen.
Es richtet sich an Entwicklung und Betrieb von Konnektoren für die öffentliche OrdoGrid-API (/api/v1). Schlüssel, Berechtigungen und Datenzuordnung behandelt API-Integration, die Koordination einer laufenden Störung Rechnungsstörung, die Bedeutung der Badges Peppol-Zustellstatus. Der vollständige Vertrag ist die API-Referenz.
Warum Duplikate teuer sind
| Was gilt | |
|---|---|
| Das Gesetz | Jede Rechnung trägt eine eindeutige fortlaufende Nummer und wird im Ausgangsrechnungsbuch erfasst (Königlicher Erlass Nr. 1, Art. 5 §1 Nr. 1); sie ist spätestens am 15. des Monats nach dem Steuertatbestand auszustellen (Art. 4 §1). Ein Dokument, das eine strukturierte Rechnung berichtigt, wird im selben Format ausgestellt (Art. 53 §2bis MwSt.-Gesetzbuch): Ein über Peppol versandtes Duplikat wird also mit einer Gutschrift (Kreditnote, Rechnungskorrektur) über Peppol berichtigt (FAQ, F5), nicht gelöscht. |
| FÖD Finanzen | Peppol erkennt keine Duplikate; sie aufzuspüren ist Aufgabe des Nutzers und seiner Software (FAQ spezifische Fragen, F4). Die Zustellung dauert meist einige Minuten bis wenige Stunden; Verzögerungen über einen Werktag melden Sie Ihrem Softwareanbieter (Peppol-FAQ, F9). |
| OrdoGrid | Dauerhafte external_id-Identitäten, 24-stündiges Replay (Rückgabe der gespeicherten Antwort) über Idempotency-Key, eine ausgehende Übertragung je Rechnung und eine Sperre für jeden erneuten Versand, solange das Ergebnis unklar ist. Diese Schutzmechanismen wirken nur, wenn Ihr Konnektor dieselben Identitäten behält. |
| Unsere Empfehlung | Das Verzeichnis, die Wiederholungsgrenzen, das Anhalten und die Alarme unten: Vorschläge, die Sie an Ihre Mengen anpassen, keine Leistungszusagen von OrdoGrid. |
Vier Schutzmechanismen und ihre Grenzen
| Schutz | Geltungsbereich und Dauer | Verhindert | Verhindert nicht |
|---|---|---|---|
Header Idempotency-Key | Der aufrufende API-Schlüssel; 24 Stunden | Eine zweite Ausführung desselben POST: Eine identische Wiederholung liefert die gespeicherte Erfolgsantwort mit Idempotent-Replay: true | Einen anderen Inhalt unter demselben Schlüssel (409 IDEMPOTENCY_KEY_REUSED); eine erneute Ausführung nach einem fehlgeschlagenen Aufruf (der Schlüssel wird freigegeben); PATCH, PUT, DELETE; eine Wiederholung unter einem rotierten Schlüssel |
external_id eines Belegs | Unternehmen, Integrations-ID und Belegart; ohne Ablauf, übersteht die Rotation | Eine zweite Rechnung oder Gutschrift für dieselbe Quelltransaktion | Eine neue ID; eine andere Integrations-ID; jede Änderung am Erstellungsinhalt (409 EXTERNAL_ID_REUSED) |
external_id einer Bewegung | Unternehmen und Integrations-ID, über alle Rechnungen und Bewegungsarten hinweg; ohne Ablauf | Dasselbe Geld doppelt zu zählen: Eine Wiederholung liefert die ursprüngliche Bewegung mit replayed: true | Eine Änderung von Betrag, Währung, Zahlungsart, Zeitpunkt oder Referenz oder dieselbe ID auf einer anderen Rechnung (EXTERNAL_ID_REUSED) |
| Peppol-Übertragungsschutz | Eine Übertragung je Rechnung oder Gutschrift | Eine zweite Übertragung: Ein angenommener Versand kommt mit replayed: true zurück, ein unklarer wird abgelehnt | Eine neue Rechnung für denselben Verkauf; ein PDF per E-Mail |
Verwenden Sie beides: Idempotency-Key macht eine sofortige Wiederholung günstig, external_id ermöglicht die Wiederherstellung nach 24 Stunden oder nach einem Schlüsselwechsel. Die API nimmt Belege auch ohne external_id an; behandeln Sie sie trotzdem als Pflichtfeld – bei Bewegungen ist sie Pflicht.
- Integrations-ID
- Der Namensraum eines API-Schlüssels (
integration_idin der API, Integrations-ID auf der Seite API-Schlüssel). Jedeexternal_idwird im Namensraum des aufrufenden Schlüssels gesucht. Bis zu 80 Buchstaben, Ziffern,_,.oder-; bei der Erstellung festgelegt; das Feld steht standardmäßig aufdefault.
Ein Identitätsverzeichnis führen
Führen Sie eine Zeile je Geschäftsereignis, nicht je HTTP-Anfrage: Quellereignis und external_id (SO-58213), Integrations-ID (erp-prod), Belegart, den exakt gesendeten Inhalt oder dessen SHA-256, den Idempotency-Key, OrdoGrid-id, number und peppol_document_id, jede Bewegung mit allen Feldern, das letzte Ergebnis mit UTC-Zeit und code sowie den Zustand in der Warteschlange mit seiner Verantwortung.
- Leiten Sie die ID aus dem Geschäftsereignis ab (1 bis 200 Zeichen). Eine UUID je Anfrage schaltet alle Schutzmechanismen oben ab.
- Frieren Sie den Inhalt bei der ersten Übermittlung ein und senden Sie ihn unverändert erneut. OrdoGrid bildet einen Fingerabdruck des gesamten Erstellungsinhalts: Ein ERP, das die Anfrage mit korrigierter E-Mail-Adresse oder Fälligkeit neu aufbaut, löst
EXTERNAL_ID_REUSEDaus. - Lassen Sie
numberweg, damit die Nummernfolge des Unternehmens sie vergibt. Eigene Nummern plus eine Wiederholung ohneexternal_idergeben409 DOCUMENT_NUMBER_TAKEN. - Tragen Sie in
referencejeder Bewegung eine lesbare Quellreferenz ein; die Buchhaltung sieht sie im Bewegungsverlauf des Bereichs Abrechnung der Rechnung. Halten Sie sie bei jeder Wiederholung identisch. - Schützen Sie das Verzeichnis. Eine Korrektur ist eine neue Zeile mit Verweis auf die alte, nie eine geänderte ID.
Den Namensraum beim Schlüsselwechsel behalten
Auf der Seite API-Schlüssel (Inhaber und Administratoren):
- Rotieren erzeugt einen neuen Schlüssel mit demselben Namen, denselben Berechtigungen, demselben Ablaufdatum und derselben Integrations-ID; der alte Schlüssel funktioniert sofort nicht mehr. Kopieren Sie das neue Geheimnis unter Kopieren Sie diesen Schlüssel jetzt: Es wird nur einmal angezeigt.
- Ein Ersatzschlüssel über Schlüssel erstellen braucht genau die alte Integrations-ID. Bleibt sie auf
default, liefern Suchen404und Wiederholungen legen neue Rechnungen oder Zahlungen an. - Die Schlüsselliste zeigt die Integrations-ID nicht: Rufen Sie
GET /api/v1/meauf und vergleichen Sieapi_key.integration_idmit Ihrem Verzeichnis, bevor Sie neu starten. - Die HTTP-Replay-Daten gehören zum alten Schlüssel; ermitteln Sie nach einer Rotation den Stand über die Suche nach
external_id.
Jedes Ergebnis vor der Wiederholung einordnen
Entscheiden Sie anhand des Fehler-code, nie anhand des Meldungstexts. Alles, was hier fehlt: Behandeln Sie das Ergebnis als unbekannt und suchen Sie das Ereignis.
Belege und Geldbewegungen
| Antwort | Gespeichert? | Maßnahme |
|---|---|---|
201; oder Idempotent-Replay: true oder replayed: true (200 bei Bewegungen) | Ja | id und number festhalten. Ein Replay liefert das erste Ergebnis erneut, keinen neuen Verkauf und keine neue Zahlung |
Zeitüberschreitung, Verbindungsabbruch, 5xx ohne hier genannten Code | Unbekannt | Zuerst über external_id suchen: GET /api/v1/invoices/lookup oder /api/v1/credit-notes/lookup für Belege, GET /api/v1/invoices/payments/lookup für Bewegungen |
400 VALIDATION_ERROR, UNKNOWN_FIELD, INVALID_AMOUNT_PRECISION, CURRENCY_MISMATCH, INVALID_OCCURRENCE_TIME, UNKNOWN_VAT_TYPE | Nein | Zuordnung berichtigen; den korrigierten Inhalt unter derselben external_id senden (kommt EXTERNAL_ID_REUSED, siehe Sonderfälle). Keine automatische Wiederholung |
401 API_KEY_EXPIRED, API_KEY_REVOKED, INVALID_API_KEY; 403 INSUFFICIENT_SCOPE | Nein | Warteschlange anhalten. INVALID_API_KEY: das konfigurierte Geheimnis prüfen. Durch Rotieren widerrufener Schlüssel: das neue Geheimnis einsetzen. Abgelaufener oder aus anderem Grund widerrufener Schlüssel oder fehlende Berechtigungen: Rotieren hilft nicht (es behält Berechtigungen und Ablaufdatum bei und wird für abgelaufene oder widerrufene Schlüssel nicht angeboten); daher über Schlüssel erstellen einen neuen Schlüssel anlegen, genau die alte Integrations-ID eintragen, sie mit GET /api/v1/me prüfen und dann mit denselben Identitäten fortfahren |
429 RATE_LIMITED | Nein | Retry-After Sekunden warten; drosseln |
409 IDEMPOTENT_REQUEST_IN_PROGRESS | Erster Aufruf läuft noch | Einige Sekunden warten; mit demselben Schlüssel und Inhalt wiederholen |
409 EXTERNAL_OPERATION_IN_PROGRESS | Ein anderer Aufruf hält die Identität | Länger als zwei Minuten warten (die Ausführungssperre), dann suchen |
409 IDEMPOTENCY_KEY_REUSED oder EXTERNAL_ID_REUSED | Erste Fassung besteht oder ist reserviert | Anhalten; gespeicherten und neuen Inhalt vergleichen; nie mit neuem Schlüssel oder neuer ID umgehen |
409 SETTLEMENT_CONFLICT | Nein | Gleichzeitige Änderung an der Rechnung; nach einer Wartezeit mit derselben external_id wiederholen |
409 OVERPAYMENT, OVER_REFUND | Nein | Nicht wiederholen; prüfen, ob das Geld schon unter einer anderen ID erfasst ist |
409 DOCUMENT_FINANCIAL_CONTENTS_LOCKED bei einer Änderung | Nein | Eine Zahlung ist erfasst, die Rechnung ist für Peppol vorbereitet oder über Peppol versandt, oder der Beleg ist eine gespeicherte Gutschrift: nicht ändern; mit einer neuen Gutschrift oder Rechnung berichtigen |
502 DOCUMENT_CREATED | Ja, PDF oder Anhänge unvollständig | Identischen Inhalt unter derselben external_id senden, um ihn abzuschließen; ohne external_id details.document_id verwenden und nie erneut anlegen |
Anfragelimits gelten je Schlüssel und Minute (standardmäßig 120); lesen Sie X-RateLimit-Remaining und X-RateLimit-Reset (in Sekunden), statt die Zahl fest einzuprogrammieren.
Peppol-Versand
Lesen Sie GET /api/v1/peppol/invoices/{id}/status (oder das Gegenstück für Gutschriften) mit der Berechtigung peppol:read. transmission_state beschreibt die Übergabe durch OrdoGrid an seinen Zugangspunkt; status folgt der Zustellung und entspricht den Badges in Peppol → Outbox (processed ist Traité).
Code oder transmission_state | Bedeutung | Maßnahme |
|---|---|---|
403 PEPPOL_APPROVAL_REQUIRED, PEPPOL_LIMIT_REACHED | Nichts angelegt oder gesendet | Die Autorisation Peppol unterzeichnen oder den Tarif unter Abrechnung & Abonnement wechseln; dieselbe Anfrage erneut senden |
PEPPOL_CLIENT_NOT_FOUND | Nichts übertragen; bei POST /api/v1/peppol/send besteht die Rechnung bereits | MwSt.-Nummer mit GET /api/v1/peppol/participants/{vat_number} prüfen, dann die bestehende Rechnung senden; kann der Kunde nicht über Peppol empfangen, dieselbe Rechnung auf anderem Weg zustellen |
preparing, 409 PEPPOL_TRANSMISSION_IN_PROGRESS | XML wird erstellt und archiviert | Mindestens fünf Minuten warten, dann den Status lesen |
prepared, preparation_failed | Noch nicht übergeben | Etwaige Ursache beheben (etwa ein fehlendes PDF) und dieselbe Rechnung erneut senden |
accepted | Der Zugangspunkt hat die Nachricht übernommen; das ist nicht die Annahme durch den Käufer | status bis processed verfolgen |
rejected, PEPPOL_TRANSMISSION_REJECTED | Ausdrücklich abgelehnt | Ursache finden; ein erneuter Versuch sendet dieselben archivierten Bytes. Falscher Inhalt: Fehlgeschlagenen Peppol-Versand oder abgelehnte Rechnung beheben |
sending, uncertain, PEPPOL_TRANSMISSION_UNCERTAIN | Die Nachricht ist vielleicht schon im Netzwerk | Anhalten: keine neue Rechnung, keine Kopie per E-Mail; das Ergebnis mit dem OrdoGrid-Support abgleichen |
409 PEPPOL_HISTORY_RECONCILIATION_REQUIRED | Ältere doppelte Übertragungen bestehen | Den OrdoGrid-Support kontaktieren |
PEPPOL_ARCHIVE_HASH_MISMATCH, XML_NOT_AVAILABLE, PDF_NOT_AVAILABLE | Die archivierte Datei kann nicht wie gespeichert geliefert werden | Eskalieren; nie eine neu erzeugte Datei als Original ausgeben |
Die Invoice-Response-Spezifikation von OpenPeppol trennt Transportbestätigungen von der geschäftlichen Entscheidung des Käufers, und Käufer müssen nicht antworten. Führen Sie Übertragungszustand, Kundenantwort und Zahlungsausgleich in getrennten Feldern: Zugestellt heißt weder angenommen noch bezahlt.
Die Wiederholungsschleife
Unsere vorgeschlagenen Startwerte, keine Produktgrenzen: Wartezeiten von 1, 2, 4, 8, 16 und 32 Sekunden, begrenzt auf 60, mit ±20 % Zufallsstreuung; sechs Versuche je Ereignis, danach mit Begründung anhalten. Wartezeiten wegen 429 zählen nicht mit. Verwenden Sie einen Idempotency-Key je Geschäftsvorgang (SO-58213-create) für alle Versuche; ändern Sie den Inhalt nur nach einem 4xx, wenn OrdoGrid den Schlüssel freigegeben hat.
solange Versuche < 6:
r = POST /api/v1/invoices (eingefrorener Inhalt, gleicher Idempotency-Key)
2xx -> erledigt(r.id, r.number)
429 -> Retry-After warten; weiter
endgültiger 4xx oder *_REUSED -> anhalten(code); Ende
502 DOCUMENT_CREATED -> Versuche += 1; weiter (identisches erneutes Senden schließt den Beleg ab)
EXTERNAL_OPERATION_IN_PROGRESS -> 150 s warten
l = GET /api/v1/invoices/lookup?external_id=...
200 -> erledigt(l.id, l.number) 409 -> 150 s warten 404 -> wiederholen
Versuche += 1; Wartezeit(Versuche) warten
anhalten("Wiederholungsbudget aufgebraucht")
Nach 24 Stunden läuft der Idempotency-Key ab; eine identische Wiederholung bleibt durch external_id geschützt. PATCH, PUT und DELETE haben kein Replay: Lesen Sie nach einer verlorenen Antwort den Beleg mit GET und vergleichen Sie, bevor Sie die Änderung erneut anwenden.
Rechenbeispiel: Zeitüberschreitung, Schlüsselrotation, Überweisung
Verhaeghe Technics BV (Kortrijk) fakturiert aus seinem ERP mit einem Schlüssel „ERP Produktion“, Integrations-ID erp-prod. Auftrag SO-58213 geht an die Brasserie Lambert SRL (Namur), die über Peppol empfängt: 8 Std. Maschinenwartung × 95,00 € = 760,00 € und eine mobile Pumpe zu 1.240,00 € (keine Bauleistung, daher keine Umkehr der Steuerschuld), also 2.000,00 € netto + 420,00 € MwSt. zu 21 % = 2.420,00 €.
12. Oktober 2026, 14:02 Uhr UTC (16:02 Uhr in Brüssel). POST /api/v1/peppol/send mit external_id SO-58213 und Idempotency-Key SO-58213-send läuft nach 30 Sekunden in eine Zeitüberschreitung.
- Einordnen. Unbekanntes Ergebnis: kein erneuter Versand.
- Suchen.
GET /api/v1/invoices/lookup?external_id=SO-58213liefert200: Rechnung F-2026-0418 besteht (diese Route legt die Rechnung vor dem Versand an). - Übertragung lesen. Der Status zeigt
transmission_stateuncertain,transmitted: false. Die Verzeichniszeile wird angehalten; verantwortlich Anke Peeters; nächste Prüfung 15:00 Uhr UTC. - Abschließen. Um 15:00 Uhr ist der Zustand
accepted; um 15:20 Uhr iststatusprocessed(Traité in Peppol → Outbox). Eine Rechnung, eine Übertragung, 2.420,00 € offen.
Ein naiver Konnektor, der dreimal mit jeweils neuer UUID wiederholt, hätte F-2026-0419 bis F-2026-0421 angelegt und versandt: 3 × 2.420,00 € = 7.260,00 € zusätzliche Forderungen, davon 1.260,00 € MwSt., die Peppol nicht als Duplikate kennzeichnet. Jede braucht eine eigene Gutschrift über Peppol (NC-2026-0031 bis NC-2026-0033) und einen Anruf beim Kunden.
20. Oktober. Die Administratorin klickt auf Rotieren; GET /api/v1/me zeigt weiterhin erp-prod. Um 9:15 Uhr UTC erfasst die Bankanbindung die erste Überweisung:
{"external_id":"bank-20261020-0144","amount":"1000.00","currency":"EUR","method":"bank_transfer","occurred_at":"2026-10-20T09:12:00Z","reference":"Auszug 203 Zeile 14"}
Die Antwort geht verloren. Der gespeicherte Inhalt wird mit demselben Idempotency-Key erneut gesendet: Das ursprüngliche 201 kommt zurück, markiert mit Idempotent-Replay: true (ohne den Header oder nach 24 Stunden antwortet die dauerhafte Identität: 200 mit replayed: true). In beiden Fällen ist outstanding "1420.00". Eine neu aufgebaute Referenz wie „Ausz. 203/14“ hätte 409 EXTERNAL_ID_REUSED ergeben.
Hätte der Konnektor zwischen der verlorenen Antwort und der Wiederholung auf einen über Schlüssel erstellen angelegten und auf default belassenen Schlüssel gewechselt, hätte diese Wiederholung eine zweite Zahlung über 1.000,00 € erfasst: outstanding 420,00 €, obwohl der Kunde noch 1.420,00 € schuldet, was erst am 3. November bei der Ablehnung der echten Zahlung über 1.420,00 € mit OVERPAYMENT aufgefallen wäre. So aber bringt die Zahlung bank-20261103-0029 outstanding auf "0.00" und settlement.status auf settled.
Sonderfälle und häufige Fehler
| Situation | Richtige Reaktion |
|---|---|
Die Suche liefert 404 nach einer Zeitüberschreitung | Zuerst den Namensraum mit GET /api/v1/me prüfen, dann den identischen Inhalt unter derselben external_id senden; nie eine neue ID, „weil es sie nicht gibt“ |
EXTERNAL_ID_REUSED, nachdem jemand den Auftrag im ERP geändert hat | Die Buchhaltung entscheidet, welche Fassung stimmt; eine bestehende falsche Rechnung erhält eine Gutschrift und eine neue Rechnung. Kein -v2 anhängen |
Ein korrigierter Inhalt ergibt EXTERNAL_ID_REUSED nach einer Ablehnung während der Erstellung (etwa OVERPAYMENT bei Anzahlungen zur Erstellung oder DOCUMENT_NUMBER_TAKEN) | Die Identität bleibt an den abgelehnten Inhalt gebunden. Liefert die Suche deutlich nach zwei Minuten noch 409 EXTERNAL_OPERATION_IN_PROGRESS, wurde nichts gespeichert: vom OrdoGrid-Support bestätigen lassen, dann eine neue ID verwenden und beide im Verzeichnis verknüpfen |
IDEMPOTENT_REQUEST_IN_PROGRESS länger als einige Minuten | Suchen; fehlt das Ereignis, den identischen Inhalt mit neuem Idempotency-Key senden; die external_id verhindert weiterhin ein Duplikat |
| Eine Überweisung begleicht zwei Rechnungen | Bewegungs-IDs sind über alle Rechnungen eindeutig: bank-20261020-0144-a und -b |
| Falscher Betrag erfasst | Eine Stornierung hebt immer die ganze Bewegung auf: stornieren, dann den richtigen Betrag unter neuer ID erfassen |
| Der Kunde findet eine als Traité markierte Rechnung nicht | An seinen Peppol-Anbieter zugestellt: Der Kunde prüft dort. Nicht erneut senden und nicht mailen |
Geschäftsergebnisse überwachen, nicht nur die Verfügbarkeit
| Kennzahl | Vorgeschlagener Alarm | Verantwortlich |
|---|---|---|
| Ältestes noch nicht übermitteltes Ereignis | Älter als 30 Minuten während der Bürozeiten | Betrieb |
| Ältester angehaltener Eintrag | Älter als ein Werktag | Warteschlangenverantwortung |
Versand in sending oder uncertain | Jeder älter als 4 Stunden | Integrationsbetrieb |
| Nicht fakturierte Ereignisse, deren Frist (15. des Folgemonats) in höchstens 5 Werktagen abläuft | Jeder Fall | Buchhaltung |
4xx-Ablehnungen je Tag und code | Ein neuer Code oder eine Verdopplung von einem Tag auf den nächsten | Integrationsentwicklung |
| Replay-Antworten / Anfragen | Über 5 % während einer Stunde | Integrationsentwicklung |
Tagessummen der Quelle gegenüber document_total und payments | Jede Differenz außer 0,00 € | Finanzcontrolling |
Zählen Sie Anfragen getrennt von Geschäftsereignissen: Ein Replay ist kein neuer Umsatz. Protokollieren Sie Codes, IDs und UTC-Zeiten, nie das Geheimnis (ik_live_…) oder den Header Authorization. Lesen Sie alle Listenseiten (limit bis 100, offset) mit gleichbleibenden Filtern und halten Sie das Auszugsfenster fest; siehe Monatsabschluss.
Die Wiederherstellung vor dem Produktivstart nachweisen
OrdoGrid hat keine Testumgebung und keinen Peppol-Testmodus: Jeder Aufruf wirkt auf echte Daten, und "send": false legt trotzdem eine nummerierte Rechnung an. Testen Sie nach Möglichkeit in einem eigenen Abnahme-Unternehmen (Créer une nouvelle entreprise, neues Unternehmen anlegen) mit eigenem Schlüssel; andernfalls planen Sie je Testrechnung eine Gutschrift ein. Simulieren Sie unklare oder abgelehnte Übertragungen mit aufgezeichneten Antworten in Ihrem eigenen HTTP-Client.
| Szenario | Erwartetes Ergebnis |
|---|---|
| Anlegen, dann identische Wiederholung mit demselben, dann mit neuem Schlüssel | 201, danach zweimal 201 mit Idempotent-Replay: true; eine Rechnung |
| Gleicher Schlüssel, anderer Inhalt | 409 IDEMPOTENCY_KEY_REUSED; Eintrag angehalten |
Gleiche external_id, anderer Inhalt | 409 EXTERNAL_ID_REUSED; Eintrag angehalten, Buchhaltung informiert |
| Zwei Verarbeitungen, dasselbe Ereignis | Ein 201; die andere ein 409 „läuft noch“ oder ein Replay |
| Zahlung, dann identische Wiederholung mit neuem Schlüssel | 201, danach 200 mit replayed: true; Saldo einmal vermindert |
Zahlung über outstanding | 409 OVERPAYMENT; keine Wiederholung |
| Lastspitze über dem Limit | 429 mit Retry-After; nichts geht verloren |
| Rotieren, dann frühere Ereignisse erneut senden | Nur Replays; /me zeigt dieselbe Integrations-ID |
Abnehmen, wenn jedes Ereignis genau eine OrdoGrid-Identität hat, der Zahlungsausgleich zur Quelle passt, kein unklarer Versand wiederholt wurde und eine Vertretung die angehaltenen Einträge allein mit dem Verzeichnis bearbeiten kann. Übergeben Sie Entscheidungstabellen, Schlüsselverantwortung, Integrations-ID, Ablageort des Verzeichnisses, Schwellenwerte und Supportkontakt. Stimmen Sie nach einer Störung die gesamte betroffene Menge ab, bevor Sie die Wiederherstellung melden (Rechnungsstörung).
Aufzubewahrende Nachweise
- Das Verzeichnis: eingefrorene Inhalte oder ihre Fingerabdrücke,
Idempotency-Key-Werte, jedes Ergebnis mit UTC-Zeit undcode. - Je Peppol-Versand:
peppol_document_id, der Verlauf vontransmission_stateund das ausgetauschte XML überGET /api/v1/peppol/documents/{id}/xml(ID des Peppol-Dokuments, nicht der Rechnung;peppol:read), dazu/pdf. OrdoGrid prüft beide gegen die SHA-256-Fingerabdrücke intransmission_snapshot. - Schlüsseländerungen (wer, wann, Integrations-ID vorher und nachher) und je angehaltenem Eintrag Grund, Prüfungen, freigebende Person und Austausch mit dem Support.
- Rechnungen werden sieben Jahre ab dem 1. Januar des auf die Ausstellung folgenden Jahres aufbewahrt; OrdoGrid gibt keine Garantie für die gesetzliche Archivierung, behalten Sie daher eine eigene Kopie (Rechnungsarchivierung in Belgien).
Häufige Fragen
Wie lange warten wir nach einer Zeitüberschreitung vor einer Wiederholung?
Suchen Sie zuerst, statt zu warten. Besteht der Beleg, halten Sie ihn fest; hält ein anderer Aufruf die Identität, warten Sie länger als zwei Minuten; liefert die Suche 404, senden Sie den identischen Inhalt mit ansteigenden Wartezeiten erneut.
Dürfen wir denselben Idempotency-Key nach einem Fehler wiederverwenden?
Ja. OrdoGrid speichert nur erfolgreiche Antworten und gibt den Schlüssel nach einem Fehlschlag frei, sodass er nach einem 4xx korrigierten Inhalt tragen kann. Innerhalb von 24 Stunden nach einem Erfolg wird ein anderer Inhalt unter diesem Schlüssel abgelehnt.
Warum erhalten wir EXTERNAL_ID_REUSED, obwohl sich nur die Beschreibung geändert hat?
Bei Belegen zählt der gesamte Erstellungsinhalt, auch Beschreibungen, E-Mail-Adressen und Fälligkeiten. Bei Bewegungen zählen Betrag, Währung, Zahlungsart, Zeitpunkt und Referenz. Senden Sie den gespeicherten Inhalt erneut oder lassen Sie die Buchhaltung entscheiden.
Ist es sicher, den Peppol-Versand für dieselbe Rechnung erneut aufzurufen?
Ja, wenn der Aufruf dieselbe Rechnung betrifft: die Versandroute dieser Rechnung oder POST /api/v1/peppol/send, wiederholt mit derselben external_id (ohne external_id legt diese Route eine neue Rechnung an). Eine angenommene Übertragung kommt mit replayed auf true zurück, eine abgelehnte sendet die archivierten Bytes erneut, eine unklare wird abgelehnt. Eine neue Rechnung für denselben Verkauf oder eine Kopie per E-Mail ist nicht sicher.
Hebt das Rotieren eines API-Schlüssels den Duplikatschutz auf?
Nicht mit Rotieren, das die Integrations-ID behält. Nur das 24-stündige Replay über Idempotency-Key bleibt an den alten Schlüssel gebunden. Bei einem mit „Schlüssel erstellen“ angelegten Schlüssel müssen Sie dieselbe Integrations-ID von Hand eintragen.
Können wir Wiederholungen in einer Testumgebung prüfen?
Nein. Es gibt weder Testumgebung noch Peppol-Testmodus. Nutzen Sie nach Möglichkeit ein eigenes Abnahme-Unternehmen und simulieren Sie Peppol-Ergebnisse mit aufgezeichneten Antworten.
Quellen und Referenzen
- Referenz der öffentlichen OrdoGrid-API: Idempotenz, externe Suche und Fehlercodes
- Peppol BIS Invoice Response 3.2: Transportbestätigungen und geschäftliche Antworten
- FÖD Finanzen, FAQ E-Rechnung: spezifische Fragen (F4 Duplikate, F5 Gutschriften)
- FÖD Finanzen, Peppol-FAQ: Zustellverzögerungen (F9)
- Gesetz vom 6. Februar 2024, Art. 53 §2bis MwSt.-Gesetzbuch: berichtigende Dokumente im selben strukturierten Format (Belgisches Staatsblatt, 20.02.2024)
- Königlicher Erlass Nr. 1, Art. 4 und 5: Ausstellungsfrist und fortlaufende Nummerierung (Justel, koordinierte Fassung)