Restful API
RESTful API
Umístění API
- Generování řetězce SIND
- Generování souboru SIND
- Generování QR kódu SIND
Formát specifikace API
Ke zdroji je vždy uveden:
-
Název funkčnosti (př.: “Generování řetězce SIND”, …).
-
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.
Specifické 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á datové typy definované ve specifikaci QR Faktury.
Popis zdrojů API
Generování řetězce SIND
-
URL: ${SERVER}/generator/string
-
Metoda: GET
-
Parametry:
|
Název |
Typ |
Popis |
|---|---|---|
|
qrplatba |
BOOLEAN |
Zapíná režim integrace QR Faktury s QR Platbou. Možné hodnoty: 0 nebo 1. Výchozí hodnota: 0.
|
|
compress |
BOOLEAN |
Zapíná kompaktní formát bez diakritiky. Možné hodnoty: 0 nebo 1. Výchozí hodnota: 0.
|
|
parametry QR Faktury dle specifikace |
dle specifikace |
Parametry dle specifikace QR Faktury, popř. QR Platby (při integraci s QR Platbou). Názvy i hodnoty parametrů musí splňovat specifikaci QR Faktury. Např:
|
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 SIND s kódováním UTF-8 a s MIME type text/plain, např.:"SPD*1.0*ACC:CZ5855000000001265098001+RZBCCZPP*AM:123.12*CC:CZK*DT:20170304* MSG:testovací+faktura*X-VS:1234567890*X-INV:SID%2A1.0%2AID:identfakt123%2A DD:20171030%2ATP:0%2ATD:9%2ASA:0%2AMSG:testovací+faktura%2AON:obj1%2A INI:69274533%2AVIR:CZ7708052000%2ADPPD:20170101%2ATB0:100.00%2AT0:21.00%2AFXA:1"
Výstup odpovídá zapnutému nebo vypnutému režimu integrace QR Faktury s QR Platbou. |
Generování souboru SIND
URL: ${SERVER}/generator/sind Metoda: GET Parametry:
|
Název |
Typ |
Popis |
|---|---|---|
|
qrplatba |
BOOLEAN |
Zapíná režim integrace QR Faktury s QR Platbou. Možné hodnoty: 0 nebo 1. Výchozí hodnota: 0.
|
|
compress |
BOOLEAN |
Zapíná kompaktní formát bez diakritiky. Možné hodnoty: 0 nebo 1. Výchozí hodnota: 0.
|
|
parametry QR Faktury dle specifikace |
dle specifikace |
Parametry dle specifikace QR Faktury, popř. QR Platby (při integraci s QR Platbou). Názvy i hodnoty parametrů musí splňovat specifikaci QR Faktury. Např:
|
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 SIND s kódováním UTF-8 a s MIME type application/shortinvoicedescriptor a příponou *.sind, např.: "SPD*1.0*ACC:CZ5855000000001265098001+RZBCCZPP*AM:123.12*CC:CZK*DT:20170304* MSG:testovací+faktura*X-VS:1234567890*X-INV:SID%2A1.0%2AID:identfakt123%2A DD:20171030%2ATP:0%2ATD:9%2ASA:0%2AMSG:testovací+faktura%2AON:obj1%2A INI:69274533%2AVIR:CZ7708052000%2ADPPD:20170101%2ATB0:100.00%2AT0:21.00%2AFXA:1" |
Generování QR kódu SIND
URL: ${SERVER}/generator/image Metoda: GET Parametry:
|
Název |
Typ |
Popis |
|---|---|---|
|
qrplatba |
BOOLEAN |
Zapíná režim integrace QR Faktury s QR Platbou. Možné hodnoty: 0 nebo 1. Výchozí hodnota: 0.
|
|
compress |
BOOLEAN |
Zapíná kompaktní formát bez diakritiky. Možné hodnoty: 0 nebo 1. Výchozí hodnota: 0.
|
|
branding |
BOOLEAN |
Zapíná branding QR kódu (nápis QR Faktura nebo QR Platba+F na obrázku). Možné hodnoty: 0 nebo 1. Výchozí hodnota: 1.
|
|
qrpixelsize |
INT |
Relativní velikost jednoho pixelu (čtverce) v QR kódu. Možné hodnoty: 1 až 20. Výchozí hodnota: 4. |
|
parametry QR Faktury dle specifikace |
dle specifikace |
Parametry dle specifikace QR Faktury, popř. QR Platby (při integraci s QR Platbou). Názvy i hodnoty parametrů musí splňovat specifikaci QR Faktury. Např:
|
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 SIND, např.:
 |
