# HTTP API

> Inštalácia služby eKasa, podporované systémy, prvé volanie a pravidlá komunikácie: JSON, adresy, stavové kódy a chybové odpovede.

Zdroj: https://ekasa.ninedigit.sk/docs/rest-api

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](https://ekasa.ninedigit.sk/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](https://ekasa.ninedigit.sk/docs/environment-setup).

## Prvé volanie

Služba počúva na porte **3010**. Či beží, overíte napríklad zistením informácií o produkte:

```bash
curl http://localhost:3010/api/v1/product/info
```

Odpoveď (skrátená):

```json
{
  "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.

[Obrázok: 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:

```text
{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](https://ekasa.ninedigit.sk/docs/security).

### 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:

```text
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](https://ekasa.ninedigit.sk/docs/how-it-works).

### Chybové odpovede

Pri chybe vráti služba objekt podľa štandardu [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) (Problem Details)
doplnený o číselný kód chyby `code`:

```json
{
  "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](https://ekasa.ninedigit.sk/docs/rest-api/error-codes).

- `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](https://ekasa.ninedigit.sk/docs/rest-api/reference).
Špecifikáciu OpenAPI si stiahnete ako [openapi.json](https://ekasa.ninedigit.sk/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

- [Pripojenie a zabezpečenie](https://ekasa.ninedigit.sk/docs/security): Lokálna sieť, internet cez Expose, CORS, prihlásenie a HTTPS.
- [Registrácia dokladu](https://ekasa.ninedigit.sk/docs/receipt-registration): Typy dokladov, položky, platby a výsledok.
- [Chybové kódy](https://ekasa.ninedigit.sk/docs/rest-api/error-codes): Význam kódov v chybových odpovediach.
