Cílem tohoto dokumentu je specifikovat, jak je na straně serveru řešené API pro práci s formátem Short Invoice Descriptor (SIND).
Primárním cílem RESTful API je postkytnout prostředky pro snadnou integraci formátu např. do e-shopu nebo do online systémů pro správu faktur.
Sekundárním cílem je pak poskytnout referenční implementaci formátu SIND.
Umístění API
API je dostupné na základní adrese: https://api.qrfgen.cz/generator/
Jsou k dispozici tyto zdroje:
- Generování řetězce SIND
- Generování souboru SIND
- Generování QR kódu SIND
Příklad – generování QR kódu pro fakturu:
https://api.qrfgen.cz/generator/image?ID=12345&CC=CZK&DD=20170203&DT=20170304&AM=121.00&TP=0&TD=9&SA=0&MSG=testovací%2Bfaktura&ON=obj1&VS=123456789&TB0=100.00&T0=21.00&DPPD=20170101&ACC=CZ5855000000001265098001%2BRZBCCZPP&VIR=CZ7708052000&INI=69274533&qrplatba=1
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.
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”: “0001”,
“description”: “Popis 1. parcialni chyby, napr. vadne pole formulare”
},
{
“code”: “0002”,
“description”: “Popis 2. parcialni chyby, napr. vadne pole formulare”
}
]
}
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 "
|
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ř.: |
