Skip to content

Rozhraní pmAPI

Jump to bottom
Gabriel Bílý edited this page Feb 10, 2021 · 9 revisions

4.1. Volání rozhraní pmAPI

pmAPI vychází z principů REST API, je dostupné přes HTTPS protokol, data jsou posílaná v JSON formátu.

Jednotlivé operace jsou implementované pomocí následujících HTTP metod:

Metoda Popis
Post Získání dat a změna dat.
Get Získání dat (Přenášené parametry musí být "URL enkódovány").

Poznámka:

Vzhledem k počtu parametrů, množství jejich kombinací a různorodosti jejich obsahu, byla pro získání dat zvolena HTTP metoda POST s JSON daty, místo standardní metody GET s daty v url.

V odpovědích na volání operací pmAPI jsou použity následující HTTP status kódy:

Hodnota Význam Popis
200 OK Požadavek byl úspěšný. Standardní odpověď.
400 Bad request Požadavek nemůže být vyřízen. Chyba syntaxe zápisu nebo adresy.
403 Forbidden Přístup odepřen.
404 Not Found Zdroj nebyl nalezen.
405 Method Not Allowed Požadovaná metoda není podporována.
503 Service Unavailable Služba je dočasné mimo provoz

Při zpracování požadavku jsou nejprve kontrolovány základní parametry a ověřen podpis požadavku. V případě chyby při této základní kontrole obsahuje odpověď z hlediska bezpečnosti pouze obecný HTTP status kód (např. 400 Bad Request nebo 403 Forbidden).

4.2. Podepisování

Veškeré požadavky zaslané na pmAPI musí být podepsány soukromým klíčem obchodníka a jsou při přijetí ověřeny veřejným klíčem obchodníka.

Veškeré odpovědi od pmAPI jsou podepsány soukromým klíčem banky a měly by být při přijetí obchodníkem ověřeny veřejným klíčem banky.

4.2.1. Sestavení podpisu volání

Z dat odesílaných na server sestavíme RETEZEC_ZPRAVY tak, že jednotlivé datové položky seřadíme za sebe v pořadí, v jakém jsou ve specifikaci uvedeny. Pro oddělení jednotlivých položek se použije oddělovač „|“. Do výpočtu zahrneme všechny parametry odeslané v požadavku. Pokud tedy nebude některý nepovinný parametr použit, nebude ani ve výsledném řetězci.

Pokud je položkou zprávy vnořený datový objekt, prostupuje se položkami tohoto objektu. V případě seznamu se do výsledného řetězce vkládají položky ve stejném pořadí, v jakém jsou uvedeny ve zprávě.

Čísla jsou reprezentována v ASCII podobě, znaky jsou zapisované ve své binární reprezentaci (nejsou povoleny entity \uXXXX). Pro samotný výpočet podpisu se pak použije privátní klíč obchodníka.

Pro samotný výpočet podpisu se pak použije privátní klíč obchodníka.

Signature = BASE64_ENCODE(RSA_SIGN(RETEZEC_ZPRAVY))

Příklad:

RETEZEC_ZPRAVY = "M1TEST0001|20160215|12050|87598547|F05334EE|1789600"
RSA_SIGNATURE = RSA_SIGN(RETEZEC_ZPRAVY)
base64-encoded-signature = BASE64_ENCODE(RSA_SIGNATURE)
Zpráva = {
  "PosId":"M1TEST0001",
  "Date":"20160215",
  "Amount":12050,
  "VarSymbol":"87598547",
  "AuthCode":"F05334EE",
  "SeqId":"1789600",
  "Signature":"base64-encoded-signature"
}

V případě ověření podpisu na POSmerchant API u GET operací do podpisu vstupují hodnoty parametrů, které jsou „URL dekódovány“.

Pro výpočet podpisu (RSA_SIGN) je potřeba použít algoritmus založený na SHA-1. Například v Javě je potřeba použít při inicializaci třídy java.security.Signature algoritmus "SHA1withRSA", v PHP je potřeba použít "OPENSSL_ALGO_SHA1", což je defaultní algoritmus pro funkce openssl_sign() a openssl_verify().

4.2.1.1. Příklad sestavení podpisu pro požadavek posílaný pomocí metody POST

V operaci pro zjištění stavu transakce payment/state podepisujeme parametry následujícím způsobem.

Požadovaný výstup

curl -v –X POST https://posman.csob.cz/api/pmapi/v1.0/payment/state \
-H "Content-Type:application/json" \
-d '{
  "PosId":"M1TEST0001",
  "Date":"20160215",
  "Amount":12050,
  "VarSymbol":"87598547",
  "AuthCode":"F05334EE",
  "SeqId":"1789600",
  "Signature":"base64-encoded-signature"
}'

Výpočet Signature

RETEZEC_ZPRAVY = "M1TEST0001|20160215|12050|87598547|F05334EE|1789600"
Signature = BASE64_ENCODE(RSA_SIGN(RETEZEC_ZPRAVY))
4.2.1.2. Příklad sestavení podpisu pro požadavek posílaný pomocí metody GET

Přenášené parametry v URL musí být „URL enkódovány“.

V operaci pro stažení konkrétního výpisu report/get podepisujeme parametry následujícím způsobem.

Požadovaný výstup

curl -v -X GET https://posman.csob.cz/api/pmapi/v1.0/report/get/12547/458849/00001.zip/url-encoded-base64-encoded-signature

Výpočet Signature

RETEZEC_ZPRAVY = "12547|458849|00001.zip"
Signature = BASE64_ENCODE(RSA_SIGN(RETEZEC_ZPRAVY))

4.2.2. Ověření podpisu odpovědi

Podobně jako u vytvoření podpisu požadavku se pro ověření podpisu odpovědi z jednotlivých položek odpovědi vytvoří RETEZEC_ZPRAVY a pro ověření podpisu se použije veřejný klíč mpAPI.

4.2.2.1. Příklad sestavení podpisu pro odpověď

V operaci pro stažení konkrétního výpisu report/get vypočítáme podpis následujícím způsobem.

Odpověď

{`
  "PosId":"M1TEST0001",
  "Date":"20160215",
  "Amount":12050,
  "VarSymbol":"87598547",
  "AuthCode":"F05334EE",
  "SeqId":"1789600",
  "ResultCode":0,
  "ResultMessage":"OK",
  "DateTime":"20160215132045",
  "PayStatus":"authorized",
  "Signature":"base64-encoded-signature"
}

Výpočet Signature

RETEZEC_ZPRAVY = "M1TEST0001|20160215|12050|87598547|F05334EE|1789600|0|OK|20160215132045|authorized"
Signature = BASE64_ENCODE(RSA_SIGN(RETEZEC_ZPRAVY))

4.3. Podepisování

4.3.1. Transakce

4.3.1.1. Zjištění stavu transakce payment/state

HTTP metoda: POST

Formát dat: JSON

Požadavek

Požadavky pro payment/state, payment/reverse a payment/process obsahují jednotnou sadu parametrů popisující transakci. U jednotlivých volání funkcí jsou již uvedeny pouze parametry rozšiřující tuto společnou definici.

Položka Typ Popis
PosId String Identifikátor platebního terminálu. 10 znaků.
Date String Datum vzniku transakce ve formátu YYYYMMDD.
Amount Number Částka transakce v setinách základní měny.
VarSymbol String Variabilní symbol.
AuthCode String Autorizační kód.
SeqId String Sekvenční id transakce.
Signature String Podpis požadavku, kódováno v BASE64.

Struktura dat podpisu požadavku:

PosId|Date|Amount|VarSymbol|AuthCode|SeqId

Příklad volání:

curl -v –X POST https://posman.csob.cz/api/pmapi/v1.0/payment/state \
-H "Content-Type:application/json" \
-d '{
  "PosId":"M1TEST0001",
  "Date":"20160215",
  "Amount":12050,
  "VarSymbol":"87598547",
  "AuthCode":"F05334EE",
  "SeqId":"1789600",
  "Signature":"base64-encoded-signature"
}

Návratové hodnoty

Návratové hodnoty pro payment/state, payment/reverse a payment/process obsahují jednotnou sadu parametrů, popisující aktuální transakci, její stav a výsledek operace. U jednotlivých volání funkcí jsou již uvedeny pouze příklady návratových hodnot s odkazem na tuto společnou definici.

Položka Typ Popis
PosId String Identifikátor platebního terminálu. 10 znaků.
Date String Datum vzniku transakce ve formátu YYYYMMDD.
Amount Number Částka transakce v setinách základní měny.
Currency String Měna.
VarSymbol String Variabilní symbol.
AuthCode String Autorizační kód.
SeqId String Sekvenční id transakce.
ResultCode Number Výsledek operace, viz výčet.
ResultMessage String Textový popis výsledku operace.
DateTime String Datum a čas vzniku transakce ve formátu YYYYMMDDHHMMSS.
PayStatus String Stav transakce.
Signature String Podpis požadavku, kódováno v BASE64.

Návratové kódy:

ResultCode ResultMessage Popis
0 OK Operace proběhla korektně.
100 Missing parameter {name} Chybějící povinný parametr.
110 Invalid parameter {name} Chybný formát parametru.
120 Payment not found Platba nenalezena.
130 Payment not unique Transakce není jednoznačně určena.
140 Operation not allowed Nepovolená operace.

Struktura dat podpisu odpovědi:

PosId|Date|Amount|VarSymbol|AuthCode|SeqId|ResultCode|ResultMessage|DateTime|PayStatus

Příklad návratových hodnot pro úspěšně zpracovaný požadavek:

{
  "PosId":"M1TEST0001",
  "Date":"20160215",
  "Amount":12050,
  "VarSymbol":"87598547",
  "AuthCode":"F05334EE",
  "SeqId":"1789600",
  "ResultCode":0,
  "ResultMessage":"OK",
  "DateTime":"20160215132045",
  "PayStatus":"authorized",
  "Signature":"base64-encoded-signature"
}

Příklad návratových hodnot pro neúspěšně zpracovaný požadavek:

{
  "PosId":"M1TEST0001",
  "Date":"20160215",
  "VarSymbol":"87598547",
  "AuthCode":"F05334EE",
  "SeqId":"1789600",
  "ResultCode":100,
  "ResultMessage":"Missing parameter 'Amount'",
  "Signature":"base64-encoded-signature"
}
4.3.1.2. Reverzování transakce payment/reverse

HTTP metoda: POST

Formát dat: JSON

Požadavek

Základní parametry jsou shodné s definicí popsanou u operace payment/state.

Položka Typ Popis
ProcessedAmount Number Částka transakce v setinách základní měny.

Struktura dat podpisu volání:

Struktura je shodná jako u operace payment/state doplněna o hodnotu |ProcessedAmount.

Příklad volání:

curl -v –X POST https://posman.csob.cz/api/pmapi/v1.0/payment/reverse \
-H "Content-Type:application/json" \
-d '{
  "PosId":"M1TEST0001",
  "Date":"20160215",
  "Amount":12050,
  "VarSymbol":"87598547",
  "AuthCode":"F05334EE",
  "SeqId":"1789600",
  "ProcessedAmount":"2000",
  "Signature":"base64-encoded-signature"
}

Návratové hodnoty

Návratové hodnoty jsou shodné s definicí popsanou u operace payment/state.

Struktura dat pro podpis odpovědi je shodná jako u operace payment/state.

Příklad návratových hodnot pro úspěšně zpracovaný požadavek:

{
  "PosId":"M1TEST0001",
  "Date":"20160215",
  "Amount":12050,
  "VarSymbol":"87598547",
  "AuthCode":"F05334EE",
  "SeqId":"1789600",
  "ResultCode":0,
  "ResultMessage":"OK",
  "DateTime":"20160215132045",
  "PayStatus":"authorized",
  "Signature":"base64-encoded-signature"
}

Příklad návratových hodnot pro neúspěšně zpracovaný požadavek:

{
  "PosId":"M1TEST0001",
  "Date":"20160215",
  "VarSymbol":"87598547",
  "AuthCode":"F05334EE",
  "SeqId":"1789600",
  "ResultCode":100,
  "ResultMessage":"Missing parameter 'Amount'",
  "Signature":"base64-encoded-signature"
}
4.3.1.3. Znovuproplacení transakce payment/process

HTTP metoda: POST Formát dat: JSON

Požadavek

Základní parametry jsou shodné s definicí popsanou u operace payment/state.

Položka Typ Popis
ProcessedAmount Number Částka transakce v setinách základní měny.

Podpis volání je shodný s operací payment/reverse.

Příklad volání:

curl -v –X POST https://posman.csob.cz/api/pmapi/v1.0/payment/reverse \
-H "Content-Type:application/json" \
-d '{
  "PosId":"M1TEST0001",
  "Date":"20160215",
  "Amount":12050,
  "VarSymbol":"87598547",
  "AuthCode":"F05334EE",
  "SeqId":"1789600",
  "ProcessedAmount":"2000",
  "Signature":"base64-encoded-signature"
}'

Návratové hodnoty

Návratové hodnoty jsou shodné s definicí popsanou u operace payment/state.

Podpis odpovědi je shodný s operací payment/reverse.

Příklad návratových hodnot pro úspěšně zpracovaný požadavek:

{
  "PosId":"M1TEST0001",
  "Date":"20160215",
  "Amount":12050,
  "VarSymbol":"87598547",
  "AuthCode":"F05334EE",
  "SeqId":"1789600",
  "ResultCode":0,
  "ResultMessage":"OK",
  "DateTime":"20160215132045",
  "PayStatus":"authorized",
  "Signature":"base64-encoded-signature"
}

Příklad návratových hodnot pro neúspěšně zpracovaný požadavek:

{
  "PosId":"M1TEST0001",
  "Date":"20160215",
  "VarSymbol":"87598547",
  "AuthCode":"F05334EE",
  "SeqId":"1789600",
  "ResultCode":100,
  "ResultMessage":"Missing parameter 'Amount'",
  "Signature":"base64-encoded-signature"
}

4.3.2. Výpisy

Pro přístup ke konkrétnímu výpisu je nutné zadat jeho unikátní ReportId. Tento identifikátor je uveden v POSMerchantu (https://posman.csob.cz/posmerchant), na záložce Obchodníci – Výpisy.

Výpisy

Detail výpisů

4.3.2.1. Seznam vygenerovaných výpisů report/list

HTTP metoda: POST

Formát dat: JSON

Požadavek

Položka Typ Popis
MerchantId String Identifikátor obchodníka.
ReportId String Identifikátor výpisu.
Date String Datum ve formátu YYYYMMDD.
Signature String Podpis požadavku, kódováno v BASE64.

Struktura dat podpisu volání:

MerchantId|ReportId|Date

Příklad volání:

curl -v –X POST https://posman.csob.cz/api/pmapi/v1.0/report/list \
-H "Content-Type:application/json" \
-d '{
  "MerchantId":"12547",
  "ReportId":"458849",
  "Date":"20160215",
  "Signature":"base64-encoded-signature"
}'

Návratové hodnoty

Položka Typ Popis
MerchantId String Identifikátor obchodníka.
ReportId String Identifikátor výpisu.
Date String Datum ve formátu YYYYMMDD.
ResultCode Number Výsledek operace, viz. výčet.
ResultMessage String Textový popis výsledku operace.
Files Object Seznam názvů souborů výpisů.
Signature String Podpis požadavku, kódováno v BASE64.

Report:

Položka Typ Popis
Name String Název výpisu.

Návratové kódy:

ResultCode ResultMessage Popis
0 OK Operace proběhla korektně.
100 Missing parameter {name} Chybějící povinný parametr.
110 Invalid parameter {name} Chybný formát parametru.
120 Merchant not found Obchodník nenalezen.
130 Report not found Výpis nenalezen.

Struktura dat pro podpis odpovědi:

MerchantId|ReportId|Date|ResultCode|ResultMessage|[Files]*

Files:

Name|Dir|Extension|Length|LastModified

Příklad návratových hodnot pro úspěšně zpracovaný požadavek:

{
  "MerchantId":"12547",
  "ReportId":"458849",
  "Date":"20160215",
  "ResultCode":0,
  "ResultMessage":"OK",
  "Files":[
    {
      "name": "00001.zip",
    },
    {
      "name": "00002.zip",
    },
    {
      "name": "00003.zip",
    }
  ],
  "Signature":"base64-encoded-signature"
}

Příklad návratových hodnot pro neúspěšně zpracovaný požadavek:

{
  "MerchantId":"12547",
  "Date":"20160215",
  "ResultCode":100,
  "ResultMessage":"Missing parameter 'ReportId'",
  "Signature":"base64-encoded-signature"
}
4.3.2.2. Stažení konkrétního výpisu report/get

HTTP metoda: GET Formát dat: URL

Požadavek

Položka Typ Popis
MerchantId String Identifikátor obchodníka.
ReportId String Identifikátor výpisu.
Dir String Název složky.
File String Název souboru výpisu.
Signature String Podpis požadavku, kódováno v BASE64.

Struktura dat podpisu volání:

MerchantId|ReportId|Dir|File

URL

https://posman.csob.cz/api/pmapi/v1.0/report/get/{MerchantId}/{ReportId}/{Dir}/{File}/{Signature}

Příklad volání:

curl -v -X GET https://posman.csob.cz/api/pmapi/v1.0/report/get/12547/458849/0001/00001.zip/url-encoded-base64-encoded-signature

Návratové hodnoty Standardní HTTP status kódy.

Soubor výpisu.

4.3.3. Uživatelské reporty

Umožňuje stahování výpisů z PM API do souboru CSV či XLSX. Stahování probíhá na pozadí a následně je možné tento výpis kdykoli znova stáhnout. Report se vytváří na základě dané konfigurace. Konfigurace reportů lze vyhledat v POSMerchantu (https://posman.csob.cz/posmerchant), na záložce Obchodníci – Uživatelské reporty.

Uživatelské reporty

4.3.3.1. Seznam vygenerovaných výpisů customReport/list

HTTP metoda: POST

Formát dat: JSON

Požadavek

Položka Typ Popis
MerchantId String Identifikátor obchodníka.
Date String Datum ve formátu YYYYMMDD.
Signature String Podpis požadavku, kódováno v BASE64.

Struktura dat podpisu volání:

MerchantId|Date

Příklad volání:

curl -v –X POST https://posman.csob.cz/api/pmapi/v1.0/customReport/list \
-H "Content-Type:application/json" \
-d '{
  "MerchantId":"12547",
  "Date":"20160215",
  "Signature":"base64-encoded-signature"
}'

Návratové hodnoty

Položka Typ Popis
MerchantId String Identifikátor obchodníka.
ReportId String Identifikátor výpisu.
Date String Datum ve formátu YYYYMMDD.
ResultCode Number Výsledek operace, viz. výčet.
ResultMessage String Textový popis výsledku operace.
Files Object Seznam názvů souborů výpisů.
Signature String Podpis požadavku, kódováno v BASE64.

Report:

Položka Typ Popis
Name String Název výpisu.

Návratové kódy:

ResultCode ResultMessage Popis
0 OK Operace proběhla korektně.
100 Missing parameter {name} Chybějící povinný parametr.
110 Invalid parameter {name} Chybný formát parametru.
120 Merchant not found Obchodník nenalezen.
130 Report not found Výpis nenalezen.

Struktura dat pro podpis odpovědi:

MerchantId|ReportId|Date|ResultCode|ResultMessage|[Files]*

Files:

Name|Dir|Extension|Length|LastModified

Příklad návratových hodnot pro úspěšně zpracovaný požadavek:

{
  "MerchantId":"12547",
  "ReportId":"458849",
  "Date":"20160215",
  "ResultCode":0,
  "ResultMessage":"OK",
  "Files":[
    {
      "name": "00001.zip",
    },
    {
      "name": "00002.zip",
    },
    {
      "name": "00003.zip",
    }
  ],
  "Signature":"base64-encoded-signature"
}

Příklad návratových hodnot pro neúspěšně zpracovaný požadavek:

{
  "MerchantId":"12547",
  "Date":"20160215",
  "ResultCode":100,
  "ResultMessage":"Missing parameter 'ReportId'",
  "Signature":"base64-encoded-signature"
}
4.3.3.2. Stažení konkrétního výpisu customReport/get

HTTP metoda: GET Formát dat: URL

Požadavek

Položka Typ Popis
MerchantId String Identifikátor obchodníka.
Year String Rok výpisu.
Month String Měsíc výpisu.
File String Název souboru výpisu.
Signature String Podpis požadavku, kódováno v BASE64.

Struktura dat podpisu volání:

MerchantId|Year|Month|File

URL

https://posman.csob.cz/api/pmapi/v1.0/customReport/get/{MerchantId}/{Year}/{Month}/{File}/{Signature}

Příklad volání:

curl -v -X GET https://posman.csob.cz/api/pmapi/v1.0/customReport/get/12547/2020/01/00001.zip/url-encoded-base64-encoded-signature

Návratové hodnoty Standardní HTTP status kódy.

4.3.4. Account Transport

4.3.4.1. Seznam tapů transport/tap/list

HTTP metoda: POST

Formát dat: JSON

Požadavek

Položka Typ Popis
MerchantId String Identifikátor obchodníka.
DateFrom String Datum od ve formátu YYYYMMDD.
DateTo String Datum do ve formátu YYYYMMDD.
Vs String Variabilní symbol.
Token String Token.
Status Number Status tapu.
ResponseCode Number Návratový kód terminálu.
TerminalId String Identifikátor terminálu.
Signature String Podpis požadavku, kódováno v BASE64.

Struktura dat podpisu volání:

MerchantId|DateFrom|DateTo

Příklad volání:

curl -v –X POST https://posman.csob.cz/api/pmapi/v1.0/transport/tap/list \
-H "Content-Type:application/json" \
-d '{
  "MerchantId":"12547",
  "DateFrom":"20160205",
  "DateTo":"20160215",
  "Vs":"12547",
  "Token":"ABCDE12345",
  "Status":"1",
  "ResponseCode":"2",
  "TerminalId":"12345", 
  "Signature":"base64-encoded-signature"
}'

Návratové hodnoty

Položka Typ Popis
MerchantId String Identifikátor obchodníka.
DateFrom String Datum od ve formátu YYYYMMDD.
DateTo String Datum do ve formátu YYYYMMDD.
Vs String Variabilní symbol.
Token String Token.
Status Number Status.
ResponseCode Number Návratový kód terminálu.
TerminalId String Identifikátor terminálu.
ResultCode Number Výsledek operace. Viz výčet
ResultMessage String Textový popis výsledku operace.
TapList Object Seznam nalezených tapů.
Signature String Podpis požadavku, kódováno v BASE64.

TapList

Položka Typ Popis
TapDttm String Datum a čas tapu ve formátu DD.MM.YYYY HH:MM:SS
TerminalId String Identifikátor terminálu.
TerminalStatus Integer Status odbavení na terminálu.
TerminalResponse Integer Návratový kód, který vydal terminál při odbavení karty.
Token String Karetní token.
MaskedPan String Maskované číslo karty.
Vs String Variabilní symbol tapu z terminálu.
ValidatorId String Identifikátor validátoru.
TxCounter Integer Pořadové číslo transakce z validátoru.
Amount Long Částka jízdenky.
Vat Integer Daň.
LineId String Číslo linky.
VehicleId VehicleId Číslo spoje.
EntryStopTariffNumber String Tarifní (pořadové) číslo výchozí zastávky.
EntryStopNumber String Evidenční číslo zastávky.
EntryStopZoneNumber String Číslo zóny výchozí zastávky.
ExitStopZoneNumber String Číslo zóny cílové zastávky.

Návratové kódy:

ResultCode ResultMessage Popis
0 OK Operace proběhla korektně.
100 Missing parameter {name} Chybějící povinný parametr.
110 Invalid parameter {name} Chybný formát parametru.
160 Merchant not found Obchodník nenalezen.
180 Date out of range Datum poslední kontroly přesáhl 1 měsíc od aktuálního data.
190 Taps not found Tapy nenalezeny.

Struktura dat pro podpis odpovědi:

MerchantId|DateFrom|DateTo|ResultCode|ResultMessage|[TapList]*

TapList:

TerminalId|TerminalStatus|TerminalResponse|StoplistVersion|Token|MaskedPan|Vs|TapDttm|ValidatorId|TxCounter|Amount|Vat|LineId|VehicleId|EntryStopTariffNumber|EntryStopNumber|EntryStopZoneNumber|ExitStopZoneNumber

Příklad návratových hodnot pro úspěšně zpracovaný požadavek:

{
  "MerchantId":"12547",
  "DateFrom":"20160205",
  "DateTo":"20160215",
  "ResultCode":0,
  "ResultMessage":"OK",
  "TapList":[
    {
       "TapDttm"	  : "20.07.2016 21:24:35",
"TerminalId" 	  : "145456",
"TerminalStatus": 1,
"TerminalResponse": 1,
"StopListVersion": "124",
"Token"	  : "4546456",
"Vs" 		  : "54878124",
"ValidatorId"	  : "874",
"TxCounter"	  : 2,
"Amount"	  : 10000,
"Vat"	 	  : 20,
"LineId" 	  : "132",
"VehicleId"	  : "324",
"EntryStopTariffNumber": "3",
"EntryStopNumber": "5",
"EntryStopZoneNumber": "2",
"ExitStopZoneNumber": "4"
    },
     {
       "TapDttm"	  : "12.08.2016 13:52:31",
"TerminalId" 	  : "145456",
"TerminalStatus": 2,
"TerminalResponse": 1,
"StopListVersion": "125",
"Token"	  : "4546478",
"Vs" 		  : "54878125",
"ValidatorId"	  : "874",
"TxCounter"	  : 3,
"Amount"	  : 20000,
"Vat"	 	  : 20,
"LineId" 	  : "132",
"VehicleId"	  : "324",
"EntryStopTariffNumber": "7",
"EntryStopNumber": "10",
"EntryStopZoneNumber": "1",
"ExitStopZoneNumber": "2"
    }
  ],
  "Signature":"base64-encoded-signature"
}

Příklad návratových hodnot pro neúspěšně zpracovaný požadavek:

{
  "DateFrom":"20160205",
  "DateTo":"20160215",
  "ResultCode":100,
  "ResultMessage":"Missing parameter MerchantId",
  "Signature":"base64-encoded-signature"
}
4.3.4.2. Seznam clearingových transakcí transport/clear/list

HTTP metoda: POST

Formát dat: JSON

Požadavek

Položka Typ Popis
MerchantId String Identifikátor obchodníka.
DateFrom String Datum od ve formátu YYYYMMDD.
DateTo String Datum do ve formátu YYYYMMDD.
Vs String Variabilní symbol.
Token String Token.
Amount Number Zastropovaná částka.
Signature String Podpis požadavku, kódováno v BASE64.

Struktura dat podpisu volání:

MerchantId|DateFrom|DateTo

Příklad volání:

curl -v –X POST https://posman.csob.cz/api/pmapi/v1.0/transport/clear/list \
-H "Content-Type:application/json" \
-d '{
  "MerchantId":"12547",
  "DateFrom":"20160205",
  "DateTo":"20160215",
  "Vs":"10500",
  "Token":"ABCDE12345",
  "Amount":"10200",
  "Signature":"base64-encoded-signature"
}'

Návratové hodnoty

Položka Typ Popis
MerchantId String Identifikátor obchodníka.
DateFrom String Datum od ve formátu YYYYMMDD.
DateTo String Datum do ve formátu YYYYMMDD.
Vs String Variabilní symbol.
Token String Token.
Status Number Status.
ResultCode Number Výsledek operace. Viz výčet
ResultMessage String Textový popis výsledku operace.
ClearList Object Seznam nalezených clearingových transakcí.
Signature String Podpis požadavku, kódováno v BASE64.

ClearList

Položka Typ Popis
Token String Karetní token.
MaskedPan String Maskované číslo karty.
AmountBase Long Částka základní (součet všech tapů)
AmountFinal Long Částka zastropovaná (snížená částka na denní jízdné).
FirstTapDttm String Datum prvního tapu ve formátu DD.MM.YYYY HH:MM:SS.
LastTapDttm String Datum zúčtování ve formátu DD.MM.YYYY HH:MM:SS.
PayDttm String Číslo zóny výchozí zastávky.
Vs String Variabilní symbol.

Návratové kódy:

ResultCode ResultMessage Popis
0 OK Operace proběhla korektně.
100 Missing parameter {name} Chybějící povinný parametr.
110 Invalid parameter {name} Chybný formát parametru.
160 Merchant not found Obchodník nenalezen.
180 Date out of range Datum poslední kontroly přesáhl 1 měsíc od aktuálního data.
200 Clears not found Clearingové transakce nenalezeny nenalezeny.

Struktura dat podpisu odpovědi:

MerchantId|DateFrom|DateTo|ResultCode|ResultMessage|[ClearList]*

ClearList:

Token|MaskedPan|AmountBase|AmountFinal|FirstTapDttm|LastTapDttm|PayDttm|Vs

Příklad návratových hodnot pro úspěšně zpracovaný požadavek:

{
  "MerchantId":"12547",
  "DateFrom":"20160205",
  "DateTo":"20160215",
  "ResultCode":0,
  "ResultMessage":"OK",
  "ClearList":[
    {
"Token" 	: "145456",
"MaskedPan"	: "145446****4545",
"AmountBase" : 10000,
"AmountFinal": 8000,
"FirstTapDttm": "08.01.2016 12:51:28",
"LastTapDttm" : "10.01.2016 02:15:35",
"PayDttm"	 : "10.04.2016 02:25:35",
"Vs" 		  : "54878124"
    },
     {
"Token" 	: "145456",
"MaskedPan"	: "921646****4975",
"AmountBase" : 20000,
"AmountFinal": 16000,
"FirstTapDttm": "20.07.2017 14:24:45",
"LastTapDttm" : "20.07.2017 21:01:35",
"PayDttm"	 : "20.07.2017 22:15:35",
"Vs" 		  : "42378124"
    }
  ],
  "Signature":"base64-encoded-signature"
}

Příklad návratových hodnot pro neúspěšně zpracovaný požadavek:

{
  "DateFrom":"20160205",
  "DateTo":"20160215",
  "ResultCode":100,
  "ResultMessage":"Missing parameter MerchantId",
  "Signature":"base64-encoded-signature"
}

4.3.5. DCC

4.3.5.1. Aktuální kurzovní lístek dcc/kurz

HTTP metoda: POST

Formát dat: JSON   Požadavek

Položka Typ Popis
MerchantId String Identifikátor obchodníka.
OutputFormat String Formát výstupních dat kurzovního lístku.
Signature String Podpis požadavku, kódováno v BASE64.

Struktura dat podpisu volání:

MerchantId|OutputFormat

Příklad volání:

curl -v –X POST https://posman.csob.cz/api/pmapi/v1.0/dcc/kurz \
-H "Content-Type:application/json" \
-d '{
  "MerchantId":"12547",
  "OutputFormat":"XML",
  "Signature":"base64-encoded-signature"
}'

Návratové hodnoty

Položka Typ Popis
MerchantId String Identifikátor obchodníka.
OutputFormat String Formát výstupních dat kurzovního lístku.
Name String Název výstupního souboru kurzovního lístku.
KurzListek String Data kurzovního lístku ve výstupním formátu.
Signature String Podpis požadavku, kódováno v BASE64.

Struktura dat podpisu odpovědi:

MerchantId|OutputFormat|ResultCode|ResultMessage|Name|KurzListek

Popis dat kurzovního lístku, podle daných formátů:

Textový formát:

textový kód vstupní měny;číselný kód vstupní měny;textový kód výstupní měny;číselný kód výstupní měny;částka za jednotku vstupní měny;datum platnosti od;datum a čas platnosti do

XML formát:

<DCCKL>
<ITEM>
      <CURRENCY_NUM_SRC> textový kód vstupní měny </CURRENCY_TXT_SRC> 
      <CURRENCY_NUM_SRC> číselný kód vstupní měny </CURRENCY_NUM_SRC>
      <CURRENCY_TXT_DST> textový kód výstupní měny </CURRENCY_TXT_DST>
      <CURRENCY_NUM_DST> číselný kód výstupní měny </CURRENCY_NUM_DST>
      <AMOUNT> částka za jednotku vstupní měny </AMOUNT>
      <VALID_FROM> datum platnosti od </VALID_FROM>
      <VALID_TO> datum a čas platnosti do *</VALID_TO>
</ITEM>
… 
…
</DCCKL>
  • Datum a čas platnosti do, je 24 hodin po čase žádosti o kurzovní lístek.

Návratové kódy:

ResultCode ResultMessage Popis
0 OK Operace proběhla korektně.
100 Missing parameter {name} Chybějící povinný parametr.
110 Invalid parameter {name} Chybný formát parametru.
160 Merchant not found Obchodník nenalezen.
180 Date out of range Datum poslední kontroly přesáhl 1 měsíc od aktuálního data.
210 DCC kurz not found Kurzovní lístek nebyl nalezen.

Příklad návratových hodnot pro úspěšně zpracovaný požadavek:

{
  "MerchantId":"12547",
  "OutputFormat":"XML",
  "ResultCode":0,
  "ResultMessage":"OK",
  "Name":"DCC_06092018_f2bc5.xml",
  "KurzListek":
"<DCCKL>
  <ITEM>
      <CURRENCY_TXT_SRC>DKK</CURRENCY_TXT_SRC>
      <CURRENCY_NUM_SRC>208</CURRENCY_NUM_SRC>
      <CURRENCY_TXT_DST>CZK</CURRENCY_TXT_DST>
      <CURRENCY_NUM_DST>203</CURRENCY_NUM_DST>
      <AMOUNT>0.2928871</AMOUNT>
      <VALID_FROM>2018-09-05</VALID_FROM>
      <VALID_TO>2018-09-06 06:35:04</VALID_TO>
  </ITEM>
  <ITEM>
      <CURRENCY_TXT_SRC>EUR</CURRENCY_TXT_SRC>
      <CURRENCY_NUM_SRC>978</CURRENCY_NUM_SRC>
      <CURRENCY_TXT_DST>CZK</CURRENCY_TXT_DST>
      <CURRENCY_NUM_DST>203</CURRENCY_NUM_DST>
      <AMOUNT>27.07109</AMOUNT>
      <VALID_FROM>2018-09-05</VALID_FROM>
      <VALID_TO>2018-09-06 06:35:04</VALID_TO>
  </ITEM>
</DCCKL>",
  "Signature":"base64-encoded-signature"
}

Příklad návratových hodnot pro neúspěšně zpracovaný požadavek:

{
  "ResultCode":100,
  "ResultMessage":"Missing parameter MerchantId",
  "Signature":"base64-encoded-signature"
}

4.3.6. Pomocné funkce

4.3.6.1. Kontrola dostupnosti echo

HTTP metoda: GET

Požadavek

Požadavek nemá žádné parametry.

URL

https://posman.csob.cz/api/pmapi/v1.0/echo

Příklad volání:

curl -v -X GET https://posman.csob.cz/api/pmapi/v1.0/echo

Návratové hodnoty

Položka Typ Popis
Date String Datum ve formátu YYYYMMDDHHMMSS.

Příklad návratových hodnot:

20160217154501

Home

1. Slovníček nejdůležitějších pojmů

2. Funkce pmAPI

3. Postup integrace, klíče a kde je vzít

4. Rozhraní pmAPI

Clone this wiki locally