WooCommerce-REST-API-Adapter

Eine unmittelbar einsetzbare, kompatible REST-API für STOAR, die das Protokollformat von WooCommerce v3 nachbildet — dieselben URL-Pfade (/wp-json/wc/v3/...), dieselbe flache Query-Parameter-Syntax, dieselben JSON-Feldnamen in der Antwort, dieselben Auth-Optionen. Bestehende WooCommerce-Client-Bibliotheken (z. B. automattic/woocommerce PHP/JS, klarna/woocommerce-rest-api Node) sprechen ohne Änderung mit STOAR.

Der Adapter ist die zweite Implementierung von STOARs erweiterbarem API-Adapter-Framework (die erste war Magento). Er zeigt, wie eine grundlegend andere Anbietervariante — flache Query-Parameter statt verschachteltem searchCriteria[…], Basic Auth statt ausschließlich Bearer, das Statusvokabular processing/completed statt paid/delivered — auf derselben Datenschicht neben Magento steht.

Inhaltsverzeichnis #

• Schnellstart
• Authentifizierung
• Endpunkte
  • Bestellungen auflisten
  • Einzelne Bestellung abrufen
  • Notizen auflisten
  • Notiz hinzufügen
  • Erstattungen auflisten
  • Erstattung anlegen
  • Produkte auflisten
  • Einzelnes Produkt abrufen
• Query-Parameter
• Feld-Mapping (WooCommerce ↔ STOAR)
• Statusübersetzung
• Antwortstruktur
• Praxisbeispiel
• Fehlerstruktur
• Rate-Limiting

Schnellstart #

# 1. Get a Sanctum token with woocommerce:admin ability — issued via /manager/api-tokens
#    or via the Magento token endpoint (POST /rest/V1/integration/admin/token), then
#    grant the woocommerce:admin ability inside /manager.
TOKEN="2|L5pXj63e881lkgtHPK7Hjozyq7Pb3trHCy0iaDRf76405f72"

# 2. List the last 5 orders (Bearer auth — STOAR extension; works alongside Basic)
curl -s "https://app.stoar.ai/wp-json/wc/v3/orders?per_page=5&orderby=date&order=desc" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.[] | {id, status, total, currency}'

# 3. Use HTTP Basic just like a real WooCommerce store
curl -s "https://app.stoar.ai/wp-json/wc/v3/products?per_page=3" \
  -u "any-key:$TOKEN"

# 4. Or stuff credentials into the query string (still over HTTPS only)
curl -s "https://app.stoar.ai/wp-json/wc/v3/products?consumer_key=any&consumer_secret=$TOKEN"

Authentifizierung #

WooCommerce kennt drei Auth-Varianten; der Adapter akzeptiert alle und überführt sie intern in dieselbe Prüfung eines Sanctum-Personal-Access-Tokens. Tokens werden auf STOARs Seite /manager/api-tokens ausgestellt (oder programmatisch über AdminUser::createToken('label', ['woocommerce:admin'])).

Abbildung auf Sanctum

Der Adapter ignoriert consumer_key (du kannst jede beliebige Zeichenkette übergeben — "any-key" funktioniert). consumer_secret MUSS ein gültiges Sanctum-Personal-Access-Token sein, dessen abilities-Array woocommerce:admin enthält.

Diese Abbildung ist reine Interpretationsschicht; aus Sicht von STOAR ist jede WC-Anfrage lediglich eine per Bearer authentifizierte Sanctum-Anfrage. Dieselbe Personal-Access-Token-Zeile trägt beides:

• einen Magento-Client, der /rest/V1/orders nutzt (benötigt die Ability magento:admin)
• einen WooCommerce-Client, der /wp-json/wc/v3/orders nutzt (benötigt die Ability woocommerce:admin)

Du kannst ein einzelnes Token mit beiden Abilities ausstellen oder getrennte — ganz wie du möchtest.

Kunden-Tokens

Kundenbezogene Endpunkte sind noch nicht verfügbar. Die Ability woocommerce:customer ist für die künftige Nutzung reserviert.

Endpunkte #

Alle Pfade sind relativ zu /wp-json/wc/v3 (wortgleich der WordPress-REST-Namespace).

GET /wp-json/wc/v3/orders

Bestellungen auflisten.

Autorisierung: Bearer / Basic / Query, mit der Ability woocommerce:admin.

Query-Parameter: siehe Query-Parameter.

Antwort (200): flaches JSON-Array mit Bestellungen. Die Pagination steckt in den Headern, NICHT im Body:

HTTP/1.1 200 OK
X-WP-Total:      150
X-WP-TotalPages: 8
Content-Type:    application/json

[
  { /* order */ },
  { /* order */ }
]

Warum Header statt Hülle? Genau das ist die tatsächliche Konvention von WooCommerce — anders als Magentos {items, search_criteria, total_count}-Wrapper. WC-Client-Bibliotheken (die offiziellen PHP-/JS-Clients von Automattic) lesen X-WP-Total, um ihre Pagination-Cursor zu steuern.

GET /wp-json/wc/v3/orders/{id}

Einzelne Bestellung anhand der numerischen id.

Antwort (200): siehe Antwortstruktur.

Fehler:

{
  "code":    "woocommerce_rest_shop_order_invalid_id",
  "message": "Invalid shop_order ID.",
  "data":    { "status": 404, "id": 99999 }
}

GET /wp-json/wc/v3/orders/{id}/notes

Listet die Statusverlaufseinträge der Bestellung, aufbereitet als WooCommerce-Notizen.

Antwort (200):

[
  {
    "id":               42,
    "author":           "system",
    "date_created":     "2026-04-10T12:00:00+00:00",
    "date_created_gmt": "2026-04-10T12:00:00+00:00",
    "note":             "Payment received",
    "customer_note":    false,
    "_links":           { "self": [...], "collection": [...], "up": [...] }
  }
]

customer_note ist immer false, weil Stoar auf Datenebene nicht zwischen kundensichtbaren und rein internen Notizen unterscheidet.

POST /wp-json/wc/v3/orders/{id}/notes

Fügt eine Notiz hinzu (in Stoar auf eine neue OrderStatusLog-Zeile abgebildet).

Anfrage:

{ "note": "Customer phoned to confirm delivery slot" }

customer_note (bool) wird akzeptiert, hat derzeit aber keine Wirkung.

Antwort (201): die neue Notiz in derselben Struktur wie die Einträge von GET .../notes.

Fehler:

• 400 rest_invalid_param — note fehlt
• 404 — unbekannte Bestell-id

GET /wp-json/wc/v3/orders/{id}/refunds

Listet die Erstattungen einer Bestellung. Stoar hat keine separate Erstattungstabelle — der Adapter liefert entweder:

• [], wenn refunded_amount === 0, oder
• [{...}] mit einer synthetischen Erstattungszeile, deren id === parent_id === order.id ist

[
  {
    "id":               123,
    "parent_id":        123,
    "date_created":     "2026-04-12T08:00:00+00:00",
    "amount":           "30.00",
    "reason":           "",
    "refunded_by":      0,
    "refunded_payment": true,
    "meta_data":        [],
    "line_items":       [],
    "api_refund":       true
  }
]

POST /wp-json/wc/v3/orders/{id}/refunds

Löst eine Erstattung aus. Delegiert an Stoars vorhandenes Order::processRefund(), das Stripe über StripeService::processRefund() aufruft. Bei einer vollständigen Erstattung markiert Stoar die Bestellung als refunded, bei Teilerstattungen wird refunded_amount aufsummiert.

Anfrage:

{ "amount": 30, "reason": "Customer changed mind" }

Beide Felder sind optional. Fehlt amount, erstattet Stoar den gesamten noch erstattungsfähigen Restbetrag.

Antwort (201): die Erstattungszeile in der oben gezeigten Struktur.

Fehler:

• 404 — unbekannte Bestell-id
• 422 woocommerce_rest_invalid_state — Bestellung ist nicht erstattungsfähig (kein Stripe Payment Intent, Status nicht paid/processing/shipped/delivered)

GET /wp-json/wc/v3/products

Produkte auflisten.

Query-Parameter: siehe Query-Parameter.

Antwort (200): flaches Array, mit den Headern X-WP-Total / X-WP-TotalPages.

GET /wp-json/wc/v3/products/{id}

Einzelnes Produkt anhand der numerischen id (NICHT über die SKU wie bei Magento).

Antwort (200): siehe Antwortstruktur.

Fehler: 404 woocommerce_rest_product_invalid_id.

Query-Parameter #

WooCommerce nutzt flache Query-String-Parameter — deutlich einfacher als Magentos verschachtelte searchCriteria[…]-Grammatik. Die Übersetzung in dieselben herstellerneutralen Wertobjekte OrderQuery / ProductQuery findet in den Adapter-Klassen Search/OrderQueryParser und Search/ProductQueryParser statt.

Gemeinsame Parameter (Bestellungen + Produkte)

Nur Bestellungen

Nur Produkte

Unbekannte Parameter werden stillschweigend ignoriert (wie bei WC). Filterwerte, die sich in nichts Sinnvolles übersetzen lassen (z. B. ?status=on-hold bei Produkten), ergeben eine leere Gruppe, keinen 400er.

Feld-Mapping (WooCommerce ↔ STOAR) #

Bestellung

Bestellposition line_item

Produkt

Statusübersetzung #

WooCommerce und Stoar verwenden unterschiedliche Statusvokabulare. Der Adapter übersetzt bidirektional: beim Filtern (?status=processing) werden WC-Werte auf Stoar abgebildet, beim Serialisieren der Antworten wird Stoars status zurück auf WC abgebildet.

Bestellstatus

Produktstatus

Produkttyp

Filterwerte, die auf null abbilden (z. B. ?status=trash bei Produkten), werden stillschweigend ignoriert — sie erzeugen keinen Fehler.

Antwortstruktur #

Bestellung — kommentiertes Beispiel

{
  "id":             456,
  "parent_id":      0,
  "number":         "456",
  "order_key":      "abc123…",
  "created_via":    "checkout",
  "version":        "8.5.0",
  "status":         "processing",
  "currency":       "EUR",
  "date_created":   "2026-04-10T09:00:00+00:00",
  "date_modified":  "2026-04-10T09:30:00+00:00",
  "discount_total": "0.00",
  "discount_tax":   "0.00",
  "shipping_total": "5.00",
  "shipping_tax":   "0.00",
  "cart_tax":       "10.00",
  "total":          "115.00",
  "total_tax":      "10.00",
  "prices_include_tax": false,
  "customer_id":    45,
  "customer_note":  "",
  "billing":        { /* WC address shape (flat) */ },
  "shipping":       { /* WC address shape (flat) */ },
  "payment_method": "stripe",
  "payment_method_title": "Credit / Debit Card",
  "transaction_id": "pi_test_…",
  "date_paid":      "2026-04-10T09:05:00+00:00",
  "date_completed": null,
  "cart_hash":      "",
  "meta_data":      [
    { "id": 0, "key": "_stoar_status",       "value": "paid" },
    { "id": 0, "key": "_stoar_lookup_token", "value": "abc123…" }
  ],
  "line_items": [
    {
      "id":            456,
      "name":          "Widget",
      "product_id":    789,
      "variation_id":  12,
      "quantity":      2,
      "tax_class":     "",
      "subtotal":      "100.00",
      "subtotal_tax":  "10.00",
      "total":         "100.00",
      "total_tax":     "10.00",
      "taxes":         [],
      "meta_data":     [],
      "sku":           "WID-1-A",
      "price":         50
    }
  ],
  "tax_lines":      [],
  "shipping_lines": [
    {
      "id":           0,
      "method_title": "Standard",
      "method_id":    "flat_rate",
      "instance_id":  "",
      "total":        "5.00",
      "total_tax":    "0.00",
      "taxes":        [],
      "meta_data":    []
    }
  ],
  "fee_lines":    [],
  "coupon_lines": [],
  "refunds":      [],
  "_links":       {
    "self":       [{ "href": "https://app.stoar.ai/wp-json/wc/v3/orders/456" }],
    "collection": [{ "href": "https://app.stoar.ai/wp-json/wc/v3/orders" }]
  }
}

Produkt — gekürztes Beispiel

{
  "id":                 789,
  "name":               "Widget",
  "slug":               "widget",
  "permalink":          "https://app.stoar.ai/product/widget",
  "type":               "simple",
  "status":             "publish",
  "featured":           true,
  "catalog_visibility": "visible",
  "description":        "<p>A great widget</p>",
  "short_description":  "Great widget",
  "sku":                "WID-1",
  "price":              "79.99",
  "regular_price":      "99.99",
  "sale_price":         "79.99",
  "on_sale":            true,
  "purchasable":        true,
  "manage_stock":       true,
  "stock_quantity":     42,
  "stock_status":       "instock",
  "weight":             "1.5",
  "categories":         [{ "id": 5, "name": "Widgets", "slug": "widgets" }],
  "images":             [
    { "id": 0, "src": "products/widget.webp", "name": "primary",   "position": 0, "alt": "" },
    { "id": 0, "src": "products/g1.webp",     "name": "gallery-1", "position": 1, "alt": "" }
  ],
  "attributes":         [],
  "variations":         [],
  "meta_data":          [
    { "id": 0, "key": "_stoar_id", "value": "789" },
    { "id": 0, "key": "_stoar_low_stock_threshold", "value": "3" }
  ],
  "_links":             {
    "self":       [{ "href": "https://app.stoar.ai/wp-json/wc/v3/products/789" }],
    "collection": [{ "href": "https://app.stoar.ai/wp-json/wc/v3/products" }]
  }
}

Bei einem konfigurierbaren bzw. variablen Produkt ist variations mit Varianten-ids gefüllt, und stock_quantity ist die Summe der Variantenbestände.

Praxisbeispiel #

Live-Antwort aus der Produktion für GET /wp-json/wc/v3/orders/10126 (USD 936,98, zwei Positionen mit einfachen Produkten, bezahlt per PayID). Personenbezogene Daten anonymisiert.

Anfrage

GET /wp-json/wc/v3/orders/10126
Authorization: Bearer 2|L5pXj63e881lkgtHPK7Hjozyq7Pb3trHCy0iaDRf76405f72

Antwort

{
  "id":               10126,
  "parent_id":        0,
  "number":           "10126",
  "order_key":        "REDACTED-FOR-DOCS",
  "created_via":      "checkout",
  "version":          "8.5.0",
  "status":           "processing",
  "currency":         "USD",
  "date_created":     "2025-06-03T04:56:43+00:00",
  "date_modified":    "2025-06-03T04:56:43+00:00",
  "discount_total":   "0.00",
  "discount_tax":     "0.00",
  "shipping_total":   "0.00",
  "shipping_tax":     "0.00",
  "cart_tax":         "0.00",
  "total":            "936.98",
  "total_tax":        "0.00",
  "prices_include_tax": false,
  "customer_id":      5794,
  "customer_note":    "",
  "billing": {
    "first_name": "Jane",
    "last_name":  "Doe",
    "company":    "",
    "address_1":  "1 Example Street",
    "address_2":  "",
    "city":       "Phoenix",
    "state":      "AZ",
    "postcode":   "85001",
    "country":    "US",
    "email":      "",
    "phone":      "+1-555-0100"
  },
  "shipping":         { /* same shape as billing */ },
  "payment_method":   "payid",
  "payment_method_title": "PayID",
  "transaction_id":   "",
  "date_paid":        null,
  "date_completed":   null,
  "cart_hash":        "",
  "meta_data": [
    { "id": 0, "key": "_stoar_status",       "value": "paid" },
    { "id": 0, "key": "_stoar_lookup_token", "value": "REDACTED-FOR-DOCS" }
  ],
  "line_items": [
    {
      "id":           30219,
      "name":         "Reloop Terminal Mix 8",
      "product_id":   112238,
      "variation_id": 95589,
      "quantity":     3,
      "tax_class":    "",
      "subtotal":     "897.00",
      "subtotal_tax": "0.00",
      "total":        "897.00",
      "total_tax":    "0.00",
      "taxes":        [],
      "meta_data":    [],
      "sku":          "RELOOP_TERMINALMIX8_025-DEF",
      "price":        299
    },
    {
      "id":           30220,
      "name":         "Premium Skateboard Socks",
      "product_id":   51706,
      "variation_id": 33857,
      "quantity":     2,
      "tax_class":    "",
      "subtotal":     "39.98",
      "subtotal_tax": "0.00",
      "total":        "39.98",
      "total_tax":    "0.00",
      "taxes":        [],
      "meta_data":    [],
      "sku":          "SK8-SOCK-027-DEF",
      "price":        19.99
    }
  ],
  "tax_lines":      [],
  "shipping_lines": [
    {
      "id":           0,
      "method_title": "Free Shipping",
      "method_id":    "flat_rate",
      "instance_id":  "",
      "total":        "0.00",
      "total_tax":    "0.00",
      "taxes":        [],
      "meta_data":    []
    }
  ],
  "fee_lines":    [],
  "coupon_lines": [],
  "refunds":      [],
  "_links":       {
    "self":       [{ "href": "https://app.stoar.ai/wp-json/wc/v3/orders/10126" }],
    "collection": [{ "href": "https://app.stoar.ai/wp-json/wc/v3/orders" }]
  }
}

Fallstricke, die Integratoren kennen sollten

Sie überschneiden sich mit denen von Magento — die zugrunde liegenden Stoar-Daten sind dieselben, nur in einer anderen Hülle gerendert:

Fehlerstruktur #

WooCommerce-Fehler sehen so aus:

{
  "code":    "machine_readable_code",
  "message": "Human-readable message",
  "data":    { "status": 404, "id": 99999 }
}

… also NICHT wie Magentos {message, parameters, trace}.

data.status spiegelt stets den HTTP-Code. Ressourcenspezifische Schlüssel (data.id) kommen hinzu, wo sie sinnvoll sind.

Rate-Limiting #

Dieselbe per Sanctum-Token gekennzeichnete Drosselung, die Magento schützt (api-rest, standardmäßig 60 Anfragen/Minute), schützt auch die WC-Routen. Beides konfigurierst du global unter /manager/api-settings. Beim Auslösen nutzt die Antwort die WC-Fehlerhülle:

{
  "code":    "woocommerce_rest_too_many_requests",
  "message": "Too many requests. Please retry after a short pause.",
  "data":    { "status": 429 }
}

Die Oberfläche zur Konfiguration ist im Abschnitt Rate-Limiting der Magento-Dokumentation Schritt für Schritt beschrieben.

Siehe auch #

• app/Api/Core/OrderRepository.php, app/Api/Core/ProductRepository.php — die Abstraktionsgrenze, auf die sich jeder Adapter stützt
• app/Api/Adapters/WooCommerce/Support/StatusTranslator.php — bidirektionales Vokabular-Mapping
• WooCommerce-REST-API-Referenz — die Upstream-Spezifikation, die dieser Adapter nachbildet