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: 01. 10. 2014
Tomáš Khűr
[email protected]
OBSAH Změny v dokumentu................................................................................................................................ 1 1
Webová služba SOAP, verze 2.2.0 ................................................................................................... 2 1.1
Popis rozhraní .......................................................................................................................... 2
1.1.1
Komunikace ..................................................................................................................... 2
1.1.2
Produkční prostředí ......................................................................................................... 2
1.1.3
Testovací prostředí .......................................................................................................... 2
1.1.4
Číselníky ........................................................................................................................... 2
1.2
Metody a entity ....................................................................................................................... 3
1.2.1
Metoda TranAdd() ........................................................................................................... 4
1.2.2
Metoda TranGet()............................................................................................................ 7
1.2.3
Metoda BalanceGet() ...................................................................................................... 7
1.3
Příklady použití pravidel .......................................................................................................... 8
1.3.1
Způsob výpočtu ............................................................................................................... 8
1.3.2
Příklady ............................................................................................................................ 8
1.4
Platba kartou IBOD u obchodního partnera – Platební brána IBOD ..................................... 11
1.4.1
Metoda PaymentGet()................................................................................................... 11
1.4.2
Metoda PaymentSet() ................................................................................................... 12
1.4.3
Metoda PaymentStornoSet() ........................................................................................ 12
1.4.4
Metoda PaymentHistoryGet() ....................................................................................... 13
1.5
Kontakt a podpora ................................................................................................................. 13
ZMĚNY V DOKUMENTU DATUM 15. 12. 2013 15. 12. 2013 15. 12. 2013 15. 12. 2013 15. 12. 2013 27. 7. 2014 1. 10. 2014
ZMĚNA Nové WSDL pro verzi 2.0.0 Nový obrázek „Metody a entity“ Entita „Tran“ nově obsahuje vlastnost „Seller“ Entita „TranStatus“ nově obsahuje vlastnost „Seller“ Sekce „Platba kartou IBOD u obchodního partnera“ Entita "PaymentSetRequest" nově obsahuje "PaymentFid" Rozšířena "Platba kartou IBOD u obchodního partnera"
detail detail detail detail detail detail detail
[1]
1 WEBOVÁ SLUŽBA SOAP, VERZE 2.2.0 1.1 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ů. 1.1.1 Komunikace Protokol: HTTPS (nešifrované HTTP není podporováno) Port: 443 Verze SOAP: 1.1, 1.2 1.1.2 Produkční prostředí Adresa služby: https://gate.ibod.cz/v2/api.svc Adresa WSDL: https://gate.ibod.cz/v2/wsdl.xml Adresa číselníků: https://gate.ibod.cz/v2/api.aspx 1.1.3 Testovací prostředí Adresa služby: https://test.gate.ibod.cz/v2/api.svc Adresa WSDL: https://test.gate.ibod.cz/v2/wsdl.xml Adresa číselníků: https://test.gate.ibod.cz/v2/api.aspx 1.1.4 Čí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 0 1 2+
Popis OK – operace se zdařila. CHYBA AUTORIZACE CHYBA: #důvod chyby#
[2]
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]
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 1000 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]
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ř. -1250) 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. Vlastnost PartnerId
Datový typ String
Vyžadováno Ano
Trans
Tran[]
Ano
Popis Unikátní identifikátor partnera, klíč pro testovací a produkční prostředí je různý. Pole transakcí ke zpracování – max. 1000 záznamů.
Vyžadováno Ano Ano
Popis Návratová hodnota dle číselníku. Návratová hodnota v textové podobě.
TranAddResponse Výstupní entita metody. Vlastnost Result Text
Datový typ Int String
Tran Entita představuje jednu transakci (nebo storno transakci) u partnera. Vlastnosti Vlastnost TranId
Datový typ String
Vyžadováno Ano
Place
String
Ano
Seller
String
Ne
Card
String
Ano
Created
DateTime
Ano
Popis Unikátní identifikátor transakce partnera. Duplicitní transakce nebudou zpracovány. Maximálně 50 znaků. 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ů. Identifikátor obsluhy, dle uvážení partnera. Slouží pro lepší orientaci při řešení reklamací, statistických ukazatelů, soutěží a dalších. Číslo karty iBOD (16 znaků) nebo čárový kód (13 znaků) bez mezer. 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]
TranRules
TranRule[]
Ne
TranItems
TranItem[]
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ň. 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. Vlastnost RuleId Text
Datový typ Int String
Vyžadováno Ano Ne
Value
Decimal
Ano
Popis Identifikace skupiny pravidel. Textová hodnota – doplňující údaj. Maximálně 50 znaků. Vstupní hodnota pro výpočet pravidla.
TranItem Entita představuje jednu položku transakce. Vlastnost ItemId
Datový typ String
Vyžadováno Ano
Text
String
Ne
Amount Price
Decimal Decimal
Ano Ano
TranRules
TranRule[]
Ne
Popis Identifikace položky partnera. Preference: 1. EAN, 2. Interní kód zboží Maximálně 50 znaků. Název položky. Maximálně 50 znaků. *Množství. *Celková cena za položku včetně DPH (jednotková cena*množství) 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]
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. Vlastnost PartnerId TranId Count
Datový typ String String Int
Vyžadováno Ano Ano Ano
Popis Unikátní identifikátor partnera. Od jakého TranId (včetně) budou vráceny záznamy. Počet vrácených záznamů: min. = 1, max. = 1000.
Při požadavku na počet záznamů mimo výčet 1-1000 je vrácen právě jeden záznam. TranGetResponse Výstupní entita metody. Vlastnost Result Text TranStatuses
Datový typ Int String TranStatus[]
Vyžadováno Ano Ano Ne
Popis Návratová hodnota dle číselníku. Návratová hodnota v textové podobě. Pole stavů transakcí.
TranStatus Entita představuje stav zpracování jedné transakce. Vlastnost TranId Seller Status Changed Points
Datový typ String String Int DateTime Int
Vyžadováno Ano Ne Ano Ano Ano
Popis Unikátní identifikátor transakce partnera. Identifikátor obsluhy. Stav transakce dle číselníku. Datum a čas poslední změny stavu včetně vytvoření. Počet přidělených bodů – může být NULL.
1.2.3 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. Vlastnost PartnerId Card
Datový typ String String
Vyžadováno Ano Ano
Popis Unikátní identifikátor partnera. Číslo karty iBOD (16 znaků) nebo čárový kód (13 znaků) bez mezer.
BalanceGetResponse Výstupní entita metody. Vlastnost Result Text Points
Datový typ Int String Int
Vyžadováno Ano Ano Ano
Popis Návratová hodnota dle číselníku. Návratová hodnota v textové podobě. Počet bodů (může být i záporný). [7]
1.3 PŘÍKLADY POUŽITÍ PRAVIDEL 1.3.1 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. 1.3.2
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 TranId Place Card Created TranRules TranItems
Data 20140314-1b Kladno-2 1234567890123 2013-04-12T10:22:30 RuleId 2 NULL
Text NULL
Value 850
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]
Transakce B – klient nakoupí u partnera za 20 000,- 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 TranId Place Card Created TranRules
TranItems
Data 1936 1 1234567890124 2013-05-1T11:01:01 RuleId 2 10 NULL
Text NULL akční zboží
Value 20000 2
Výpočet -
na transakci je aplikována skupina pravidel ID = 2 s částkou 20 000 Kč 20000 / 25 = 800 na transakci je aplikována skupina pravidel ID = 10 s počtem 2ks
-
2 * 50 = 100 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]
Transakce C – klient nakoupí u partnera 3 položky celkem za 10 200,- 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 10 000 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 10 000 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 TranId Place Card Created TranRules
TranItems
Data 1937 15 1234567890125 2013-06-10T15:25:13 RuleId 2 ItemId 15648946516 RuleId 4
Text obj. č. 259874 Text CD SONY Text NULL
Value 10200 Amount 2
Price 100 Value 2
Výpočet -
-
-
na transakci je aplikována skupina pravidel ID = 2 s částkou 10 200 Kč. V této skupině jsou obratové pravidlo (za 25 Kč 4 body) a rozsahové pravidlo (za částku nad 10000 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 10200 Kč / 25 = 408 * 4 = 1632 10200 Kč > 10000 = 100 2 ks * 65 = 130 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 10.000 Kč 100 bodů o za nákup značky Sony 130 bodů
[10]
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
1.4.1 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. Vlastnost PartnerId Card
Datový typ String String
Vyžadováno Ano Ano
Pin Price
String Decimal
Ne Ano
Popis Unikátní identifikátor partnera. Číslo karty iBOD (16 znaků) nebo čárový kód (13 znaků) bez mezer. Autorizační kód zadaný klientem (4 znaky). Hodnota nákupu v Kč včetně DPH. [11]
PaymentGetResponse Výstupní entita metody. Vlastnost Result Text PaymentValues
Datový typ Int String PaymentValue[]
Vyžadováno Ano Ano Ne
Popis Návratová hodnota dle číselníku. Návratová hodnota v textové podobě. 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. Vlastnost Points Value
Datový typ Int Int
Vyžadováno Ano Ano
Popis Počet čerpaných bodů. Nominální hodnota slevy.
1.4.2 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. Vlastnost PartnerId Place Seller Card
Datový typ String String String String
Vyžadováno Ano Ano Ne Ano
Pin Price Value PaymentFid
String Decimal Int String
Ne Ano Ano Ne
Popis Unikátní identifikátor partnera. Identifikátor obchodního místa (50 znaků). Identifikátor obsluhy (50 znaků). Číslo karty iBOD (16 znaků) nebo čárový kód (13 znaků) bez mezer. Autorizační kód zadaný klientem (4 znaky). Hodnota nákupu v Kč včetně DPH. Nominální hodnota požadované slevy. Identifikátor platby partnera. Slouží pro řešení reklamací a vyúčtování (50 znaků).
PaymentSetResponse Výstupní entita metody. Vlastnost Result Text PaymentId
Datový typ Int String Int
Vyžadováno Ano Ano Ano
Popis Návratová hodnota dle číselníku. Návratová hodnota v textové podobě. Unikátní identifikátor slevové transakce. Toto Id je třeba uschovat pro pozdější potřebu.
1.4.3 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]
PaymentStornoSetRequest Vstupní entita metody. Vlastnost PartnerId Place Seller PaymentId
Datový typ String String String Int
Vyžadováno Ano Ne Ne Ano
Popis Unikátní identifikátor partnera. Identifikátor obchodního místa (50 znaků). Identifikátor obsluhy (50 znaků). Id slevové transakce PartnerSetResponse.
PaymentStornoSetResponse Výstupní entita metody. Vlastnost Result Text
Datový typ Int String
Vyžadováno Ano Ano
Popis Návratová hodnota dle číselníku. Návratová hodnota v textové podobě.
1.4.4 Metoda PaymentHistoryGet() Slouží k získání přehledu plateb. PaymentHistoryGetRequest Vstupní entita metody. Vlastnost PartnerId PaymentId
Datový typ String Int
Vyžadováno Ano Ano
Count
Int
Ano
Popis Unikátní identifikátor partnera. Od jakého PaymentId (včetně) budou vráceny záznamy. Počet vrácených záznamů: min. = 1, max. = 1000.
PaymentHistoryGetResponse Výstupní entita metody. Vlastnost Result Text PaymentStatuses
Datový typ Int String PaymentStatus[]
Vyžadováno Ano Ano Ne
Popis Návratová hodnota dle číselníku. Návratová hodnota v textové podobě. Pole stavů plateb.
PaymentStatus Entita prezentující platební/slevovou transakci. Vlastnost PaymentId Place Seller Status
Datový typ Int String String Int
Vyžadováno Ano Ne Ne Ano
Changed Points Value
DateTime Int Int
Ano Ano Ano
Popis Id slevové transakce. Identifikátor obchodního místa (50 znaků). Identifikátor obsluhy (50 znaků). 0 … uplatněno 1 … stornováno Datum a čas poslední změny. Počet uplatněných bodů. 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]
Tomáš Khür +420 603 954 162
[email protected] Pro produkční podporu, nastavení pravidel, akcí a jejich prezentaci kontaktujte: Michaela Synková +420 739 383 900
[email protected]
[14]
