A partnerkövető API használata

A Yaplet nem látja a fizetési folyamatodat, tehát a webshopodnak kell szólnia, ha eladás történt. Amikor egy vevő partnerkuponnal rendel, hívd meg a nyomkövető végpontot a saját szerveredről: a Yaplet rögzíti az eladást, kiszámolja a jutalékot, frissíti a partner egyenlegét, és a vevőt ehhez a partnerhez sorolja. Az ismételt rendelésekkel és a duplán elküldött hívásokkal nem kell külön foglalkoznod.

Hitelesítés

Minden kérés a szervezeted egyik API-kulcsát viszi a Y-API-Key fejlécben. Kulcsokat a Beállítások → Szervezeti beállítások → API oldalon hozhatsz létre — a szervezetednek több elnevezett kulcsa is lehet, és itt bármelyik működik, ezért érdemes erre egy külön kulcsot létrehozni (nevezd el mondjuk úgy, hogy Affiliate követés), amit később a többi integrációd megtörése nélkül törölhetsz. A teljes kulcsot egyszer látod, a létrehozáskor — akkor másold ki, mert utána a Yaplet már csak egy lenyomatát tárolja.

Végpont

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

Az {affiliate_code} helyére a partner kuponkódja kerül — az, amit a vevő a fizetésnél beírt. Ha egyetlen jóváhagyott partnernek sincs ilyen kódja, a válasz success: false lesz 200-as státusszal. Ez nem HTTP-hiba: azt jelenti, hogy nem rögzült jutalék.

A kérés törzse

{
  "order_id": "order_12345",
  "total_amount": 100.00,
  "customer": {
    "email": "[email protected]",
    "name": "Jane Smith",
    "customer_id": "cust_789",
    "customer_metadata": { "source": "website" }
  },
  "commission": 10.00,
  "notes": "Summer sale order",
  "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	A rendelésed azonosítója. Szervezetenként csak egyszer rögzíthető — ismétlésre 409 a válasz.
total_amount	number	A rendelés összege tizedes számként. Valódi, nullánál nagyobb szám lehet, legfeljebb egymilliárd; szöveget vagy negatív értéket 400-zal utasít vissza. A százalékos jutalék ebből számolódik.
customer.email	string	A vevő e-mail címe. A Yaplet ez alapján ismeri fel a visszatérő vásárlókat.

Opcionális mezők

Mező	Típus	Leírás
commission	number	A pontos jóváírandó összeg, a Yaplet saját számítása helyett. Nulla vagy több lehet, legfeljebb egymilliárd. Vigyázz: a 0 küldése a partner kulcsára esik vissza ahelyett, hogy nullát fizetne.
timestamp	number	A rendelés időpontja. A legfeljebb 10 jegyű értéket másodpercként olvassa és megszorozza 1000-rel; a hosszabbat ezredmásodpercként. Alapból a hívás beérkezésének ideje.
notes	string	Szabad szöveg, a jutalék mellé mentve.
customer.name	string	A vevő megjelenítendő neve. Ennek híján az e-mail cím @ előtti része.
customer.customer_id	string	A te saját azonosítód a vevőre, Külső Azonosítóként tárolva.
customer.customer_metadata	object	Bármi más, amit meg akarsz őrizni a vevőről.
product	object	Termékadatok, például id, name és category. A jutalék mellé kerül a kimutatásokhoz; az összeget nem befolyásolja.
metadata	object	Bármi más, amit meg akarsz őrizni a rendelésről, például kampányazonosítók.

Hol van az élő leírás

A vezérlőpultban is ott van ennek a leírásnak egy példánya, ami mindig a futó kóddal egyezik, kész kéréstörzzsel és mindkét válaszpéldával: Marketing → Affiliate kezelés → API.

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"
  }
}

Ha a kód ismeretlen vagy a partner nincs jóváhagyva:

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

Hibakódok

Státusz	Jelentés
200, success: false értékkel	Egyetlen jóváhagyott partnernek sincs ilyen kuponkódja — semmi nem rögzült.
400	Hiányzik egy kötelező mező, vagy a total_amount / commission nem érvényes szám.
401	A Y-API-Key fejléc hiányzik, vagy nem illik egyetlen kulcsra sem.
403	A szervezeted nem rendelkezik az Affiliates jogosultsággal.
409	Ez az order_id már rögzült a szervezetedben.
500	Nálunk hibázott valami.

Jó gyakorlatok

• A szerveredről hívd, soha a böngészőből. Egy API-kulcs az egész szervezetre szóló hozzáférést ad; aki kiolvassa az oldaladból, használni is tudja.
• A valódi rendelésazonosítódat küldd. Ez akadályozza meg, hogy ugyanaz az eladás kétszer számítson.
• Ne csak a státuszkódot nézd, hanem a success mezőt is. A 200-as válasz success: false értékkel azt jelenti, hogy a kuponkód nem talált jóváhagyott partnert.
• Visszamenőleges feltöltésnél küldj timestamp értéket. Különben a régi rendelések az importálás pillanatára datálódnak, és elromlanak a kimutatásaid.

Mi következik

A Termékszintű jutalékfelülírás beállítása cikkben nézheted meg, hogyan küldj termékenkénti összeget, és melyik kulcs nyer.