Über die Leadnodes API können Sie einen gekauften Lead in zwei Schritten reklamieren: Zuerst prüfen Sie mit dem Endpunkt Refundable, ob und mit welchen Gründen der Lead reklamierbar ist. Anschließend legen Sie mit dem Endpunkt Refunds Create die Reklamation an.

Warum muss ich zuerst den Refundable-Endpunkt aufrufen?

Reklamationsgründe und Reklamationsfristen sind in Leadnodes nicht global festgelegt. Sie hängen vom konkreten Lead ab:

Leadsparte: Jede Leadsparte kann eigene Reklamationsgründe und eine eigene Reklamationsfrist haben. Manche Leadsparten sind gar nicht reklamierbar.
Nutzer (Käufer): Für einzelne Käufer kann eine abweichende Reklamationsfrist hinterlegt sein. Außerdem muss das Reklamationsrecht für den Nutzer freigeschaltet sein.
System: Ist weder für die Leadsparte noch für den Nutzer eine Frist hinterlegt, gilt die Standardfrist des Systems.

Der Refundable-Endpunkt löst diese Regeln für den angefragten Lead auf und liefert Ihnen genau die Reklamationsgründe (inklusive ihrer IDs), die für diesen Lead gültig sind. Eine Reklamation mit einer ID, die nicht in dieser Liste enthalten ist, wird abgelehnt.

Schritt-für-Schritt-Anleitung

Schritt 1: Prüfen, ob der Lead reklamierbar ist

Senden Sie eine GET-Anfrage an:

https://app.leadnodes.com/api/v2/refunds/refundable/{lead_id}

Ersetzen Sie {lead_id} durch die ID des Leads. Authentifizieren Sie sich wie bei allen API-Aufrufen mit Ihrem API-Token im Header Authorization: Bearer ….

Schritt 2: Antwort auswerten

Lead ist reklamierbar ("refundable": true):

{
  "refundable": true,
  "reasons": [
    { "id": 17, "title": "Kunde nicht erreichbar", "description": "…", "is_active": 1 },
    { "id": 18, "title": "Falsche Kontaktdaten", "description": "…", "is_active": 1 }
  ],
  "refundable_until": "2025-12-26T13:25:08.000000Z",
  "error": null
}

reasons: Liste der zulässigen Reklamationsgründe. Merken Sie sich die id des passenden Grundes für Schritt 3.
refundable_until: Ende der Reklamationsfrist (UTC). Bis zu diesem Zeitpunkt kann die Reklamation angelegt werden.

Lead ist nicht reklamierbar ("refundable": false):

{
  "refundable": false,
  "error": "Refund period is expired."
}

In diesem Fall enthält error den Grund. Legen Sie dann keine Reklamation an, sie würde mit demselben Fehler abgelehnt.

Schritt 3: Reklamation anlegen

Senden Sie eine POST-Anfrage an:

https://app.leadnodes.com/api/v2/refunds/create/{lead_id}

Mit folgendem JSON-Body:

{
  "refund_reason_id": 17,
  "refund_comment": "Kunde war nach mehreren Versuchen nicht erreichbar."
}

refund_reason_id (Pflicht): Eine ID aus der Liste reasons aus Schritt 2.
refund_comment (Pflicht): Ihre Begründung im Freitext. Ein aussagekräftiger Kommentar beschleunigt die Bearbeitung.

Erfolgreiche Antwort:

{
  "message": "Refund successfully created.",
  "refund_id": 29750
}

Schritt 4 (optional): Status der Reklamation abfragen

Den weiteren Verlauf können Sie jederzeit über GET https://app.leadnodes.com/api/v2/refunds/status/{lead_id} abfragen. Der Status ist open (in Prüfung), accepted (angenommen) oder declined (abgelehnt).

Wie deute ich die Fehlermeldungen?

Fehler	Bedeutung	Was tun?
`Refund already created.`	Für diesen Lead existiert bereits eine Reklamation.	Status über den Status-Endpunkt prüfen. Keine zweite Reklamation möglich.
`User can not issue refunds.`	Der Lead ist keinem Käufer zugewiesen, wurde manuell erfasst oder der Käufer hat kein Reklamationsrecht.	Wenden Sie sich an Ihren Lead-Anbieter, um das Reklamationsrecht freischalten zu lassen.
`Lead Type is not refundable.`	Die Leadsparte ist grundsätzlich nicht reklamierbar.	Keine Reklamation möglich. Bei Fragen an den Lead-Anbieter wenden.
`Refund period is expired.`	Die Reklamationsfrist ist abgelaufen.	Keine Reklamation mehr möglich. Prüfen Sie Leads künftig zeitnah nach dem Kauf.
`No refund reasons.`	Für diese Leadsparte bzw. diesen Nutzer sind keine Reklamationsgründe hinterlegt.	Wenden Sie sich an Ihren Lead-Anbieter.
`Invalid refund_reason_id`	Die übergebene ID ist für diesen Lead nicht zulässig.	Nur IDs aus der `reasons`-Liste des Refundable-Endpunkts verwenden.

Weitere häufig gestellte Fragen

Kann ich die Reklamationsgründe einmalig abrufen und zwischenspeichern?

Davon raten wir ab. Die Gründe können sich je Leadsparte und Nutzer unterscheiden und jederzeit vom Anbieter geändert oder deaktiviert werden. Fragen Sie den Refundable-Endpunkt vor jeder Reklamation für den konkreten Lead ab.

Ab wann läuft die Reklamationsfrist?

Die Frist beginnt mit dem Zeitpunkt der Zuweisung (Kauf) des Leads und wird in Tagen gerechnet. Das genaue Fristende finden Sie im Feld refundable_until.

Welche Nutzerrolle benötige ich für die API-Reklamation?

Der API-Token muss zu einem Käufer-Nutzer gehören, dem der Lead zugewiesen ist, oder zu einem System-Administrator des Systems. Andere Nutzer erhalten eine Berechtigungsfehlermeldung.

Kann ich eine Reklamation über die API wieder zurückziehen oder ändern?

Nein. Eine einmal angelegte Reklamation kann über die API nicht geändert oder gelöscht werden. Sie wird vom Lead-Anbieter geprüft und angenommen oder abgelehnt.

Wie reklamiere ich einen Lead über die API?