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. Wird kein Wert übergeben, generiert das System automatisch einen (`AUTOID_…`). Aliasse: `token`, `bestid`.	String	✅ Ja
campaign_id	ID der Kampagne, der die Order zugeordnet wird. Kann alternativ über `emid`, `vc`, `admedia_id` oder `advertiser_id` aufgelöst werden.	Integer	✅ Ja
trigger_id	ID des Triggers, der bei Nutzung von `ordertoken` zwingend angegeben werden muss. Alternativ per `trigger_title`. Alias: `eventid`.	Integer	✅ Ja
status	Status der Order: `0` = offen, `1` = bestätigt, `2` = storniert. (Bei der Anlage immer `0` – Statusänderung erfolgt über den PUT-Endpoint.)	Integer	✅ Ja
turnover	Bestellwert in Kampagnenwährung. Komma und Punkt als Dezimaltrenner erlaubt. Alias: `preis`.	Float	✅ Ja
original_turnover	Bestellwert in Fremdwährung.	Float	Nein
commission	Provisionswert in Kampagnenwährung. Kann übergeben werden, falls selbst berechnet. Wert `"autocalculate"` berechnet bei dynamischen Triggern automatisch aus `turnover × trigger_value`.	Float	Nein
cancel_reason	Angabe eines Stornogrundes bei Status = 2 (storniert).	String	Nein
currency	Bestellwährung als 3-stelliger ISO-Code (z. B. `EUR`, `CHF`). Default = Kampagnen-Einstellung, sonst `EUR`. Umrechnungskurs wird automatisch gesetzt.	String	Nein
descr	Freitext-Beschreibung der Order (max. 255 Zeichen). Alias: `beschreibung`.	String	Nein
trigger_tstamp	Bestellzeitpunkt als Unix-Timestamp. Akzeptiert auch Apache-Log-Format bzw. eine 24-stellige Mongo-ObjectId (wird umgerechnet). Fehlt der Wert, wird die aktuelle Zeit genutzt.	Integer	Nein
emid	Klick-/Action-ID aus dem Tracking (24-stellig hex). Dient der Klick-Zuordnung und kann die `campaign_id` auflösen.	String	Nein*
vc	Gutscheincode-Tracking: löst Kampagne/Werbemittel über die Admedia-Einstellungen auf.	String	Nein*
project_id	Direkte Zuordnung per Projekt (Publisher). Erzeugt eine Track-Action, sofern eine Connection zur Kampagne besteht.	Integer	Nein*
subid	Attributionswert (SubID), wird am Auftrag gespeichert (max. 500 Zeichen).	String	Nein
sub_status	Substatus der Order (frei belegbar).	String	Nein
get_parameters	Objekt `{ "key": "value", … }` mit beliebigen Zusatzfeldern (z. B. `voucher`, `coupon`). Wird vor dem Tracking flach aufgelöst und am Auftrag gespeichert.	Object	Nein
(beliebiger Key)	Jeder weitere, nicht reservierte Parameter wird als Key/Value am Auftrag gespeichert (`orders_getparameter`, Key max. 25 Zeichen). Arrays landen als `key[subkey]`.	String	Nein

* Kampagnen-/Klick-Zuordnung: campaign_id ist Pflicht, kann aber alternativ über emid, vc, admedia_id oder advertiser_id aufgelöst werden. Für die Zuordnung zur ursprünglichen Klick-/View-Aktion sollte eine der Attributions-Methoden (emid oder project_id) mitgegeben werden.

Dublettenschutz: Dieselbe Kombination aus campaign_id + trigger_id + ordertoken wird innerhalb abgelehnt (ORDER_EXISTS / ORDER_REQUEST_FREEZED).

📘 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.