Skip to main content

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.