A partnernyomkövető API használata

Amikor egy vásárló affiliate-kuponkóddal lead rendelést, hívd meg a nyomkövető API-t a szerverodről az eladás rögzítéséhez, a jutalék kiszámításához és a partner egyenlegének frissítéséhez. Az API automatikusan kezeli a duplikáció-megelőzést és a vásárlóhoz rendelést.

Hitelesítés

Minden kéréshez szükséges az API-kulcsod a Y-API-Key fejlécben. Az API-kulcsodat az irányítópulton találod a Settings → API menüpontban.

Végpont

POST https://yaplet.com/api/affiliates/track/{affiliate_code}

Cseréld ki az {affiliate_code} részt a partner kuponkódjára — arra a kódra, amelyet a vásárló a pénztárnál adott meg. Ha a kód nem létezik, vagy a partner nincs jóváhagyva, az API success: false választ ad 200-as státusszal — ez nem HTTP-hiba, csupán jelzés, hogy nem lett jutalék rögzítve.

Kérés törzse

{
  "order_id": "order_12345",
  "total_amount": 100.00,
  "customer": {
    "email": "[email protected]",
    "name": "Kovács Anna",
    "customer_id": "cust_789",
    "customer_metadata": { "source": "website" }
  },
  "commission": 10.00,
  "notes": "Nyári akció rendelés",
  "timestamp": 1640995200000,
  "product": {
    "id": "prod_123",
    "name": "Pro Plan",
    "category": "subscription"
  },
  "metadata": { "utm_source": "newsletter" }
}

Kötelező mezők

Mező	Típus	Leírás
order_id	string	Egyedi rendelésazonosító. Ugyanaz az order_id szervezetenként csak egyszer követhető nyomon — duplikátumok 409-es hibát adnak.
total_amount	number	Rendelés összege tizedes formátumban. Százalékos jutalékszámításhoz szükséges.
customer.email	string	Vásárló e-mail-címe. A vásárlóhoz rendeléshez és a duplikáció-kezeléshez szükséges.

Opcionális mezők

Mező	Típus	Leírás
commission	number	A számított jutalék felülírása pontos összeggel. Ha nincs megadva, a Yaplet a partner kulcsa alapján számítja ki.
timestamp	number	Rendelési idő ezredmásodpercben. A legfeljebb 10 jegyű értékeket másodpercként kezeli, és 1000-rel megszorozza; a 13 jegyű értékeket változtatás nélkül használja. Alapértelmezetten az aktuális szerveri idő.
notes	string	Szabad szöveges megjegyzés, amely a jutalékrekordban jelenik meg.
customer.name	string	Vásárló megjelenített neve. Alapértelmezetten az e-mail-cím @ előtti része.
customer.customer_id	string	A saját rendszeredből származó vásárlóazonosító kereszthivatkozáshoz.
customer.customer_metadata	object	Bármilyen extra vásárlóadat (forrás, szegmens stb.).
product	object	Termékinformáció (id, name, category). A jutalékkal együtt tárolódik riportoláshoz.
metadata	object	Bármilyen extra rendelésadat (UTM-paraméterek, kampányazonosítók stb.).

Kódpéldák

A teljes kérés- és válaszpéldákért JavaScript, cURL, PHP és Python nyelven nézd meg a fejlesztői dokumentációt, amelyre az irányítópult Settings → API oldaláról jutsz el.

Válasz

Sikeres esetben:

{
  "success": true,
  "data": {
    "commission_id": "comm_abc123",
    "partner_id": "partner_xyz",
    "customer_id": "customer_456",
    "commission_amount": 10.00,
    "order_id": "order_12345",
    "affiliate_code": "PARTNER_CODE"
  }
}

Érvénytelen vagy nem jóváhagyott kód esetén:

{ "success": false, "message": "No approved affiliate partner found for coupon code: PARTNER_CODE" }

Hibakódok

Státusz	Jelentés
200 + success: false	A kód nem található, vagy a partner nincs jóváhagyva — nem lett jutalék rögzítve.
400	Hiányzó kötelező mezők (order_id, total_amount vagy customer.email).
401	Hiányzó vagy érvénytelen Y-API-Key fejléc.
403	A szervezetednek nincs hozzáférése az Affiliates funkcióhoz.
409	Duplikáció — ez az order_id már nyomon lett követve a szervezetednél.
500	Szerverhiba.

Bevált gyakorlatok

• Csak szerveroldalról hívd. Soha ne tedd elérhetővé a Y-API-Key-t kliensoldalon lévő JavaScriptben.
• Egyedi rendelésazonosítókat használj. Az API 409-es hibával utasítja vissza a duplikált order_id értékeket — mindig a rendelés stabil azonosítóját add meg.
• Ellenőrizd a success mezőt a válaszban. Egy 200-as válasz success: false értékkel azt jelenti, hogy nem lett jutalék rögzítve — lehet, hogy rossz a kuponkód.
• Korábbi rendelésekhez add meg a timestamp mezőt. Ha visszamenőleg töltesz fel korábbi rendeléseket, add meg a timestamp mezőt, hogy a riportdátumok pontosak legyenek.

Mi a következő lépés?

Lásd: Termékszintű jutalék-felülírások beállítása — hogyan adhatsz át termékadatokat, és melyik kulcs alkalmazandó.