# Order Webservice

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

## 📝 Einleitung
Um neue Orders automatisiert im easy.affiliate-System anzulegen, steht ein REST-konformer Webservice zur Verfügung. Über die HTTP-Methode **POST** können neue Transaktionen übermittelt werden. Jeder User erhält hierfür einen Authentifizierungs-Token und eine Login-ID, die im Frontend einsehbar sind.

---

## 🔐 Authentifizierung
Für den Zugriff sind folgende Header erforderlich:

| Header | Beschreibung | Typ |
| :--- | :--- | :--- |
| **Content-Type** | Muss auf `application/json` gesetzt sein | String |
| **X-Network-ID** | Netzwerk-ID: meist `-1` für mandantenübergreifende API | Integer |
| **X-Auth-Token** | Dein API-Token (im Frontend sichtbar) | String |
| **X-Auth-ID** | Deine Login-ID (im Frontend sichtbar) | Integer |

---

## 📩 Endpunkte

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

---

## 🧪 Beispiel (cURL)

```bash
curl -X POST \
  -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 '[{
    "ordertoken": "testorder001",
    "campaign_id": 1,
    "trigger_id": 2,
    "status": 1,
    "turnover": 199.99,
    "commission": 20.00
  }]' \
  https://SUBDOMAIN.de/ws/V6/admin/JSON/Orders
```

---

### 🧾 Body-Parameter

| Parameter | Beschreibung | Datentyp | Pflichtfeld |
| :--- | :--- | :--- | :--- |
| **ordertoken** | Eindeutiger Identifier für die Order. Muss systemweit eindeutig sein. | String | ✅ Ja |
| **campaign_id** | ID der Kampagne, der die Order zugeordnet wird. | Integer | ✅ Ja |
| **trigger_id** | ID des Triggers, der bei Nutzung von `ordertoken` zwingend angegeben werden muss. | Integer | ✅ Ja |
| **status** | Status der Order: `0` = offen, `1` = bestätigt, `2` = storniert | Integer | ✅ Ja |
| **turnover** | Bestellwert in Kampagnenwährung | Float | ✅ Ja |
| **original_turnover** | Bestellwert in Fremdwährung | Float | Nein |
| **commission** | Provisionswert in Kampagnenwährung. Kann übergeben werden, falls selbst berechnet | Float | Nein |
| **cancel_reason** | Angabe eines Stornogrundes bei Status = 2 (storniert) | String | Nein |

---

### 📘 Hinweise

 **Wichtige Implementierungsdetails:**
* **ordertoken:** Muss **eindeutig** sein – idealerweise eine Kombination aus Zeitstempel, Shop-ID oder externer Ordernummer.
* **trigger_id:** Wenn du diese nicht kennst, frage im Frontend deine Kampagnenkonfiguration ab.
* **Bulk-Aktionen:** Du kannst auch mehrere Orders in einem Array auf einmal anlegen.
* **Updates:** Wird eine Order mit gleichem `ordertoken` bereits im System gefunden, kann ein `PUT-Request` genutzt werden, um sie zu aktualisieren.

# 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,
        "commission": 0.99
    },
    {
        "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

> Im nachfolgenden werden die Standard-Parameter aufgelistet. Es ist aber über die API möglich, alle zur Verfügung stehenden Parameter zu updaten.

| Parameter | Erklärung | Datentyp | Pflichtfeld |
| :--- | :--- | :--- | :--- |
| **id** | Hier wird die Transaktionsid hinterlegt.<br>Aufbau: `"id":"ID"` | String | Ja (oder `ordertoken`) |
| **ordertoken** | Hier wird der Ordertoken hinterlegt.<br>Aufbau: `"ordertoken":"ORDERTOKEN"` | String | Ja (oder `id`).* |
| **campaign_id** | Hier wird die Campaign_id hinterlegt.<br>Aufbau: `"campaign_id":CAMPAIGN_ID` | Integer | Ja |
| **trigger_id** | Hier wird die Trigger ID hinterlegt.<br>Aufbau: `"trigger_id":TRIGGER_ID` | Integer | Nein, nur falls `ordertoken` genutzt wird. |
| **status** | Hier wird der Status hinterlegt.<br>**Werte:** `-5` (ausstehende Nachbuchung), `0` (offen), `1` (bestätigt), `2` (storniert) | Integer | Nein |
| **turnover** | Hier wird der Bestellwert der Transaktion in Kampagnenwährung hinterlegt.<br>Aufbau: `"turnover":TURNOVER` | Float | Nein |
| **original_turnover** | Hier wird der Bestellwert der Transaktion in Fremdwährung hinterlegt.<br>Aufbau: `"original_turnover":TURNOVER_IN_FREMDWÄHRUNG` | Float | Nein |
| **commission** | Hier wird die Provisionshöhe in Kampagnenwährung hinterlegt, falls Sie die Commission selbst berechnen möchten. | Float | Nein |
| **cancel_reason** | Übergeben Sie den Stornogrund.<br>Aufbau: `"cancel_reason":"Stornogrund"` | String | Nein |

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