gruene-seele/dev/partnercenter-api/README.md

PARTNERCENTER API Connector

Verbindet den WooCommerce-Shop (gruene-seele.bio) mit dem PARTNERCENTER-/ERP-System (https://api.gruene-seele.bio/): leitet Bestellungen weiter, überträgt DHL-Labels und gleicht den Versandstatus („Ampel" in der Bestellliste) ab.

• Aktuelle Version: 1.6.0
• API-Basis-URL: https://api.gruene-seele.bio/ (fest im Code, public/partnercenter-api/partnercenter-api.php)
• Zugangsdaten: als Konstanten in der wp-config.php des Shops:

  define('PARTNERCENTER_API_EMAIL', '…');
  define('PARTNERCENTER_API_PASSWORD', '…');
  define('PARTNERCENTER_API_DEV', false); // true = Testmodus
  

---

Die Status-Ampel (WICHTIG)

In der WooCommerce-Bestellliste (Spalte „PARTNERCENTER Status") zeigt ein farbiger Punkt den Fulfilment-Status aus dem ERP:

ERP-Status	Bedeutung	Anzeige im Shop
open	offen	🟠 orange
process	in Bearbeitung / Wartestellung	🟠 orange
sent	versendet	🟢 grün
close	abgeschlossen	🟢 grün
pick_up	Abholung (erfüllt)	🟢 grün
cancel	storniert	🔴 rot
(leer/unbekannt)	—	⚠️

So funktioniert der Abgleich

1. Beim Weiterleiten einer Bestellung setzt der Connector das Meta _partnercenter_api_order_status = open und merkt sich die Bestell-ID in der Option _partnercenter_api_unclear_order_ids.
2. Der stündliche WP-Cron-Event partnercenter_api_fetch_orders_status fragt für alle „unklaren" Bestellungen POST /api/wp/status ab und schreibt den neuen Status ins Meta.
3. Erreicht eine Bestellung einen Endzustand (sent, close, pick_up, cancel), fällt sie aus der Warteliste.

Merksatz: Läuft dieser Cron nicht (oder scheitert die API-Anmeldung), bleibt jede Bestellung auf ihrem Initialwert open = orange — egal wie korrekt das ERP antwortet. Genau das war die Ursache des „Ampel bleibt orange"-Fehlers (Testphase 08/2026, AP-38).

---

Cron einrichten & prüfen

Der Shop läuft mit DISABLE_WP_CRON = true; WP-Cron wird über einen System-Crontab angestoßen (empfohlen, verlässlicher als der Request-basierte WP-Cron):

*/5 * * * * wget --delete-after --timeout=50 --tries=1 https://www.gruene-seele.bio/wp-cron.php > /dev/null 2>&1

Ist der Status-Event eingeplant?

wp cron event list | grep -i partnercenter

• Zeile mit partnercenter_api_fetch_orders_status (recurrence 1 hour) → alles gut.
• Keine Ausgabe → der Event fehlt (Hauptursache des Ampel-Bugs). Nachplanen:

  wp cron event schedule partnercenter_api_fetch_orders_status now hourly
  

Seit v1.6.0 selbstheilend: partnercenter_api_ensure_cron() (Hook init) plant den Event bei jedem Request automatisch nach, falls er fehlt. Ein manuelles Nachplanen ist danach im Normalfall nicht mehr nötig — der obige Check bleibt aber das Diagnosemittel Nr. 1.

Abgleich manuell auslösen und prüfen

# Wie viele Bestellungen warten aktuell auf einen Status?
wp option get _partnercenter_api_unclear_order_ids --format=json
# ( []  = nichts offen / alles abgearbeitet )

# Abgleich sofort ausführen …
wp cron event run partnercenter_api_fetch_orders_status

# … und an einer bekannten, versendeten Bestellung prüfen:
wp post meta get <ORDER_ID> _partnercenter_api_order_status
# erwartet: sent  (→ grün)

---

Fehlersuche: Ampel bleibt orange

1. Event eingeplant? → wp cron event list | grep partnercenter (siehe oben). Fehlt er, nachplanen bzw. Plugin einmal deaktivieren/reaktivieren.
2. Nach wp cron event run bleibt der Status open? → Dann scheitert die API-Anmeldung. Konstanten prüfen und Login direkt testen:

   wp config get PARTNERCENTER_API_EMAIL
   wp config get PARTNERCENTER_API_PASSWORD
   
   # Login (Werte einsetzen) — es muss ein access_token zurückkommen:
   curl -s -X POST https://api.gruene-seele.bio/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"<EMAIL>","password":"<PASS>","remember_me":true}'
   
   # Status mit dem Token abfragen — erwartet "status":"sent":
   curl -s -X POST https://api.gruene-seele.bio/wp/status \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <TOKEN>" \
     -d '{"wp_order_numbers":[<ORDER_ID>]}'
   

3. Login schlägt fehl (kein Token / 401) → Zugangsdaten in wp-config.php falsch/abgelaufen.
4. api.gruene-seele.bio aus dem Shop nicht erreichbar → Firewall/DNS:

   curl -sI https://api.gruene-seele.bio/ | head -1
   

5. Status ist free oder ⚠️ → veraltete Connector-/ERP-Version. Ab v1.6.0 ist das Status-Mapping vollständig (Wartestellung process, pick_up, cancel).

---

Änderungen in v1.6.0

• AP-34 — Varianten-Artikelnummer: compose_cart_content() sendet jetzt die eigene SKU der Variation ($order_item->get_product()->get_sku(), Fallback Eltern-SKU) statt der Eltern-SKU. Vorbedingung: jede Variation braucht im Shop eine eigene, gepflegte Artikel-Nr. (SKU) = die wp_number des jeweiligen ERP-Produkts.
• AP-38 — Status-Ampel:
  • partnercenter_api_ensure_cron() (Hook init) plant den Status-Cron selbstheilend nach.
  • Ampel-Mapping ergänzt: pick_up → grün, cancel → rot (vorher beide ⚠️).
  • Endzustände pick_up/cancel fallen aus der stündlichen Warteliste.

Rollout

1. Plugin-Ordner partnercenter-api/ in wp-content/plugins/ austauschen.
2. Einmal deaktivieren + reaktivieren (oder mind. eine Seite aufrufen, damit partnercenter_api_ensure_cron() greift).
3. wp cron event list | grep partnercenter → Event muss vorhanden sein.
4. wp cron event run partnercenter_api_fetch_orders_status und an einer versendeten Bestellung sent/grün prüfen.