Arbeitsanleitung18 Min. Lesezeit

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 GesetzJede 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 FinanzenPeppol 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).
OrdoGridDauerhafte 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 EmpfehlungDas 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

SchutzGeltungsbereich und DauerVerhindertVerhindert nicht
Header Idempotency-KeyDer aufrufende API-Schlüssel; 24 StundenEine zweite Ausführung desselben POST: Eine identische Wiederholung liefert die gespeicherte Erfolgsantwort mit Idempotent-Replay: trueEinen 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 BelegsUnternehmen, Integrations-ID und Belegart; ohne Ablauf, übersteht die RotationEine zweite Rechnung oder Gutschrift für dieselbe QuelltransaktionEine neue ID; eine andere Integrations-ID; jede Änderung am Erstellungsinhalt (409 EXTERNAL_ID_REUSED)
external_id einer BewegungUnternehmen und Integrations-ID, über alle Rechnungen und Bewegungsarten hinweg; ohne AblaufDasselbe Geld doppelt zu zählen: Eine Wiederholung liefert die ursprüngliche Bewegung mit replayed: trueEine Änderung von Betrag, Währung, Zahlungsart, Zeitpunkt oder Referenz oder dieselbe ID auf einer anderen Rechnung (EXTERNAL_ID_REUSED)
Peppol-ÜbertragungsschutzEine Übertragung je Rechnung oder GutschriftEine zweite Übertragung: Ein angenommener Versand kommt mit replayed: true zurück, ein unklarer wird abgelehntEine 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_id in der API, Integrations-ID auf der Seite API-Schlüssel). Jede external_id wird im Namensraum des aufrufenden Schlüssels gesucht. Bis zu 80 Buchstaben, Ziffern, _, . oder -; bei der Erstellung festgelegt; das Feld steht standardmäßig auf default.

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.

  1. Leiten Sie die ID aus dem Geschäftsereignis ab (1 bis 200 Zeichen). Eine UUID je Anfrage schaltet alle Schutzmechanismen oben ab.
  2. 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_REUSED aus.
  3. Lassen Sie number weg, damit die Nummernfolge des Unternehmens sie vergibt. Eigene Nummern plus eine Wiederholung ohne external_id ergeben 409 DOCUMENT_NUMBER_TAKEN.
  4. Tragen Sie in reference jeder Bewegung eine lesbare Quellreferenz ein; die Buchhaltung sieht sie im Bewegungsverlauf des Bereichs Abrechnung der Rechnung. Halten Sie sie bei jeder Wiederholung identisch.
  5. 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):

  1. 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.
  2. Ein Ersatzschlüssel über Schlüssel erstellen braucht genau die alte Integrations-ID. Bleibt sie auf default, liefern Suchen 404 und Wiederholungen legen neue Rechnungen oder Zahlungen an.
  3. Die Schlüsselliste zeigt die Integrations-ID nicht: Rufen Sie GET /api/v1/me auf und vergleichen Sie api_key.integration_id mit Ihrem Verzeichnis, bevor Sie neu starten.
  4. 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

AntwortGespeichert?Maßnahme
201; oder Idempotent-Replay: true oder replayed: true (200 bei Bewegungen)Jaid und number festhalten. Ein Replay liefert das erste Ergebnis erneut, keinen neuen Verkauf und keine neue Zahlung
Zeitüberschreitung, Verbindungsabbruch, 5xx ohne hier genannten CodeUnbekanntZuerst ü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_TYPENeinZuordnung 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_SCOPENeinWarteschlange 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_LIMITEDNeinRetry-After Sekunden warten; drosseln
409 IDEMPOTENT_REQUEST_IN_PROGRESSErster Aufruf läuft nochEinige Sekunden warten; mit demselben Schlüssel und Inhalt wiederholen
409 EXTERNAL_OPERATION_IN_PROGRESSEin anderer Aufruf hält die IdentitätLänger als zwei Minuten warten (die Ausführungssperre), dann suchen
409 IDEMPOTENCY_KEY_REUSED oder EXTERNAL_ID_REUSEDErste Fassung besteht oder ist reserviertAnhalten; gespeicherten und neuen Inhalt vergleichen; nie mit neuem Schlüssel oder neuer ID umgehen
409 SETTLEMENT_CONFLICTNeinGleichzeitige Änderung an der Rechnung; nach einer Wartezeit mit derselben external_id wiederholen
409 OVERPAYMENT, OVER_REFUNDNeinNicht wiederholen; prüfen, ob das Geld schon unter einer anderen ID erfasst ist
409 DOCUMENT_FINANCIAL_CONTENTS_LOCKED bei einer ÄnderungNeinEine 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_CREATEDJa, PDF oder Anhänge unvollständigIdentischen 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_stateBedeutungMaßnahme
403 PEPPOL_APPROVAL_REQUIRED, PEPPOL_LIMIT_REACHEDNichts angelegt oder gesendetDie Autorisation Peppol unterzeichnen oder den Tarif unter Abrechnung & Abonnement wechseln; dieselbe Anfrage erneut senden
PEPPOL_CLIENT_NOT_FOUNDNichts übertragen; bei POST /api/v1/peppol/send besteht die Rechnung bereitsMwSt.-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_PROGRESSXML wird erstellt und archiviertMindestens fünf Minuten warten, dann den Status lesen
prepared, preparation_failedNoch nicht übergebenEtwaige Ursache beheben (etwa ein fehlendes PDF) und dieselbe Rechnung erneut senden
acceptedDer Zugangspunkt hat die Nachricht übernommen; das ist nicht die Annahme durch den Käuferstatus bis processed verfolgen
rejected, PEPPOL_TRANSMISSION_REJECTEDAusdrücklich abgelehntUrsache finden; ein erneuter Versuch sendet dieselben archivierten Bytes. Falscher Inhalt: Fehlgeschlagenen Peppol-Versand oder abgelehnte Rechnung beheben
sending, uncertain, PEPPOL_TRANSMISSION_UNCERTAINDie Nachricht ist vielleicht schon im NetzwerkAnhalten: keine neue Rechnung, keine Kopie per E-Mail; das Ergebnis mit dem OrdoGrid-Support abgleichen
409 PEPPOL_HISTORY_RECONCILIATION_REQUIREDÄltere doppelte Übertragungen bestehenDen OrdoGrid-Support kontaktieren
PEPPOL_ARCHIVE_HASH_MISMATCH, XML_NOT_AVAILABLE, PDF_NOT_AVAILABLEDie archivierte Datei kann nicht wie gespeichert geliefert werdenEskalieren; 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.

  1. Einordnen. Unbekanntes Ergebnis: kein erneuter Versand.
  2. Suchen. GET /api/v1/invoices/lookup?external_id=SO-58213 liefert 200: Rechnung F-2026-0418 besteht (diese Route legt die Rechnung vor dem Versand an).
  3. Übertragung lesen. Der Status zeigt transmission_state uncertain, transmitted: false. Die Verzeichniszeile wird angehalten; verantwortlich Anke Peeters; nächste Prüfung 15:00 Uhr UTC.
  4. Abschließen. Um 15:00 Uhr ist der Zustand accepted; um 15:20 Uhr ist status processed (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

SituationRichtige Reaktion
Die Suche liefert 404 nach einer ZeitüberschreitungZuerst 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 hatDie 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 MinutenSuchen; fehlt das Ereignis, den identischen Inhalt mit neuem Idempotency-Key senden; die external_id verhindert weiterhin ein Duplikat
Eine Überweisung begleicht zwei RechnungenBewegungs-IDs sind über alle Rechnungen eindeutig: bank-20261020-0144-a und -b
Falscher Betrag erfasstEine Stornierung hebt immer die ganze Bewegung auf: stornieren, dann den richtigen Betrag unter neuer ID erfassen
Der Kunde findet eine als Traité markierte Rechnung nichtAn seinen Peppol-Anbieter zugestellt: Der Kunde prüft dort. Nicht erneut senden und nicht mailen

Geschäftsergebnisse überwachen, nicht nur die Verfügbarkeit

KennzahlVorgeschlagener AlarmVerantwortlich
Ältestes noch nicht übermitteltes EreignisÄlter als 30 Minuten während der BürozeitenBetrieb
Ältester angehaltener EintragÄlter als ein WerktagWarteschlangenverantwortung
Versand in sending oder uncertainJeder älter als 4 StundenIntegrationsbetrieb
Nicht fakturierte Ereignisse, deren Frist (15. des Folgemonats) in höchstens 5 Werktagen abläuftJeder FallBuchhaltung
4xx-Ablehnungen je Tag und codeEin neuer Code oder eine Verdopplung von einem Tag auf den nächstenIntegrationsentwicklung
Replay-Antworten / AnfragenÜber 5 % während einer StundeIntegrationsentwicklung
Tagessummen der Quelle gegenüber document_total und paymentsJede 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.

SzenarioErwartetes Ergebnis
Anlegen, dann identische Wiederholung mit demselben, dann mit neuem Schlüssel201, danach zweimal 201 mit Idempotent-Replay: true; eine Rechnung
Gleicher Schlüssel, anderer Inhalt409 IDEMPOTENCY_KEY_REUSED; Eintrag angehalten
Gleiche external_id, anderer Inhalt409 EXTERNAL_ID_REUSED; Eintrag angehalten, Buchhaltung informiert
Zwei Verarbeitungen, dasselbe EreignisEin 201; die andere ein 409 „läuft noch“ oder ein Replay
Zahlung, dann identische Wiederholung mit neuem Schlüssel201, danach 200 mit replayed: true; Saldo einmal vermindert
Zahlung über outstanding409 OVERPAYMENT; keine Wiederholung
Lastspitze über dem Limit429 mit Retry-After; nichts geht verloren
Rotieren, dann frühere Ereignisse erneut sendenNur 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 und code.
  • Je Peppol-Versand: peppol_document_id, der Verlauf von transmission_state und das ausgetauschte XML über GET /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 in transmission_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