Funnel-Ereignisse erfassen

Ein Funnel-Ereignis ist ein benannter Schritt, den ein vermittelter Kunde nach dem Klick erreicht: ein begonnener Antrag, ein genehmigter Antrag, ein Konto mit Einzahlung. Du legst die Schritte in der Kampagne fest, und dein Backend meldet jeden davon mit einem signierten Postback. Rekomi erfasst, wer den Kunden vermittelt hat, bezahlt den Affiliate, wenn der Schritt eine Vergütung hat, und zeigt den ganzen Funnel pro Affiliate.

Ereignisse stehen neben Verkäufen und Leads. Sie ändern nie deine Zahlen für Verkäufe, Leads oder Klicks, und sie funktionieren unabhängig davon, ob ein Zahlungsanbieter verbunden ist.

Erforderlicher Plan: Starter oder höher. Konten in der Testphase werden immer angenommen.

Deine Ereignisse festlegen

Öffne die Kampagne, geh zu Provision und füge deine Schritte unter Funnel-Ereignisse hinzu. Jedes Ereignis hat:

• einen Namen (zum Beispiel Application approved),
• einen Schlüssel, der aus dem Namen gebildet wird (application_approved). Den Schlüssel sendet dein Postback, und er ändert sich nie. Ein Name ohne lateinische Buchstaben oder Ziffern bekommt einen Schlüssel wie event_3, der neben dem Namen angezeigt wird,
• optional eine Vergütung pro Ereignis, einen Festbetrag in deiner Heimatwährung. Lass sie leer, wenn du einen Schritt nur erfassen willst.

Die Reihenfolge der Liste ist die Reihenfolge der Spalten im Funnel-Bericht. Eine Kampagne kann bis zu 20 Ereignisse erfassen.

Endpunkt

POST /api/tracking/event

Produktion: https://api.rekomi.com/api/tracking/event (auch erreichbar als /api/v1/tracking/event).

Die Authentifizierung ist dieselbe wie beim S2S-Postback für Verkäufe: dein API-Schlüssel in Authorization: Bearer rk_live_*, dazu ein Header X-Rekomi-Signature mit einem HMAC-SHA256 über {unix-seconds}.{raw-body}, berechnet mit dem Signing Secret des Schlüssels. Nutze dieselbe Signierfunktion. Der Zeitstempel darf höchstens 300 Sekunden von der aktuellen Zeit abweichen, und der Schlüssel braucht Schreibrechte.

Anfrageinhalt

{
  "event": "application_approved",
  "externalEventId": "app_58213_approved",
  "affiliateSlug": "jane-recommends",
  "customerId": "cust_58213",
  "customerEmail": "user@example.com",
  "amountCents": 2500000,
  "currency": "USD",
  "subId": "newsletter"
}

• event (Pflicht): der Schlüssel eines der Ereignisse der Kampagne.
• externalEventId (Pflicht): deine eindeutige ID für dieses Vorkommen, bis zu 128 Zeichen. Sie ist in deinem ganzen Konto eindeutig. Eine Wiederholung mit derselben ID ist also sicher und liefert immer die erste Erfassung zurück, egal was die Wiederholung sonst mitsendet.
• affiliateSlug (optional): der Affiliate, der den Kunden vermittelt hat. Sende ihn beim ersten Schritt mit. Bei späteren Schritten kannst du ihn weglassen und nur den Kunden senden (siehe Den Affiliate nur einmal senden).
• customerId (optional): deine eigene ID für den Kunden. Darüber hängen die Schritte eines Kunden zusammen.
• customerEmail (optional): die E-Mail-Adresse des Kunden, die genauso genutzt wird, wenn du keine Kunden-ID hast.
• programId (optional): die ID der Kampagne. Zusammen mit affiliateSlug gesendet, muss sie die Kampagne dieses Affiliates sein. Ohne Slug gesendet, beschränkt sie die Suche nach dem Kunden auf diese Kampagne. Bewirbt ein Affiliate mehr als eine deiner Kampagnen, sende den Link-Slug der Kampagne, die du meinst.
• amountCents (optional): ein Wert für den Schritt in kleinsten Einheiten von currency, zum Beispiel ein eingezahlter Betrag. Er wird für deine Auswertungen gespeichert und ändert die Vergütung nicht.
• currency (optional): ISO-4217-Code für amountCents und für commissionCents, wenn du es mitsendest. Standard ist deine Heimatwährung.
• commissionCents (optional): was dieses Vorkommen dem Affiliate zahlt, wenn dein Backend den Betrag selbst festlegt. Es ersetzt die eingestellte Vergütung des Ereignisses für dieses eine Vorkommen. Sende 0, um den Schritt ohne Zahlung zu erfassen.
• subId (optional): der Kanal-Tag, den der Besuch des Kunden mitbrachte.
• occurredAt (optional): wann der Schritt passiert ist (ISO 8601), wenn du ihn nachträglich meldest. Ein Wert ohne Zeitzone wird als UTC gelesen. Nicht in der Zukunft und höchstens fünf Jahre zurück.

Sende bei jedem Aufruf entweder affiliateSlug oder einen Kunden (customerId oder customerEmail).

Den Affiliate nur einmal senden

Die meisten Backends kennen den vermittelnden Affiliate, wenn der Kunde zum ersten Mal kommt, und erst danach ihre eigene Kunden-ID. Deshalb ermittelt Rekomi den Affiliate in dieser Reihenfolge:

1. affiliateSlug, wenn du ihn sendest.
2. Das jüngste frühere Ereignis mit derselben customerId.
3. Das jüngste frühere Ereignis mit derselben customerEmail.
4. Ein erfasster Lead mit dieser E-Mail-Adresse aus den letzten 90 Tagen.

Eine typische Integration sendet also den Slug mit dem ersten Schritt und eine feste customerId mit jedem Schritt:

{ "event": "lead", "externalEventId": "c58213_lead", "affiliateSlug": "jane-recommends", "customerId": "cust_58213" }

{ "event": "funded", "externalEventId": "c58213_funded", "customerId": "cust_58213" }

Antwort

Ein neu erfasstes Ereignis:

{ "ok": true, "eventId": "0b6f...", "conversionId": "c0nv...", "commissionCents": 5000, "overCap": false }

• conversionId ist gesetzt, wenn der Schritt dem Affiliate etwas gezahlt hat. Ab da ist das Geld eine ganz normale Provision: Sie erscheint auf der Seite Conversions als Bonus, wartet die Rückerstattungsfrist ab und wird mit allem anderen ausgezahlt.
• overCap ist true, wenn der Affiliate schon eine Volumen-Obergrenze erreicht hatte, die auf Zurückhalten eingestellt ist. Der Schritt wird trotzdem erfasst. Hat er eine Vergütung, zeigt conversionId auf eine zurückgehaltene Provision (Status Invalidated, commissionCents in dieser Antwort 0), die ausgezahlt wird, sobald du sie auf der Seite Conversions validierst.

Ein Ereignis, das schon erfasst war:

{ "ok": true, "deduped": true, "eventId": "0b6f..." }

Zwei Fälle gelten als schon erfasst: dieselbe externalEventId und dasselbe Ereignis für denselben Kunden. Ein Kunde wird nur einmal genehmigt, ein zweites application_approved für dieselbe customerId liefert also das erste zurück.

Fehler

409 external_event_id_reused bedeutet, dass die externalEventId schon für ein anderes Ereignis verwendet wurde: Nutze eine ID pro Schritt, zum Beispiel die Kunden-ID plus den Schlüssel des Ereignisses. 401 mit leerem Antwortinhalt bedeutet, dass der Schlüssel, die Signatur oder der Zeitstempel abgelehnt wurde. 402 plan_tier_required bedeutet, dass das Konto unter Starter liegt und keine Testphase läuft. 413 bedeutet, dass der Inhalt größer als 8,192 Bytes ist, 429 bedeutet, dass du schneller sendest, als das Rate-Limit erlaubt, und 500 persist_failed bedeutet, dass das Ereignis nicht gespeichert werden konnte. Wiederhole es dann mit derselben externalEventId. Alles andere ist ein 400 mit einem error-Code:

Beispiel

import crypto from "node:crypto";

const BEARER = process.env.REKOMI_API_KEY!;         // rk_live_...
const SIGNING = process.env.REKOMI_SIGNING_SECRET!; // rks_...

async function trackEvent(input: {
  event: string;
  externalEventId: string;
  affiliateSlug?: string;
  customerId?: string;
  customerEmail?: string;
}) {
  const body = JSON.stringify(input); // serialize once: these exact bytes are signed and sent
  const t = Math.floor(Date.now() / 1000);
  const sig = crypto.createHmac("sha256", SIGNING).update(`${t}.${body}`).digest("hex");
  const res = await fetch("https://api.rekomi.com/api/tracking/event", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${BEARER}`,
      "X-Rekomi-Signature": `t=${t},sig=${sig}`,
      "Content-Type": "application/json",
    },
    body,
  });
  if (!res.ok) throw new Error(`Rekomi event failed: ${res.status} ${await res.text()}`);
  return res.json();
}

Ereignisse auslesen

• Dashboard: Der Tab Performance der Kampagne zeigt die Tabelle Funnel, mit einer Zeile pro Affiliate und einer Spalte pro Ereignis, samt CSV-Export.
• API: GET /api/v1/programs/{programId}/funnel liefert denselben Bericht (Filter since, until und affiliateId; format=csv für die Tabelle). GET /api/v1/funnel-events listet die erfassten Vorkommen (programId, affiliateId, event, since, until, take, skip), und GET /api/v1/funnel-events/export.csv exportiert sie.
• Webhooks: Jedes erfasste Ereignis löst event.recorded aus. Ein Schritt mit Vergütung löst außerdem das übliche conversion.created aus.

Gut zu wissen

• Der Betrag eines Ereignisses mit Vergütung ist für jeden Affiliate gleich. Um verschiedenen Affiliates verschiedene Beträge zu zahlen, sende commissionCents im Postback mit.
• Entfernst du ein Ereignis, das schon erfasste Vorkommen hat, wird es archiviert: Es nimmt keine Postbacks mehr an, und sein Verlauf bleibt im Bericht. Wenn du ein Ereignis entfernst, werden auch die Volumen-Obergrenzen entfernt, die darauf festgelegt sind.
• Die Vergütung eines Ereignisses ist Geld. In einer Kampagne, die mit Guthaben belohnt, lassen sich Ereignisse erfassen, aber sie können keine Vergütung tragen.
• Ereignisse werden nicht über /api/tracking/refund erstattet. Um die Provision eines bezahlten Schritts zurückzuholen, weise seinen Bonus auf der Seite Conversions ab oder passe ihn an.