Schnittstelle

Eigenes System anbinden

Für alles ohne fertiges Modul: Abo-Systeme, Buchungsplattformen, Eigenentwicklungen. Zwei Aufrufe genügen.

Bestellung

Eine Bestellung melden

Vom eigenen Server aus, sobald eine Bestellung entsteht. Beträge werden als ganzzahlige Centbeträge übergeben — eine Dezimalzahl wäre die Einladung zu Rundungsfehlern, die sich über viele Bestellungen zu echten Differenzen summieren.

POST https://api.affleo.de/api/v1/tracking/conversion
Content-Type: application/json

{
  "tenantId": "IHRE_KENNUNG",
  "externalOrderId": "1042",
  "amount": 11900,
  "currency": "EUR",
  "email": "kunde@example.com",
  "referralCode": "ANNA10"
}

Feld	Pflicht	Bedeutung
externalOrderId	ja	Ihre Bestellnummer. Verhindert Doppelzählung.
amount	ja	Nettobetrag in Cent, ganzzahlig
email	empfohlen	Grundlage der Kundenzuordnung. Wird sofort zu einem Schlüsselwert verrechnet, nie im Klartext gespeichert.
referralCode	bedingt	Wenn bekannt. Sonst greift Klick oder Kundenzuordnung.
clickId	bedingt	Aus dem Browser-Skript, falls Sie es weiterreichen können
type	nein	`sale`, `lead` oder `subscription_renewal`

Abonnements

Wiederkehrende Zahlungen

Bei Abo-Systemen entsteht die Folgebestellung ohne Zutun des Kunden. Es gibt keinen Klick, kein Cookie, keinen Empfehlungscode — trotzdem soll der Partner vergütet werden.

Der Weg dafür führt über die Kundenzuordnung: Der Kunde wird einmal einem Partner zugeordnet, danach findet ihn jede weitere Bestellung über die E-Mail wieder.

Erstens: Kunden zuordnen

Beim ersten Kontakt, solange der Empfehlungscode noch bekannt ist. Auch dann, wenn noch keine Zahlung erfolgt:

POST https://api.affleo.de/api/v1/tracking/customer

{
  "tenantId": "IHRE_KENNUNG",
  "email": "kunde@example.com",
  "referralCode": "ANNA10"
}

Zweitens: Verlängerungen melden

Bei jeder Abrechnung. Ohne Empfehlungscode — den findet Affleo über die Kundenzuordnung:

POST https://api.affleo.de/api/v1/tracking/conversion

{
  "tenantId": "IHRE_KENNUNG",
  "externalOrderId": "sub_88",
  "amount": 2900,
  "currency": "EUR",
  "email": "kunde@example.com",
  "type": "subscription_renewal"
}

Bei subscription_renewal geht das Datum in die Doppelzählungssperre ein. Abo-Systeme verwenden für alle Verlängerungen häufig dieselbe Bestellnummer — ohne diese Unterscheidung ginge jede Provision außer der ersten verloren.

Erstattung

Eine Retoure melden

Der Aufruf, den man am ehesten weglässt — und der am teuersten fehlt. Ohne ihn bleibt eine gutgeschriebene Provision bestehen, obwohl die Ware zurückging.

POST https://api.affleo.de/api/v1/tracking/refund
Content-Type: application/json

{
  "tenantId": "IHRE_KENNUNG",
  "externalOrderId": "1042",
  "amount": 5000,
  "reason": "Ware beschädigt"
}

Felder beim Melden einer Erstattung
Feld	Pflicht	Bedeutung
externalOrderId	ja	Ihre Bestellnummer aus der ursprünglichen Meldung
amount	nein	Betrag dieser Erstattung in Cent. Ohne Angabe geht die ganze Bestellung zurück.
reason	nein	Freitext, höchstens 500 Zeichen

Teilerstattungen addieren sich

amount ist der Betrag des einzelnen Vorgangs, nicht die laufende Summe. Zwei Teilerstattungen über je 50,00 € werden als zwei Aufrufe mit je 5000 gemeldet; zusammen ergeben sie 100,00 €. Wer stattdessen den kumulierten Stand schickt, bucht doppelt zurück.

Zurückgebucht wird anteilig über alle Stufen. Werden von 200,00 € genau 50,00 € erstattet, geht ein Viertel jeder Provision zurück — aus 36,00 € werden 27,00 €.

Antwort

202 Accepted

{
  "conversionId": "…",
  "status": "refunded",
  "gesamtErstattet": "5000"
}

status steht auf refunded, solange nur ein Teil erstattet wurde, und auf cancelled, sobald der volle Bestellwert zurückgegangen ist.

Fehlerantworten
Code	Bedeutung
404	Bestellnummer für diesen Mandanten unbekannt — meist ist die ursprüngliche Meldung nie angekommen
409	Bereits vollständig erstattet, oder die Summe überschreitet den Bestellwert

Diesen Aufruf sollten Sie protokollieren und im Fehlerfall wiederholen. Beim Bestelleingang bleiben Gutscheincode und Kundenzuordnung als zweiter Weg; bei der Erstattung gibt es keinen.

Im Browser

Ohne Serverzugriff

Erlaubt Ihr System keinen Serveraufruf, meldet das Skript die Bestellung über ein Ereignis:

window.dispatchEvent(new CustomEvent('affleo:conversion', {
  detail: {
    orderId: '1042',
    amount: 119.00,
    currency: 'EUR',
    email: 'kunde@example.com'
  }
}));

Der Serveraufruf ist verlässlicher: Er erreicht uns auch dann, wenn der Kunde die Seite sofort schließt oder ein Werbeblocker das Skript verhindert.