API

Átfogó API az affiliate rendelések nyomon követéséhez, jutalékok kiszámításához és partnerkapcsolatok kezeléséhez az affiliate programodban.

Áttekintés

Az Affiliate Rendelés Nyomkövető API zökkenőmentes integrációt tesz lehetővé az affiliate nyomon követés beépítéséhez az e-kereskedelmi platformodba. Amikor egy ügyfél affiliate kóddal vásárol, ez az API rögzíti a rendelést, létrehozza vagy frissíti az ügyfélrekordokat, kiszámítja a jutalékokat a partner beállítások alapján, és nyomon követi az affiliate program statisztikákat.

Hitelesítés

Minden API kéréshez hitelesítés szükséges az API kulcsoddal.

API kulcs szükségesAdd meg a Y-API-Key fejlécet minden kérésben. Az API kulcsodat a vezérlőpult beállításokban találod a Beállítások > API menüpont alatt.

Végpont részletek

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

Új affiliate rendelés rögzítése és jutalék kiszámítása a partner beállítások alapján. Ügyfélrekordokat és partner statisztikákat hoz létre vagy frissít. Érvénytelen affiliate kódoknál success: false-t ad vissza (normális viselkedés).

Alap URL: https://yaplet.com/api/affiliates/track/YOUR_AFFILIATE_CODE

Fontos: Cseréld ki a YOUR_AFFILIATE_CODE-ot a tényleges affiliate partner kuponkódjára. Ha a kód érvénytelen, az API success: false-t ad vissza (ez a várt viselkedés, nem hiba).

Kérés struktúra

Fejlécek

{
  "Content-Type": "application/json",
  "Y-API-Key": "YOUR_API_KEY"
}

Kérés törzs

{
  "order_id": "order_12345",
  "total_amount": 100.0,
  "customer": {
    "email": "[email protected]",
    "name": "John Doe",
    "customer_id": "cust_12345",
    "customer_metadata": {
      "source": "website",
      "campaign": "summer2024"
    }
  },
  "commission": 10.0,
  "notes": "First order from customer",
  "timestamp": 1640995200000,
  "product": {
    "id": "prod_123",
    "name": "Premium Plan",
    "category": "subscription"
  },
  "metadata": {
    "campaign_id": "camp_123",
    "utm_source": "facebook"
  }
}

Válasz példák

Sikeres nyomon követés (érvényes affiliate kód)

Állapot: 200 OK

{
  "success": true,
  "data": {
    "commission_id": "comm_123456789",
    "partner_id": "partner_123",
    "customer_id": "customer_456",
    "commission_amount": 10.0,
    "order_id": "order_12345",
    "affiliate_code": "AFFILIATE_CODE"
  }
}

Érvénytelen affiliate kód

Állapot: 200 OK

{
  "success": false,
  "message": "No approved affiliate partner found for coupon code: AFFILIATE_CODE"
}
Az érvénytelen affiliate kódok success: false-t adnak vissza 200-as állapotkóddal. Ez normális viselkedés és azt jelzi, hogy a kód nem található a rendszerben.

Jutalékszámítás

A jutalékok automatikusan a partner beállítások és a következő prioritási szabályok alapján kerülnek kiszámításra:

Számítási prioritás

  1. Partner felülírás: Ha a partnernek ignore_product_rate = true van beállítva és van kulcsa, a partner kulcsa mindig használatba kerül
  2. Egyéni jutalék: Ha jutalék összeg van megadva az API kérésben, az az összeg kerül használatra
  3. Partner kulcs: Ha a partnernek van kulcsa (és ignore_product_rate hamis), a partner kulcsa kerül használatra
  4. Nincs jutalék: Ha a fenti feltételek egyike sem teljesül, jutalék = 0

Kulcs típusok

Százalékos kulcs

commission = total_amount * (rate.value / 100)

Példa: $100 rendelés × 10% = $10 jutalék

Fix kulcs

commission = rate.value

Példa: $5 jutalék rendelésenként

Kódpéldák

const response = await fetch('https://yaplet.com/api/affiliates/track/YOUR_AFFILIATE_CODE', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Y-API-Key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
        "order_id": "order_12345",
        "total_amount": 100.0,
        "customer": {
            "email": "[email protected]",
            "name": "John Doe",
            "customer_id": "cust_12345",
            "customer_metadata": {
                "source": "website",
                "campaign": "summer2024"
            }
        },
        "commission": 10.0,
        "notes": "First order from customer",
        "timestamp": 1640995200000,
        "product": {
            "id": "prod_123",
            "name": "Premium Plan",
            "category": "subscription"
        },
        "metadata": {
            "campaign_id": "camp_123",
            "utm_source": "facebook"
        }
    })
});

const result = await response.json();
console.log('Response:', result);

Mezőhivatkozás

Kötelező mezők

MezőTípusLeírás
order_idstringA rendelés egyedi azonosítója. Duplikált jutalékok megelőzésére és nyomon követésre használatos.
total_amountnumberRendelés összege decimális formátumban. Jutalékszámításhoz és bevétel nyomon követéshez használatos.
customer.emailstringÜgyfél e-mail cím. Ügyfél azonosításhoz és ismételt vásárlások nyomon követéséhez szükséges.
Y-API-KeyheaderAPI hitelesítési kulcs. Biztonsági validáláshoz a kérés fejlécekben kell szerepelnie.

Opcionális mezők

MezőTípusAlapértelmezettLeírás
timestampnumberJelenlegi időbélyegRendelés időbélyeg milliszekundumban. Ha nincs megadva, a jelenlegi szerver idő kerül használatra. Másodperceket (10 számjegy) és milliszekundumokat (13 számjegy) egyaránt elfogad.
commissionnumberPartner kulcsból számítvaEgyéni jutalék összeg. Ha nincs megadva, a partner kulcs beállítások alapján kerül kiszámításra.
notesstringnullTovábbi megjegyzések a rendelésről vagy jutalékról.
customer.namestringE-mail előtag (@ előtti rész)Ügyfél teljes neve megjelenítési célokra.
customer.customer_idstringnullKülső ügyfél azonosító a rendszeredből kereszthivatkozáshoz.
customer.customer_metadataobjectÜres objektum {}További ügyfél adatok, mint forrás, kampány stb.
productobjectÜres objektum {}Termékinformáció, beleértve azonosítót, nevet, kategóriát stb. Riportolási célokra tárolva.
metadataobjectÜres objektum {}További rendelés metaadatok, mint kampány azonosítók, UTM paraméterek stb.

URL paraméterek

ParaméterLeírás
affiliate_codeCseréld ki a YOUR_AFFILIATE_CODE-ot a tényleges affiliate partner kuponkódjára. Ha a kód érvénytelen vagy nem létezik, az API success: false-t ad vissza (ez normális viselkedés, nem hiba).

Hibakezelés

Gyakori hibakódok

KódÜzenetLeírás
401API key is required / Invalid API keyHiányzó vagy érvénytelen Y-API-Key fejléc
403UnauthorizedA felhasználónak nincs engedélye az API használatához
400Affiliate code is required in URLHiányzó affiliate kód az URL útvonalban
400order_id and total_amount are requiredHiányzó kötelező mezők a kérés törzsben
400Customer with email is requiredHiányzó ügyfél objektum vagy customer.email mező
400Both customer and partner information are required to create a commissionHiányzó ügyfél vagy partner adatok a jutalék létrehozásához
409Order {order_id} has already been tracked for this organizationDuplikátum felderítés - ez a rendelés már feldolgozásra került
500Internal server errorSzerverhiba a feldolgozás során
Duplikátum megelőzésAz API megakadályozza a duplikált jutalékokat ugyanahhoz a rendelés azonosítóhoz a szervezeteden belül. Ha ugyanazt a rendelést többször próbálod nyomon követni, 409-es hibát kapsz.

Integrációs legjobb gyakorlatok

  1. Affiliate kódok validálása: Mindig ellenőrizd, hogy az affiliate kód létezik-e a nyomon követési kérések küldése előtt
  2. Érvénytelen kódok kezelése: Számíts success: false válaszokra érvénytelen kódoknál - ez normális viselkedés
  3. Duplikátumok megelőzése: Használj egyedi rendelés azonosítókat a duplikált jutalék nyomon követés elkerülésére
  4. Ügyfél adatok megadása: Legalább az ügyfél e-mail címet add meg a megfelelő nyomon követéshez
  5. Időbélyegek használata: Add meg a rendelés időbélyegeket a pontos riportoláshoz
  6. Sebességkorlátok figyelése: Implementálj megfelelő hibakezelést és újrapróbálkozási logikát

Támogatás

Az Affiliate API-val kapcsolatos további támogatásért vagy kérdésekért keresd a támogatási csapatunkat vagy nézd meg az API beállításokat a vezérlőpultodon.