HTTP API

Integrujem cez

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.

Webové rozhranie služby eKasa: stav systému, úložisko a informácie o pokladničnom programe

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.

  • title a texty v errors sú určené pre človeka a ich znenie sa môže meniť.
  • errors je len pri chybe validácie (-900). Kľúčom je cesta k vlastnosti, napríklad Items[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.

Kam ďalej

Esc

↑↓ výberEnter otvoriťEsc zavrieť

Chýba vám niečo v dokumentácii?

Napíšte nám, s čím potrebujete pomôcť. Ozveme sa do pár hodín.

Údaje použijeme len na odpoveď. Viac v ochrane osobných údajov.