Textová podoba smlouvy - Hlídač státu.

Upozornění: Text přílohy byl získán strojově a nemusí přesně odpovídat originálu. Zejména u strojově nečitelných smluv, kde jsme použili OCR. originál smlouvy stáhnete odsud

Datová věta pro MSK

Vlastník dokumentace: Koordinátor ODIS s.r.o.

Verze 1.0.46.33 (verze pro výběrové řízení na dopravce)
16. 10. 2014
Obsah

Obsah ........................................................................................................................................... 2
Historie změn ............................................................................................................................... 4
Popis datových toků CC MSK ..................................................................................................... 6
Typy předávání DAT ................................................................................................................... 8
1. Datový tok mezi CC MSK a dopravcem ................................................................................. 9
Datový tok od CC MSK k dopravci.............................................................................................9
Datový tok od dopravce k CC MSK .......................................................................................... 10
2. Datový tok mezi CC MSK a cestujícím.................................................................................10
Datový tok od CC MSK k cestujícímu ...................................................................................... 10
Datový tok od cestujícího k CC MSK ....................................................................................... 11
3. Datový tok mezi CC MSK a KODIS ..................................................................................... 11
Datový tok od CC MSK ke KODIS...........................................................................................11
Datový tok od KODIS k CC MSK............................................................................................. 11
Věta KODIS ................................................................................................................................... 13
Obecné informace ...................................................................................................................... 13
Aktivace karty v CC...................................................................................................................13
Zablokovaní a odblokování a pozastavení karty + změna jejich parametrů .............................. 16
Změna profilů na kartě ............................................................................................................... 18
Seznam všech karet v systému...................................................................................................20
Aktivace zařízení........................................................................................................................22
Zablokovaní a odblokování zařízení .......................................................................................... 23
Transakce na zařízení.................................................................................................................26
Podezřelé transakce....................................................................................................................34
Zasílání transakcí ODIS/neODIS pro ODIS/neODIS karty ze zařízení ODIS .......................... 35
Zasílání transakce jako potvrzení, že za daný den zařízení dodalo seznam transakcí ............... 36
Zasílání transakce jako MULTI-LÍSTEK do CCMSK. ............................................................. 37
Řešení neukončených nahrání e-shop transakcí na strojku........................................................39
Blacklist karet ................................................................................................................................ 40
Denylist bankovních karet ............................................................................................................. 42
Význam použitých datových položek ........................................................................................ 42
Zpracování odpovědí.................................................................................................................. 43
Metoda GetLastIssuedDenyListSequenceNo ............................................................................ 44
Metoda GetDenyList..................................................................................................................45
Metoda GetDenyListBinary.......................................................................................................47
Green-list peněženky/kupónů ........................................................................................................ 48
Inkarta ............................................................................................................................................ 51
Zobrazení informace In Karty přes webové rozhraní CC .......................................................... 52
Vrácení informace o zůstatku EP na kartě ................................................................................. 53
Vrácení kupónů na kartě ............................................................................................................ 54
Nestandardní situace, reklamace, storno a výměny karet .......................................................... 55
Reklamace/storno nákupu EP na eshopu ....................................................................................... 61
Reklamace nákupu EP na eshopu .............................................................................................. 61
Storno nákupu EP na eshopu ..................................................................................................... 61
Posílaní souborů s pozdějším zpracováním ................................................................................... 62
Stažení souboru s odpovědí po zpracování .................................................................................... 62
Příklady užití .................................................................................................................................. 63
Příklady užití – rozšíření ................................................................................................................ 70
Dlouhodobé jízdné ..................................................................................................................... 70

2
Krátkodobé jízdné ...................................................................................................................... 71
Jednotlivé jízdné ........................................................................................................................ 72
Kilometrické jízdné....................................................................................................................74
Stažení transakcí z CC MSK pomocí webové služby. ................................................................... 75
WSDL: ....................................................................................................................................... 77
Vygenerování hesla z CC MSK pomocí webové služby ........................................................... 80
WSDL pro GetUserPasswordByCardNo ................................................................................... 81
Stažení karet se změnami profilu z CC MSK pomocí webové služby .......................................... 83
Stažení všech transakcí z CC MSK pro dopravce za měsíc...........................................................84
Stažení všech transakcí z CC MSK pro dopravce na vlastních kartách provedených u jiného
dopravce za měsíc. ......................................................................................................................... 85
Dodatek 1 ....................................................................................................................................... 86
Dodatek 2 ....................................................................................................................................... 88

3
Historie změn

Datum Verze Popis Autor
Doplnění upřesnění ke kapitolám Aktivace zařízení, XT-card
20. 02. 2015 1.0.46.9 Transakce zařízení, Příklady užití, Blacklist karet XT-card
Úprava příkladů 32 a 33 v sekci Příklady užití XT-card
24. 02. 2015 1.0.46.10 Úprava položky zones XT-card
17. 08. 2015 1.0.46.11 Úprava znění povinnosti položky „amount“ při resetu XT-card
14. 10. 2015 1.0.46.12 počítadla zařízení
Doplnění nových položek card-emv-token a card-emv- XT-card
18. 01. 2016 1.0.46.13 block-noticed do datové věty XT-card
Doplnění kapitoly Denylist včetně příkladů XT-card
20. 01. 2016 1.0.46.15 Doplnění příkladu 35. přiložení bankovní karty (tapnutí)
25. 01. 2016 1.0.46.16 do kapitoly Příklady užití XT-card
04. 02. 2016 1.0.46.17 Doplnění nové hodnoty „tap“ do stávající položky
Transtype XT-card
15. 02. 2016 1.0.46.18 Přepracování kapitoly Denylist bankovních karet (nyní
WS)
18. 03. 2016 1.0.46.19 Doplnění kapitoly Vygenerování hesla z CC MSK
pomocí webové služby
Doplnění kapitoly Stažení karet se změnami profilu z CC
MSK pomocí webové služby
Doplnění položek customerprofile a customerprofiler2 do
odpovědi v rámci stažení všech karet za dopravce
Doplnění kapitoly Denylist bankovních karet o:

 URL adresy webové služby včetně WSDL,
 návratové chybové kódy
 podrobnější popis jednotlivých položek

přenášených struktur
Doplnění kapitoly Řešení neukončených nahrání e-shop
transakcí na strojku

04. 04. 2016 1.0.46.20 Úprava elementu device-id XT-card

11. 04. 2016 1.0.46.21 Doplnění kapitoly Denylist bankovních karet o: XT-card
 binární podoba denylistu
09. 05. 2016 1.0.46.22 XT-card
24. 05. 2016 1.0.46.23 Doplnění nových položek card-emv-taplist-number a XT-card
card-emv-vehicle-number do datové věty
13. 06. 2016 1.0.46.24 Doplnění kapitoly Změna profilů na kartě, Stažení karet XT-card
12. 07. 2016 1.0.46.25 se změnami profilu z CC MSK pomocí webové služby a XT-card
04. 08. 2016 1.0.46.26 Seznam všech karet v systému XT-card
Doplnění kapitoly Aktivace karty v CC
26. 10. 2016 1.0.46.27 Doplnění kapitoly Reklamace/storno nákupu EP z eshopu XT-card
16. 11. 2016 1.0.46.28 Úprava kapitoly Změna profilů na kartě, Stažení karet se XT-card
29. 11. 2016 1.0.46.29 změnami profilu z CC MSK pomocí webové služby a XT-card
14. 12. 2016 1.0.46.30 Seznam všech karet v systému – přidání parametru XT-card
„datum změny profilu u dopravce“
Úprava příkladu č. 14
Úprava a doplnění příkladů v rámci chystané dělby tržeb
Úprava příkladů pro převod kupónu na kartě
Úprava kapitoly Vrácení informace o zůstatku na kartě a

4
1. 2. 2017 1.0.46.31 Vrácení kupónů na kartě XT-card
31. 3. 2017 1.0.46.32 Přidání příkladu pro prodej krátkodobého jízdného na XT-card
25. 5. 2017 1.0.46.33 papír, placeno hotově, 24 hodinová celosíťová obyčejná XT-card
(200 Kč)
Přidání nového příznaku tariff-type="NP" jako
nepřestupní pro odlišení nepřestupní jízdenky zasílané
v jedné transakci v oblasit Ostrava XXL.
Od 2. 7. změna zóny 354 na 78

5
Popis datových toků CC MSK

1. KODIS Zavedení dopravce do CC
(Provádí se ručně z www formuláře)

2. Dopravce Aktivace zařízení CLEARING MSK
Odpověď s výsledkem aktivace zařízení

3. Dopravce Aktivace karet
Odpověď s výsledkem aktivace karet

4. Dopravce Zaslání transakcí
Potvrzení přijetí jednotlivých transakcí

5. Dopravce Deaktivace karty/zařízení
6. Dopravce Potvrzení o úspěšnosti/neúspěšnosti operace
jednotlivých transakcí

Žádost o blacklist/whitelist
Data blacklistu/whitelistu

6
Schéma datových toků CC MSK
Clearing MSK

1 2 3

Dopravce

Cestující KODIS
(držitel karty) (Blue Pixel)

7
Typy předávání DAT

1. Prostřednictvím www rozhraní

Předávání dat (informací) prostřednictvím www je myšleno získání informací prohlížením příslušné
webové stránky na adrese „clearing.kodis.cz“.

2. Prostřednictvím xls souboru

Předávání dat (informací) prostřednictvím xls souboru je myšleno získání informací z příslušné
webové stránky na adrese „clearing.kodis.cz“ na které je umožněno stažení dané informace ve
formátu xls a uložení a PC uživatele.

3. Prostřednictvím e-mailu

Týká se pouze zasílání hesla, heslo přijde na e-mailovou adresu, která je zadána v aktivačních
údajích, zasílaných na server ve větě KODIS ve formátu XML.

4. Prostřednictvím XML souboru

Komunikace prostřednictvím XML souboru je hlavním komunikačním kanálem Clearingu pro
komunikaci s dopravci.

Jedná se o zaslání XML souboru dle specifikace věty KODIS na adresu
„clearing.kodis.cz/readdata.aspx“ metodou POST. V metodě POST jsou zasílány celkem 3
parametry name, passwd a XMLdata. První dva obsahují informace o Loginu a Heslu. Poslední
parametr obsahuje XML formát zprávy pro CCMSK dle specifikace věty KODIS. Na každou takto
zaslanou XML zprávu server odpoví opět dle specifikace věty KODIS.

Příklad:

POST clearing.kodis.cz/readdata.aspx HTTP/1.1
Cache-Control: no-cache
Connection: Keep-Alive
Content-Length: 4539
Content-Type: multipart/form-data; boundary=----FormData----
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Host: 10.0.0.80
User-Agent: Java/1.6.0_21

------FormData----
Content-Disposition: form-data; name="name"

ttt
------FormData----
Content-Disposition: form-data; name="passwd"

ttt
------FormData----
Content-Disposition: form-data; name="XMLdata"; filename="message.xml"
Content-Type: text/xml

------FormData------

1. Datový tok mezi CC MSK a dopravcem

Datový tok od CC MSK k dopravci
1. Prostřednictvím www rozhraní
 Informace o všech uživatelích daného dopravce v systému.
 Informace o všech kartách daného dopravce v systému.
 Informace o všech zařízeních daného dopravce v systému.
 Informace o všech transakcích daného dopravce v systému.
 Informace o všech dávkách zaslaných daným dopravcem do systému.
 Black list.
 Historie přihlášení uživatelů daného dopravce.
 Zůstatky na EP daného dopravce.
 Zařízení bez transakcí daného dopravce.
1. Prostřednictvím xls souborů
 Rozúčtování podle linek, zón a obcí daného dopravce. Dopravce bude stahovat jednou měsíčně,

data jsou zpracovávána v termínech určených platnou Smlouvou o dělbě tržeb mezi dopravci
v Integrovaném dopravním systému Moravskoslezského kraje.
2. Prostřednictvím XML souboru
 Black list karet dle specifikace věty KODIS. Blacklist přichází ihned po dotazu, předpokládá se,
že dopravce bude stahovat denně a importovat do odbavovacích zařízení co nejdříve, nejpozději
však do 3. dne od stažení.
 Green listy dle specifikace věty KODIS. Green list přichází ihned po dotazu, předpokládá se, že
dopravce bude stahovat denně a importovat do odbavovacích zařízení co nejdříve, nejpozději
však do 3. dne od stažení.
 Seznam všech karet daného dopravce v systému dle specifikace věty KODIS. Seznam karet
přichází ihned po dotazu, předpokládá se, že dopravce může stahovat dle své potřeby, z hlediska
CC není nutno stahovat vůbec.
 Odpověď s výsledkem operace pro aktivaci zařízení dle specifikace věty KODIS. Přichází
okamžitě po zaslání dotazu.
 Odpověď s výsledkem operace pro aktivaci karet dle specifikace věty KODIS. Přichází
okamžitě po zaslání dotazu.
 Odpověď s výsledkem operace pro přijetí jednotlivých transakcí dle specifikace věty KODIS.
Přichází okamžitě po zaslání dotazu.
 Odpověď s výsledkem operace zablokovaní, odblokování a pozastavení karet dle specifikace
věty KODIS. Přichází okamžitě po zaslání dotazu.

9
 Odpověď s výsledkem operace změna parametrů karet dle specifikace věty KODIS. Přichází
okamžitě po zaslání dotazu.

 Odpověď s výsledkem operace zablokovaní a odblokování zařízení dle specifikace věty KODIS.
Přichází okamžitě po zaslání dotazu.

3. Prostřednictvím webové služby (WS)
 Seznam všech transakcí, včetně transakcí provedených u jiných dopravců, k zadanému číslu

karty za zvolené období.

Datový tok od dopravce k CC MSK
1. Prostřednictvím XML souborů

 Aktivace zařízení dle specifikace věty KODIS. Dopravce musí provést dříve, než bude
vytvořená první transakce z tohoto zařízení, nejlépe ještě před instalací zařízení do vozidla.

 Aktivace karet dle specifikace věty KODIS. Dopravce musí provést dříve, než bude zaslaná
první transakce na této kartě, nejlépe při předání karty cestujícímu.

 Veškeré transakce dle specifikace věty KODIS. Dopravce zasílá transakce alespoň jednou denně
(aby měl cestující co nejaktuálnější přehled o svých jízdách na webovém rozhraní), nejpozději
však do 3 dnů od provedení transakce.

 Dopravce zasílá transakce v termínech dle platné Smlouvy o dělbě tržeb mezi dopravci
v Integrovaném dopravním systému Moravskoslezského kraje.

 Zablokovaní, odblokování a pozastavení karet dle specifikace věty KODIS. Dopravce zasílá na
Clearing okamžitě po oznámení cestujícím (do všech odbavovacích zařízení se distribuuje
nejpozději do 3 dnů)

 Změna parametrů karet dle specifikace věty KODIS. Dopravce zasílá dle charakteru změny,
nejlépe co nejdříve.

 Změna stavů transakcí umístěných v greenlistech (změna stavu kupónu v případě nahrání
předplaceného kupónu na kartu a změna stavu dobití EP v případě nahrání dobití EP
prostřednictvím e-shopu)

 Zablokovaní a odblokování zařízení dle specifikace věty KODIS. Dopravce zasílá okamžitě
v případě, kdy může dojít k zneužití zařízení (ztráta, krádeže apod.) v případě technické poruchy
nebo likvidace postačí zaslat do posledního termínu zasílání dat pro provádění zúčtování za
daný měsíc dle platné Smlouvy o dělbě tržeb mezi dopravci v Integrovaném dopravním systému
Moravskoslezského kraje.

 Žádost o blacklist dle specifikace věty KODIS. Dopravce bude zasílat denně a získaný blacklist
importovat do odbavovacích zařízení co nejdříve, nejpozději však do 3. dne od stažení.

 Žádost o greenlisty dle specifikace věty KODIS. Dopravce bude zasílat denně a získaný
blacklist importovat do odbavovacích zařízení co nejdříve, nejpozději však do 3. dne od stažení

 Žádost o seznam všech karet daného dopravce v systému dle specifikace věty KODIS.

2. Datový tok mezi CC MSK a cestujícím

Datový tok od CC MSK k cestujícímu
Clearing poskytuje data cestujícímu – držiteli karty:

10
1. Prostřednictvím www rozhraní
Tato data jsou poskytnuta na základě zadání správných přihlašovacích údajů:
 základní informace o kartě (vydavatel, číslo karty, aktivace karty),
 přehled jízd provedených na danou kartu,
 přehled kupónů zakoupených na danou kartu,
 pohyby na elektronické peněžence
2. Prostřednictvím e-mailu
 přístupové heslo

Datový tok od cestujícího k CC MSK
Cestující neposílá na Clearing žádná data.

3. Datový tok mezi CC MSK a KODIS

Datový tok od CC MSK ke KODIS
2. Prostřednictvím www rozhraní

 Informace o všech uživatelích v systému.
 Informace o všech kartách v systému.
 Informace o všech zařízeních v systému.
 Informace o všech transakcích v systému.
 Informace o všech dávkách zaslaných v systému.
 Black list.
 Historie přihlášení.
 Report pro ČNB.
 Zůstatky na EP.
 Billing EP.
 Statistiku držitelů karet podle profilů.
 Soupis podezřelých transakcí.
 Zařízení bez transakcí.

3. Prostřednictvím xls souborů
 Rozúčtování podle linek, zón a obcí za všechny dopravce.
 Rozúčtování podle spojů.

4. Prostřednictvím XML souboru
 Black list.

Datový tok od KODIS k CC MSK
 Zavedení dopravců do systému - data jsou zaváděna prostřednictvím www rozhraní.

11
 Rozúčtování dle Blue Pixel – data jsou předávána ve formátu xls.
12
Věta KODIS

Obecné informace

XML soubory
Při zasílání xml dat prostřednictvím webového rozhraní CC, je nutné zasílat data ve správném
kódování. Požadovaný typ kódování je UTF-8.
Soubory mohu být zasílány v zip formátu, avšak pro každou skupiny XML souborů
(aktivace/deaktivace karet, transakce, aktivace/deaktivace zařízení, apod.) musí být samostatný zip.
XML soubory pro aktivace karet a zařízení musí být odeslány dříve, než budou na těchto kartách a
zařízeních provedeny a odeslány jakékoliv transakce v XML souborech do CC.

Aktivace karty v CC

Tento XML soubor se posílá jako seznam aktivovaných karet a aplikací na ni u daného
provozovatele. Příklad XML souboru pro aktivaci karty

newcard
1

3
cz

...

V rámci elementu se nacházejí elementy , které mají následující atributy:

cardsno – výrobní číslo čipu karty v hexadecimálním tvaru přidělené výrobcem čipu např.
„04A456B1F0D380“ (povinná položka)
card_kodis - identifikační číslo karty, řetězec o délce max. 20 znaků, tak jak je uveden na kartě
(povinná položka)
cardlogin – nepoužívaná položka (nepovinná položka)
cardpwd – heslo pro přihlášení k portálu (nepovinná položka)
email - email držitele karty. Má-li mít držitel přístup k informacím o své kartě, jež jsou uloženy na
CCMSK, musí být email vyplněn. Na tento email je zasíláno první heslo pro přihlášení. (povinná
položka v případě požadavku na přístup do systému CCMSK)
valid_from – datumový začátek platnosti karty (povinná položka)
valid_to – datumový konec platnosti karty (povinná položka)
note - umožňuje přidat ke kartě poznámku (nepovinná položka)
customerprofile - číslo profilu 1 na kartě (nepovinná položka)
cp-date-from – začátek intervalu platnosti profilu č. 1 na kartě. Povinný pro

actdeact=“customerprofile“.
cp-date-to – konec intervalu platnosti profilu č. 1 na kartě. Povinný pro actdeact=“customerprofile“.
cp-date - datum změny profilu č. 1 u dopravce. Povinný pro actdeact=“customerprofile“.
customerprofile2 - číslo profilu 2 na kartě (nepovinná položka)
cp2-date-from – začátek intervalu platnosti profilu č. 2 na kartě. Povinný pro

actdeact=“customerprofile2“.
cp2-date-to – konec intervalu platnosti profilu č. 2 na kartě. Povinný pro
actdeact=“customerprofile2“.
cp2-date – datum změny profilu č. 2 u dopravce. Povinný pro actdeact=“customerprofile2“.

Karta může obsahovat 1 až n aplikací na kartě, které se aktivují přidáním elementu , který má
dva atributy:

appID - který určuje číslo aplikace v dekadickém formátu. Číslo aplikace může nabývat hodnoty 1
až 2 147 483 647, pro aplikaci jízdenka je určeno číslo „4609“ a pro aplikaci EP je
„34965“. Tyto dvě aplikace jsou povinné. Při aktivaci karty se vždy vytvoří aplikace 0, i
když nebude přidán element do XML u dané karty. Do této aplikace 0 budou
přiřazeny všechny transakce s nezadanou hodnotou aplikace, nebo pokud neexistuje žádná
jiná aplikace. (povinná položka).

max_counter – maximální počet transakcí u dané aplikace. Slouží pro kontrolu, zda počet transakcí
nepřekročil povolený počet transakcí. Pokud je uvedena hodnota 0 nebo není uvedena žádná
hodnota, kontrola se neprovádí (nepovinná položka)

Jako odpověď CC posílá seznam karet, které byly úspěšné aktivované. U neaktivovaných karet je
uveden důvod, proč nebyly úspěšně aktivované. U úspěšně aktivovaných je hodnota atributu „stat”
IS_OK.

newcard_ret

14
1

3
cz

...

cardsno – výrobní číslo karty v hexadecimálním tvaru (povinná položka)
stat – status operace – definuje úspěšnost operace. V případě úspěchu má hodnotu IS_OK (povinná
položka)
reason – obsahuje textový důvod neprovedení operace (povinná položka)

15
Zablokovaní a odblokování a pozastavení karty + změna jejich parametrů

V systému lze zablokovat, trvale zablokovat, odblokovat a zničit kartu. Navíc je možno pomocí
tohoto XML i měnit login, heslo, poznámku, email či typ držitele ke kartě. Karty již musí být
aktivovány v systému.
Příklad XML souboru pro jednotlivé operace s kartami.

actdeact_card
1

9
cz

...

cardsno – výrobní číslo karty v hexadecimálním tvaru (povinná položka)
actdeact – typ operace „act“ odblokování, „deact“ zablokování, „deact_ever“ zablokování navždy,
„destroy“ zešrotování, „note“ změní poznámku ke kartě, „cardlogin“ změní login ke kartě,
„cardpwd“ změní heslo ke kartě, “email“ změní email držitele, „incard“ = nahrání In Karty na
ODIS kartu (povinná položka)

date – kdy se aktivace/deaktivace má provést. Povinná pro actdeact = „act“ nebo actdeact = „deact“
nebo actdeact = „deact_ever“ nebo actdeact = „destroy“, jinak se ignoruje.

note – nová poznámka ke kartě. Povinný pro actdeact = „note“, jinak se ignoruje.
cardlogin – nový login ke kartě. Povinný pro actdeact = „cardlogin“, jinak se ignoruje.
cardpwd – nové heslo ke kartě. Povinný pro actdeact = „cardpwd“, jinak se ignoruje.
email – nový email držitele. Povinný pro actdeact = „email“, jinak se ignoruje.

16
Jako odpověď CC zasílá seznam karet s úspěšností, s jakou byly aktivovány nebo deaktivovány a
důvod proč se operace nezdařila.

actdeact_card_ret
1

3
cz

...

cardsno – výrobní číslo karty v hexadecimálním tvaru (povinná položka)
actdeact - typ provedené operace - „act“, „deact“, „deact_ever“, „note“, „cardlogin“, „cardpwd“,
„email“ (povinná položka)
stat – status operace – definuje úspěšnost operace. V případě úspěchu má hodnotu IS_OK (povinná
položka)
reason – obsahuje textový důvod neprovedení operace (povinná položka)

17
Změna profilů na kartě

V systému lze změnit profily na kartě. Změnu profilů lze provézt jak pro vlastní, tak cizí karty.
Získání informací o změnách profilů na kartách popisuje kapitola „Stažení karet se změnami proflů
z CCMSK pomocí webové služby“, případně jak získat aktuální profily vlastních karet popisuje
kapitola „Seznam všech karet v systému“.

Příklad XML souboru pro změnu profilů na kartě:

actdeact_card
1

2
cz

cardsno – výrobní číslo karty v hexadecimálním tvaru (povinná položka)
actdeact – typ operace „customerprofile“ – změna profilu 1 na kartě, „customerprofile2“ – změna
profilu 2 na kartě (povinná položka)
customerprofile – číslo profilu 1 na kartě. Povinný pro actdeact = „customerprofile“, jinak se

ignoruje. V případě zrušení profilu 1 na kartě se zasílá hodnota „0“.
customerprofile2 – číslo profilu 2 na kartě. Povinný pro actdeact = „customerprofile2“, jinak se

ignoruje. V případě zrušení profilu 2 na kartě se zasílá hodnota „0“.
date-from – začátek intervalu platnosti profilu karty. Povinný pro actdeact=“ customerprofile“ a

actdeact=“ customerprofile2“. V případě zrušení profilu je nepovinný.
date-to – konec intervalu platnosti profilu karty. Povinný pro actdeact=“ customerprofile“ a

actdeact=“ customerprofile2“. V případě zrušení profilu je nepovinný.
date – datum změny profilu u dopravce. Povinný pro actdeact=“customerprofile“ a actdeact=“
customerprofile2“.

18
Jako odpověď CC zasílá seznam karet s úspěšností, s jakou byly provedeny změny profilů na kartě
a důvod proč se operace nezdařila.

actdeact_card_ret
1

2
cz

cardsno – výrobní číslo karty v hexadecimálním tvaru (povinná položka)
actdeact - typ provedené operace - „customerprofile“, „customerprofile2 (povinná položka)
stat – status operace – definuje úspěšnost operace. V případě úspěchu má hodnotu IS_OK (povinná

položka)
reason – obsahuje textový důvod neprovedení operace (povinná položka)

Příklad XML souboru pro zrušení profilu na kartě na kartě:

actdeact_card
1

2
cz

19
Seznam všech karet v systému

Z CC je možno vyexportovat seznam všech karet, které byly v systému aktivovány.
Formát XML je následující:
Dopravcům se budou vracet pouze jejich vlastní karty.

card_list
1

1
cz

Jako odpověď CC zasílá XML obsahující seznam karet:

card_list_ret
1

n
cz

…

cardsno - výrobní číslo karty v hexa (povinná položka)
cardlogin – login, pod kterým se bude klient přihlašovat k portálu (povinná položka)
cardState – stav karty: -1=zešrotovaná, 0=blokovaná/neplatná, 1=aktivní (povinná položka)
providerName – název subjektu, který poskytuje karty. Položka je povinná pokud má uživatel právo
na vrácení všech karet v systému
customerprofile – číslo profilu 1 na kartě (povinná položka)
cp-date-from – začátek intervalu platnosti profilu 1 karty (povinná položka)
cp-date-to – konec intervalu platnosti profilu 1 karty (povinná položka)
cp-date – datum změny profilu 1 u dopravce (povinná položka)

20
customerprofile2 – číslo profilu 2 na kartě (povinná položka)
cp2-date-from – začátek intervalu platnosti profilu 2 karty (povinná položka)
cp2-date-to – konec intervalu platnosti profilu 2 karty (povinná položka)
cp2-date – datum změny profilu 2 u dopravce (povinná položka)
Poznámka: karta se stavem zablokovaná navždy se vypisuje jako neplatná, tedy se stavem=0, neboť
se jedná o neplatnou kartu.
Poznámka: karta se stavem sešrotována se záměrně vypisuje se stavem -1, ačkoliv se jedná rovněž o
neplatnou kartu, z důvodu rozlišení, že tyto karty se již v systému nemohou vyskytnout, neboť
fyzicky neexistují.

21
Aktivace zařízení

Tento XML soubor se posílá jako seznam aktivovaných zařízení u daného provozovatele. Jednou
použité číslo zařízení se nedá již znovu použít ani po zablokování předcházejícího zařízení. Zařízení
je možné aktivovat (stejně jako další operace) pouze pomocí XML souboru. XML však lze rovněž
nahrát ručně přes webové rozhraní.
Příklad XML souboru pro aktivaci nového zařízení.

newdevice
1

3
cz

...

Jednotlivé atributy mají následující vlastnosti

device-id – číslo zařízení. Musí být u daného provozovatele jedinečné a nedá znovu použít pro jiné
zařízení i po zakázání předchozího (povinná položka)
samno – je číslo SAM modulu v hexadecimálním formátu (nepovinná položka)
cashno – dekadické číslo pokladny (nepovinná položka)
premise - provozovna provozovatele, kterému patří dané zařízení (nepovinná položka)
max_counter – maximální počet transakcí na daném zařízení (poslední hodnota použitelná pro
řadu). Indikuje, kdy se číselník transakcí na zařízení vynuluje. Je nutné, aby hodnota čítače se
„neotočila“ (nevynulovala) za časový úsek menší než 24 hodin (povinná položka)
valid_from – datumový začátek platnosti zařízení (povinná položka)
valid_to – datumový konec platnosti, zařízení - Clearing akceptuje největší možnou hodnotu
31.12.9999. Je však vhodné zařízení aktivovat s „rozumnou“ hodnotou, např. 31.12.2050 apod. –
toto platí pro všechny atributy, které se týkají časového rozsahu (povinná položka)
where – textový popis místa, kde je zařízení umístěno (nepovinná položka)
note - umožňuje přidat k zařízení poznámku (nepovinná položka)
subprovider - umožňuje zařízení přiřadit k departmentu (oddělení), jehož kód je v atributu zadán
(nepovinná položka)

22
Jako odpověď CC zasílá seznam zařízení, která byla úspěšně aktivovaná. U neaktivovaných
zařízení je uveden důvod, proč nebyly úspěšně aktivované. U úspěšně aktivovaných je hodnota
IS_OK.

newdevice_ret
1

3
cz

...

device-id – dekadické číslo zařízení, Musí být u daného provozovatele jedinečné (povinná položka)
stat – status operace – definuje úspěšnost operace. V případě úspěchu má hodnotu IS_OK (povinná

položka)
reason – obsahuje textový důvod neprovedení operace (povinná položka)

Zablokovaní a odblokování zařízení

V systému lze zablokovat a odblokovat zařízení, změnit poznámku a umístění zařízení, i jeho
přiřazení k departmentu. Zařízení již musí být aktivováno v systému.
Příklad XML souboru pro zablokování a odblokování zařízení.

actdeact_device
1

n
cz

…

device-id – dekadické číslo zařízení (povinná položka)
actdeact – typ operace „act“ aktivace, „deact“ deaktivace, „deact_ever“ deaktivace navždy, „note“ –

změní se poznámka ke kartě, „where“ změní se umístění zařízení, „subprovider“ změní
přiřazení zařízení k departmentu, „samno” změní číslo SAM modulu, „cashno“ změní číslo
pokladny, “premise” změní provozovnu provozovatele, kterému patří dané zařízení (povinná
položka)

date – kdy se aktivace/deaktivace má provést. Povinná pro actdeact = „act“ nebo actdeact = „deact“
nebo actdeact = „deact_ever“, jinak se ignoruje.

note – nová poznámka k zařízení. Povinný pro actdeact = „note“, jinak se ignoruje.
where – místo, kde je zařízení umístěno. Povinný pro actdeact = „where“, jinak se ignoruje.
subprovider - umožňuje změnit přiřazení zařízení k departmentu, jehož kód je v atributu zadán.

Povinný pro actdeact = „subprovider“, jinak se ignoruje.
samno - umožňuje změnit číslo SAM modulu. Povinný pro actdeact = „samno“, jinak se ignoruje.
cashno - umožňuje změnit číslo pokladny. Povinný pro actdeact = „cashno“, jinak se ignoruje.
premise - umožňuje změnit provozovnu provozovatele, kterému patří dané zařízení. Povinný pro

actdeact = „premise“, jinak se ignoruje.

Jako odpověď CC zasílá seznam zařízení s úspěšností, s jakou byly aktivovány nebo deaktivovány a
důvod proč se operace nezdařila.

actdeact_device_ret
1

3
cz

cardsno – dekadické číslo zařízení (povinná položka)

24
actdeact - typ provedené operace - „act“, „deact“, „deact_ever“, „note“, „where“, „subprovider“,
„samno”, „cashno“, “premise”.
stat – status operace – definuje úspěšnost operace. V případě úspěchu má hodnotu IS_OK (povinná

položka)
reason – obsahuje textový důvod neprovedení operace (povinná položka)

25
Transakce na zařízení

Systém transakcí nebude používat odpočty, transakce bude identifikována číslem transakce, které je
unikátní v rámci zařízení. Každé aktivované zařízení musí zaslat seznam transakcí za každý den i
v případě, že na něm žádná transakce neproběhla nebo v případě, že zařízení není provozováno,
postačí zaslat alespoň jednou k poslednímu dni v měsíci, a to do termínu dle Smlouvy o dělbě tržeb.

Nebude-li zařízení delší dobu používáno, např. u záložních zařízení, je možno jej zablokovat (viz
kapitola Zablokování a odblokování zařízení. Je-li zařízení zablokováno, nejsou z něj, od doby
zablokování, na Clearing zasílány transakce.

Nezašle-li dopravce veškeré, transakce za daný měsíc za všechny strojky (včetně prázdných
transakcí k poslednímu dni v měsíci, pokud aktivované strojky nebyly v provozu), potvrdí KODISu
úplnost zaslaných transakcí e-mailem do termínu stanoveného pro zasílání transakcí platnou
smlouvou o dělbě tržeb, pak bude provedeno rozúčtování transakcí tak, jako by byly úplné. Pokud
bude rozúčtování již provedeno, není možno již žádné zpětné zaslání transakcí.

Je-li známo, že některá data nebude možno vyčíst, dopravce sdělí tuto skutečnost KODISu mailem
do termínu stanoveného pro zasílání transakcí platnou smlouvou o dělbě tržeb.

Storno transakcí je řešeno na zařízení, pokud zařízení již odešle transakci na clearing, transakce je
zaúčtována. Stornování se provádí přes reklamace a storno viz Reklamace.

Název zasílaného souboru je doporučen následovně:

T1267275_110429_00763.xml
XXXXXXX_RRMMDD_ZZZZZ

Kde:

XXXXXXX – výrobní číslo terminálu
RRMMDD – rok, měsíc a den otevření odpočtu
ZZZZZ – číslo počátečního lístku, pořadové číslo transakce v rámci terminálu

Pomocí tohoto XML se do systému vkládají transakce.

...

U transakcí se nesmí číslo transakce v atributu tx-id v rámci jednoho zařízení otočit dříve než
nastane hodnota definovaná při aktivací zařízení u atributu max_counter. Pokud je potřeba otočit
číslo dříve než nastane hodnota definovaná u zařízení je potřeba, informovat CC o změně řady
speciální transakcí (type=“devcounter“).

26
Element obsahuje atributy:

device-id – číslo zařízení (jedinečné v rámci dopravce) v desítkové soustavě od 0 do 999999999999
(povinná položka)

samno – Číslo SAM modulu (Security Access Module), jedinečné v rámci kraje, v desítkové
soustavě (povinná položka, kromě případu kde není dostupná čtečka karet - prodej
papírových jízdenek/kupónů)

cashno – Číslo pokladny (jedinečné v rámci dopravce) v desítkové soustavě (integer) (nepovinná
položka)

paycount – Celkový počet následujících vybíjecích (debetních) transakcí na daném zařízení -
hodnota v EP se touto transakcí snižuje (povinná položka)

depozitcount – Celkový počet následujících dobíjecích (kreditních) transakcí na daném zařízení -
hodnota v EP se touto transakcí zvyšuje (povinná položka)

sumcount – Celkový počet následujících transakcí v řádcích. Kontroluje se při příjmu transakcí
(povinná položka)

vat – Sazba daně z přidané hodnoty DPH v procentech [%] na daném zařízení platná pro následující
transakce, pokud se neurčí jiná sazba DPH u jednotlivé samotné transakce (povinná
položka)

premise - Číslo provozovny dopravce, do které náleží dané zařízení (maximálně 20
alfanumerických znaků) (nepovinná položka)

Element obsahuje atributy:

tx-id – Pořadové číslo transakce na zařízení (v desítkové soustavě). Pokud je atribut
type=“devcounter“, potom hodnota tx-id musí obsahovat hodnotu počítadla transakcí po
předčasném přerušení číselné řady - předčasném „přetočení“ počítadla transakcí (povinná
položka) Existuje výjimka, kdy číslo transakce muže být stejné a nejedná se o multi
transakci – jde o stornování následující transakce pro ČD - viz příklad 26. V případě použití
transakce typu „odp“ se transakčí řada nepřerušuje, ale pokračuje dále aby byla zachována
posloupnost (tx-id odp transakce = poslední tx-id + 1).

card-id – Výrobní číslo čipu karty (v šestnáctkové soustavě) přidělené výrobcem čipu karty
(jednoznačné pro všechny karty na světě) (povinná položka pro práci s kartou)

appl-id - Číslo aplikace (AID) na kartě v desítkové soustavě (pro aplikaci jízdenka je „4609“ a pro
aplikaci EP je „34965“). Současně obsahuje také typ karty (povinná položka pro práci s
kartou)

type - Typ operace. Hodnota (částka – atribut amount) transakce je vždy kladná. Typ operace pak
rozlišuje, zda se jedná o kreditní nebo debetní operaci. Kreditní operace hodnotu v
elektronické peněžence EP zvýšila a debetní operace hodnotu v EP snížila. Typ operace
„dep“ představuje kreditní operaci, „pay“ debetní operaci a „devcounter“ se používá v
případě, jestliže dojde ke změně číselné řady na daném zařízení dříve, než dojde k jeho
přirozenému přetečení, potom je nutno zaslat transakci s typem transakce devcounter, který

27
oznamuje, že číselná řada transakcí začíná znovu (první hodnota řady je 1.) a v položce tx-id
je uvedeno nové počáteční číslo transakce. Typ operace „odp“ udáví informační transakci,
že zařízení nezaslalo žádné transakce. Toto je nutné pro kontrolu doručených transakcí za
daný den. (povinná položka)

amount-type – Způsob platby: definuje způsob platby (v hotovosti, elektronickou peněženkou EP,
bankovní platební kartou, atd.). Konstanta „cash“ definuje hotovostní platbu, kdy se
nepracuje z EP, „ep“ platbu elektronickou peněženkou nebo práce s elektronickou
peněženkou (při nabíjení hotovostí zde bude „ep“), “card“ platbu bankovní platební kartou,
"bank" platbu převodem, „prepaid“ použito v případě že probíhá jízda na časový kupón,
„ep-cash“ – vracení části peněz z EP, „move“ – slouží k identifikaci vybití peněženky na
staré kartě nebo na nabití při převodu peněz ze staré karty. Pro transakce zasílané ze strojků
do CC MSK provedené nad kupónem na základě green-listu se používá hodnota “eshop”
(povinná položka).

transtype – Typ transakce definuje, co která transakce představuje. „Například: jízda v MHD, nákup
jízdenky na MHD, parkování, parkování u obchodního domu v Ostravě, atd. Univerzální typ
(jiný) je „uni“. „mhd“ je jakákoliv jízda (check-in / check-out), „mhdp“ nákup časové
jízdenky, „park“ parkování, „parkobos“ parkování u obchodního domu v Ostravě,
„mhdpr“ – reklamace kuponu, „mhdr“ – reklamace jízdy nebo ZS. V případě transakcí
prováděných s kartami, které nepatří do CCMSK a je s nimi prováděna operace na
zařízeních kdy dochází k změně čísla transakce na zařízení, musí být odesílána vyrovnávací
transakce, pak transtype obsahuje „outside-odis“. Jako označení stornování transakce se
uvádí v tomto tagu hodnota „cancel“.
Pro případ zasílání jen nákupu kilometrické jízdenky se zde uvádí „mhdtb“ (ticket buy) –
pro označení nákupu a ne jízdy. Musí však platit, že pak samotná jízda musí zasílat stále
všechny požadované informace jako cenu, zs, atd.
Pro žádosti z e-shopu se používají hodnoty “eshop-ep” pro dobití EP a “eshop-c” pro dobití
kupónu, „eshop-epr“ pro reklamaci dobití EP.
Pro nedokončené transakce se používá hodnota „incomplete“.
Pro přiložení bankovní karty (tapnutí) k terminálu se používá hodnota „tap“.(povinná
položka)

jumboaccount – Příznak u transakcí pracujících s JUMBO účtem (podobně jako u peněženky EPIK
na In-kartě Českých drah). V případě hodnoty “yes” se pracuje s JUMBO účtem a v případě
hodnoty „no“ se pak s JUMBO účtem nepracuje (nepovinná položka)

when – datum a čas vzniku transakce (povinná položka)

baseamount – Ceníková základní hodnota (částka) transakce před slevami (nepovinná položka)

amount – Skutečná hrazená hodnota (částka) transakce odečtená z EP nebo v hotovosti nebo
platební kartou po všech slevách s DPH. Pouze pokud je Typ operace type „pay“ nebo
„dep“. Při „“devcounter“ se je „0“. Při jízdě na časový lístek je „0“ povinná položka pokud
type je „pay“, „dep“ nebo „devcounter“.

currency – Peněžní měna, ve které byla provedena transakce (pokud není uvedena, je automaticky
měnou Kč - standardní hodnota pro Kč je „CZK“) (nepovinná položka)

vat – Sazba daně z přidané hodnoty DPH v procentech [%] v případech, kdy se sazba DPH liší od
společné daně DPH na zařízení uvedené v hlavičce transakcí (povinná položka pro
předplacenou jízdu na kupón – uvádí se hodnota DPH 0)

28
balance_before – Zůstatek (hodnota) v elektronické peněžence EP před provedením transakce s EP
(povinná položka v případě práce s EP)

balance_after – Zůstatek (hodnota) v elektronické peněžence EP po provedení transakce s EP
(povinná položka v případě práce s EP)

departure-id – Jako první je uvedeno číslo nástupní zastávky podle CIS JŘ a jako druhé je uvedeno
tarifní číslo nástupní zastávky, čísla jsou oddělená středníkem. (Povinná položka v případě
transakce související s nástupem do vozidla)

departure-zone – Číslo tarifní zóny nástupní zastávky (Povinná položka v případě transakce
související s nástupem do vozidla)

arrival-id – Jako první je uvedeno číslo výstupní zastávky podle CIS JŘ a jako druhé je uvedeno
tarifní číslo výstupní zastávky, čísla jsou oddělená středníkem (Povinná položka v případě
transakce související s výstupem z vozidla)

arrival-zone – Číslo tarifní zóny výstupní zastávky (check-out). Při odbavení jednorázové jízdenky
(check-in), kde cestující hlásí dopředu výstupní zastávku, bude uvedena zóna této výstupní
zastávky. V ostatních případech bude uvedena zóna poslední zastávky daného spoje. Při
odbavení kupónu, kde cestující hlásí dopředu výstupní zastávku, bude uvedena zóna této
výstupní zastávky, v ostatních případech bude uvedena nepovinně zóna poslední zastávky
daného spoje. (Povinná položka v případě transakce související s výstupem a nástupem
z/do vozidla)

zone – Seznam tarifních zón, pro které platí zakoupený časový kupón na kartě (pouze pro transakce
s hodnotou atributu transtype = “mhdp“). Zóny jsou odděleny středníkem. Lze uvést
maximálně deset zón (Povinná položka v případě práce s kupóny). Pro síťovou jízdenku se
zde uvádí číslo 352.

Od 2. 7. 2017 změna zóny 354 na 78.

line – Číslo linky podle CIS JŘ, na kterou je provedena transakce (Povinná položka v případě
transakce související s jízdou)

V případě prodeje kúponů se v čísle linky zasílá číslo prodejního místa.

Druh Číslo Možná

MHD Nový Jičín Dopravce a provozovna provozovny předprodej
Technické služby města Nového Jičína,
PAD příspěvková organizace 804 804xxx
PAD ARRIVA MORAVA a.s., provozovna Bruntál
MHD Bruntál Osoblažská dopravní společnost s.r.o. 850 850xxx
MHD Krnov ARRIVA MORAVA a.s.
PAD ARRIVA MORAVA a.s. 851 851xxx
PAD ČSAD Frýdek-Místek a.s.
PAD ARRIVA MORAVA a.s., provozovna Třinec 855 855xxx
MHD Frýdek- ČSAD Vsetín, provozovna Jablunkov
Místek 856 856xxx
MHD Třinec ČSAD Frýdek-Místek a.s.
PAD ARRIVA MORAVA a.s. 860 860xxx
PAD ČSAD Karviná a.s.
ČSAD Havířov a.s., provozovna Český Těšín 861 861xxx

862 862xxx

865 865xxx

866 866xxx

870 870xxx

871 871xxx

29
PAD ČSAD Havířov a.s., provozovna Havířov 872 872xxx

MHD Český Těšín ARRIVA MORAVA a.s. 875 875xxx

MHD Havířov ČSAD Havířov a.s. 876 876xxx

MHD Karviná ČSAD Karviná a.s. 877 877xxx

MHD Orlová ČSAD Karviná a.s. 878 878xxx

PAD ARRIVA MORAVA a.s., provozovna Nový Jičín 880 880xxx

MHD Studénka ARRIVA MORAVA a.s. 885 885xxx

PAD ARRIVA MORAVA a.s., provozovna Olomouc 890 890xxx

PAD TQM-holding s.r.o. 900 900xxx

MHD Opava Městský dopravní podnik Opava, a.s. 905 905xxx

PAD ARRIVA MORAVA a.s., provozovna Ostrava 910 910xxx

MHD Ostrava Dopravní podnik Ostrava a.s. 915 915xxx

PAD ARRIVA MORAVA a.s., provozovna Přerov 920 920xxx

PAD ARRIVA MORAVA a.s., provozovna Šumperk 930 930xxx

PAD ČSAD Vsetín, provozovna Vsetín 940 940xxx

PAD ARRIVA MORAVA a.s., provozovna Jeseník 950 950xxx

GW Train Regio 998

České dráhy 999

Aktuální ke dni 2. 11. 2016.

Prodej kupónu bude nejprve přidělen dopravci, který ho prodal. Následně pokud má
dopravce několik provozoven, bude prodej pod konkrétní provozovnu přidělen na základě
prvního trojčíslí uvedené linky v transakci dle číselníku.

Pokud bude chtít dopravce, aby zakoupené časové kupóny na přepážce (popřípadě i e-shop)
spadaly pod konkrétní provozovnu, bude muset upravit prodejní SW tak, aby prodeje byly
zasílány v transakci s číslem linky, která by identifikovala provozovnu i přepážku v rámci
provozovny. Číslování linky obsahuje v prvých 3 číslicích číslo provozovny a čísla přepážek
budou číslovány od 999 sestupně (998, 997 atd.).

Označení pro vlaky (jedná se o dopravce ČD a GWTR). Vlaky posílají v transakci pouze
číslo vlaku, číslo spoje nikoliv. Toto číslo je maximálně 5místné na rozdíl od autobusů (ty
mají vždy 6míst).

sequence – Číslo spoje podle CIS JŘ, na kterou je provedena transakce (Povinná položka v případě
transakce související s jízdou)

tariff – Atribut určuje platnost jízdenky - vyjádřeno dle číselníku KODIS položkou TP – Tarif
Profile): (Povinná položka v případě transakce obsahující tarif)

Kombinace vychází z číselníku tarifů, který je dostupný v samostatném dokumentu. Při
zaslání transakce s kombinací tarifu, která není v číselníku, nebude transakce zpracována
v rámci dělby tržeb.

tariff-type – Typ jízdenky určuje druh jízdenky - vyjádřeno „JD“ - jednotlivá, „PP“ - předplatní,
„PS“ - přestupní, „NP“ - nepřestupní, atd. Hodnota NP se používá pouze pro označení
elektronické nepřestupní jízdenky z ceníku pro jednotlivé jízdné Ostrava XXL s kartou
ODISka zasílané v jedné transakci, neplatí pro dvě transakce. (Povinná položka v případě
transakce obsahující tarif.)

in-zone – Tarifní oblast v rámci jednorázového jízdného (včetně jízdy při přestupu): Ostrava,
Opava, Region, atd. (Nepovinná položka, lze použít v případě transakce související s jízdou)

30
base-rate – Atribut říká, zda byla použita základní sazba (obdoba platby při nástupu do TAXI).
První jednotlivé jízdné bude se základní sazbou, další přestupní jízdné bude bez základní
sazby. První jednotlivé jízdné bude se základní sazbou „zs“, další přestupní jízdné bude bez
základní sazby „0“ (Povinná položka v případě transakce související s jízdou)

person-type – Typ osoby - vyjádřeno dle číselníku KODIS položkou CP – Customer Profile anebo
jako multilístek s označením 99. (Povinná položka v případě transakce obsahující tarif)

valid-from – platnost jízdenky od. (Povinná položka v případě transakce obsahující časový tarif)

valid-to – platnost jízdenky do. (Povinná položka v případě transakce obsahující časový tarif)

km_count – počet kilometrů u kilometrické jízdenky (Povinná položka v případě transakce
obsahující kilometrický tarif)

zones – Čísla uznaných zón, kterými cestující na zakoupenou jízdenku projede a které jsou zároveň
platné pro aktuálně zakoupené kupóny (pouze pro transakce s hodnotou atributu transtype
jinou, než “mhdp“). Obsahuje maximálně 10 zón oddělených středníkem.

Vyplňuje se také při odbavení jednotlivé jízdenky MHD (pro danou oblast MĚSTO), kde
cestující hlásí dopředu výstupní zastávku, budou uvedeny zóny daného spoje mezi nástupní
a výstupní zastávkou. V ostatních případech, budou uvedeny zóny do poslední zastávky
daného spoje. (Povinná položka v případě transakce související s jízdou)

Pro jednotlivé jízdenky kilometrické se nevyplňuje.

Od 2. 7. 2017 změna zóny 354 na 78.

chech-in – Čas nástupu do vozidla (Neovinná položka, lze použít v případě transakce související s
jízdou při použití čipové karty)

check-out – Čas výstupu z vozidla (neovinná položka, lze použít v případě transakce související s
jízdou při použití čipové karty pro nákup jednotlivého regionálního jízdného a při využití
zkráceného městského jízdného)

check-km – počet projetých kilometrů v rámci „check-in“ a „check-out“ (nepovinná položka)

transtypetext – Popisem transakce je například: Parkovací místo u ZOO - uvádí se pouze, pokud je
hodnota atributu transtype „uni“ (nepovinná položka)

loyalty – Počet získaných věrnostních bodů za transakci (nepovinná položka)

note – Poznámka k transakci (nepovinná položka, vhodné použít pro reklamace, storna, převody
kuponu atd.). Uvádí se zde například informace o přesunu kuponu s číslem karty, nebo
pokud se jedná o storno transakci z určitého důvodu ap. Tuto informaci zákazník vidí na
výpisu transakcí. Při zpracování není brán zřetel na obsah.

31
tranret – Vrací se zpět v rámci potvrzení jednotlivých transakcí. Slouží k jednoznačné identifikaci
transakce v rámci clearingové operace (nepovinná položka)

serviceid – jednoznačný identifikátor transakce/služby, používá se pro koupi předem definovaných
služeb (nepovinná položka)

eshop-tr-id – jednoznačné číslo transakce vygenerované na straně CC. Povinné pro dobití EP nebo
kupónu přes e-shop a také pro transakce ze strojků, které byly provedeny na základě
transakcí z green-listu EP/kuponu.

passengers-count – položka informující, že se jedná o hromadnou jízdenku, kde je více cestujících
započítaných v jedné ceně (povinné v případě pořízení kuponu přes eshop –
transtype=eshop-c). V případě pořízení kupónu přes e-shop je passengers-count=“1“. Na e-
shopu není možné nahrát jeden kupón pro více držitelů karet. (Pro dokupované jizdenky
DPO, které se zapisují do benefitu bude uváděn passenger-count dle skutečnosti.)

tiket-id – jedná se o číslo jízdenky (nepovinná položka pro dopravce kteří mají stejné číslo jízdenky
a číslo transakce). Existují totiž dopravci, kteří nemají stejné číslování jízdenky a číslo
transakce a pak by nebylo možno s takovou transakcí jednoduše pracovat. Tiket-id se týká
vytištěné jízdenky, v případě např. check-out transakce nebude vydávána (nebude tištěna).

Tagy pro multitransakce.
U všech multi transakcí je uvedeno stejné číslo transakce s tím, že musí být povinně uvedeny dva

tagy multi-index a multi-sum.

multi-index – jedná se o index multitransakce (v rámci jedné multi-transakce musí být unikátní)

multi-sum – jedná se o počet multi transakcí v jedné multitransakci. Nutné pro kontrolu dodaných
transakcí.

Další tagy se používají jen pro případy reklamací jízdy, zs, karty, kuponu atd.

card-kodis-id – Číslo karty v systému ODIS (v desítkové soustavě - 20 cifer).(Povinná položka u
reklamací pro převod EP/tarifu a nebo vyplacení peněz z EP pro ztracenou či vadnou kartu)

reclamation-provider – kód dopravce, který vlastní zařízení na kterém došlo k chybě (povinná
položka pro reklamace spojené s reklamování ZS a jízdy).

reclamation-device – číslo zařízení, kde byla reklamovaná transakce provedena. (povinná položka
v případě reklamace jízdy a ZS)

reclamation – Číslo reklamované transakce pod, kterou byla v systému CCMSK vedena (číslo lístku
dle našich informací – uvádějte jako celé číslo), jedná se o povinnou položku v případě
reklamace (pro případy reklamace ve vozidle, reklamace karty, reklamace vrácení poměrné
části kuponu je hodnota tohoto tagu je 0.

supplementary-date – jedná se o datum, kdy byla transakce provedena. Povinné pro některé typy
reklamací.

reclamation-multi-index – jedná se o číslo multi-indexu pro reklamování multi transakce.

32
Tagy pro práci s bankovní kartou:

card-emv-token – číslo tokenu bankovní karty

card-emv-block-noticed – identifikátor stavu, zda cestující obdržel informaci o umístnění bankovní
karty na denylist (0 = karta není na denylistu, tzn. cestující informaci neobdržel; 1 = karta je
na denylistu, tzn. cestující informaci obdržel)

card-emv-taplist-number – pořadové číslo taplistu v rámci vozidla

card-emv-vehicle-number – identifikátor vozidla

Jako odpověď CC zasílá XML obsahující potvrzení jednotlivých transakcí

transaction_ret
1

n
cz

…

device-id – dekadické číslo zařízení, na kterém byla transakce provedena (povinná položka)
card-id – číslo karty v hexadecimálním formátu (povinná položka)
appl-id – dekadické číslo aplikace na kartě (povinná položka)
date – datum a čas provedení transakce (povinná položka)
tx-id – číslo transakce na daném zařízení (povinná položka)
eshop-tr-id – číslo transakce na e-shopu (povinná položka pouze v případě transakce z e-shopu se
žádostí na dobití časového kupónu/EP)
tranret – obsahuje hodnotu z došlé transakce u atributu tranret (povinná položka)
stat – status operace – definuje úspěšnost operace. V případě úspěchu má hodnotu IS_OK (povinná

položka), v případě neúspěchu a neuložení transakce v CC je vráceno k dané transakci
IS_ERROR. Pokud dojde k nějakým problémům s přijímanou transakcí, a to z důvodu, že
některé parametry jsou podezřele zadány nebo zde chybí, je uvedeno IS_WARNING, což
znamená, že transakce je přijata, ale je zařazena mezi podezřelé transakce.
Reason – obsahuje textový důvod neprovedení operace (povinná položka). Jejich seznam najdete
v dodatku číslo 1 na konci tohoto dokumentu.

33
Podezřelé transakce
Podezřelé transakce jsou transakce, které byly do CC přijaty, ale z technických či logických důvodů
jsou označeny jako vadné (neexistující karta, chybějící číslo zóny u předplatní atd.). Zobrazují se ve
výpisu podezřelých transakcí a je možno zjistit, jaká chyba byla u příjmu zjištěna a lze je také uznat
za korektní. Je třeba však brát na zřetel, že kontrola zobrazuje jen první chybu, kterou nalezne, a
tudíž operátor musí kontrolovat celou transakci. Po jejím uznání bude transakce zavedena do CC
jako korektní a bude zaúčtována jako běžná transakce.

34
Zasílání transakcí ODIS/neODIS pro ODIS/neODIS karty ze zařízení ODIS
Při odbavování cestujících na strojcích ODIS nastávají jisté specifické situace při vydávání neODIS
jízdenek a také při práci s neODIS kartami. Zde je výčet možných situací, které popisují jak
v daném případě postupovat. NeODIS karta - je karta dopravce nepatřící do ODIS sytému karet.
Tyto karty nejsou a nebudou zaváděný do CCMSK. NeODIS jízdenky které je možno prodávat na
zařízeních ODIS jsou jízdenky konkrétního dopravce nepatřící do systému ODIS.

Zde jsou možné případy:
1. Jízdenka "neODIS" hrazená v hotovosti.
Tyto transakce se do CCMSK nezapisují. Provede se jen zaslání vyrovnávací transakce a tedy
pohyb počítadla zařízení:

2. Jízdenka "neODIS" hrazená kartou ODISKa a transakce hrazené kartou ODISka, které nemají
být zahrnuty do dělby tržeb.
Tyto transakce se do CCMSK zapisují jen z pohledu pohybu EP na kartě. Provede se jen zaslání
vyrovnávací transakce společně s informací o pohybu na EP:

3. Jízdenka "neODIS" hrazená kartou neODIS.
Tyto transakce se do CCMSK nezapisují. Provede se jen zaslání vyrovnávací transakce a tedy
pohyb počítadla zařízení:

4. Jízdenka "ODIS" hrazená v hotovosti.
Běžná situace popsaná ve větě KODIS:

5. Jízdenka "ODIS" hrazená kartou neODIS.
Platba v hotovosti:

35
Zasílání transakce jako potvrzení, že za daný den zařízení dodalo seznam
transakcí
V případě, že zařízení v daný den nevygenerovalo transakci a bylo aktivní, je třeba do systému
odeslat potvrzovací transakci tohoto stavu.
Její formát je:

36
Zasílání transakce jako MULTI-LÍSTEK do CCMSK.
Jen pro firmu Mikroelektronika je zaveden způsob příjmu multi-lístku ve větě KODIS následovně:
(multi-lístek je sloučení několika lístků do jedné transakce)

Multilístek
Příklad situaci multi lístku s více zákaznickými profily na jednom lístku (CP), a jednou jízdou
z A do B:

Multi-lístek bude mít v person-type uveden speciální nový typ 99, který označuje situaci
sloučení jízdenky (například pro cestujícího, dítě a zvíře, atp.).

Příklad multi-lístku (sloučení jednotlivé jízdenky s jízdenkou pro psa):

Příklad multi-lístku (sloučení jednotlivé jízdenky pro dospělé 3 cestující 3x52 Kč):

Dodatek:
 tariff-type v tomto typu multilístku musí být jen pro stejné jízdenky - jednotlivá,
předplatní a přestupní (JD, PP, PS). Sloučení není možné.

Multi lístek s přestupem.
Příklad pro situaci multi lístku s víc zákaznickými profily na jednom lístku (CP), jednou
jízdou z A do B a přestupní jízdenkou z B do C:

Příklad multi-lístku (více pasažérů s dvěmi linkospoji):
První transakce s prvním spojem na, který si v multi lístku zakoupil jízdenku:

Druhá transakce s druhým spojem na, který si v multi lístku zakoupil jízdenku (kde dochází
k přestupu):

Jízdenka s přestupem.

37
Příklad pro situaci jízdenky s jedním zákaznickým profilem na jednom lístku (CP), jednou
jízdou z A do B a přestupní jízdenkou z B do C:
Příklad jízdenky s přestupem (jeden pasažér s dvěmi linkospoji), jízda je prováděna v jednom
vozidle a nedochází k dalšímu odbavení cestujícího v místě přestupu.
První transakce s prvním spojem na, který si v multi lístku zakoupil jízdenku:

Pro balance-before a balance-after je zde v příkladu vidět specifická situace - zůstatky na EP jsou u
obou transakcí stejné (balance-before je hodnota před první operací a balance-after je hodnota po
druhé transakci). Je to z důvodu nemožnosti zasílat aktuální zůstaky ke každé multi transakci.
Ti dopravci, kteří umění tyto zůstatky zasílat je zasílají. Pro ty, kteří toto neumějí, musí být
v CCMSK nastaven u dopravce speciáln příznak.

38
Řešení neukončených nahrání e-shop transakcí na strojku
Dojde-li k odtržení karty v procesu zápisu e-shop transakce z greenlistu na kartu, může se stát, že
cestující má na kartě již zapsáno id transakce, které brání opětovnému dobití, protože stojky zapisují
dobíjecí transakci z greenlistu pouze pokud je na kartě nižší identifikátor transakce (bezpečnostní
opatření).

1) Ověří u jaké transakce z greenlisu bylo zapsáno číslo transakce, ale nebylo provedeno
samotné dobití.
To lze učinit zjištěním, které e-shop transakce byly na CC MSK zaslány a které zůstaly
na greenlistu.
Případně vyčtením čísla greenlistové transakce přímo z karty, pokud držitel neměl více
dobíjecích transakcí z e-shopu.

2) Zapíše si takto zjištěné číslo transakce z greenlistu, které bude potřebovat pro zaslání
transakce o zápisu dobití e-shop transakce na kartu na CC MSK.

3) Provede zápis dobití na kartu a do CC MSK zašle transakci informující o zápisu na
kartu, se stejnými parametry, jako by ji provedl strojek, jen číslo zařízení bude skutečné
číslo zařízení, ze kterého je reklamace řešena.

39
Blacklist karet

CC udržuje seznam zakázaných karet. Při odeslání následujícího XML se vrátí seznam zakázaných
karet. Je možné si vyžádat blacklist jen pro určitého dopravce pokud v elementu < blacklist > se
definují tito dopravci. Pokud nejsou uvedeni, tak se vrátí globální seznam zakázaných karet. Dále je
možné zažádat o rozšířený blacklist, tzn. nejen seznam karet aktuálně umístěných v blacklistu, ale
také karet, které v blacklistu již nejsou z důvodu vypršení platnosti a karet, které již v blacklistu
nejsou z důvodu sešrotování. Příklad XML souboru pro získání blacklistu karet.

blacklist
1

1
cz

DPO
1

provider – kód dopravce (nepovinná položka). V případě, že není uveden žádný kód dopravce, vrací
se blacklist pro všechny dopravce.
extend – rozšířený blacklist, hodnoty 0 nebo 1 v případě požadavku na rozšířený blacklist
(nepovinná položka)

Jako odpověď CC zasílá seznam zakázaných karet

blacklist_ret
1

3
cz

< blacklist_ret cardsno="000000001" cardKODIS="95456665235458"
date=“1.1.2007 14:30:00“ cardstate=“3“ />

40
cardsno – výrobní číslo karty v hexadecimálním tvaru (povinná položka)
cardKODIS – logické číslo karty (povinná položka)
date – datum zneplatnění karty (povinná položka)
provider – kód dopravce (povinná položka v případě globálního blacklistu)
cardstate – stav karty (povinná položka v případě rozšiřeného blacklistu)
Hodnota atributu cardstate může nabývat hodnot:

0: karta je na blacklistu
2: karta je na blacklistu trvale zablokovaná
3: karta je na blacklistu a je zešrotovaná
4: karta je na blacklistu a vypršela její platnost, ale není zešrotovaná

41
Denylist bankovních karet

CC udržuje seznam bankovních karet, které jsou odmítnuté vydavatelem pro použití ve veřejné
dopravě DPO. Nejde o “zakázané karty”, protože karty mohou fungovat mimo veřejnou dopravu.

V ostré verzi CC MSK je WS dostupná na:
http://clearing.kodis.cz/WebService/DataService.asmx
V testovací verzi CC MSK je WS dostupná na:
http://clearing.kodis.cz/WebServiceTest/DataService.asmx

Aktuální WSDL soubor je možné získat na výše uvedených adresách, přidání postfixu ?WSDL
k dané URL adrese.

Význam použitých datových položek

 CardEmvToken – EMV karetní token
 DenyListType – typ DenyListu

o FULL = plný
o INC = inkrememtální
 DenyList – Struktura DenyListu. Odpověď může obsahovat i několik
struktur DenyList za sebou, v případě že je požadováno stažení
inkrementálního seznamu nebo více vydaných seznamů najednou (rozsah
definovaný položkami SequenceNoStart a SequenceNoEnd).
o DenyListHeader – Hlavička DenyListu

 FileVersion – Verze struktury DenyListu
 IssueDateTime – Datum vydání DenyListu
 SequenceNo – Pořadové číslo DenyListu
 Type (viz položka DenyListType)
 ItemsCount – Počet záznamů na DenyListu
 Reset – Má-li tento příznak hodnotu true, pak došlo k resetu

DenyListu, tzn. všechny dřívější položky EMV karet na
seznamu byly vymazány (pokud tento DenyList obsahuje
nějaké položky, jedná se již o nové zánamy EMV karet na
seznamu). Reset Denylistu je obvykle prováděn jednou
denně na přelomu dne, kdy je z bankovního back office
stažen zvela nový plný DenyList, který je potřeba nově
nasadit na CC. Příznak je důležitý v případě požadavku na
stažení inkrementálního DenyListu, čímž je klient
informován, že byl nasazen zcela nový seznam odmítnutých
EMV karet (čímž došlo k narušení posloupnosti změn).
o DenyListItems – Seznam karet v DenyListu
 DenyListItem – Jedna položka DenyListu

 CardEmvToken – EMV karetní token
 OriginDateTime – Datum vzniku události
 BlockNoticed - příznak, že uživateli bylo už

zobrazeno, že má kartu na denylistu
 StateCode – Kód stavu EMV karty (pouze u

inkrementálního DenyListu)
o ADD = přidání karty na DenyList (blokace)
o DEL = odebrání karty z DenyListu
(odblokace)

42
o FileName – Jméno binárního souboru DenyListu
o Data – binární data souboru DenyListu

 Password – Uživatelské heslo provozovatele
 ResponseStatus – Struktura s výsledkem zpracování dotazu

o ErrorCode – Pokud je 0, vše je OK
o ErrorMessage – Text chyby
 SequenceNo – Pořadové číslo DenyListu
 SequenceNoStart – Počáteční pořadové číslo DenyListu
 SequenceNoEnd – Koncové pořadové číslo DenyListu
 UserLogin – Uživatelský login provozovatele


Zpracování odpovědí

Zpracování chyb
V jednotlivých XML odpovědích zde uvedených metod webové služby je vždy navrácen následující
element určující výsledek zpracování metody webové služby:

int
string

V tagu ResponseStatus se mohou objevit následující kombinace hodnot u elementu ErrorCode a

ErrorMessage:

0 „OK“

 -1 „Uživatelský účet nenalezen (chybný uživatelský login nebo heslo)“

 -2 „Uživatelský účet nemá přiděleno právo 'Online XML komunikace'“

 -3 „Nepodařilo se získat pořadové číslo posledně vydaného DenyListu“

 -4 „Chybná hodnota vstupního parametru DenyListType

(CardEmvDenylistBatchTypeCode)“

 -5 „Hodnota parametru SequenceNoStart nesmí být větší než hodnota parametru

SequenceNoEnd“

 -6 „Hodnoty parametrů SequenceNoStart a SequenceNoEnd musí být v rozsahu

<1;LastIssuedDenyListSequenceNo>“

 - 32768 chybový text výjimky

Zpracování vrácených dat
Pokud nedošlo k chybě a vrací-li daná metoda smysluplná data, obsahuje další element, který
následuje po elementu datovou část s odpovědí (liší se
podle typu volané metody webové služby).

43
Binární podoba DenyListu
DenyList je možné také stahovat v binární podobě.

Popis souboru: Popis
Název souboru Soubor stoplistu (upload)
ST.YYMMDDHHMISS YYMMDDHHMISS … je řídící hodnota
pro verzi stoplistu v terminálu. Stejná
hodnota je uvedena v hlavičce zdrojových
XML dat

Formát souboru:

Položka Délka Popis

ROWS_NUM 4B Udává celkový počet tokenů (záznamů) ve stoplistu

ROW_LEN 1B Délka jednoho záznamu. Do délky záznamu se počítá
max_len(TOKEN)+STATUS

TOKEN 33B Vlastní karetní token. Pozn: 33B je pro aktuálně používaný
formát tokenu.

STATUS 1B 0…. info N/A
1 …. Držitel karty byl informován o blokované kartě

Soubor stoplistu obsahuje neoddělená binární data (ne ASCII), kde jednotlivé tokeny jsou
vzestupně seřazeny. Položka STATUS do třízení nevstupuje.

Zdrojovým podkladem pro binární stoplist jsou XML data stoplistu.

Příklad:

000000022210CDF8F44E6C266C6B8FC8BF010370288CF2136B134E44CC22E26D79344C46D13E0110
DDF8F44E6C266C6B8FC8BF010370288CF2136B134E44CC22E26D79344C46D13E00

Metoda GetLastIssuedDenyListSequenceNo
Metoda vrátí pořadové číslo posledně vydaného plného DenyListu.

Požadavek:

POST /DataService.asmx HTTP/1.1
Host: localhost
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

string
string

Odpověď:

HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

int
string

int

Metoda GetDenyList
Metoda vrátí seznam karet na DenyListu

Požadavek:

POST /DataService.asmx HTTP/1.1
Host: localhost
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

string
string
FULL or INC
int
int

Odpověď:

HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

int
string

string
dateTime
int
FULL or INC
int
boolean

string
dateTime
boolean
ADD or DEL

string
dateTime
int
FULL or INC
int
boolean

string
dateTime
boolean
ADD or DEL

46
Metoda GetDenyListBinary
Metoda vrátí seznam karet na DenyListu v binární podobě

Požadavek:

POST /DataService.asmx HTTP/1.1
Host: localhost
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

string
string
FULL or INC
int
int

Odpověď:

HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

int
string

string
base64Binary

47
Green-list peněženky/kupónů

CC udržuje seznam dobití EP/kupónů, které je na fyzickou kartu teprve dohrát. Při odeslání
následujícího XML se vrátí seznam těchto transakcí. Je možné si vyžádat green-list jen pro určitého
dopravce a to tak že v elementu < greenlist > se definuje jejich seznam (oddělení čárkou). Pokud
nejsou uvedeni, tak se vrátí globální seznam transakcí. Seznam je navíc možno omezit datumovým
rozsahem. To zda se vrací dobití EP nebo kupónu se rozlišuje pomocí elementu .
Příklad XML souboru:

greenlist
1

1
cz

< greenlist>
EP
0,1
2012-06-01
2012-06-01

type – typ seznamu – EP=seznam pro EP, COUPON=seznam pro kupóny (povinná položka)
provider – kód(y) dopravce, pokud není specifikováno, vrací se seznam pro všechny dopravce
(nepovinná položka)
datefrom – počáteční datum rozsahu (nepovinná položka)
dateto – koncové datum rozsahu – (nepovinná položka)

Jako odpověď CC zasílá seznam transakcí pro:

a) dobití EP

greenlist_ret
1

3
cz

…

cardsno – výrobní číslo karty v hexadecimálním tvaru – max. 16 znaků (povinná položka)
card_kodis - identifikační číslo karty, řetězec o délce max. 20 znaků (povinná položka)
provider – kód subjektu (poskytovatele) karty – hodnota 0 až 200 (povinná položka)
contractsaleagent – pokladník, který nabíjel EP (nepovinná položka)
contractsaledevice – číslo prodejního místa (nepovinná položka)
amount – částka dobití EP – hodnota 0 až 4500 (povinná položka)
trno – identifikační číslo transakce (povinná položka)
tr_type – typ transakce, zdali se jedná o pěněženku nebo kupón – hodnota EP nebo COUPON
(povinná položka)
currency – měna – CZK=české koruny, bráno jako default není li hodnota specifikována (nepovinná
položka)

b) dobití kupónu

greenlist_ret
1

3
cz

…

cardsno – výrobní číslo karty v hexadecimálním tvaru – max. 16 znaků (povinná položka)
card_kodis - identifikační číslo karty, řetězec o délce max. 20 znaků (povinná položka)
provider – kód subjektu (poskytovatele) karty – hodnota 0 až 200 (povinná položka)
contractsaleagent – pokladník, který nabíjel EP (nepovinná položka)
contractsaledevice – číslo prodejního místa (nepovinná položka)
tp – tariff-profile kupónu (povinná položka)
cp – customer-profile kupónu (povinná položka)
zones – seznam zón oddělených čárkou (povinná položka)
validfrom – počátek platnosti kupónu (povinná položka)

49
validto – konec platnosti kupónu (povinná položka)
amount – Cena za kupón – hodnota 0 až 4500 (povinná položka)
passengers-count – počet cestujících – hodnota 0 až 60 (povinná položka)
trno – identifikační číslo transakce (povinná položka)
tr_type – typ transakce, zdali se jedná o pěněženku nebo kupón – hodnota EP nebo COUPON
(povinná položka)
currency – měna – CZK=české koruny, bráno jako default není li hodnota specifikována (nepovinná
položka)
contractjourneytype – typ trasy (povinná položka)

Mapování ostatních informací je pro přehlednost zobrazeno zde:

Položka CCMSK položky

ContractProvider Dobití kuponu Dobití EP
CouponType
ContractSaleAgent provider
ContractSaleDevice
ContractSaleSerialNumber tariff-type
ContractValidityStartDate
ContractValidityStartTime contractsaleagent contractsaleagent
ContractValidityEndDate
ContractValidityEndTime contractsaledevice contractsaledevice
ContractAmount trno
ContractTariffProfile
ContractCustomerProfile validfrom
ContractPrice
ContractJourneyZones validfrom
WalletPersProvider
WalletPersCreditTransaction validto
ContractHasJourney
validto
passengers-count
tp
cp

amount amount

zones provider
contractjourneytype trno

50
Inkarta

Stahování informace zda na ODIS kartě byla nahrána In Karta (Incard-list)
CC udržuje seznam karet, na kterých je nahrána In Karta, tzv. incard-list. Je možné si vyžádat
incard-list jen pro určitou kartu. Pokud není uvedena, vrátí se seznam všech karet, na kterých je
nahrána In Karta. Příklad XML souboru pro získání incard-listu.

incardlist
1

1
cz

000000009

cardsno – výrobní číslo karty v hexadecimálním tvaru (nepovinná položka)

Jako odpověď CC zasílá incard-list.

incardlist_ret
1

1
cz

cardsno – výrobní číslo karty v hexadecimálním tvaru (povinná položka)
incard – položka uvádí, zdali je na kartě nahrána In Karta - „1“, či nikoliv – „0“ (povinná
položka)

51
Další příklad XML souboru pro získání incard-listu.

incardlist
1

1
cz

Jako odpověď CC zasílá incard-list.

incardlist_ret
1

3
cz

cardsno – výrobní číslo karty v hexadecimálním tvaru (povinná položka)
incard – položka uvádí, zdali je na kartě nahrána In Karta - „1“, či nikoliv – „0“ (povinná
položka)

Zobrazení informace In Karty přes webové rozhraní CC
Pokud má cestující na své kartě nahranou In Kartu, zobrazí se mu položka In Karta v základních
informacích o kartě.

52
Vrácení informace o zůstatku EP na kartě
Stahování informace o aktuálním zůstatku na ODIS kartě. (WalletBalance)
Příklad XML souboru pro získání zůstatku na EP.

walletbalance
1

1
cz

920311106280024785

card_kodis – logické číslo karty (povinná položka)

Jako odpověď CC zasílá zůstatek na EP.

walletbalance_ret
1

1
cz

cardsno – výrobní číslo karty v hexadecimálním tvaru (povinná položka)
balance_after – aktuální zůstatek EP na kartě (povinná položka)
provider – číslo dopravce dle číselníku MSK (povinná položka)
valid_from – platnost karty od (povinná položka)
valid_to – platnost karty do (povinná položka)
card_state – stav karty, 1 = aktivní, 0 = neaktivní (povinná položka)

53
Vrácení kupónů na kartě
Stahování informace o kupónech na ODIS kartě. (TicketsInfo)
Příklad XML souboru pro získání kupónů.

ticketsinfo
1

1
cz

920311106280024785

card_kodis – logické číslo karty (povinná položka)

Jako odpověď CC zasílá kupóny.

ticketsinfo_ret
1

1
cz

54
Nestandardní situace, reklamace, storno a výměny karet
Stručný popis řešení nestandardních situací v systému s příklady výskytů a jejich řešení v rámci
systému.

Možné typy situací:
1. Reklamace přímo ve vozidle (při odbavování cestujícího).

2. Převod peněz nebo kupónu ze staré vadné nebo zablokované karty na novou.

3. Vyplacení částky z EP v hotovosti.
4. vrácení kupónu nevyužitého nebo využitého částečně
5. Reklamace na přepážce lísku/neoprávněného započítání základní sazby. Tento typ

reklamace se v systému provádí zadáním všech potřebných informací pro identifikaci, o
jakou transakcí se jednalo, viz dále. Tuto reklamaci může provést jen vydavatel karty a smí
tak reklamovat transakce provedené jen na svých vlastních zařízeních.
6. Reklamace na přepážce lísku/neoprávněného započítání základní sazby. Tento typ
reklamace se v systému provádí zadáním všech potřebných informací pro identifikaci, o
jakou transakcí se jednalo, viz dále. Tento typ reklamací se provádí v situacích, kdy je
sporná transakce provedena na zařízení jiného dopravce, než je vydavatel karty. Tyto
reklamace se zákazníkem vyřizuje dopravce ve spolupráci s vydavatelem.

Reklamace ve vozidle:

Storno v autobuse je možné pouze ihned při odbavení cestujícího, jinak není umožněna. Pak se
zasílají obě transakce, původní a stornovaná transakce (která musí být v transakční řadě následující
po stornované transakci). V takovém případě, se transakce nebude do zúčtovávání započítávat.

Stornovaná transakce má kromě stejných údajů jako transakce ještě příznak reclamation (s
hodnotou 0 nebo číslo transakce – dle typu). Takto zavedenou storno transakcí se označí transakce
jako storno a nebude se zahrnovat do celkového zúčtování. Pro transakce, kde se pracuje s EP a
dochází ke storno transakci, která mění stav EP, je nutné v balance-after a balance-before uvádět
aktuální stav EP, který je na kartě po storno operaci.

Příklad:
Transakce:

Storno poslední transakce:

Poznámka pro tento případ: Mezi transakcí a stornovanou transakcí (kde je reclamation=0) nesmí
být vložena žádné jiná transakce a čísla jejich transakcí musí jít chronologicky za sebou!
Je nutné také dodržet formátování a hodnoty parametrů v storno transakci, a to i when tedy čas
odeslání, vyjma situace operace s kartou, u těch je ve storno transakci nutno uvádět balance-after a
balance-before takové jaké jsou na kartě.

Storno transakce dle reclamation čísla (prioritně ČD):

Poznámka pro tento případ: Je nutné také dodržet formátování a hodnoty parametrů v storno
transakci a to i when tedy čas odeslání, vyjma situace operace s kartou, u těch je ve storno transakci
nutno uvádět balance-after a balance-before takové jaké jsou na kartě.
V tomto případě jde dokonce o situaci, kdy mezi prodejem a stornem došlo na kartě k pohybu -40
Kč.

Pro typy reklamací, které nedokáže rozhodnout dopravce sám, se používá webový formulář
na CCMSK.
Tyto reklamace se provádí na přepážce, která má přístup k CCMSK webu. Všechny reklamace
vyžadují, aby byla uživateli odebrána stvrzenka či karta, kterou reklamuje a uživatel nemohl
reklamaci opakovaně uplatnit jinde. Bude mu vytištěn doklad o provedené reklamaci.

Průběh této reklamace je následující: Dopravce, který řeší danou reklamaci v případě, že není
schopen řešit případ ve svém systému, zapíše tuto reklamaci do reklamačního formuláře na webu
CCMSK. Tento formulář bude mít následující položky:

Karta č: / Nová karta č: / Číslo zařízení: /Číslo transakce:
Typ reklamace

 Jízdného
 karty
Reklamace jízdného
 Kupón
 jednotlivé jízdné
 ZS
Reklamace karty
 Vracení části peněz z EP
 Výměna nové/ztracené/vadné karty
Popis reklamace či problému.
Popis vyřešení reklamace. (např. dohrán kupón, vrácena ZS atd.)

56
Zda je reklamace postoupena dopravci a identifikace kterému. Nebo zda byla předána KODISu.
Zápis provedl (číslo dopravce a označení přihlášené obsluhy).
Informace o stavu:

 Uzavřeno (možnost zadat číslo transakce, která situaci dořešila)
 Postoupeno (Komu)
Možnost Tisk účtenku.

Pokud reklamaci vyřeší přímo dopravce, u kterého k reklamaci došlo, bude reklamace uzavřena.

Pokud, ale reklamaci nemůže vyřídit, nebo nesouhlasí s reklamací, může postoupit reklamaci dál.
Podle situace je postoupena vydavateli karty a nebo KODISu, s výjimkou reklamace kuponu,
v takovém případě je nejprve postoupena prodejci kuponu. V případě, že tento dopravce nesouhlasí,
může být postoupena reklamace KODISu k rozhodnutí o sporné reklamaci mezi dopravci.

Celý systém reklamací funguje tak, že v případě vracení peněz cestujícímu z důvodu chyby jednoho
dopravce je mu tato částka stržena jako náhrada za chybu, kterou způsobil.

Převod peněz nebo kupónu z vadné nebo zablokované karty na novou
Pro tuto situaci se v transakční větě musí zadat v amount-type nový řetězec move, který identifikuje
pohyb peněz jen na jiné medium. U pohybu na EP transtype = uni a u kuponu transtype = mhdp.
Smí ji provádět jen dopravce, který je zároveň vydavatel karty.
Při zasílání těchto transakcí se nebere zřetel na to, zda je karta na blacklistu zablokovaná nebo
neplatná.

Příklad (převod peněz na novou kartu):
Vybití EP staré (vyměňované) karty

Vybití z EP ztracené/vadné karty

Zde není uvedeno card-id ani app-id. Pro tento případ se zde využije tag card-kodis-id je v něm pak
uvedeno logické číslo karty, ze které se vybíjí hodnota EP.

Nabití EP nové karty

Tato transakce o nabití není započítávána a jedná se jen o převod na novou kartu.

Převod kupónu na novou kartu:
Zrušení kuponu ze staré karty:

Zrušení kuponu ze ztracené/vadné karty:

Zde není card-id ani app-id v card-kodis-id je uvedeno číslo karty, ze které se převádí kupóny.
Kupón bude zneplatněn.

Nahrání kuponu na novou kartu:

Nejedná so o nákup nového kupónu.

Vyplacení částky z EP v hotovosti
Pro vyplacení části/všech peněz z EP se musí ve transakční větě zadat ep-cash, kdy se identifikuje,
že se jedná o výplatu peněz z EP. Transtype = uni

Příklad (vrácení hotovosti z karty):

Příklad (vrácení hotovosti ze ztracené karty):

Reklamace dlouhodobé časové jízdenky (kupónu)

Reklamace dlouhodobých časových jízdenek se pro účely zúčtování importují do BP a účtují se v
BP jako doposud, pro účely zobrazení cestujícímu na CC se bude zasílat storno transakce obsahující
datum platnosti kupónu, číslo karty a zóny, podle těchto údajů se dohledá původní transakce a
barevně označí, současně se zobrazí cestujícímu storno transakce obsahující datum a čas, místo atd.

Storno transakce časové jízdenky se v transakční větě označí v tagu transtype, kde se uvede
„mhdpr“. Tak bude jasně řečeno, že se jedná o reklamaci časové jízdenky. Spolu s tímto údajem
musí být vyplněny i ostatní informace o kupónu, jeho platnosti apod. obdobně jako při koupi
kupónu. V amount je uvedena vrácená částka zákazníkovi z části nebo celého kupónu podle situace.
Pokud kupón obsahuje více zón, musí být vrácen celý!

Příklad (Reklamace kupónu vrací poměrnou část):

V amount je poměrná část vráceného kuponu, v případě že je vyplácena nějaká pokuta nebo
manipulační poplatek, v amount musí být celá částka, která je zákazníkovi vrácena. Teprve
následně lze provést výběr z EP a nebo peníze za kupon vyplácet jen v hotovosti, zaplatit poplatek a
zbytek peněz pak nahrát na peněženku.

Reklamace jízdy nebo (ZS) na přepážce (pro vlastní transakce):
Pokud chyba vznikla na zařízení dopravce, u kterého je reklamace podána, a je zároveň vydavatel
karty, pak musí strojek odeslat na CCMSK transakci o vyřízení této reklamace.

Tato reklamace se označí tak, že se v transakční větě zašle v transtype „mhdr“ Reclamation
obsahuje číslo lístku (číslo reklamované transakce) a reclamation-device obsahuje číslo zařízení
reklamované transakce.

59
Tato reklamace se vždy vztahuje k uživateli s kartou.
V případě, že není schopen dopravce vydat doklad ve svém systému, vyplní formulář reklamací na
webu CCMSK.

Příklad (Reklamace jízdenky/zs):

Po odeslání této transakce na CCMSK je vydán lístek, kde je číslo lístku (transakce).
Tato transakce nebude do konečného zúčtování započítána.
Uživatel karty bude mít ve výpise jízd na webu CCMSK označenou konkrétní stornovanou
transakci, a uvidí tam také transakci, s vrácením peněz a datem kdy byla reklamace uplatněna.

V případě, že je pro řešení použit formulář reklamací na CCMSK, bude nové číslo lístku a číslo
strojku zapsáno společně do reklamačního formuláře pro potvrzení a ukončení této reklamace.

Reklamace jízdy nebo ZS na přepážce (pro transakce provedené na zařízení jiném než je
vydavatel karty):
Reklamace jízdy nebo ZS se vyřizuje vždy u dopravce, u kterého vznikla.
Pokud chyba nevznikla na zařízení vydavatele karty, pak dopravce, který vyřizuje reklamaci, vyplní
reklamační formulář na CCMSK a vznese dotaz na KODIS o potvrzení posloupnosti předchozích
jízd pro uznání nároku odečtení. Zákazník je odkázán na dořešení reklamace do 5ti dnů od podání
reklamace a je mu vytisknut doklad

Po dořešení reklamace se zákazníkem a po uznání nároku na odečet ZS odesílá do CCMSK ze
strojku transakce, kde v transtype se zadá „mhdr“. Dále v Reclamation se zadá číslo reklamovaného
lístku (číslo transakce), reclamation-device obsahuje číslo zařízení reklamované transakce a
reclamation-provider obsahuje kód dopravce.
Tato reklamace se vždy vztahuje k uživateli s kartou.

Příklad (Reklamace jízdenky/zs po schválení reklamace Kodisem – u vydavatele karty):

60
Reklamace/storno nákupu EP na eshopu

U řešení reklamací a storna nákupu EP (žádosti o dobití EP) na eshopu je důležité zohlednit, zdali
byl nákup již zahrnut do aktuálního měsíčního rozúčtování.

Reklamace nákupu EP na eshopu
Reklamace nákupu EP na eshopu se používá v případech, kdy nákup byl již zahrnut do aktuálního
měsíčního rozúčtování. Cestující následně přišel (např. v dalším měsíci) na přepážku reklamovat
nákup z důvodu nefunkčního nahrání zakoupeného EP na kartu apod.

Tyto transakce budou zahrnuty do měsíčního rozúčtování jako vratky a budou mít vliv na
vypočtený celkový zůstatek na kartách.

Příklad transakce nákup EP na eshopu (žádost o dobití EP):

Příklad reklamace nákupu EP na eshopu (žádosti o dobití EP):

Storno nákupu EP na eshopu
Storno nákupu EP na eshopu se používá v případech, kdy nákup nebyl zahrnut do aktuálního
měsíčního rozúčtování. Došlo k nesprávnému odeslání transakce z důvodu nefunkčního eshopu
apod.

Storno transakce nákupu EP na eshopu lze zasílat pouze ve stejném měsící, kdy byl proveden
nákup.

Tyto transakce nebudou zahrnuty do měsíčního rozúčtování.

Příklad transakce nákup EP na eshopu (žádost o dobití EP):

Příklad storna nákupu EP na eshopu (žádosti o dobití EP):

61
Posílaní souborů s pozdějším zpracováním

CC umožňuje přijímat jednotlivé XML a zip soubory dle specifikace věty KODIS tak, že nebudou
zpracovávány okamžitě, ale jen se přijmou a uloží pro pozdější zpracování. Při přijímání se
nekontroluje obsah zprávy.
Pro posílání příkazů s pozdějším zpracováním se postupuje stejně jako při posílaní příkazů
s okamžitým zpracováním. Data se neposílají na „clearing.kodis.cz/readdata.aspx“, ale na stránku
„clearing.kodis.cz/ReadDataButProcessLater.aspx“ metoda POST a parametry zůstaly stejné.
Odpovědí je informace zda došlo/nedošlo při příjmu k chybě v standardní hlavičce.
Po přijmutí dávky s pozdějším zpracováním se daná dávka objeví v seznamu dávek jako dávka
s pozdějším zpracováním. Zpracování provádí aplikace, která v daný okamžik (22:00 h) dávky
s pozdějším zpracováním zpracuje. Po zpracování se dávka zobrazí v seznamu stejně jako při
okamžitém zpracování.

Stažení souboru s odpovědí po zpracování

CC umožňuje stažení souboru s odpovědí po zpracování. Stažení je možno provést bud z stránky
s seznamem dávek, nebo přes stránku na adrese „clearing.kodis.cz/GetFile.aspx“ metodou POST.
V metodě POST jsou zasílány celkem 3 parametry name, passwd a filename. První dva obsahují
informace o Loginu a Heslu. Poslední parametr obsahuje název odeslaného souboru na zpracování.
Odpovědí je bud chybové XML nebo daný soubor. Pokud bylo posláno více souborů se stejným
názvem, vyhledá se ten poslední.

62
Příklady užití

1. Prodej jednotlivého regionálního jízdné (papírová kilometrická jízdenka) na papír, platba
v hotovosti ve vozidle s provedením jízdy

2. Prodej jednotlivého regionálního jízdné (papírová kilometrická jízdenka) na papír, platba
z EP ve vozidle s provedením jízdy

3. Prodej jednotlivého městského jízdné (papírová MHD jízdenka) na papír, platba v hotovosti

4. Prodej jednotlivého městského jízdné (papírová MHD jízdenka) na papír, platba z EP

5. Prodej jednotlivého regionálního jízdné (kilometrická jízdenka) na BČK, platba z EP ve
vozidle s provedením jízdy

6. Prodej jednotlivého městského jízdné (MHD jízdenka) na BČK, platba z EP

7. Jízda na el. jízdenku (uznání přestupu na MHD jízdenku)

63
8. Dobití EP

9. Dobití časového kupónu v hotovosti

10. Dobití časového kupónu z EP

11. Jízda na časový kupón

12. Storno jízdenky
Viz kapitola reklamace.

13. Prodej jednotlivého regionálního jízdné (kilometrická jízdenka) na BČK, platba z EP (jen
nákup) bez jízdy

14. MULTI-Transakce: Jízda na kupón z BČK + doplatek za km jízdné

15. MULTI-Transakce: Prodej dvou jednotlivých jízd na přípojové spoje regionálního jízdné
(kilometrická jízdenka) na BČK, platba z EP (V druhém případě se nejedná o jízdu ale jen o

64
nákup jízdenky a ve vozidle, kde jízda pokračuje, je třeba vygenerovat transakci jízdy (není
jisté, že daný pasažér tuto jízdu nastoupil).

Transakce ve vozidle kde jízda pokračuje, vypadá takto:

16. Prodej jednotlivého regionálního jízdné (kilometrická jízdenka) na BČK, platba v hotovosti
ve vozidle s provedením jízdy

17. Prodej papírového kupónu a platba v hotovosti

18. Pořízení žádosti na dobití EP přes e-shop bankovním převodem

Poznámka: jednoznačné ID e-shop transakce vygeneruje CC a vrátí ho v odpovědním XML
v atributu eshop-tr-id

19. Pořízení žádosti na dobití EP přes e-shop platební kartou

Poznámka: jednoznačné ID e-shop transakce vygeneruje CC a vrátí ho v odpovědním XML
v atributu eshop-r-id

20. Storno žádosti na dobití EP přes e-shop

65
21. Příklad reklamace nákupu EP na eshopu (žádosti o dobití EP)

22. Provedení fyzického dobití EP na základě transakce z green-listu

23. Pořízení žádosti na dobití časového kupónu přes e-shop bank. převodem

Poznámka: jednoznačné ID e-shop transakce vygeneruje CC a vrátí ho v odpovědním XML
v atributu eshop-tr-id

24. Pořízení žádosti na dobití časového kupónu přes e-shop bank. převodem

Poznámka: jednoznačné ID e-shop transakce vygeneruje CC a vrátí ho v odpovědním XML
v atributu eshop-tr-id

25. Storno žádosti na dobití časového kupónu přes e-shop

26. Provedení fyzického dobití časového kupónu na základě transakce z green-listu

27. Storno transakce speciálně pro ČD – jedná se o storno, při kterém je tx-id stejné jak pro
stornovanou tak pro stornující transakci. Musí však být dodrženo vyplnění transtype a
reclamation.

Transakce:

Storno transakce:

67
28. Storno jednotlivého regionálního jízdného (papírová kilometrická jízdenka) na papír, platba
v hotovosti ve vozidle s provedením jízdy

Storno transakce poslední:

Storno transakce dle reclamation čísla (prioritně ČD):

29. Příklad multi-lístku (sloučení jednotlivé jízdenky s jízdenkou pro psa):

30. Příklad multi-lístku (sloučení jednotlivé jízdenky pro dospělé 3 cestující 3x52 Kč):

68
31. Příklad zaslání nedokončené transakce (EM-test)

32. Příklad zaslání transakce „devcounter“

33. Prodej jízdenky Check-in, platba z EP v případě kde cestující hlásí dopředu výstupní
zastávku

34. Prodej jízdenky Check-in, platba z EP v případě kde cestující nehlásí dopředu výstupní
zastávku

35. Prodej jízdenky Check-out, vrácení na EP

36. Přiložení bankovní karty (tapnutí)

69
Příklady užití – rozšíření

Dlouhodobé jízdné
Pro dlouhodobé jízdné platí pravidla:

 tarif 1, 7, 30, 90, 180, 365 denní
 tarif 5 měsíční

Příklady transakcí dlouhodobého jízdného:

1. Prodej dlouhodobého jízdného na papír, placeno hotově (student 15-26, 90 denní, zóny 30 + 94 +
100 + 101)

2. Prodej dlouhodobého jízdného na EP, platba hotově (přenosný, 7 denní, zóny 1 + 2 + 3 + 12 + 15)

3. Jízda na zakoupené dlouhodobé jízdné (vozidlo projíždí zónami 1, 4, 12, 15, 17 – zakoupené
dlouhodobé jízdné platí pro zóny 1, 2, 3, 12, 15)

4. Prodej dlouhodobého jízdného na EP, platba z EP (dospělý 15+, 30 denní, zóny 1 + 4)

5. Jízda na zakoupené dlouhodobé jízdné (vozidlo projíždí zónami 1, 2, 3 – zakoupené dlouhodobé
jízdné platí pro zóny 1, 4)

70
Krátkodobé jízdné
Pro krátkodobé jízdné platí pravidla:

 prodej v zóně 354 (Ostrava XXL) a 352 (celá síť)
 tarif 10, 30, 45, 60, 90 minutová
 tarif 24 hodinová a 24 hodinová skupinová
 tarif 70 minutová SMS, 90 minutová SMS, 24 hodinová SMS
Pozn.: od 2. 7. 2017 změna zóny 354 na 78
Příklady transakcí krátkodobého jízdného:
1. Prodej krátkodobého jízdného na papír, placeno hotově, 10 minutová žákovská (5 Kč)

2. Prodej krátkodobého jízdného na papír, placeno hotově, 24 hodinová skupinová (200 Kč)

3. Prodej krátkodobého jízdného na papír, placeno hotově, 60 minutová obyčejná (26 Kč)

4. Prodej krátkodobého jízdného na papír, placeno hotově, 24 hodinová celosíťová obyčejná (200 Kč)

71
Jednotlivé jízdné
Pro jednotlivé jízdné platí pravidla:

 hodnota atributu „tariff“ bude „1“ (viz číselník tarifů)
 jízda v městských zónách – 5, 45, 60, 90, 100
 jízda v Ostrava XXL zóně – 354 (přestupní a nepřestupní elektronické jízdné)

Pozn.: od 2. 7. 2017 změna zóny 354 na 78

Příklady transakcí jednotlivého jízdného:

1. Papírová obyčejná, město Bruntál

2. Na ODIS kartu obyčejná, město Český Těšín (použité linky 875000 a 866000)

3. Elektronické jízdné přestupní mezi linkami 915000 a 910000 (20 Kč)

4. Elektronické jízdné nepřestupní zasílané ve dvou transakcích (14Kč)

5. Elektronické jízdné nepřestupní zasílané v jedné transakci (14Kč)

73
Kilometrické jízdné
Pro kilometrické jízdné platí pravidla:

 hodnota atributu „tariff“ bude „1“ (viz číselník tarifů)
 bez zóny
Příklady transakcí kilometrického jízdného:
1. Cestující jede linkou 900231 z Vítkov, aut.st. na zastávku Fulnek, žel.st. spojem 9 (na místě je 7:00),

tam přestoupí na spoj 12 linky 880613 (odjezd z Fulnek, žel.st. 7:03) a vystoupí na zastávce
Studénka, žel. st. Cena s ODISKOU 46 Kč (v prvním spoji zaplatí 29Kč, v druhém 17Kč).

2. Cestující jede z Třince, aut.st. do Těšína,aut.st. linkou 861761. Bez ODISky 20 Kč spojem 27.

3. Cestující jede bez ODISky spojem 7 linky 860765 ze zastávky Třinec, aut.st. na zastávku Frýdek-
Místek, Frýdek, aut. nádr. je tam 6:19 a přestoupí v 6:30 na spoj 2 linky 880621 a vystoupí na
zastávce Nový Jičín, aut. nádr. cena 84 Kč (v prvním spoji zaplatí 41 kč, v druhém 43 Kč).

74
Stažení transakcí z CC MSK pomocí webové služby.

Pomocí webové služby můžete ze serveru na KODISu stáhnou pro danou kartu v časovém intervalu
transakce provedené na kartě. Předání dat probíhá on-line, ihned po obdržení dotazu na server. Platí
zde však omezení, a to že všechny transakce může stahovat jen vydavatel karty. Pokud uživatel,
který se hlásí, není vydavatelem karty, stáhnou se jen jeho vlastní transakce.

K ostré verzi CC MSK je WS dostupná na: http://clearing.kodis.cz/WebService/DataService.asmx
K testovací verzi CC MSK je WS na: http://clearing.kodis.cz/WebServiceTest/DataService.asmx

Dostupné jsou dvě metody:

GetTransactionForCardNoHex() – na základě čísla čipu získáte transakce karty.
Parametry:
From - Datum a čas od.
To - Datum a čas do.
cardNoHex - Číslo čipu karty.
userLogin – Login oprávněného uživatele.
password – Heslo pro login.
Vrací string hodnotu ve formátu XML dle specifikace s odpovědí.

GetTransactionForCardNo() – na základě čísla ODIS karty (logické číslo karty) získáte transakce
karty.
Parametry:
From - Datum a čas od.
To - Datum a čas do.
cardNoKodis - Logické číslo karty.
userLogin – Login oprávněného uživatele.
password – Heslo pro login.
Vrací string hodnotu ve formátu XML dle specifikace s odpovědí.

Specifikace XML odpovědi:

Význam atributů je stejný jako u věty KODIS. Některé atributy o zařízení byly vynechány.

75
Seznam chybových hlášení:
2 -- nenalezen uživatel nebo špatné heslo
1 -- nenalezeno číslo čipu karty v DB

76
WSDL:

Pro GetTransactionForCardNoHex
SOAP 1.1
Následuje ukázkový požadavek a odpověď SOAP 1.1. Uvedené zástupce je třeba nahradit
skutečnými hodnotami.

POST /DataService.asmx HTTP/1.1
Host: localhost
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://tempuri.org/GetTransactionForCardNoHex"

dateTime
dateTime
string
string
string

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

string

SOAP 1.2
Následuje ukázkový požadavek a odpověď SOAP 1.2. Uvedené zástupce je třeba nahradit
skutečnými hodnotami.

POST /DataService.asmx HTTP/1.1
Host: localhost
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

dateTime
dateTime
string

77
string
string

HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

string

HTTP POST
Následuje ukázka požadavku a odpovědi HTTP POST. Uvedené zástupce je třeba nahradit
skutečnými hodnotami.

POST /DataService.asmx/GetTransactionForCardNoHex HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
Content-Length: length

from=string&to=string&cardNoHex=string&userLogin=string&password=string
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

string

Pro GetTransactionForCardNo
SOAP 1.1
The following is a sample SOAP 1.1 request and response. The placeholders shown need to be
replaced with actual values.

POST /WebService/DataService.asmx HTTP/1.1
Host: clearing.kodis.cz
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://tempuri.org/GetTransactionForCardNo"

dateTime
dateTime
string
string
string

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

string

SOAP 1.2
The following is a sample SOAP 1.2 request and response. The placeholders shown need to be
replaced with actual values.

POST /WebService/DataService.asmx HTTP/1.1
Host: clearing.kodis.cz
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

dateTime
dateTime
string
string
string

HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

string

79
Vygenerování hesla z CC MSK pomocí webové služby
Pomocí webové služby můžete ze serveru na KODISu vygenerovat a stáhnou heslo pro danou
kartu. Předání dat probíhá on-line, ihned po obdržení dotazu na server. Neplatí zde omezení, že
vygenerovat a stáhnout heslo může jen vydavatel karty. Dopravci mohou vygenerovat a stáhnout
heslo rovněž pro cizí karty.
Ostrá verze CC MSK bude WS na: https://clearing.kodis.cz/WebService/DataService.asmx
Testovací verze CC MSK bude WS na: https://clearing.kodis.cz/WebServiceTest/DataService.asmx
Dostupná je metoda:
GetUserPasswordByCardNo (cardNoKodis, userLogin, password) - Metoda pro vygenerování a
získání nového heska ke kartě a uživatelskému účtu karty.
Parametry:
cardNoKodis – Výrobní číslo čipu karty v hexadecimálním tvaru přidělené výrobcem
userLogin – Přihlašovací jméno dopravce
password – Přihlašovací heslo dopravce
Vrací string hodnotu s vygenerováným heslem v případě úspěchu, které splňuje následující
pravidla:

1. heslo je dlouhé minimálně 8 znaků
2. heslo obsahuje minimálně 1 číslici
3. heslo obsahuje minimálně 1 velké písmeno
4. heslo obsahuje minimálně 1 malé písmeno
V případě chyby metoda vrátí jeden z možných chybových stavů:
CHYBA: Dopravce nebyl identifikován dle přihlašovacího jména a hesla.
CHYBA: Karta nebyla nalezena.
CHYBA: Uživatel ke kartě nebyl nalezen.
CHYBA: Ukládání hesla do DB.

80
WSDL pro GetUserPasswordByCardNo

SOAP 1.1
Následuje ukázkový požadavek a odpověď SOAP 1.1. Uvedené zástupce je třeba nahradit
skutečnými hodnotami.

POST /DataService.asmx HTTP/1.1
Host: localhost
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://tempuri.org/GetUserPasswordByCardNo"

string
string
string

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

string

SOAP 1.2
Následuje ukázkový požadavek a odpověď SOAP 1.2. Uvedené zástupce je třeba nahradit
skutečnými hodnotami.

POST /DataService.asmx HTTP/1.1
Host: localhost
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

string
string
string

81
HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

string

HTTP POST
Následuje ukázka požadavku a odpovědi HTTP POST. Uvedené zástupce je třeba nahradit
skutečnými hodnotami.

POST /DataService.asmx/GetUserPasswordByCardNo HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
Content-Length: length
cardNoHex=string&userLogin=string&password=string
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

string

82
Stažení karet se změnami profilu z CC MSK pomocí webové služby

Pomocí webové služby lze stáhnout pro daného dopravce seznam vlastních karet, na kterých došlo
ke změně zákaznického profilu ve vybraném časovém intervalu. Předání dat probíhá on-line, ihned
po obdržení dotazu na server.

K ostré verzi CC MSK je WS dostupná na: http://clearing.kodis.cz/WebService/DataService.asmx
K testovací verzi CC MSK je WS na: http://clearing.kodis.cz/WebServiceTest/DataService.asmx

Dostupná je metoda:

GetProviderCardCp()

Parametry:
DateFrom - Datum a čas intervalu od
DateTo - Datum a čas intervalu do
UserLogin – Uživatelský login provozovatele
Password – Uživatelské heslo provozovatele

Vrací string hodnotu ve formátu XML dle specifikace s odpovědí.

Specifikace XML odpovědi:

…

Význam atributů:

cardsno – výrobní číslo karty v hexadecimálním tvaru (povinná položka)
type – typ profilu na kartě – „customerprofile“ = profil 1, „customerprofile2“ = profil 2
customerprofile – číslo profilu na kartě, v případě zrušení profilu na kartě se zasílá hodnota „0“
(povinná položka)
date-from – začátek intervalu platnosti profilu na kartě (povinná položka v případě existujícího
profilu a hodnoty začátek intervalu platnosti na kartě)
date-to – konec intervalu platnosti profilu na kartě (povinná položka v případě existujícího profilu a
hodnoty konce intervalu platnosti na kartě)
date – datum změny profilu na kartě u dopravce (povinná položka)
provider – dopravce, který provedl změnu profilu na kartě (povinná položka)

83
Stažení všech transakcí z CC MSK pro dopravce za měsíc.

Tuto funkci najdete v menu webového rozhraní Transakce/Export transakcí. Jednou za měsíc je
provedeno stažení všech transakcí daného dopravce. Na této stránce pak vidí své soubory a má je
stažení.

Soubory jsou uloženy v zip souboru. Formát xml souboru je uvede níže.

transactions
generateDate – Datum vytvoření tohoto sestavení.
countDevices – počet zařízení pro která jsou zde data.
status – Stav dokončení, OK je vše v pořádku, ERROR došlo k chybám při generování.
version – verze sestavení. Při změně sestavení se zda objeví vyšší číslo pro identifikaci formátu
sestavení.

device
id – číslo zařízení

transaction
tagy mají stejný název a význam jako ve větě KODIS kromě těchto tagů:

bad-type – obsahuje číslo chyby.
bad-confirm – obsahuje True/False. Určuje, zda byla vadná transakce uznána (True).

84
Stažení všech transakcí z CC MSK pro dopravce na vlastních kartách
provedených u jiného dopravce za měsíc.

Tuto funkci najdete v menu webového rozhraní Transakce/Export cizích transakcí. Jednou za měsíc
je provedeno stažení všech transakcí, které byly provedeny u jiných dopravců na kartách dopravce.
Na této stránce si můžete dané transakce stáhnout v jednom souboru.
Soubory jsou uloženy v zip souboru. Formát xml souboru je uvede níže.

transactions
generateDate – Datum vytvoření tohoto sestavení.
status – Stav dokončení, OK je vše v pořádku, ERROR došlo k chybám při generování.
countTransaction – celkový počet transakcí
version – verze sestavení. Při změně sestavení se zde objeví vyšší číslo pro identifikaci formátu
sestavení.
transaction
tagy mají stejný název a význam jako ve větě KODIS kromě těchto tagů:

bad-type – obsahuje číslo chyby.
bad-confirm – obsahuje True/False. Určuje, zda byla vadná transakce uznána (True).

85
Dodatek 1

Seznam a popis chybových hlášení z CCMSK při importu transakcí

102001, "Nesouhlasí počet vybíjecích operací u zařízení"
102002, "Nesouhlasí počty dobíjecích operací u zařízení",
102003, "Nesouhlasí suma operací u zařízení.",
102004, "Nezadáno číslo zařízení",
102005, "Neplatný formát hlavičky pro atribut 'Vat'",
102006, "Neplatný formát pro atribut 'samno'",
102007, "Neplatný formát pro atribut 'depozitcount'",
102008, "Neplatný formát pro atribut 'paycount'",

101002, "Neplatný formát pro atribut 'cardsno'",
101003, "Neplatný formát pro atribut 'tx-id'",
101004, "Neplatný formát pro atribut 'when'",
101007, "Neplatný formát pro atribut 'amount' ",
101008, "Neplatný formát pro atribut 'balance_after'",
101009, "Neplatný formát pro atribut 'balance_before'",
101010, "Neplatný formát transakce pro atribut 'vat'",
101011, "Neplatný formát transakce pro atribut 'type'",
101012, "Neplatný formát transakce pro atribut 'amout-type'",
101013, "Neplatný formát transakce pro atribut 'transtype'",
101014, "Neplatný formát transakce pro atribut 'when'",
101015, "Neplatný formát pro atribut 'appl-id'",
100020, "Chyba: Povinná položka v případě práce s EP.",
100021, "Chyba: Povinná položka v případě transakce související s nástupem do vozidla.",
100022, "Chyba: Povinná položka v případě transakce související s výstupem z vozidla.",
100023, "Chyba: Povinná položka v případě transakce související s jízdou.",
100024, "Chyba: Povinná položka v případě transakce obsahující tarif.",
100033, "Chyba: Neznámá položka TransType.",
100034, "Reklamační transakce neobsahuje korektní data (Reklamace jízdy ve vozidle)",
100035, "Reklamační transakce neobsahuje korektní data (Reklamace jízdy u vydavatele karty).",
100036, " Reklamační transakce neobsahuje korektní data (Reklamace u jiného než vydavatele

karty).",
100037, " Reklamační transakce neobsahuje korektní data (Povinná položka v případě transakce

obsahující časový tarif).",
100038, "Vyrovnávací transakce nesmí obsahovat práci s EP.",
100039, "Nebyli nalezeny položky v transakci.",
100040, "Chyba: Povinná položka v případě práce s multitransakcemi.",
100041, "Chyba: nekorektně zadán sloupec se zónami (Zone).",
100042, "Chyba: nekorektně zadán sloupec se zónami (Zones).",

200001, "Zařízení není aktivní.",
200002, "Karta není aktivní.",
200003, "Karta je na blacklistu.",
200004, "Karta v systému neexistuje.",
200005, "Aplikace pro danou kartu neexistuje nebo není zavedena.",
200006, "TariffType nenalezen v číselníku.",
200007, "PersonType nenalezen v číselníku.",

86
200008, "V číselníku zón se nepodařilo vytvořit záznam pro DepartureTariffID.",
200009, "V číselníku zón se nepodařilo vytvořit záznam pro ArrivalTariffID.",
200010, "Některé zóny v číselníku neexistují (Zone).",
200011, "Některé zóny v číselníku neexistují (Zones).",
200100, "Obecná chyba při komunikaci s Databází.",
200101, "Zařazení neexistuje.",
200102, "Transakce s tímto číslem tx-id již existuje.",
200103, "Nepodařil se zápis záznamu o transakci do tabulky.",
200104, "0-tá aplikace na kartě není vytvořena, nelze nastat data.",
200105, "Nenalezena karta dle CardKODIS",
200106, "Storno transakce nebyla přijata z důvodu nenalezení transakce ke stornování.",
200107, "Chyba při změně transakce ke stornování na stornovanou.",
200108, "Storno transakce nebyla přijata z důvodu nenalezení transakce ke stornování (Multi).",
200109, "Chyba při změně transakce ke stornování na stornovanou (Multi).",
200110, "Transakce s tímto číslem tx-id a multi-index již existuje.",
200111, "Transakce obsahuje chybný formát či sestavení pro zóny.",
200112, "Transakci se nepodařilo uložit korektně z důvodu nečitelného Zones.",
200200, "Nepodařil se zápis záznamu o transakci do tabulky.",

87
Dodatek 2
Seznam zkratek

ZS – základní sazba
KODIS – koordinátor Dopravní ODIS.
EP – elektronická peněženka
CCMSK – clearingové centrum Moravskoslezského kraje
SAM – Secure Access Module (or Secure Application Module)
XML – rozšiřitelný značkovací jazyk (Extensible Mark-up Language) je obecný značkovací jazyk

sdílení a výměnu dat.
Terminál – je zařízení uskutečňující transakce.
Multilístek – jedná se o jízdenku, na kterou jede více cestujících (několik dospělých, pes, dítě atd.).
Multitransakce – transakce skládající se z více než jedné transakce. Dají se použít k zaslání
informaci z multilístku. Tyto transakce jsou speciální v tom, že mají stejné číslo transakce (tx-id),
tedy lístku a obsahují multi-index a multi-sum.
Přestupní jízdenka – je jízdenka, která obsahuje více jízdenek na různé trasy.
Přestupní multilístek – je jízdenka, která obsahuje více jízdenek na různé trasy a zároveň na ni jede
více cestujících (několik dospělých, dětí, psů atd.).

10 000+

2020-22

600+

rok 2020 zdarma

Textová podoba smlouvy Smlouva č. 6336307: Smlouva o poskytování veřejných služeb v přepravě cestujících veřejnou

Příloha MSK_Dopravni_obsluznost_FM_ZD P13_Datova veta pro MSK.pdf

Přehledy

K-IndexIndex klíčových rizik úřadů

Žebříčky K-Indexu

Platy v nejdůležitějších úřadech

Firmy / subjekty

Speciální reporty

Rady pro uživatele Registru smluv

Statistiky smluv

Speciální reporty

Smlouvy uveřejněné konkrétní den

Zakázky podle oborů

Zakázky podle zadavatelů

10 000+

2020-22

600+

rok 2020 zdarma

Hlídač státu

Podpořte nás!

Textová podoba smlouvy Smlouva č. 6336307: Smlouva o poskytování veřejných služeb v přepravě cestujících veřejnou

Příloha MSK_Dopravni_obsluznost_FM_ZD P13_Datova veta pro MSK.pdf

K-Index
Index klíčových rizik úřadů