Einleitung
Browserbasierte Trackingmethoden versagen zunehmend: Cookie‑Blocker, ITP/ETP‑Politiken und eingeschränkte Third‑Party‑Cookies führen zu verlorenen Attributionsdaten. Für Händler bedeutet das unsichere Provisionsabrechnungen und steigende Streuverluste. Server‑to‑Server (S2S) und Conversions API (CAPI) ergänzen clientseitiges Tracking und stellen sicher, dass Abschlüsse zuverlässig erfasst, validiert und provisionsfähig übergeben werden. Dieser Leitfaden zeigt, wie Sie S2S/CAPI zu Affilentra einrichten, Ereignis‑Payloads korrekt mappen, Duplikate vermeiden und Fallback‑Prioritäten für den Provisionsprozess festlegen.
Übersicht: Architektur und Rollen
Affilentra stellt die rollengetrennte Plattform: Händler (Merchant) meldet Conversions, Affiliates liefern Klick‑/Click‑IDs, und die Plattform übernimmt Tracking, Validierung und Abrechnung. Für resilienten Betrieb empfehlen wir eine hybride Architektur:
- Clientseitiges Tracking (Pixel/JS) als primärer, leichter Weg, um Click‑IDs zu übergeben.
- Serverseitige Ereignisse (S2S/CAPI) als zuverlässige Quelle für Abschluss‑ und Zahlungsbestätigungen.
- Postback‑Mechanismen für Partner, die eigene Server‑Events senden.
Schritt 1 — Grundeinrichtung der S2S‑Schnittstelle
Vorbereitung:
- SSL/TLS für alle Endpunkte zwingend.
- Vergabe eines API‑Schlüssels oder HMAC‑Keys an Ihren Affilentra‑Account (self‑hosted: lokal verwaltbar).
- Definieren eines verbindlichen Event‑Schemas und Versionierung (z. B. v1, v2).
Implementierungsempfehlung:
- Expose einen sicheren POST‑Endpoint auf Händlerseite, der Conversions annimmt und an Affilentra weiterleitet oder direkt an Affilentra sendet, wenn Ihre Infrastruktur dies übernimmt.
- Authentifizierung per Authorization‑Header (API‑Key) oder HMAC‑Signature über Header + Timestamp, um Replay‑Angriffe zu verhindern.
- Bestätigungsantworten sollten einen eindeutigen Server‑Event‑ID zurückgeben, die Affilentra für Audits verwendet.
Schritt 2 — Payload‑Mapping: Pflichtfelder und sinnvolle Ergänzungen
Ein konsistentes Mapping reduziert Fehler beim Matching. Die folgenden Felder sollten in jedem S2S‑Event vorhanden sein:
- event_type: z. B. purchase, refund, lead
- event_id: global eindeutige ID (UUIDv4 oder ähnliche) für Deduplication
- transaction_id: Bestell‑/Zahlungsnummer des Shops
- click_id / affiliate_id: ID aus dem Affiliate‑Tracking (falls vorhanden)
- amount und currency: Brutto‑Betrag und Währung
- status: authorized, paid, refunded — zur Entscheidung über Provisionsanspruch
- timestamp: ISO8601 UTC Zeitstempel
- user_identifiers: gehashte E‑Mail (SHA256), Kunden‑ID (optional) — niemals Klartext‑Emails
Sinnvolle optionale Felder:
- item_lines: SKU, quantity, unit_price — für produktbasierte Provisionen
- client_ip, user_agent — für forensische und Anomalie‑Checks
- payment_method, shipping_status — für zeitgesteuerte Provisionen
Schritt 3 — Deduplicating & Conversion‑Validierung
Ziel: Jede Conversion nur einmal für Provisionsberechnung akzeptieren und gleichzeitig legitime mehrfach eintreffende Signale harmonisieren.
Empfohlene Dedup‑Strategie:
- Primärschlüssel: event_id. Wenn event_id vorhanden und neu, akzeptieren und speichern.
- Fallback‑Schlüssel: transaction_id + affiliate_id + window. Wenn event_id fehlt, prüft das System transaction_id kombiniert mit affiliate_id innerhalb eines konfigurierbaren Zeitfensters.
- Quellenpriorität: Weisen Sie jeder Quelle ein Vertrauenlevel zu (siehe nächste Sektion). Bei Konflikten gewinnt die Quelle mit höherer Priorität.
- Signaturprüfung: HMAC oder vergleichbare Signatur zur Validierung der Quelle.
Validierungsregeln für Provisionsberechtigung:
- Nur Events mit status = paid (oder explizit bestätigten Zahlungsstatus) auslösen Provisionszahlungen.
- Bei Rückerstattungen oder Chargebacks: auto‑markieren und Provision sperren oder zurückholen, abhängig von Ihrer Geschäftspraxis.
- Prüfen, ob click_id / affiliate_id plausibel ist und zur Kampagne passt.
Schritt 4 — Fallback‑Prioritäten im Provisionsprozess
Legende: Quellen können client (Browser‑Pixel), server (S2S/CAPI) oder partner (Affiliate‑Postback) sein. Prioritätenempfehlung für die meisten Händler:
- 1. Server‑seitige Zahlungsbestätigung (Shop -> Affilentra): Höchstes Vertrauen, weil Zahlungsstatus aus der Datenbank kommt.
- 2. Partner‑Postback mit validierter Signatur und transaction_id: Direkter Nachweis vom Affiliate‑System.
- 3. Server‑CAPI Events, die Click‑IDs enthalten und signiert sind.
- 4. Clientseitiges Pixel/JS‑Event: Gut für Echtzeit, aber geringeres Vertrauen bei Cookie‑Loss.
- 5. Manuelle/Batch‑Imports: Niedrigste Priorität und nur für Reconciliation.
Wesentliche Regeln:
- Eine bereits durch eine höhere Priorität bestätigte Conversion darf nicht durch ein nachträgliches, niedrig priorisiertes Signal überschrieben werden.
- Konflikte protokollieren und in Reconciliation‑Prozessen sichtbar machen.
- Konfigurierbare Time‑Windows: z. B. initiale Attribution durch Client und finaler Status durch Server innerhalb von 24–72 Stunden (anpassbar).
Sicherheit und Datenschutz
Empfehlungen:
- Übertragen Sie personenbezogene Daten nur gehashed (z. B. SHA256 der E‑Mail mit Salt, falls benötigt).
- Authentifizieren Sie jede S2S‑Anfrage und prüfen Sie Timestamp + Nonce, um Replay zu verhindern.
- Loggen Sie nur die für Troubleshooting notwendigen Daten und anonymisieren Sie sensible Informationen.
- Dokumentieren Sie Schema‑Versionen und bieten Sie eine Migrationsstrategie an (breaking changes vermeiden).
Betriebsablauf und Monitoring
So stellen Sie Betriebssicherheit und Nachvollziehbarkeit sicher:
- Implementieren Sie ein Dead‑Letter‑System für abgelehnte/fehlerhafte Events.
- Alerts bei Anomalien (z. B. plötzliche Rückgang an S2S‑Events oder Anstieg an Duplikaten).
- Regelmäßige Reconciliations zwischen Shop‑Orders, Zahlungsprovider und Affilentra‑Reports.
- Audit‑Logs, die Änderungen an Provisionsregeln und manuelle Adjustments dokumentieren.
Praxisfall: Mapping einer Kauf‑Bestätigung
Minimaler, akzeptabler Payload (Beispielfelder):
- event_type: purchase
- event_id: uuid-xyz
- transaction_id: 2026‑000123
- click_id: abc123
- amount: 129.90
- currency: EUR
- status: paid
- timestamp: 2026-10-23T12:34:56Z
- user_identifiers: {email_hash: "sha256:..."}
Wichtig: Wenn click_id fehlt, darf das Event trotzdem verarbeitet werden — jedoch mit niedrigerer Attributions‑Priorität und zusätzlicher Prüfung auf transaction_id.
Zusammenfassung
S2S/CAPI‑Events sind unverzichtbar, um Conversions zuverlässig zu erfassen, wenn clientseitige Methoden versagen. Richten Sie eine signierte, TLS‑geschützte S2S‑Schnittstelle ein, nutzen Sie eindeutige event_ids, mappen Sie Pflichtfelder konsistent und implementieren Sie eine klare Quellpriorität für Provisionen. Monitoring, Reconciliation und Datenschutz‑konforme Hashing‑Regeln runden das Setup ab. Die Kombination aus Client‑Pixel + S2S/CAPI mit einer deduplizierenden Validierung liefert die robusteste Grundlage für transparente Abrechnung über Affilentra.
Nächster Schritt
Affilentra selbst ausprobieren
Einheitliche Plattform, die Produktbereitstellung, Tracking, Conversion-Validierung, Provisionsberechnung und Auszahlung entlang klar getrennter Rollen transparent zusammenführt; Option zur self-hosted Installation mit Dauerlizenz ohne Umsatzbeteiligung; Händler behalten Kontrolle über Produkte, Konditionen und Werbemittel; Partner erhalten persönliche Trackinglinks und nachvollziehbare Auszahlungshistorie.