# Update / easy.affiliate REST-API (Orders)

## 📝 Einleitung
Um Orders automatisiert im **easy.affiliate-System** bearbeiten zu können, stellt die easy Marketing GmbH eine Webservice-API zur Verfügung. Diese ermöglicht es, bestehende Orders im Nachgang zu bearbeiten, sobald sie den Validierungsprozess durchlaufen.

Jedem User stehen hierfür ein **Authentifizierungs-Token** und eine **Login_id** zur Verfügung, die über das Frontend abgerufen werden können.

* **User-ID:** Wo ist die User-ID hinterlegt? (Siehe Frontend-Profil)
* **Access-Token:** Wo ist der Access-Token hinterlegt? (Siehe API-Einstellungen)

---

## Endpunkte

| Zielgruppe | URL |
| :--- | :--- |
| **Admin** | `https://SUBDOMAIN.de/ws/V6/admin/JSON/Orders` |
| **Advertiser** | `https://SUBDOMAIN.de/ws/V6/advertiser/JSON/Orders` |

---

## Beispiele

### Beispiel mit cURL
```bash
curl -X PUT \
  -H "Content-Type: application/json" \
  -H "X-Network-ID: -1" \
  -H "X-Auth-Token: ADMIN_APIUSER_TOKEN" \
  -H "X-Auth-ID: ADMIN_APIUSER_LOGIN_ID" \
  -d '[{ "campaign_id": 1, "id": 12345, "status": 1, "turnover":100.00, "commission":12.34 },{ "campaign_id": 1, "ordertoken":"123a456b", "status": 2, "turnover": 0.00 }]' \
  https://DOMAIN/ws/V6/admin/JSON/Orders
  ```
---
  ### Codebeispiel
Mit der folgenden Methode können mehrere Orders geupdatet werden. Ein Beispielaufruf sieht folgendermaßen aus:

#### Headers
| Variable | Wert / Bedeutung |
| :--- | :--- |
| **Content-Type** | `application/json` |
| **X-Network-ID** | `-1` |
| **X-Auth-Token** | `ADMIN_APIUSER_TOKEN` |
| **X-Auth-ID** | `ADMIN_APIUSER_LOGIN_ID` |

#### Body
```json
[
    {
        "id": "12345",
        "campaign_id": 1,
        "status": 1,
        "turnover": 10.00
    },
    {
        "ordertoken": "123a456b",
        "campaign_id": 1,
        "trigger_id": 1,              
        "status": 2,
        "turnover": 9.99,
        "cancel_reason": "Storno Grund"
    }
]
```
---
## Variablenerläuterung

### Headers
| Variable | Bedeutung | Datentyp |
| :--- | :--- | :--- |
| **Content-Type** | Der Content-Type des Requests | String |
| **X-NETWORKID** | Hier wird die ID des Mandanten eingetragen. Wenn nur ein Mandant vorhanden ist oder mandantenübergreifend gearbeitet wird, muss der Wert “-1” eingetragen werden. | Integer |
| **X-AUTH-TOKEN** | Hier wird der API-Authentifizierungs-Token des Admin Nutzers hinterlegt. | String |
| **X-AUTH-ID** | Hier wird die ID des Admin Nutzers hinterlegt. | Integer |

---

### Body

| Parameter | Beschreibung | Datentyp | Pflichtfeld |
| :----- | :--- | :--- | :--- |
| <span style="white-space:nowrap">**campaign_id**</span> | Kampagne, in der die Order gesucht wird. Wird **immer** benötigt – auch bei Identifikation per `id`. Alternativ über `emid` auflösbar. | <span style="white-space:nowrap">Integer</span> | <span style="white-space:nowrap">✅ Ja</span> |
| <span style="white-space:nowrap">**id**</span> | Interne Order-ID zur Identifikation der Order. Alternative zu `ordertoken`. | <span style="white-space:nowrap">Integer</span> | <span style="white-space:nowrap">✅ Ja (oder `ordertoken`)</span> |
| <span style="white-space:nowrap">**ordertoken**</span> | Ordertoken zur Identifikation. Alternative zu `id`. | <span style="white-space:nowrap">String</span> | <span style="white-space:nowrap">✅ Ja (oder `id`)</span> |
| <span style="white-space:nowrap">**trigger_id**</span> | ID des Triggers, der bei Nutzung von ordertoken zwingend angegeben werden muss. Alternativ per trigger_title. | <span style="white-space:nowrap">String</span> | <span style="white-space:nowrap">✅ Ja (oder `id`)</span> |
| <span style="white-space:nowrap">**emid**</span> | Klick-/Action-ID (24-stellig hex). Kann `campaign_id` auflösen. | <span style="white-space:nowrap">String</span> | <span style="white-space:nowrap">Nein</span> |
| <span style="white-space:nowrap">**status**</span> | `0` = offen, `1` = bestätigt, `2` = storniert, `3` = ausgezahlt. | <span style="white-space:nowrap">Integer</span> | <span style="white-space:nowrap">Nein</span> |
| <span style="white-space:nowrap">**turnover**</span> | Bestellwert in Kampagnenwährung. | <span style="white-space:nowrap">Float</span> | <span style="white-space:nowrap">Nein</span> |
| <span style="white-space:nowrap">**original_turnover**</span> | Bestellwert in Fremdwährung. **Achtung:** Wenn gesetzt, wird damit der `turnover` überschrieben. | <span style="white-space:nowrap">Float</span> | <span style="white-space:nowrap">Nein</span> |
| <span style="white-space:nowrap">**commission**</span> | Provisionswert in Kampagnenwährung. Wert `"autocalculate"` berechnet bei dynamischen Triggern automatisch`. | <span style="white-space:nowrap">Float</span> | <span style="white-space:nowrap">Nein</span> |
| <span style="white-space:nowrap">**cancel_reason**</span> | Stornogrund bei Status `2`. | <span style="white-space:nowrap">String</span> | <span style="white-space:nowrap">Nein</span> |
| <span style="white-space:nowrap">**status_change_date**</span> | Datum der Statusänderung (ISO 8601). Wird gesetzt, wenn übergeben; ansonsten bei Statuswechsel automatisch. Steuert intern auch das Billing-/Moderationsdatum. | <span style="white-space:nowrap">Datetime</span> | <span style="white-space:nowrap">Nein</span> |
| <span style="white-space:nowrap">**sub_status**</span> | Substatus der Order (frei belegbar). | <span style="white-space:nowrap">String</span> | <span style="white-space:nowrap">Nein</span> |
| <span style="white-space:nowrap">**description**</span> | Freitext-Beschreibung (max. 255 Zeichen). | <span style="white-space:nowrap">String</span> | <span style="white-space:nowrap">Nein</span> |
| <span style="white-space:nowrap">**order_currency**</span> | Bestellwährung als ISO-Code. | <span style="white-space:nowrap">String</span> | <span style="white-space:nowrap">Nein</span> |
| <span style="white-space:nowrap">**subid_value**</span> | Attributionswert (SubID). **Nicht** `subid` wie beim Create | <span style="white-space:nowrap">String</span> | <span style="white-space:nowrap">Nein</span> |
| <span style="white-space:nowrap">**get_parameters**</span> | Objekt `{ "key": "value", … }`. Wird pro Order upserted (`orders_getparameter`). | <span style="white-space:nowrap">Object</span> | <span style="white-space:nowrap">Nein</span> |

**\*) Hinweis:** Wird der `ordertoken` genutzt, ist neben der `campaign_id` auch die `trigger_id` ein Pflichtfeld.