qr-platba.cz - Specifikace RESTful API

Specifikace RESTful API | QR Platba

Qr-platba.cz Spined HTML

Specifikace RESTful API | QR Platba HomeGenerátor QR PlatbyPro uživatelePro výstavcePro vývojářeSpecifikace formátuGenerátor QR PlatbySpecifikace RESTful APIValidátor SPAYD řetězceKnihovny na GitHubuGrafický manuálKontakt Specifikace RESTful API Cílem tohoto dokumentu je specifikovat, jak je na straně serveru řešené API pro práci s formátem Short Payment Descriptor (SPAYD). Primárním cílem RESTful API je postkytnout prostředky pro snadnou integraci formátu např. do e-shopu, na webové stránky dobročinné organizace nebo do online systémů pro správu faktur. Sekundárním cílem je pak poskytnout referenční implementaci formátu a prostředky pro validaci in-house implementací formátu SPAYD. Poslední, čemu může být RESTful API k užitku, je verfikace čísla IBAN za účelem např. zamezení podvodných QR kódů. Umístění API API je dostupné na základní adrese: http://api.paylibo.com/paylibo/. Jsou k dispozici tyto zdroje: Validace řetězce SPAYD Verifikace IBAN protistrany Generování řetězce SPAYD – Parametry příkazu v ČR Generování souboru SPAYD – Parametry příkazu v ČR Generování QR kódu SPAYD – Parametry příkazu v ČR Generování řetězce SPAYD – základní parametry Generování souboru SPAYD – základní parametry Generování QR kódu SPAYD – základní parametry Příklad – generování QR kódu pro platbu Českému červenému kříži: http://api.paylibo.com/paylibo/generator/czech/image?accountNumber=222885&bankCode=5500&amount=250.00&currency=CZK&vs=333&message=FOND%20HUMANITY%20CCK Formát specifikace API Specifikace je strukturována dle jednotlivých zdrojů – ke zdroji je vždy uveden: Název funkčnosti (př.: “Validace řetězce SPAYD”, …). Adresa REST zdroje ve formátu ${API_PATH}/${VERSION}/${RESOURCE} – kde: ${API_PATH} označuje tzv. “base URL”, čili to, kde je API dostupné – v dokumentaci se nesubstituuje ${VERSION} označuje verzi API, v dokumentaci se substituuje za aktuální verzi API ${RESOURCE} označuje název konkrétního zdroje, v dokumentaci se substituuje za název zdroje Parametry dotazu jsou zachyceny v tabulce (“název”, “typ”, “popis”), povinné parametry jsou zobrazeny tučně, nepovinné běžnou tloušťkou písma. HTTP metoda, která daný scénář realizuje (jedna z hodnot GET, POST, PUT či DELETE). Popis odpovědi, vč. popisu stavových kódů HTTP protokolu, a to jak v pozitivním (vše proběhlo v pořádku), tak v negativním (došlo k chybě) případě. Obecné zásady API Obecné zásady, kterými se API řídí, jsou následující: API je verzované, aby bylo možno zajistit kompatibilitu s různými verzemi klientů. API je postavené na filosofii REST, implementovanou nad protokolem HTTP (čili jedná se o tzv. RESTful API). Server důsledně dbá na vracení stavových kódů HTTP protokolu, aby bylo možno v případě negativní odpovědi serveru (při chybě) HTTP tento kód okamžitě interpretovat, a např. přerušit připojení, a šetřila se tak přenesená data. Veškerá komunikace bude probíhat po zabezpečeném kanále (HTTPS). Mechanismus předávání chybových odpovědí Komunikační protokol je navržen tak, aby bylo možno použít HTTP stavový kód jako indikátor úspěchu či neúspěchu dotazu na server. Úspěch je tedy indikován kódy 20x, neúspěch z důvodu klientské chyby kódy 40x a neúspěch z důvodu serverové chyby kódy 50x. V případě neúspěchu libovolného typu je vrácena odpověď s tělem s MIME type application/json v následujícím formátu: { “description”: “Popis chyby, ktery se ma zobrazit uzivateli” “errors”: [ { “code”: “err001”, “description”: “Popis 1. parcialni chyby, napr. vadne pole formulare” }, { “code”: “err002”, “description”: “Popis 2. parcialni chyby, napr. vadne pole formulare” } ] } Chybové odpovědi mohou být specifické pro daný zdroj (interpretace stavového kódu může být různá pro různé zdroje), ale některé z nich jsou obecné a společné všem zdrojům. Tyto chyby jsou indikovány následujícími HTTP kódy: 418 – Zastaralá verze klienta. Je nutné aktualizovat klientskou aplikaci. 503 – Služba není dostupná. Vrácen v případě provádění údržby serveru. Klientská aplikace upozorní uživatele, že služba bude dostupná později. Popis datových typů Rozhraní používá primárně primitivní datové typy podporované formátem JSON (string, number, object, array, true, false, null). Popis zdrojů API Validace řetězce SPAYD URL: ${SERVER}/validator/string Metoda: GET Parametry: Název typ Popis paymentString STRING řetězec, který se má validovat Odpověď v negativním případě: HTTP kód Popis odpovědi, příklad 400 – Bad Request Data nejsou validní, chyby jsou vráceny dle popisu chybové odpovědi. Odpověď v pozitivním případě: HTTP kód Popis odpovědi, příklad 200 – OK Stručná odpověď text/plain, signalizující úspěšnou validaci "OK" Verifikace IBAN protistrany URL: ${SERVER}/validator/iban Metoda: GET Parametry: Název typ Popis iban STRING IBAN číslo účtu, které se má verifikovat Odpověď v negativním případě: HTTP kód Popis odpovědi, příklad 400 – Bad Request Data nejsou validní, chyby jsou vráceny dle popisu chybové odpovědi. Odpověď v pozitivním případě: HTTP kód Popis odpovědi, příklad 200 – OK Odpověď (application/json) může být trojího typu dle toho, zda je účet neznámy (klient zobrazí varování), známý/ověřený (klient zobrazí potvrzení, že účet je důvěryhodný a o jaký účet se jedná) nebo známý/zakázaný (klient zobrazí důrazné varování a důvod, proč je účet blokován). Neznámý IBAN { "result": "unknown", "iban": "CZ1212341234561234567890" } Blokovaný IBAN { "result": "banned", "iban": "CZ1212341234561234567890", "reason": "Podvodný IBAN" } Verifikovaný IBAN { "result": "verified", "iban": "CZ1212341234561234567890", "name": "Ticket Pro", "description": "TICKETPRO provozuje v ČR největší počítačovou síť pro prodej vstupenek..." } Generování řetězce SPAYD – Parametry příkazu v ČR URL: ${SERVER}/generator/czech/string Metoda: GET Parametry: Název typ Popis Pozn.: Detaily parametrů viz specifikace řetězce SPAYD accountPrefix STRING Předčíslí čísla účtu, na který se mají poslat prostředky. accountNumber STRING Číslo účtu, na který se mají poslat prostředky. bankCode STRING Kód banky účtu, na který se mají poslat prostředky. value DOUBLE Částka platby. currency STRING Měna platby. vs STRING Variabilní symbol. ks STRING Konstantní symbol. ss STRING Specifický symbol. identifier STRING Interní ID platby. stage STRING Datum splatnosti ve formátu ISO 8601 (krátky formát pro datum, tj. YYYY-mm-dd) message STRING Zpráva pro příjemce shrink BOOLEAN Použít kompaktní formát (uppercase bez diakritiky). Výchozí hodnota: true. Odpověď v negativním případě: HTTP kód Popis odpovědi, příklad 400 – Bad Request Data nejsou validní, chyby jsou vráceny dle popisu chybové odpovědi. Odpověď v pozitivním případě: HTTP kód Popis odpovědi, příklad 200 – OK Tělo odpovědi obsahuje validní řetězec SPAYD s MIME type text/plain, např.: "SPD*1.0*IBAN:CZ5855000000001265098001*AM:480.50*CC:CZK* RF:7004139146*X-SS:1234567890*DT:20120524*MSG:PLATBA ZA ZBOZI" Generování souboru SPAYD – Parametry příkazu v ČR URL: ${SERVER}/generator/czech/spayd Metoda: GET Parametry: Název typ Popis Pozn.: Detaily parametrů viz specifikace řetězce SPAYD accountPrefix STRING Předčíslí čísla účtu, na který se mají poslat prostředky. accountNumber STRING Číslo účtu, na který se mají poslat prostředky. bankCode STRING Kód banky účtu, na který se mají poslat prostředky. value DOUBLE Částka platby. currency STRING Měna platby. vs STRING Variabilní symbol. ks STRING Konstantní symbol. ss STRING Specifický symbol. identifier STRING Interní ID platby. stage STRING Datum splatnosti ve formátu ISO 8601 (krátky formát pro datum, tj. YYYY-mm-dd) message STRING Zpráva pro příjemce shrink BOOLEAN Použít kompaktní formát (uppercase bez diakritiky). Výchozí hodnota: true. Odpověď v negativním případě: HTTP kód Popis odpovědi, příklad 400 – Bad Request Data nejsou validní, chyby jsou vráceny dle popisu chybové odpovědi. Odpověď v pozitivním případě: HTTP kód Popis odpovědi, příklad 200 – OK Tělo odpovědi obsahuje soubor s validním řetězcem SPAYD s MIME type application/shortpaymentdescriptor a příponou *.spayd, např.: "SPD*1.0*IBAN:CZ5855000000001265098001*AM:480.50*CC:CZK* RF:7004139146*X-SS:1234567890*DT:20120524*MSG:PLATBA ZA ZBOZI" Generování QR kódu SPAYD – Parametry příkazu pro ČR URL: ${SERVER}/generator/czech/image Metoda: GET Parametry: Název typ Popis Pozn.: Detaily parametrů viz specifikace řetězce SPAYD accountPrefix STRING Předčíslí čísla účtu, na který se mají poslat prostředky. accountNumber STRING Číslo účtu, na který se mají poslat prostředky. bankCode STRING Kód banky účtu, na který se mají poslat prostředky. value DOUBLE Částka platby. currency STRING Měna platby. vs STRING Variabilní symbol. ks STRING Konstantní symbol. ss STRING Specifický symbol. identifier STRING Interní ID platby. stage STRING Datum splatnosti ve formátu ISO 8601 (krátky formát pro datum, tj. YYYY-mm-dd) message STRING Zpráva pro příjemce shrink BOOLEAN Použít kompaktní formát (uppercase bez diakritiky). Výchozí hodnota: true. branding BOOLEAN Použít branding QR kódu (rámeček a nápis QR Platba). Výchozí hodnota: true. size INT Rozměr QR kódu v pixelech. Odpověď v negativním případě: HTTP kód Popis odpovědi, příklad 400 – Bad Request Data nejsou validní, chyby jsou vráceny dle popisu chybové odpovědi. Odpověď v pozitivním případě: HTTP kód Popis odpovědi, příklad 200 – OK Tělo odpovědi obsahuje QR kód (application/png), který obsahuje řetězec SPAYD, např.: Generování řetězce SPAYD – základní parametry URL: ${SERVER}/generator/string Metoda: GET Parametry: Název typ Popis Pozn.: Detaily parametrů viz specifikace řetězce SPAYD iban STRING IBAN čísla účtu, na který se mají poslat prostředky. bic STRING Kód banky, u které je veden účet, na který se mají poslat prostředky. value DOUBLE Částka platby. currency STRING Měna platby. sendersReference STRING Identifikátor odesílatele platby. recipientName STRING Název příjemce. identifier STRING Interní ID platby. stage STRING Datum splatnosti ve formátu ISO 8601 (krátky formát pro datum, tj. YYYY-mm-dd) message STRING Zpráva pro příjemce shrink BOOLEAN Použít kompaktní formát (uppercase bez diakritiky). Výchozí hodnota: true. Odpověď v negativním případě: HTTP kód Popis odpovědi, příklad 400 – Bad Request Data nejsou validní, chyby jsou vráceny dle popisu chybové odpovědi. Odpověď v pozitivním případě: HTTP kód Popis odpovědi, příklad 200 – OK Tělo odpovědi obsahuje validní řetězec SPAYD (text/plain), např.: "SPD*1.0*IBAN:CZ5855000000001265098001*AM:480.50*CC:CZK* RF:7004139146*X-SS:1234567890*DT:20120524*MSG:PLATBA ZA ZBOZI" Generování souboru SPAYD – základní parametry URL: ${SERVER}/generator/spayd Metoda: GET Parametry: Název typ Popis Pozn.: Detaily parametrů viz specifikace řetězce SPAYD iban STRING IBAN čísla účtu, na který se mají poslat prostředky. bic STRING Kód banky, u které je veden účet, na který se mají poslat prostředky. value DOUBLE Částka platby. currency STRING Měna platby. sendersReference STRING Identifikátor odesílatele platby. recipientName STRING Název příjemce. identifier STRING Interní ID platby. stage STRING Datum splatnosti ve formátu ISO 8601 (krátky formát pro datum, tj. YYYY-mm-dd) message STRING Zpráva pro příjemce shrink BOOLEAN Použít kompaktní formát (uppercase bez diakritiky). Výchozí hodnota: true. Odpověď v negativním případě: HTTP kód Popis odpovědi, příklad 400 – Bad Request Data nejsou validní, chyby jsou vráceny dle popisu chybové odpovědi. Odpověď v pozitivním případě: HTTP kód Popis odpovědi, příklad 200 – OK Tělo odpovědi obsahuje soubor s řetězcem SPAYD (application/shortpaymentdescriptor) a příponou *.spayd, např.: "SPD*1.0*IBAN:CZ5855000000001265098001*AM:480.50*CC:CZK* RF:7004139146*X-SS:1234567890*DT:20120524*MSG:PLATBA ZA ZBOZI" Generování QR kódu SPAYD – základní parametry URL: ${SERVER}/generator/image Metoda: GET Parametry: Název typ Popis Pozn.: Detaily parametrů viz specifikace řetězce SPAYD iban STRING IBAN čísla účtu, na který se mají poslat prostředky. bic STRING Kód banky, u které je veden účet, na který se mají poslat prostředky. value DOUBLE Částka platby. currency STRING Měna platby. sendersReference STRING Identifikátor odesílatele platby. recipientName STRING Název příjemce. identifier STRING Interní ID platby. stage STRING Datum splatnosti ve formátu ISO 8601 (krátky formát pro datum, tj. YYYY-mm-dd) message STRING Zpráva pro příjemce shrink BOOLEAN Použít kompaktní formát (uppercase bez diakritiky). Výchozí hodnota: true. branding BOOLEAN Použít branding QR kódu (rámeček a nápis QR Platba). Výchozí hodnota: true. size INT Rozměr QR kódu v pixelech. Odpověď v negativním případě: HTTP kód Popis odpovědi, příklad 400 – Bad Request Data nejsou validní, chyby jsou vráceny dle popisu chybové odpovědi. Odpověď v pozitivním případě: HTTP kód Popis odpovědi, příklad 200 – OK Tělo odpovědi obsahuje QR kód (image/png), který obsahuje řetězec SPAYD, např.: © 2018 QR Platba, e-mail ↑ Responsive Theme powered by WordPress