API – dokumentace

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

UPOZORNĚNÍ: z důvodu bezpečnosti přecházíme plošně s API na https protokol. Každé volání na http vrátí chybovou hlášku, která bude odkazovat právě na přechod. Plný přechod čistě https komunikaci byl 1. 1. 2020.

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.
  • 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í.
  • 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.

Napsat komentář

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