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.

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.