Create / easy.affiliate REST-API (Baskets)

📝 Einleitung

Um neue Orders inklusive Warenkorb automatisiert im easy.affiliate-System anzulegen, steht ein REST-konformer Webservice zur Verfügung. Über die HTTP-Methode POST wird pro Aufruf eine Bestellung mit ihren Warenkorb-Positionen übermittelt.

Die Bestellung durchläuft dabei dieselbe Logik wie ein getrackter Verkauf mit Warenkorb (/trck/ebasket/): Publisher-Zuordnung, Provision je Position (Regeln nach Artikel, Marke, Kategorie oder Default des Triggers), Bestellwert sowie serverseitige Tags und Postbacks der Kampagne. Bestellwert, Provision und Status werden immer vom System berechnet und können nicht übergeben 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 des Mandanten (muss > 0 sein, nicht -1). Die Kampagne muss zu diesem Mandanten gehören.	Integer
X-Auth-Token	Dein API-Token (im Frontend sichtbar)	String
X-Auth-ID	Deine Login-ID (im Frontend sichtbar)	Integer

Berechtigung: Nur Admin-Logins mit Lese- und Schreibrecht auf die Bestellungen (administration_orders). Der Login muss zum Mandanten aus X-Network-ID gehören.

📩 Endpunkte

• Admin: https://SUBDOMAIN.de/ws/V6/admin/REST/Baskets

🧪 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 '{
    "campaign_id": 123,
    "trigger_id": 5,
    "ordertoken": "E-10045",
    "emid": "5f0123456789abcdef012345",
    "basket": [
      {"article_number": "A-1", "productname": "Hemd", "category": "Herren", "amount": 2, "price": 19.90, "additional": {"brand": "X"}},
      {"article_number": "B-7", "amount": 1, "price": 5}
    ]
  }' \
  https://SUBDOMAIN.de/ws/V6/admin/REST/Baskets

🧾 Body-Parameter (Order)

Parameter	Beschreibung	Datentyp	Pflichtfeld
campaign_id	ID der Kampagne, der die Order zugeordnet wird.	Integer	✅ Ja
trigger_id	ID eines Triggers dieser Kampagne (z. B. Sale-Trigger).	Integer	✅ Ja
ordertoken	Eindeutiger Identifier für die Order (eigene Bestellnummer). 1–255 druckbare ASCII-Zeichen, ohne Leerzeichen und ohne ( ) ;.	String	✅ Ja
basket	Liste der Warenkorb-Positionen (min. 1, max. 200), siehe unten.	Array	✅ Ja
emid	Klick-/Action-ID aus dem Tracking (24-stellig). Muss zu einem Klick dieser Kampagne gehören.	String	Nein*
project_id	Direkte Zuordnung per Projekt (Publisher). Das Projekt muss mit der Kampagne verbunden sein.	Integer	Nein*
currency	Bestellwährung als 3-stelliger ISO-Code (z. B. EUR, CHF). Default = Kampagnen-Einstellung, sonst EUR. Unbekannte Währungen werden abgelehnt.	String	Nein
trigger_tstamp	Bestellzeitpunkt als Unix-Timestamp (Sekunden). Fehlt der Wert, wird die aktuelle Zeit genutzt.	Integer	Nein
descr	Freitext-Beschreibung der Order (max. 255 Zeichen).	String	Nein

* Publisher-Zuordnung: Es darf entweder emid oder project_id übergeben werden, nicht beides. Beide werden vorab geprüft: Eine unbekannte/abgelaufene emid, eine emid einer anderen Kampagne oder ein nicht verbundenes Projekt wird abgelehnt, statt die Order still dem Systempartner zuzuordnen. Ohne beide Angaben entscheidet die Kampagne, ob die Order an den Systempartner geht (Antwort enthält dann notice: NO_SESSION_FOUND).

Nicht erlaubt: turnover, commission, status und alle weiteren, nicht aufgeführten Felder werden mit einem Fehler abgelehnt.

🛒 Body-Parameter (Warenkorb-Position in basket)

Parameter	Beschreibung	Datentyp	Pflichtfeld
article_number	Artikelnummer / SKU (1–255 Zeichen). Provisionsregeln nach Artikel greifen darauf.	String	✅ Ja
amount	Menge, ganze Zahl ≥ 1.	Integer	✅ Ja
price	Preis einer Einheit, ≥ 0, nur Punkt als Dezimaltrenner (z. B. 19.90), max. 4 Nachkommastellen. Bei Brutto-Tracking der Kampagne wird die MwSt. wie beim Tracking abgezogen.	Float	✅ Ja
productname	Produktname (max. 255 Zeichen).	String	Nein
category	Kategorie für Provisionsregeln nach Kategorie. Leer = Artikelnummer.	String	Nein
additional	Objekt { "key": "value", … } mit max. 50 flachen Zusatzfeldern, wird an der Position gespeichert. additional.brand wird für Provisionsregeln nach Marke genutzt. Keys: 1–50 Zeichen aus A-Z a-z 0-9 _ -; reservierte Keys (z. B. currency, emid, campaign_id, commission, turnover) sind nicht erlaubt.	Object	Nein

Der Bestellwert der Order ergibt sich aus der Summe price × amount aller Positionen, die Provision aus der Summe der Positions-Provisionen.

Dublettenschutz: Dieselbe Kombination aus campaign_id + trigger_id + ordertoken wird abgelehnt (ORDER_EXISTS), die Antwort enthält die order_id der vorhandenen Order. Ein erneuter Aufruf, z. B. nach einem Timeout, ist dadurch gefahrlos möglich.

📤 Antwort

Erfolg:

{
  "order_inserted": true,
  "order_id": 4711815,
  "emid": "5f0123456789abcdef012345",
  "sessionid": "5f0123456789abcdef000001",
  "basket": [
    {"id": 981234, "productid": "A-1", "productname": "Hemd"},
    {"id": 981235, "productid": "B-7", "productname": ""}
  ]
}

Fehler: order_inserted: false, order_id: -1, dazu error und error_description. Alle Eingabefehler werden gesammelt in einer Antwort geliefert.

Error	Bedeutung
INVALID_REQUEST	Eingabe ungültig (Pflichtfeld fehlt, Format falsch, unbekanntes Feld, Trigger gehört nicht zur Kampagne, emid/project_id passt nicht, Währung unbekannt). Details in error_description.
ORDER_EXISTS	Order mit diesem ordertoken existiert bereits für Kampagne und Trigger; order_id enthält die vorhandene Order.
TRACKING_UNAVAILABLE	Das Tracking hat nicht geantwortet, die Order wurde vermutlich nicht angelegt. Erneut senden (Dublettenschutz greift).
sonstige	Ablehnung durch die Tracking-Logik bzw. Kampagnen-Einstellungen.

📘 Hinweise

Wichtige Implementierungsdetails:

• Ein Aufruf = eine Order: Der Body ist ein einzelnes JSON-Objekt, kein Array. Mehrere Orders werden mit mehreren Aufrufen angelegt.
• ordertoken: Muss je Kampagne und Trigger eindeutig sein – idealerweise die externe Bestellnummer des Shops.
• trigger_id: Wenn du diese nicht kennst, frage im Frontend deine Kampagnenkonfiguration ab.
• Preise: Immer mit Punkt als Dezimaltrenner übergeben (12.50, nicht 12,50).