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:
  ```php
  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):

```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?
```bash
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:
  ```bash
  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
```bash
# 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:
   ```bash
   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:
   ```bash
   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.