IBOD - API. Rozhraní pro přípis bodů partnery programu ibod

Transkript

1 IBOD - API Rozhraní pro přípis bodů partnery programu ibod Abstrakt Systémová specifikace datových vět a způsobu napojení na aplikační interface věrnostního programu ibod. Dokument je určený pro ICT oddělení partnerů zapojených do programu, je přísně důvěrný a není dovoleno jeho sdílení a další šíření bez předchozího souhlasu společnosti Mr. RED s.r.o. Verze dokumentu: 2.2 Datum: Tomáš Khűr tomas.khur@mrred.cz

2 OBSAH Změny v dokumentu Webová služba SOAP, verze Popis rozhraní Komunikace Produkční prostředí Testovací prostředí Číselníky Metody a entity Metoda TranAdd() Metoda TranGet() Metoda BalanceGet() Příklady použití pravidel Způsob výpočtu Příklady Platba kartou IBOD u obchodního partnera Platební brána IBOD Metoda PaymentGet() Metoda PaymentSet() Metoda PaymentStornoSet() Metoda PaymentHistoryGet() Kontakt a podpora ZMĚNY V DOKUMENTU DATUM ZMĚNA Nové WSDL pro verzi detail Nový obrázek Metody a entity detail Entita Tran nově obsahuje vlastnost Seller detail Entita TranStatus nově obsahuje vlastnost Seller detail Sekce Platba kartou IBOD u obchodního partnera detail Entita "PaymentSetRequest" nově obsahuje "PaymentFid" detail Rozšířena "Platba kartou IBOD u obchodního partnera" detail [1]

3 1 WEBOVÁ SLUŽBA SOAP, VERZE POPIS ROZHRANÍ Pro přístup partnerů do systému je vytvořena webová služba, kde partneři mohou zadávat požadavky na přípisy bodů Komunikace Protokol: HTTPS (nešifrované HTTP není podporováno) Port: 443 Verze SOAP: 1.1, Produkční prostředí Adresa služby: Adresa WSDL: Adresa číselníků: Testovací prostředí Adresa služby: Adresa WSDL: Adresa číselníků: Číselníky Číselníky stavů jsou dostupné on-line na uvedených adresách. Obecné pravidlo při zpracování: Číselný návratový kód Popis 0 OK operace se zdařila. 1 CHYBA AUTORIZACE 2+ CHYBA: #důvod chyby# [2]

4 1.2 METODY A ENTITY Schéma zobrazuje základní přehled vazeb metod a entit. Metody mají unifikovaný vstupní objekt pojmenovaný: NázevMetodyRequest a výstupní objekt: NázevMetodyResponse. [3]

5 1.2.1 Metoda TranAdd() Metoda slouží k dávkovému předávání transakcí mezi systémem partnera a systémem ibod. Pro identifikaci klienta musí být použito číslo karty ibod nebo čárový kód karty EAN13. Přijmutí transakcí - maximální množství transakcí na vstupu je pokud selže autentizace partnera, je vyvolána chyba a dávka nebude uložena - pokud selže ověření validity dat, je vyvolána chyba a dávka nebude uložena API na vstupu nekontroluje business obsah dat, ten je kontrolován později až při zpracování - data jsou vložena do fronty pro zpracování - je vrácen úspěšný návratový kód zpracování zaslané dávky Zpracování transakcí - zaručeno do 24h od zaslání, nejčastěji do 5 minut po úspěšném přijetí dávky - dochází k ověření business obsahu dat o ověření duplicity záznamů (určeno pomocí ID transakce partnera) - duplicitní záznamy nejsou zapracovány - záznamy, které nemají správné údaje a nelze je zpracovat (například neexistující pravidlo), jsou označeny jako chybné [4]

6 Storno transakcí Pro storno transakci platí stejná pravidla, jako pro běžnou transakci - jedná se o proti-transakci. - požaduje unikání ID (jedná se o novou transakci) - pokud byly v přípisové transakci uvedeny položky ( Items ), uvedou se jen položky podléhající stornu - vzhledem k tomu, že se jedná o zápornou transakci, uvede se před hodnotou ( Value ) mínus (např ) - nemá vazbu na transakci původní - tento druh transakcí má odloženou dobu zpracování, je zapracován dle intervalu vyúčtování jednotlivých partnerů programu TranAddRequest Vstupní entita metody. PartnerId String Ano Unikátní identifikátor partnera, klíč pro testovací a produkční prostředí je různý. Trans Tran[] Ano Pole transakcí ke zpracování max záznamů. TranAddResponse Výstupní entita metody. Result Int Ano Návratová hodnota dle číselníku. Text String Ano Návratová hodnota v textové podobě. Tran Entita představuje jednu transakci (nebo storno transakci) u partnera. Vlastnosti TranId String Ano Unikátní identifikátor transakce partnera. Duplicitní transakce nebudou zpracovány. Maximálně 50 znaků. Place String Ano Identifikátor obchodního místa, dle uvážení partnera. Slouží pro lepší orientaci při řešení reklamací, statistických ukazatelů a chování klientů. Maximálně 50 znaků. Seller String Ne Identifikátor obsluhy, dle uvážení partnera. Slouží pro lepší orientaci při řešení reklamací, statistických ukazatelů, soutěží a dalších. Card String Ano Číslo karty ibod (16 znaků) nebo čárový kód (13 znaků) bez mezer. Created DateTime Ano Datum a čas vzniku transakce. Toto datum určuje efektivní datum zpracování pravidel a přidělování bodů. Datum zpracování transakce nemá na přidělování bodů vliv. [5]

7 TranRules TranRule[] Ne ID skupiny pravidel, dle kterých se řídí zpracování transakce. Naplněním této entity jsou definována pravidla pro zpracování celé transakce je možné definovat pravidla i pro jednotlivé položky košíku, jeli zasílán (viz dále). Je možné použít jednu z metod nebo obě zároveň. TranItems TranItem[] Ne Pole položek transakce (obsah nákupního košíku). Není nutné zasílat, pokud nemá být aplikováno položkové pravidlo nebo nedochází k vyžadovanému vyhodnocení obchodního chování klientů (přípis dle speciálního pravidla). Formálně nejsou vyžadována ani TranRules, ani TranItems při zpracování je však kontrolován obsah, nejsou-li data ani v jedné z entit, transakce se dále nezpracovává => nemá definované žádné pravidlo pro zpracování. Transakce nebo položka transakce může na sobě mít aplikováno jedno nebo více pravidel (definováno polem) vždy jsou vyhodnocena všechna pravidla. TranRule Entita představuje předpis (skupinu pravidel) pro zpracování transakce nebo položky transakce. Stanovená pravidla jsou před zapojením partnera do produkčního prostředí ukotvena v dokumentu jako Příloha č. 8 ke Smlouvě o účasti v programu ibod. V rámci testování zapojení probíhá implementace pouze základních (obratových) pravidel, při zapojení dalších druhů může operátor požadovat dodatečné otestování systému partnera. RuleId Int Ano Identifikace skupiny pravidel. Text String Ne Textová hodnota doplňující údaj. Maximálně 50 znaků. Value Decimal Ano Vstupní hodnota pro výpočet pravidla. TranItem Entita představuje jednu položku transakce. ItemId String Ano Identifikace položky partnera. Preference: 1. EAN, 2. Interní kód zboží Maximálně 50 znaků. Text String Ne Název položky. Maximálně 50 znaků. Amount Decimal Ano *Množství. Price Decimal Ano *Celková cena za položku včetně DPH (jednotková cena*množství) TranRules TranRule[] Ne Pravidla, dle kterých se řídí zpracování položky. *Poznámka: vlastnosti Amount a Price jsou důležité pro využití koaličního potenciálu, nicméně výpočet přidělených bodů za položku probíhá pouze dle TranRules[]. [6]

8 1.2.2 Metoda TranGet() Slouží k získání stavu zpracování transakcí partnera v systému. Metoda je vhodná k ověření stavu konkrétní transakce nebo k postupnému získání všech zaslaných transakcí pro zpracování ve vlastním systému partnera. TranGetRequest Vstupní entita metody. PartnerId String Ano Unikátní identifikátor partnera. TranId String Ano Od jakého TranId (včetně) budou vráceny záznamy. Count Int Ano Počet vrácených záznamů: min. = 1, max. = Při požadavku na počet záznamů mimo výčet je vrácen právě jeden záznam. TranGetResponse Výstupní entita metody. Result Int Ano Návratová hodnota dle číselníku. Text String Ano Návratová hodnota v textové podobě. TranStatuses TranStatus[] Ne Pole stavů transakcí. TranStatus Entita představuje stav zpracování jedné transakce. TranId String Ano Unikátní identifikátor transakce partnera. Seller String Ne Identifikátor obsluhy. Status Int Ano Stav transakce dle číselníku. Changed DateTime Ano Datum a čas poslední změny stavu včetně vytvoření. Points Int Ano Počet přidělených bodů může být NULL Metoda BalanceGet() Slouží k získání stavu bodů karty klienta. ON-LINE metoda, není určena pro dávkové zpracování. BalanceGetRequest Vstupní entita metody. PartnerId String Ano Unikátní identifikátor partnera. Card String Ano Číslo karty ibod (16 znaků) nebo čárový kód (13 znaků) bez mezer. BalanceGetResponse Výstupní entita metody. Result Int Ano Návratová hodnota dle číselníku. Text String Ano Návratová hodnota v textové podobě. Points Int Ano Počet bodů (může být i záporný). [7]

9 1.3 PŘÍKLADY POUŽITÍ PRAVIDEL Způsob výpočtu U obratových pravidel se pro výpočet standardně používá koeficient, kterým se dělí dodaná hodnota. Tento způsob výpočtu je vhodný zejména pro pravidla, kdy vstupní hodina je větší, než počet přidělených bodů. Zaokrouhlení systém vždy zaokrouhluje vypočítané body dolů - na celá čísla. Systém může dále přidělovat na definované pravidlo množství bodů rovnající se dodané hodnotě, tedy 1:1, tento způsob implementace je vhodný pro partnery s často se měnícími pravidly, větší marketingovou aktivitou a se schopností vlastní plné podpory zákazníků. Pro výpočet platí, že pro obratová pravidla přes všechny entity TranRule u transakce: - nejprve nasčítá hodnoty dle RuleId - následně vypočte body na základě koeficientu Je možné používat současně pravidla uvedená na transakci a pravidla u jednotlivých položek transakce, je však nutné mít na paměti výše uvedené o nasčítání hodnot. Špatným výběrem a kombinací pravidel je možné dosáhnout poměrně značných chyb a následných ztrát. Tato variabilita dává partnerovi možnost kompletně řídit přípis bodů nebo nechat řízení přípisu na operátorovi Příklady Transakce A klient nakoupí u partnera za 850,- Kč Požadavky partnera - za každých utracených 25,- Kč dostane klient 1 bod Entita Tran Vlastnost Data TranId b Place Kladno-2 Card Created T10:22:30 TranRules RuleId Text Value 2 NULL 850 TranItems NULL Výpočet - na transakci je aplikována skupina pravidel ID = 2 s částkou 850 Kč - v této skupině je jediné pravidlo viz výše - klient získá 850 / 25 = 34 bodů - v detailu transakce je klientovi zobrazen rozpad: o za nákup u partnera získáváte 34 bodů [8]

10 Transakce B klient nakoupí u partnera za ,- Kč + partner klientovi připíše 50 bodů za nákup 1ks speciálního zboží (logika na straně partnera) Požadavky partnera - za každých utracených 25,- Kč dostane klient 1 bod - možnost klientovi přidat jednorázově body na základě logiky nezasílané do ibodu Definice pravidel - č. 2 obratový koeficient 25 Kč x 1 bod - č. 10 jednorázový přípis 1ks x 50 bodů Entita Tran Vlastnost Data TranId 1936 Place 1 Card Created T11:01:01 TranRules RuleId Text Value 2 NULL akční zboží 2 TranItems NULL Výpočet - na transakci je aplikována skupina pravidel ID = 2 s částkou Kč / 25 = na transakci je aplikována skupina pravidel ID = 10 s počtem 2ks - 2 * 50 = klient získá 900 bodů - v detailu transakce je klientovi zobrazen rozpad: o za nákup u partnera 800 bodů o za akční zboží 100 bodů [9]

11 Transakce C klient nakoupí u partnera 3 položky celkem za ,- Kč, partner posílá položky nákupního košíku a jedna položka má aplikováno akční pravidlo, při nákupu nad dostává klient 100 bodů. Dále je nastaveno speciální pravidlo kdy konkrétní EAN kód výrobku jednorázově přičte klientovi 65 bodů za každý kus. Požadavky partnera - za každých utracených 25,- Kč dostane klient 4 bod - možnost klientovi přidat jednorázově body na základě logiky nezasílané do ibodu Definice pravidel - č. 2 obratový koeficient 25 Kč x 4 body a rozsahové pravidlo nad Kč bonus 100 bodů - č. 4 jednorázový přípis za konkrétní výrobek (dle EAN kódu) 1 x 65 bodů Entita Tran Vlastnost Data TranId 1937 Place 15 Card Created T15:25:13 TranRules RuleId Text Value 2 obj. č TranItems ItemId Text Amount Price CD SONY RuleId Text Value 4 NULL 2 Výpočet - na transakci je aplikována skupina pravidel ID = 2 s částkou Kč. V této skupině jsou obratové pravidlo (za 25 Kč 4 body) a rozsahové pravidlo (za částku nad Kč přidej 100 bodů) - dále je aplikována skupina pravidel 4 s výčtem EAN kódů partnera. Za tento uvedený získá klient 65 bodů za každý kus Kč / 25 = 408 * 4 = Kč > = ks * 65 = klient získá 1862 bodů - v detailu transakce je klientovi zobrazen rozpad: o za nákup u partnera 1632 bodů o za nákup nad Kč 100 bodů o za nákup značky Sony 130 bodů [10]

12 1.4 PLATBA KARTOU IBOD U OBCHODNÍHO PARTNERA PLATEBNÍ BRÁNA IBOD Požadavky na partnera při užívání níže popsaného API - partner musí mít podepsaný Dodatek ke Smlouvě o dodávkách do Katalogu odměn, který zahrnuje používání této části API a ve kterém je určen právní rámec, zúčtovací proces mezi partnerem a dodavatelem řešení a vymezena hranice odpovědnosti - každá implementace musí být po jejím návrhu partnerem schválena a otestována provozovatelem platební brány - bez schválení a podpisu akceptačního protokolu vydaného provozovatelem brány není možné níže uvedenou část API použít - partner nesmí ve svých systémech, ani jiným způsobem v žádném případě uchovávat PIN k IBOD kartě déle než 20 minut od zapsání klientem - komunikace mezi partnerem a zákazníkem a mezi partnerem a platební bránou musí probíhat zabezpečeně pomocí SSL/TSL Hlavní idea řešení a základní scénář - partner provede implementaci této části API na konci platebního procesu (ať v elektronickém obchodu, tak v pokladním systému) v okamžiku, kdy je známa finální částka, kterou má klient uhradit - partner zavolá metodu PaymentGet() a předá jí požadované parametry - metoda na základě identifikace klienta a požadované částky k zaplacení vrací seznam možností slev, které klient může uplatnit na svůj nákup - každá kombinace vždy určuje počet bodů, které budou odečteny z bodového konta klienta a slevu v Kč, která bude klientovi započtena na aktuální nákup - partner prezentuje a nechá klienta zvolit jednu z možností a po potvrzení zašle pomocí metody PaymentSet(), který realizuje transakci - v okamžiku realizace slevové/platební transakce jsou klientovi strženy body z jeho bodového konta a partnerovi vzniká pohledávka u provozovatele platební brány dle smluvních podmínek - realizovanou slevovou/platební transakci partner odečte od finální částky požadované po klientovi - platební transakce je možná stornovat PaymentStornoSet() po dobu 2 let, storno je možné provést jen v plné výši a právě jednou provozovateli vzniká pohledávka u partnera dle smluvních podmínek - partner může využít metody PaymentHistoryGet() pro získání přehledu provedených plateb a jejich stavu Metoda PaymentGet() Slouží k získání seznamu (PaymentValue[]) možných slev uplatnitelných na nákup na základě vstupních parametrů. PaymentGetRequest Vstupní entita metody. Nutnost zadat PIN vychází z nastavení platební brány pro konkrétní PartnerId. PartnerId String Ano Unikátní identifikátor partnera. Card String Ano Číslo karty ibod (16 znaků) nebo čárový kód (13 znaků) bez mezer. Pin String Ne Autorizační kód zadaný klientem (4 znaky). Price Decimal Ano Hodnota nákupu v Kč včetně DPH. [11]

13 PaymentGetResponse Výstupní entita metody. Result Int Ano Návratová hodnota dle číselníku. Text String Ano Návratová hodnota v textové podobě. PaymentValues PaymentValue[] Ne Pole možných variant slev klienta. PaymentValue Entita obsahuje nabídku možné slevy a počtu bodů čerpaných z účtu klienta při uplatnění této slevy. Pole těchto entit tvoří nabídku možných slev PaymentGetResponse pro klienta. Points Int Ano Počet čerpaných bodů. Value Int Ano Nominální hodnota slevy Metoda PaymentSet() Slouží k uplatnění nabídnuté slevy a čerpání bodů z klientova konta. PaymentSetRequest Vstupní entita metody. Nutnost zadat PIN vychází z nastavení platební brány pro konkrétní PartnerId. PartnerId String Ano Unikátní identifikátor partnera. Place String Ano Identifikátor obchodního místa (50 znaků). Seller String Ne Identifikátor obsluhy (50 znaků). Card String Ano Číslo karty ibod (16 znaků) nebo čárový kód (13 znaků) bez mezer. Pin String Ne Autorizační kód zadaný klientem (4 znaky). Price Decimal Ano Hodnota nákupu v Kč včetně DPH. Value Int Ano Nominální hodnota požadované slevy. PaymentFid String Ne Identifikátor platby partnera. Slouží pro řešení reklamací a vyúčtování (50 znaků). PaymentSetResponse Výstupní entita metody. Result Int Ano Návratová hodnota dle číselníku. Text String Ano Návratová hodnota v textové podobě. PaymentId Int Ano Unikátní identifikátor slevové transakce. Toto Id je třeba uschovat pro pozdější potřebu Metoda PaymentStornoSet() Slouží k stornování uplatněné slevy a navrácení bodových prostředků na účet klienta. Lze provést právě jednou. Storno je možné provést jen celkové, nikoliv částečné. [12]

14 PaymentStornoSetRequest Vstupní entita metody. PartnerId String Ano Unikátní identifikátor partnera. Place String Ne Identifikátor obchodního místa (50 znaků). Seller String Ne Identifikátor obsluhy (50 znaků). PaymentId Int Ano Id slevové transakce PartnerSetResponse. PaymentStornoSetResponse Výstupní entita metody. Result Int Ano Návratová hodnota dle číselníku. Text String Ano Návratová hodnota v textové podobě Metoda PaymentHistoryGet() Slouží k získání přehledu plateb. PaymentHistoryGetRequest Vstupní entita metody. PartnerId String Ano Unikátní identifikátor partnera. PaymentId Int Ano Od jakého PaymentId (včetně) budou vráceny záznamy. Count Int Ano Počet vrácených záznamů: min. = 1, max. = PaymentHistoryGetResponse Výstupní entita metody. Result Int Ano Návratová hodnota dle číselníku. Text String Ano Návratová hodnota v textové podobě. PaymentStatuses PaymentStatus[] Ne Pole stavů plateb. PaymentStatus Entita prezentující platební/slevovou transakci. PaymentId Int Ano Id slevové transakce. Place String Ne Identifikátor obchodního místa (50 znaků). Seller String Ne Identifikátor obsluhy (50 znaků). Status Int Ano 0 uplatněno 1 stornováno Changed DateTime Ano Datum a čas poslední změny. Points Int Ano Počet uplatněných bodů. Value Int Ano Nominální hodnota požadované slevy v Kč. 1.5 KONTAKT A PODPORA Pro technickou podporu, testování a dotazy týkající se integrace kontaktujte: [13]

15 Tomáš Khür Pro produkční podporu, nastavení pravidel, akcí a jejich prezentaci kontaktujte: Michaela Synková michaela.synkova@mrred.cz [14]