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:

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.
amount 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.
date 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
compress 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.
amount 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.
date 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
compress 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.
amount 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.
date 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
compress 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ř.:

QR Platba - QR kód

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.
amount 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.
date 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
compress 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.
amount 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.
date 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
compress 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.
amount 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.
date 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
compress 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ř.:
QR Platba - QR kód