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.
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
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"
}
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
- Partner felülírás: Ha a partnernek
ignore_product_rate = truevan beállítva és van kulcsa, a partner kulcsa mindig használatba kerül - Egyéni jutalék: Ha jutalék összeg van megadva az API kérésben, az az összeg kerül használatra
- Partner kulcs: Ha a partnernek van kulcsa (és
ignore_product_ratehamis), a partner kulcsa kerül használatra - 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);
curl -X POST https://yaplet.com/api/affiliates/track/YOUR_AFFILIATE_CODE \\
-H "Content-Type: application/json" \\
-H "Y-API-Key: YOUR_API_KEY" \\
-d '{
"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"
}
}'
<?php
$url = "https://yaplet.com/api/affiliates/track/YOUR_AFFILIATE_CODE";
$headers = [
'Content-Type: application/json',
'Y-API-Key: YOUR_API_KEY'
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
"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"
]
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode === 200) {
$result = json_decode($response, true);
echo "Response: " . print_r($result, true);
} else {
throw new Exception("Error: " . $response);
}
?>
import requests
url = "https://yaplet.com/api/affiliates/track/YOUR_AFFILIATE_CODE"
headers = {
"Content-Type": "application/json",
"Y-API-Key": "YOUR_API_KEY"
}
response = requests.post(url, headers=headers, json={
"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"
}
})
if response.status_code == 200:
result = response.json()
print('Response:', result)
else:
raise Exception(f"Error: {response.text}")
Mezőhivatkozás
Kötelező mezők
| Mező | Típus | Leírás |
|---|---|---|
order_id | string | A rendelés egyedi azonosítója. Duplikált jutalékok megelőzésére és nyomon követésre használatos. |
total_amount | number | Rendelés összege decimális formátumban. Jutalékszámításhoz és bevétel nyomon követéshez használatos. |
customer.email | string | Ü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-Key | header | API hitelesítési kulcs. Biztonsági validáláshoz a kérés fejlécekben kell szerepelnie. |
Opcionális mezők
| Mező | Típus | Alapértelmezett | Leírás |
|---|---|---|---|
timestamp | number | Jelenlegi időbélyeg | Rendelé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. |
commission | number | Partner kulcsból számítva | Egyéni jutalék összeg. Ha nincs megadva, a partner kulcs beállítások alapján kerül kiszámításra. |
notes | string | null | További megjegyzések a rendelésről vagy jutalékról. |
customer.name | string | E-mail előtag (@ előtti rész) | Ügyfél teljes neve megjelenítési célokra. |
customer.customer_id | string | null | Külső ügyfél azonosító a rendszeredből kereszthivatkozáshoz. |
customer.customer_metadata | object | Üres objektum {} | További ügyfél adatok, mint forrás, kampány stb. |
product | object | Üres objektum {} | Termékinformáció, beleértve azonosítót, nevet, kategóriát stb. Riportolási célokra tárolva. |
metadata | object | Üres objektum {} | További rendelés metaadatok, mint kampány azonosítók, UTM paraméterek stb. |
URL paraméterek
| Paraméter | Leírás |
|---|---|
affiliate_code | Cseré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 | Üzenet | Leírás |
|---|---|---|
401 | API key is required / Invalid API key | Hiányzó vagy érvénytelen Y-API-Key fejléc |
403 | Unauthorized | A felhasználónak nincs engedélye az API használatához |
400 | Affiliate code is required in URL | Hiányzó affiliate kód az URL útvonalban |
400 | order_id and total_amount are required | Hiányzó kötelező mezők a kérés törzsben |
400 | Customer with email is required | Hiányzó ügyfél objektum vagy customer.email mező |
400 | Both customer and partner information are required to create a commission | Hiányzó ügyfél vagy partner adatok a jutalék létrehozásához |
409 | Order {order_id} has already been tracked for this organization | Duplikátum felderítés - ez a rendelés már feldolgozásra került |
500 | Internal server error | Szerverhiba a feldolgozás során |
Integrációs legjobb gyakorlatok
- 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
- Érvénytelen kódok kezelése: Számíts
success: falseválaszokra érvénytelen kódoknál - ez normális viselkedés - 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
- Ügyfél adatok megadása: Legalább az ügyfél e-mail címet add meg a megfelelő nyomon követéshez
- Időbélyegek használata: Add meg a rendelés időbélyegeket a pontos riportoláshoz
- 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.