Nachbuchungsanfragen per API abrufen und bearbeiten (V6-REST-API)

Über die V6-REST-API können Sie Nachbuchungsanfragen Ihrer Publisher automatisiert abrufen, prüfen, annehmen, ablehnen und bearbeiten. Die API bietet dieselben Funktionen wie das Nachbuchungstool in der Oberfläche. Jede Entscheidung, die Sie per API treffen, erscheint dort ebenfalls und wird in der Historie der Anfrage mit Zeitpunkt und Benutzer protokolliert.

1. Zugang

Basis-URL

<Ihre-Domain> ist die Domain Ihrer Installation, also dieselbe Adresse, unter der Sie sich in der Oberfläche anmelden.

Authentifizierung

Jeder Aufruf braucht drei HTTP-Header:

Wo Sie den Token finden: Im Menü unter API → Daten-API. Dort wird Ihr API-Token angezeigt.

Berechtigung

Der Benutzer braucht das Recht Nachbuchungstool (bookingrequests_tool). Zum Abrufen genügt Leserecht, für Entscheidungen und Änderungen ist Lese- und Schreibrecht nötig. Die API arbeitet immer mit genau den Rechten des Benutzers, dessen Token Sie verwenden. Ein Advertiser-Login sieht nur die Nachbuchungen seiner eigenen Kampagnen.

2. Endpunkte im Überblick

Die vollständige technische Beschreibung mit allen Feldern finden Sie in der OpenAPI-/Swagger-Dokumentation unter https://<Ihre-Domain>/ws/docs/v6. Dort melden Sie sich mit Login-ID und Token an.

3. Nachbuchungsanfragen abrufen

curl "https://<Ihre-Domain>/ws/V6/advertiser/REST/Bookingrequests?params[state]=open&params[limit]=200" \
  -H "X-Auth-ID: <ID>" \
  -H "X-Auth-Token: <API-TOKEN>" \
  -H "X-Network-ID: 1"

Filter

Jede Zeile enthält Hinweise (warnings), die Ihnen bei der Entscheidung helfen:

Trigger einer Kampagne abfragen

curl "https://<Ihre-Domain>/ws/V6/advertiser/REST/Bookingrequests?params[view]=triggers&params[campaign_id]=1" \
  -H "X-Auth-ID: <ID>" -H "X-Auth-Token: <API-TOKEN>" -H "X-Network-ID: 1"

Eine einzelne Anfrage

curl "https://<Ihre-Domain>/ws/V6/advertiser/REST/Bookingrequests/123456" \
  -H "X-Auth-ID: <ID>" -H "X-Auth-Token: <API-TOKEN>" -H "X-Network-ID: 1"

Neben den Grunddaten liefert die Detailansicht:

• Dubletten: bestehende Transaktionen mit derselben Bestellnummer, demselben Trigger und derselben Kampagne, unabhängig vom Publisher,
• Gutschein-Prüfung: ob der Code unbekannt ist, einem anderen Publisher gehört, zum Kaufzeitpunkt ungültig war oder schon eingelöst wurde,
• die verfügbaren Trigger der Kampagne,
• die Historie aller Änderungen.

Diese Prüfungen sind Hinweise für Ihre Entscheidung. Sie blockieren nichts.

4. Annehmen, ablehnen, Trigger zuweisen

Alle Aktionen laufen über POST Bookingrequests mit einem JSON-Body. In order_ids können Sie mehrere Anfragen auf einmal übergeben.

Annehmen

curl -X POST "https://<Ihre-Domain>/ws/V6/advertiser/REST/Bookingrequests" \
  -H "X-Auth-ID: <ID>" -H "X-Auth-Token: <API-TOKEN>" -H "X-Network-ID: 1" \
  -H "Content-Type: application/json" \
  -d '{ "action": "accept", "order_ids": [123456, 123457], "status": 1 }'

Beim Annehmen wird die Provision nach den Kampagneneinstellungen zum Kaufzeitpunkt neu berechnet. Das gilt nicht, wenn sie vorher manuell überschrieben wurde (siehe Abschnitt 5).

Ablehnen

curl -X POST "https://<Ihre-Domain>/ws/V6/advertiser/REST/Bookingrequests" \
  -H "X-Auth-ID: <ID>" -H "X-Auth-Token: <API-TOKEN>" -H "X-Network-ID: 1" \
  -H "Content-Type: application/json" \
  -d '{ "action": "reject", "order_ids": [123458], "reject_code": "already_booked", "reason": "Bestellung bereits über Partner X getrackt" }'

Ein Ablehnungsgrund (reject_code) ist Pflicht:

Der Publisher sieht Grund und Text.

Trigger zuweisen (mehrere Anfragen derselben Kampagne)

{ "action": "trigger", "order_ids": [123456, 123457], "trigger_id": 2 }

Provisionsvorschau (ohne zu speichern)

{ "action": "preview", "order_id": 123456, "trigger_id": 2, "turnover": 89.90 }

Die Vorschau liefert die Provision, die sich mit diesem Trigger und Warenkorbwert ergeben würde. Mit "lead": true wird sie für einen Lead ohne Warenkorbwert berechnet. Für die Vorschau genügt Leserecht.

Die Aktionen accept, reject und trigger liefern je Order ein eigenes Ergebnis. So sehen Sie, welche Orders verarbeitet wurden und welche nicht.

5. Eine Anfrage bearbeiten

curl -X PUT "https://<Ihre-Domain>/ws/V6/advertiser/REST/Bookingrequests/123456" \
  -H "X-Auth-ID: <ID>" -H "X-Auth-Token: <API-TOKEN>" -H "X-Network-ID: 1" \
  -H "Content-Type: application/json" \
  -d '{ "trigger_id": 1, "turnover": 79.90 }'

Eine manuell überschriebene Provision wird markiert und beim Annehmen nicht neu berechnet.

6. Entscheidungen gesammelt per CSV übergeben

Viele Entscheidungen auf einmal können Sie auch als CSV übergeben. Das Format ist dasselbe wie beim Import im Nachbuchungstool:

{ "action": "import", "content": "order_id;action;status;reject_code;reason;trigger_id\n123456;accept;1;;;\n123458;reject;;cancelled;;", "apply": true }

Ohne apply (Standard false) wird die Datei nur geprüft. Übernommen wird erst ein Aufruf mit "apply": true. Wir empfehlen, immer zuerst einen Prüflauf zu machen.

7. Hinweise für Publisher pflegen

Über Bookingrequesthints (GET / PUT / POST / DELETE) pflegen Sie den Hinweistext mit bis zu sechs Screenshots. Publisher sehen ihn beim Einreichen einer Nachbuchung, zum Beispiel mit der Angabe, wo die Bestellnummer steht oder welche Daten nicht mitgeschickt werden sollen. Es gibt einen allgemeinen Hinweis für alle Kampagnen und optional einen eigenen je Kampagne, der dann Vorrang hat.

8. Benachrichtigung bei neuen Anfragen

Unabhängig von der API erhalten Sie bei jeder neuen Nachbuchungsanfrage eine E-Mail an Ihre Kontaktadresse. Sie enthält Kampagne, Publisher, Anzahl, Warenkorbwert, mögliche Dubletten, Gutschein-Hinweise und die Zahl aller offenen Anfragen. Die Mail eignet sich gut als Auslöser für einen API-Abruf. Alternativ fragen Sie die API regelmäßig ab, zum Beispiel einmal pro Stunde mit params[state]=open.

9. Typischer Ablauf einer Integration

1. Abrufen: GET Bookingrequests?params[state]=open
2. Abgleichen: Bestellnummer und Warenkorbwert mit Ihrem Shop- oder ERP-System vergleichen. Optional die Detailansicht GET Bookingrequests/{id} für Dubletten und Gutscheine nutzen.
3. Korrigieren (optional): PUT Bookingrequests/{id} bei abweichendem Warenkorbwert oder Trigger.
4. Entscheiden: POST Bookingrequests mit accept (Status 0 oder 1) bzw. reject und Grund.

10. Fehlercodes

Fehlerantworten haben immer einen JSON-Body mit error: true und einer Meldung in msg. Bei ungültigen Zeilen steht zusätzlich die Liste errors dabei.

Bei Fragen zur Einrichtung wenden Sie sich gern an unseren Support.