Riverty Payment: Integration API und Console Commands

Riverty für OXID eShop 7 - externe REST-Integration-API für Capture/Void/Refund und der Cronjob-Befehl für die automatische Datenpflege.

English Version

Zurück zur Übersicht

Riverty Payment: Integration API und Console Commands

Live Demo: Teste dieses und weitere Plugins live — ohne Installation, ohne Risiko: demo.markus-michalski.net

Integration API (optional)

Externer Endpunkt für ERP-/WMS-/Middleware-Systeme, um Capture, Void und Refund auszulösen, ohne den OXID-Admin zu nutzen. Die Regeln entsprechen denen im Riverty-Tab der Bestellung. Das Freischalten und die Secret-Generierung machst du im Admin (siehe Konfiguration). Hier steht die Schnittstellen-Referenz für die Anbindung.

Endpunkt: POST /index.php?cl=mmd_riverty_integration_api (die vollständige URL deines Shops zeigt der Admin bei den Integration-API-Einstellungen an; nur über HTTPS aufrufen).

Auth: Header X-Riverty-Integration-Secret mit dem im Admin generierten Secret (zeitkonstanter Vergleich). Fehlgeschlagene Authentifizierungen werden ins Server-Error-Log geschrieben. Ein Rate-Limit gibt es nicht, das gehört auf die Infrastruktur-Ebene (z.B. fail2ban oder WAF).

Request-Body (JSON):

{
  "type": "capture",
  "orderNumber": "2026070001",
  "mode": "partial",
  "items": [{"sku": "ART-001", "quantity": 1}],
  "includeShipping": false,
  "idempotencyKey": "erp-job-48213"
}

Feld	Pflicht	Bedeutung
`type`	ja	`capture`, `void` oder `refund` (Aliase `cancel` und `cancellation` für `void`)
`orderId` oder `orderNumber`	ja, eines von beiden	Bestellung über OXID-Bestell-ID oder Bestellnummer
`mode`	nein	`full` oder `partial` (Default: `partial`)
`items`	bei `partial`	Liste mit `sku` (alternativ `productNumber` oder `articleNumber`) und `quantity`
`includeShipping`	nein	Versandkosten bei Teil-Capture/-Refund mit einbeziehen
`captureNumber`	nein	Nur Refund: Capture, aus der erstattet wird. Pflicht, wenn ein Artikel in mehreren Captures vorkommt
`idempotencyKey`	nein	Max. 255 Zeichen, verhindert doppelte Ausführung bei Retries

Verhalten je Typ:

capture: full zieht alle noch offenen Positionen ein und setzt zusätzlich das Versanddatum der Bestellung. partial zieht nur die angegebenen Positionen ein und lässt das Versanddatum unberührt. Nach jedem erfolgreichen Capture greifen die Einstellungen "als bezahlt markieren" und "Ordner nach Capture".
void: storniert immer die gesamte noch offene autorisierte Menge. Eine Teilmengen-Variante gibt es über die API nicht.
refund: full erstattet alle eingezogenen, noch nicht erstatteten Positionen. partial erstattet die angegebenen Positionen.

Antwort: JSON mit success und message. Bei erfolgreichem Capture kommt zusätzlich captureNumber zurück. Fehler enthalten error: true. Fachliche Fehler liefern zusätzlich einen maschinenlesbaren reason, z.B. invalid_json, order_not_found, no_transaction, cannot_capture, cannot_void, cannot_refund, sku_not_on_order, sku_not_captured, capture_number_required. Fehler der Riverty-API kommen als 400 ohne reason, die Meldung steht in message.

Response-Codes:

Code	Bedeutung
200	Erfolg
400	Ungültiges JSON, Validierungsfehler, Fachfehler (z.B. Bestellung nicht gefunden, Status erlaubt die Aktion nicht) oder Fehler der Riverty-API (ohne `reason`)
401	Secret fehlt oder falsch
403	Integration API deaktiviert
409	Idempotency-Key wird gerade verarbeitet
422	Idempotency-Key mit abweichendem Request-Body wiederverwendet
503	Secret nicht konfiguriert
500	Unerwarteter Fehler

Idempotenz: Wird derselbe idempotencyKey mit identischem Body erneut gesendet, bekommst du die gespeicherte Antwort zurück, ohne dass die Operation noch einmal läuft. Fehlgeschlagene Anfragen (Status ab 400) werden nicht gespeichert, ein Retry läuft also neu. Gespeicherte Keys räumt oe:riverty:cleanup nach der Aufbewahrungsfrist der API-Logs auf.

Console Commands und Cronjob

Command	Beschreibung
`oe-console oe:riverty:cleanup`	Räumt abgelaufene API-Logs, gespeicherte Idempotency-Keys und abgebrochene Pending-Transaktionen auf

Die Aufbewahrungsfristen stellst du im Admin ein (siehe Konfiguration). Der Befehl macht drei voneinander unabhängige Aufräumläufe, ein Fehler in einem stoppt die anderen nicht:

API-Logs löschen, die älter als die konfigurierte Frist sind.
Pending-Transaktionen ohne Bestellbezug als abgelaufen markieren, sobald die Reservierung abgelaufen ist (ohne Ablaufdatum nach 24 Stunden, und nur wenn sie mindestens 15 Minuten unberührt sind), und abgelaufene Transaktionen löschen, wenn die Aufbewahrungsfrist seit der Markierung vorbei ist. Transaktionen mit Bestellbezug werden nie angefasst.
Gespeicherte Idempotency-Keys löschen, die älter als die API-Log-Frist sind.

Löschungen laufen in Blöcken von 5000 Zeilen.

Option --dry-run zeigt die betroffenen Zeilenzahlen, ohne zu löschen oder zu markieren.

OXID hat keinen eigenen Cron für Module, der Aufruf läuft über die System-Crontab:

0 3 * * * cd /var/www/html && vendor/bin/oe-console oe:riverty:cleanup >> /var/log/riverty-cleanup.log 2>&1

Der Befehl arbeitet immer im Kontext eines Shops (Standard: Shop 1). Bei mehreren Subshops legst du pro Shop eine Zeile mit der globalen Option --shop-id an:

0 3 * * * cd /var/www/html && vendor/bin/oe-console oe:riverty:cleanup --shop-id=2 >> /var/log/riverty-cleanup.log 2>&1

Praxis-Beispiele

Beispiel 1: Teil-Refund per Integration API

curl -X POST "https://shop.example.com/index.php?cl=mmd_riverty_integration_api" \
  -H "X-Riverty-Integration-Secret: <secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "refund",
    "orderNumber": "2026070001",
    "mode": "partial",
    "items": [{"sku": "ART-001", "quantity": 1}],
    "captureNumber": "801006570",
    "idempotencyKey": "erp-refund-9911"
  }'

Beispiel 2: Cronjob im Dry-Run testen, bevor er scharf geschaltet wird

vendor/bin/oe-console oe:riverty:cleanup --dry-run