Autor článku
API - dokumentace
API slouží ke vzdálené komunikaci s vaším affiliate prostředím. Dobrým příkladem je schvalování konverzí, kdy můžete z pohodlí vašeho e-shopu či účetního software ihned po obdržení platby schválit také konverzi v AffilBoxu. Není to již třeba dělat na dvou místech.
Kapitoly
UPOZORNĚNÍ – HTTPS
Naše API lze napojit na libovolnou aplikaci (webovou či desktopovou), která umožňuje POSTování dat. Pro komunikaci se serverem se využívá XML dotazů a server vrací v XML odpověď, zda vše proběhlo v pořádku a v případě chyby také její příčinu.
Ukázkový PHP kód s informací, jak přidat novou konverzi naleznete pro PHP zde.
Kde najdu API Url i klíč?
API URL i Api klíč naleznete ve vaší licenci AffilBoxu v položce Nastavení – nastavení uživatele.
Konverze:
Přidání konverze
Tento příklad přidá konverzi s hodnotou 630:
[sourcecode language=“xml“]
<?xml version=“1.0″ encoding=“UTF-8″?>
<request>
<key>váš API klíč </key>
<method>AddConversion</method>
<partner_id>0c7ef928</partner_id>
<campaign_id>1</campaign_id>
<conversion_id>2589633</conversion_id>
<value>630</value>
</request>
[/sourcecode]
Parametry pro API
Jednotlivé parametry nahraďte za správné hodnoty následovně:
- key – API klíč (string). Jedná se o váš klíč, který naleznete ve vašem profilu po přihlášení. (Nastavení – Nastavení uživatele)
- partner_id – E-mail nebo affilId partnera (string). ID partnera, kterému chcete provizi přiřadit. Může se jednat o jeho affiliate kód, nebo email.
- campaign_id – ID kampaně (int). ID kampaně, ke které provize náleží. ID kampaně naleznete v editaci soukromé kampaně boxu s Tracking kódem. Hledejte řádek „var kampan = XXX“.
- conversion_id – ID transakce (string). Nejčastěji bývá ID transakce číslo objednávky nebo e-mail zákazníka. Toto ID budete potřebovat například při schvalování konverze – pro porovnání s fakturačním systémem.
- value – cena konverze (double). Konečná hodnota provize pro partnera.
- channelId – propagační kanál (string). Pro zjištění, z jakého zdroje vám do Affilboxu plyne nejvíce konverzí. Více o této funkci.
- orderValue – cena objednávky (double). Suma objednávky, bez DPH, poštovného a balného. V případě využití tohoto parametru proběhne klasický výpočet jako v konverzním kódu.
Nepovinné položky
<count_value>true</count_value> – Určuje, zda se má počítat provize z ceny objednávky (true / false) – pokud není tento parametr vyplněn, bere se automaticky hodnota false.
<note> – poznámka (string).
<currency> – měna (string). Měna, čeká na označení měny – nutno mít aktivován plugin Měny.
Přidání bonusu
XML kód:
[sourcecode language=“xml“]
<?xml version=“1.0″ encoding=“UTF-8″?>
<request>
<key>abcdefghijklm</key>
<method>AddBonus</method>
<partner_id>PARTNER_ID</partner_id>
<text>TEXT</text>
<value>VALUE</value>
</request>
[/sourcecode]
Parametry pro API
Jednotlivé parametry nahraďte za správné hodnoty následovně:
- key – API klíč (string). Jedná se o váš klíč, který naleznete ve vašem profilu po přihlášení.
- method – AddBonus – jedná se o metodu přidání bonusu.
- partner_id – E-mail nebo affilId partnera (string). ID partnera, kterému chcete provizi přiřadit. Může se jednat o jeho affiliate kód, nebo email.
- text – popis (string). Zde vyplňte popisek, za co obdržel partner provizi.
- value – částka (double). Celková částka konverze.
Potvrzení / zamítnutí konverze
XML kód:
[sourcecode language=“xml“]
<?xml version=“1.0″ encoding=“UTF-8″?>
<request>
<key>abcdefghijklm</key>
<method>ConfirmConversion</method>
<conversion_id>CONVERSION_ID</conversion_id>
<value>VALUE</value>
</request>
[/sourcecode]
Parametry pro API
Jednotlivé parametry nahraďte za správné hodnoty následovně:
- key – API klíč (string). Jedná se o váš klíč, který naleznete ve vašem profilu po přihlášení.
- method – ConfirmConversion – jedná se o metodu potvrzení konverze.
- conversion_id – id transakce (string). ID které jste přiřadili konverzi.
- value – Hodnota true / false podle toho, zda chcete konverzi schválit nebo zamítnout.
- campaign_id – id kampaně (nepovinné – je potřeba doplnit, pokud máte stejné ID transakce ve více kampaních)
- note – poznamka (string)
Získání informací o více konverzích
XML kód:
[sourcecode language=“xml“]
<?xml version=“1.0″ encoding=“UTF-8″?>
<request>
<key>abcdefghijklm</key>
<method>GetConversions</method>
<partner_id>PARTNER_ID</partner_id>
<filter_state>STATE</filter_state>
<filter_date_from>DATE_FROM</filter_date_from>
<filter_date_to>DATE_TO</filter_date_to>
</request>
[/sourcecode]
Parametry pro API
Jednotlivé parametry nahraďte za správné hodnoty následovně:
- key – API klíč (string). Jedná se o váš klíč, který naleznete ve vašem profilu po přihlášení.
- method – GetConversions – jedná se o metodu získání seznamu konverzí.
- partner_id – E-mail nebo affilId partnera (string). ID inzerenta, jehož konverze chceme získat. Může se jednat o jeho affiliate kód, nebo email.
- coupon – kupon, který byl využit při vytvoření dané konverze.
- filter_state – Výběr konverzí pouze určitého stavu – povolené hodnoty: waiting / rejection / authorized / invoiced.
- filter_date_from – Datum od kdy vypsat konverze, formát „yyyy-mm-dd hh:mm“.
- filter_date_to – Datum do kdy vypsat konverze, formát „yyyy-mm-dd hh:mm“
- campaign_id – id kampane (int). ID kampaně, ke které provize náleží. ID kampaně naleznete v editaci soukromé kampaně boxu s Tracking kódem. Hledejte řádek „var kampan = XXX“.
- conversion_id – id konverze (string)
- conversions_id – více id konverzí (string). Více id konverzí oddělených středníkem.
Získání informací o jedné konverzi
XML kód:
[sourcecode language=“xml“]
<?xml version=“1.0″ encoding=“UTF-8″?>
<request>
<key>abcdefghijklm</key>
<method>GetConversion</method>
<conversion_id>CONVERSION_ID</conversion_id>
</request>
[/sourcecode]
Parametry:
Jednotlivé parametry nahraďte za správné hodnoty následovně:
- key – API klíč (string). Jedná se o váš klíč, který naleznete ve vašem profilu po přihlášení.
- method – GetConversion – jedná se o metodu získání informací o konverzi.
- conversion_id – id transakce (string). ID které jste přiřadili konverzi.
- coupon – kupon, který byl využit při vytvoření dané konverze.
Změna konverze
XML kód:
[sourcecode language=“xml“]
<?xml version=“1.0″ encoding=“UTF-8″?>
<request>
<key>abcdefghijklm</key>
<method>UpdateConversion</method>
<partner_id>PARTNER_ID</partner_id>
<conversion_id>CONVERSION_ID</conversion_id>
<state>NEW_STATE</filter_state>
<value>NEW_VALUE</value>
<commission>NEW_COMISSION</value>
</request>
[/sourcecode]
Parametry:
Jednotlivé parametry nahraďte za správné hodnoty následovně:
- key – API klíč (string). Jedná se o váš klíč, který naleznete ve vašem profilu po přihlášení.
- method – UpdateConversion – změna hodnot konverze.
- partner_id – (string) E-mail nebo affilId partnera (string). ID partnera, jenž je vlastníkem konverze.
- conversion_id – (string) ID konverze, kterou chceme měnit.
- state – Nový stav konverze – povolené hodnoty: waiting / rejection / authorized / invoiced.
- value – (double). Hodnota objednávky.
- commission – (double). Výše provize.
- campaign_id – id kampane (int) ID ID kampaně, ke které provize náleží. ID kampaně naleznete v editaci soukromé kampaně boxu s Tracking kódem. Hledejte řádek „var kampan = XXX“.
- note – poznámka (string)
u funkce „update conversion“ můžete také změnit konverzi do stavu Čekající na schválení – „waiting“
Partneři:
Získání informací o partnerovi
XML kód:
[sourcecode language=“xml“]
<?xml version=“1.0″ encoding=“UTF-8″?>
<request>
<key>abcdefghijklm</key>
<method>GetPartner</method>
<partner_id>PARTNER_ID</partner_id>
</request>
[/sourcecode]
Parametry:
Jednotlivé parametry nahraďte za správné hodnoty následovně:
- key – API klíč (string). Jedná se o váš klíč, který naleznete ve vašem profilu po přihlášení.
- method – GetPartner – jedná se o metodu získání informací o partnerovi.
- partner_id – E-mail nebo affilId partnera (string). ID partnera, jehož informace chcete získat. Může se jednat o jeho affiliate kód, nebo email.
Získání seznamu partnerů
XML kód:
[sourcecode language=“xml“]
<?xml version=“1.0″ encoding=“UTF-8″?>
<request>
<key>abcdefghijklm</key>
<method>GetPartners</method>
</request>
[/sourcecode]
Parametry:
Jednotlivé parametry nahraďte za správné hodnoty následovně:
- key – API klíč (string). Jedná se o váš klíč, který naleznete ve vašem profilu po přihlášení.
- method – GetPartners – jedná se o metodu získání seznamu všech partnerů.
- register_from – registrace od (YYYY-mm-dd)
- register_to – registrace do (YYYY-mm-dd)
- last_login_from – posledni prihlaseni od (YYYY-mm-dd)
- last_login_to – posledni prihlaseni do (YYYY-mm-dd)
- souhlas_sdeleni – datum, kdy váš partner odsouhlasil zasílání marketingových sdělení.
Vytvoření nového nebo získání informace o stávajícím partnerovi
XML kód:
[sourcecode language=“xml“]
<?xml version=“1.0″ encoding=“UTF-8″?>
<request>
<key>abcdefghijklm</key>
<method><strong>GetOrCreatePartner</strong></method>
</request>
[/sourcecode]
Parametry:
- key – API klíč (string). Jedná se o váš klíč, který naleznete ve vašem profilu po přihlášení.
- affilid – volitelný parametr (string) pro vytvoření vlastního tvaru affiliate ID – jinak se vygeneruje automaticky naším systémem.
- email – email (string)
Přidání prokliků
XML kód:
[sourcecode language=“xml“]
<?xml version=“1.0″ encoding=“UTF-8″?>
<request>
<key>abcdefghijklm</key>
<method>AddClick</method>
</request>
[/sourcecode]
Parametry:
- key – API klíč (string). Jedná se o váš klíč, který naleznete ve vašem profilu po přihlášení.
- method – AddClick
- partner_id – email nebo affilid partnera (string)
- campaign_id – id kampaně (int)
- date – datum (YYYY-mm-dd H:i:s)
- count – počet (int)
Nepovinný parametr pro API
- channelId – propagační kanál (string). Pro zjištění, z jakého zdroje vám do Affilboxu plyne nejvíce kliků.
Získání seznamu kampaní
XML kód:
[sourcecode language=“xml“]
<?xml version=“1.0″ encoding=“UTF-8″?>
<request>
<key>abcdefghijklm</key>
<method>GetCampaigns</method>
</request>
[/sourcecode]
Parametry:
- key – API klíč (string). Jedná se o váš klíč, který naleznete ve vašem profilu po přihlášení.
- partner_id – možno přidat filtr jen na určitého inzerenta. E-mail nebo affilId partnera (string). Může se jednat o jeho affiliate kód, nebo email.
Návratová hodnota NO DATA
Pokud vám vrátí API chybu s informací „NO DATA“, nejspíše jste nezaslali XML požadavek v POST proměnné „data“. Jak to lze udělat v PHP a C# naleznete v ukázkových příkladech na začátku článku.
API v2
Připravujeme novou verzi REST API, které vám umožní z AffilBoxu vytáhnout ještě více informací, než doposud.