Metadata

Jeder POST /v1/checkouts akzeptiert ein optionales metadata-Objekt. Vorgio speichert es auf der Rechnung (in der JSON-Spalte invoices.metadata), spiegelt es in jedem Webhook-Payload zurück und gibt es bei GET /v1/invoices/{id} aus. Es ist der empfohlene Weg, um Vorgio-Events mit den Datensätzen Ihres Shops zu verknüpfen.

#Schema

Frei strukturiertes JSON-Objekt (kein Array, kein Skalar).
Schlüssel auf oberster Ebene müssen Strings sein.
Werte können beliebige JSON-kodierbare Typen sein.
≤ 16 KB serialisiert.

 1"metadata": {
 2  "shop_order_id": "1234",
 3  "channel": "web",
 4  "customer_segment": "returning",
 5  "tags": ["bday-promo"]
 6}

#Das kanonische Muster: Shop-Bestell-ID

Der mit Abstand nützlichste Schlüssel ist die eigene Bestell-ID des Shops, als String:

 1"metadata": {
 2  "shop_order_id": "1234"
 3}

Wenn später der invoice.paid-Webhook eintrifft, macht Ihr Handler Folgendes:

 1$shopOrderId = $event['metadata']['shop_order_id'] ?? null;
 2if (! $shopOrderId) {
 3    Log::warning('Vorgio webhook missing shop_order_id', ['event' => $event['id']]);
 4    return response('', 200); // ack so Vorgio doesn't retry
 5}
 6$order = Order::find($shopOrderId);
 7$order->markPaid();

Kodieren Sie IDs immer als String, auch wenn Ihr Shop Integer verwendet — JSON unterscheidet nach einem Round-Trip durch zwischengeschaltete Systeme nicht zwischen 1234 und "1234", PHP/JS/Python-=== aber sehr wohl.

#Muster mit mehreren Schlüsseln

Für Shops, die eine reichhaltigere Korrelation benötigen:

 1"metadata": {
 2  "shop": "wc",
 3  "order_id": "1234",
 4  "checkout_id": "abc-…",
 5  "promo_codes": ["SUMMER10"],
 6  "fulfillment_method": "shipping"
 7}

Diese werden unverändert durchgereicht. Vorgio interpretiert keinen davon.

#Wofür `metadata` nicht gedacht ist

Nicht für sensible Daten. Wird im Klartext in der Vorgio-DB gespeichert und ist für jeden mit Zugriff auf das Team des Händlers sichtbar. Legen Sie hier keine PII ab, die Sie nicht auch auf der Rechnung selbst hätten.
Nicht für Query-Filter. Sie können nicht GET /v1/invoices?metadata.shop_order_id=1234 aufrufen — metadata ist nicht abfragbar. Wenn Sie eine Rechnung anhand Ihrer Shop-Bestell-ID nachschlagen müssen, haben Sie zwei Optionen: (a) speichern Sie die Vorgio-invoice_id zum Checkout-Zeitpunkt im Bestell-Datensatz Ihres Shops (empfohlen) oder (b) iterieren Sie über GET /v1/invoices und filtern Sie clientseitig.
Nicht für Retry-Koordination. Verwenden Sie dafür den Idempotency-Key-Header.
Nicht nach dem Anlegen editierbar. v1 stellt kein PATCH /v1/invoices/{id} für metadata bereit. Setzen Sie es zum Checkout-Zeitpunkt und behandeln Sie es als unveränderlich.

#Praxisbeispiel: WooCommerce

 1$payload = [
 2    // … client, invoice, send …
 3    'metadata' => [
 4        'shop_order_id'   => (string) $order->get_id(),
 5        'shop_order_key'  => $order->get_order_key(),     // for /my-account/view-order/<id>?key=…
 6        'shop_admin_url'  => admin_url('post.php?post=' . $order->get_id() . '&action=edit'),
 7    ],
 8];