Pri HTTP API beží eKasa ako služba na počítači alebo ako aplikácia na Androide. Váš softvér s ňou komunikuje cez HTTP a JSON, takže na programovacom jazyku nezáleží. API je rovnaké na všetkých platformách.
Inštalácia
Inštalátory nájdete na stránke Na prevzatie. Služba sa po inštalácii spustí sama.
| Systém | Verzia | Inštalácia |
|---|---|---|
| Windows | 10 a novší, 32 aj 64-bit | MSI |
| Windows | 7, 8 a 8.1 | MSI pre staršie systémy |
| macOS | 11 Big Sur a novší, Apple Silicon aj Intel | PKG |
| Linux | x64 (Ubuntu, Debian, Fedora, RHEL…) a ARM64 (Raspberry Pi 3+ s Ubuntu Server) | SH |
| Android | tablet alebo kiosk s Androidom 10 a novším | APK súbor |
| Android | platobný terminál | obchod s aplikáciami výrobcu |
Na platobné terminály sa eKasa neinštaluje z APK súboru, ale z obchodu s aplikáciami, ktorý je v termináli: na zariadeniach Sunmi zo Sunmi Store, na PAX z MAX Store a na iMin z iMin Store. Terminály Ingenico sa dodávajú s nainštalovanou eKasou.
Aplikácia obsahuje všetko potrebné, .NET netreba inštalovať zvlášť. Na vývoj stačí In-Memory úložisko bez hardvéru, ako popisuje Príprava prostredia.
Prvé volanie
Služba počúva na porte 3010. Či beží, overíte napríklad zistením informácií o produkte:
curl http://localhost:3010/api/v1/product/info
Odpoveď (skrátená):
{
"vendorName": "Nine Digit, s. r. o.",
"api": { "name": "Portos eKasa API", "version": "9.0.7" },
"chdu": { "name": "Memory Record Repository", "version": "1.0" },
"operatingSystem": { "platform": "MacOS", "architecture": "Arm64" }
}
Na tej istej adrese je aj webové rozhranie služby (http://localhost:3010) s nastaveniami, stavom systému
a formulármi na skúšobnú registráciu dokladu.

Pravidlá komunikácie
Adresa
Adresa každej požiadavky sa skladá z adresy zariadenia, portu a cesty s verziou API:
{server_address}/api/v1/{cesta}
{server_address} je adresa služby s portom, napríklad http://localhost:3010, ak váš softvér beží na tom istom
zariadení. Inak je to IP adresa zariadenia v lokálnej sieti, napríklad http://192.168.1.20:3010. Rovnaký zápis
{server_address} používajú príklady v celej dokumentácii. Pripojenie z inej siete alebo z internetu popisuje Pripojenie a zabezpečenie.
Formát
Požiadavky aj odpovede sú v JSON s kódovaním UTF-8 a názvy vlastností sú v tvare camelCase. Do každej požiadavky s telom pridajte hlavičky:
Content-Type: application/json; charset=utf-8
Accept: application/json
Sumy, ceny a množstvá odporúčame posielať ako reťazce (napríklad "3.00"), aby sa pri prevode
nestratila presnosť.
Stavové kódy
| Kód | Význam |
|---|---|
200 |
Požiadavka je spracovaná. |
202 |
Doklad je prijatý, ale ešte nie je zaevidovaný v systéme eKasa, alebo ho systém eKasa odmietol. Výsledok je v tele odpovede. |
400 |
Požiadavka obsahuje neplatné údaje. |
401 |
Chýbajú prihlasovacie údaje alebo nie sú správne. |
403 |
Operáciu nemožno vykonať, napríklad pre stav úložiska alebo pri prístupe z internetu. |
404 |
Záznam sa nenašiel. |
500 |
Neočakávaná chyba služby. |
Ako vyhodnotiť výsledok registrácie dokladu (isSuccessful je true, null alebo false), popisuje
Ako funguje eKasa.
Chybové odpovede
Pri chybe vráti služba objekt podľa štandardu RFC 9457 (Problem Details)
doplnený o číselný kód chyby code:
{
"type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#900-validationerror",
"title": "Validácia zlyhala",
"status": 400,
"code": -900,
"errors": {
"Text": ["Pole 'Text' nesmie byť prázdne."]
},
"instance": "/api/v1/printers/print"
}
Nezameňte dve čísla v odpovedi:
| Pole | Čo to je | Hodnoty |
|---|---|---|
status |
stavový kód HTTP, rovnaký ako v hlavičke odpovede | kladné: 400, 403, 500… |
code |
kód chyby eKasy, ktorý presne určuje príčinu | vždy záporné: -900, -100… |
code je vždy záporný, aby sa nedal pomýliť so stavovým kódom HTTP. Jednému stavu zodpovedá viac kódov chyby,
napríklad 403 môže vzniknúť pre stav úložiska aj pre prístup z internetu. Chybu v kóde preto spracujte podľa
code. Zoznam kódov je v článku Chybové kódy.
titlea texty verrorssú určené pre človeka a ich znenie sa môže meniť.errorsje len pri chybe validácie (-900). Kľúčom je cesta k vlastnosti, napríkladItems[0].Name.
Referencia API
Všetky endpointy s parametrami, dátovými modelmi, odpoveďami a príkladmi sú v referencii HTTP API. Špecifikáciu OpenAPI si stiahnete ako openapi.json a môžete z nej vygenerovať klienta pre svoj jazyk.
Nainštalovaná služba má popis svojej verzie aj priamo na adrese http://localhost:3010/docs, špecifikáciu na
http://localhost:3010/swagger/v1/swagger.json.