+420 777 431 109 (po-pá 9-15h)

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.

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. (Příklad pro C#)

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.
  • 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“.
  • show_ip – zobrazit IP adresu (true/false).
  • 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]

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.
  • show_ip – zobrazit IP adresu  (true/false).

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]

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]

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]

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

[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í.
  • email – email (string)

Přidání prokliků

[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)

Získání seznamu kampaní

[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.



Napsat komentář

Vaše emailová adresa nebude zveřejněna. Vyžadované informace jsou označeny *