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

🧾 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*
admedia_id	Werbemittel-ID. Ergänzt `project_id`-Tracking und löst die `campaign_id` auf.	Integer	Nein*
advertiser_id	Advertiser-ID zur Fallback-Kampagnen-Auflösung bzw. Session-Zuordnung.	Integer	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*
publisher_id	Wird intern zu `project_id` aufgelöst.	Integer	Nein*
trackid	Track-/Session-ID zur Zuordnung (24-stellig hex).	String	Nein*
actionid	Explizite Action-ID zur Session-Auflösung (24-stellig hex).	String	Nein*
pvid	Post-View-ID (24-stellig hex), wird als `trackid` verwendet.	String	Nein*
trs	Session-ID (24-stellig hex); sonst aus dem Cookie.	String	Nein*
forcedTrackId	Erzwingt eine bestimmte `trackid`.	String	Nein
click_timestamp	Klickzeitpunkt (Unix-Timestamp) bei `project_id`-Tracking.	Integer	Nein
clickOverwritesVoucher	Lässt bei Gutscheincode-Tracking einen echten Klick den Voucher-Fallback überschreiben.	Flag	Nein
source	Wert `fp` markiert die Conversion als Fingerprint-Tracking.	String	Nein
ezActivateFingerprintTracking	Aktiviert Fingerprint-Tracking für den Request.	Bool	Nein
ident_suffix	Suffix, das an die Tracking-Identifikation (`source`) angehängt wird.	String	Nein
subid	Attributionswert (SubID), wird am Auftrag gespeichert (max. 500 Zeichen).	String	Nein
sub_status	Substatus der Order (frei belegbar).	String	Nein
hide_order	Wert `1` legt die Order versteckt an (`visibility = 0`).	Integer	Nein
visibility	Sichtbarkeit direkt setzen: `0` (versteckt) oder `1` (sichtbar).	Integer	Nein
lifetime	Setzt die Klick-/Cookie-Mindestlaufzeit auf „unbegrenzt" und qualifiziert damit auch ältere Klicks.	Bool	Nein
blockTags	Unterdrückt das Ausführen der Order-Tags/Pixel in der Antwort.	Flag	Nein
trackingTest	Wert `true` = Testmodus; die Order wird nach `data.orders_trackingtest` statt in den Echtbestand geschrieben.	Bool	Nein
t	Antwortformat: `json`, `js`, `img` oder `exec_tags_only`. Alias über `mode` (`1` = js, `2` = img).	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, trackid, actionid, pvid, trs, project_id/publisher_id, vc) mitgegeben werden.

Reservierte Keys (werden nicht als Custom-Parameter gespeichert): prid, bestid, beschreibung, preis, lead, sale, js, currency, campaign_id, project_id, pid, trigger_id, token, descr, turnover, t, eventid, nwtrack, json, callback, _url, emid, actionid, trackid, subid, pvid, _.

Dublettenschutz: Dieselbe Kombination aus campaign_id + trigger_id + ordertoken wird innerhalb von 60 Sekunden abgelehnt (ORDER_EXISTS / ORDER_REQUEST_FREEZED). Der Vergleichsschlüssel ist per Kampagnen-Setting order_constraint_key umstellbar (emid, sessionid, ordertoken_projectid).

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