Order Webservice

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

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)

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

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

[
    {
        "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. Aufbau: `"id":"ID"`	String	Ja (oder `ordertoken`)
ordertoken	Hier wird der Ordertoken hinterlegt. Aufbau: `"ordertoken":"ORDERTOKEN"`	String	Ja (oder `id`).*
campaign_id	Hier wird die Campaign_id hinterlegt. Aufbau: `"campaign_id":CAMPAIGN_ID`	Integer	Ja
trigger_id	Hier wird die Trigger ID hinterlegt. Aufbau: `"trigger_id":TRIGGER_ID`	Integer	Nein, nur falls `ordertoken` genutzt wird.
status	Hier wird der Status hinterlegt. Werte: `-5` (ausstehende Nachbuchung), `0` (offen), `1` (bestätigt), `2` (storniert)	Integer	Nein
turnover	Hier wird der Bestellwert der Transaktion in Kampagnenwährung hinterlegt. Aufbau: `"turnover":TURNOVER`	Float	Nein
original_turnover	Hier wird der Bestellwert der Transaktion in Fremdwährung hinterlegt. 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. Aufbau: `"cancel_reason":"Stornogrund"`	String	Nein

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