How you connect to eKasa depends on where your software runs. It is simplest on the same device and in the shop’s local network. From the internet, eKasa is reachable only over a secure connection.
This article applies to the HTTP API. The .NET library runs directly inside your application and uses no network connection.
Where your software runs
| Your software | eKasa address | Encryption |
|---|---|---|
| on the same device | http://localhost:3010 |
not needed, traffic never leaves the device |
| in the local network | https://ekasa.local:4010 (from version 9.1.0) |
HTTPS recommended (below) |
| in the cloud or another network | the Expose address | always HTTPS |
In the local network, from version 9.1.0 we recommend communicating over HTTPS and connecting by the name
ekasa.local. The connection is encrypted, credentials cannot be intercepted and the name keeps working even if the
device’s IP address changes.
Older versions support only HTTP on the device’s IP address, for example http://192.168.1.24:3010. In that case,
give the device a fixed IP address (for example with a reservation in the router); otherwise it may change after a
restart and your software will not find it.
Access from the internet
Local communication uses unencrypted HTTP, so from version 9.0.4 eKasa does not allow it from the internet. It accepts requests only from:
- the same device (
127.0.0.1,::1), - the private networks
10.0.0.0/8,172.16.0.0/12and192.168.0.0/16and local IPv6 addresses, - the Expose service.
A request from a public IP address, for example through a port forwarded on the router, is rejected with status 403:
{
"type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-100-generalerror",
"title": "Prístup bol odmietnutý",
"status": 403,
"code": -100,
"detail": "Prístup zo siete internet (volanie z IP adresy inej ako 127.0.0.1 (localhost) alebo privátnych adries …) je z bezpečnostných dôvodov povolené iba cez zabezpečené spojenie medzi koncovými bodmi. …"
}
The wording of detail may change between versions. Recognise this situation by status 403 and code -100.
A public IP address, dynamic DNS or port forwarding is therefore not a suitable way of remote access.
If your software runs outside the shop’s local network, you have three options:
- Expose (recommended): built into eKasa, with nothing else to install, no ports to open and an encrypted connection. The Expose credentials are entered directly in the eKasa settings.
- VPN: the remote server gets an address from the shop’s private network and eKasa treats it as a local client. It suits customers who already use a VPN, who need to connect several devices or whole networks, or whose network is managed by an IT team. VPN configuration is not part of eKasa.
- Your own app in the shop’s network (a bridge): it runs on the same device or in the same network as eKasa, calls it locally and talks to your server in its own way. It is a custom solution that you design, secure and operate yourself. Nine Digit does not provide such an app.
You can also put your own reverse proxy in front of eKasa. Test it before going live, though: whether eKasa lets
the request through depends on the proxy configuration and on how headers such as X-Forwarded-For are handled.
Expose
Expose gives eKasa a permanent web address with an encrypted HTTPS connection. eKasa opens the connection to the Expose service itself, so the shop needs neither a public IP address nor router configuration. Requests and responses are the same as with a local connection; only the address changes:
local: POST http://192.168.1.24:3010/api/v1/requests/receipts/cash_register
via Expose: POST https://moja-kaviaren.expose.ninedigit.sk/v1/requests/receipts/cash_register
Only the API is available through Expose, not the web interface. If you are interested in Expose, contact us.
Browser applications (CORS)
If JavaScript on a web page calls eKasa directly from the browser, the browser lets the request through only if eKasa allows the page’s origin. Set the allowed origins in the web interface in the Systém → Nastavenia (System → Settings) menu, on the Ostatné (Other) tab, section CORS:
| Field | What to enter |
|---|---|
| Povolené domény (Allowed origins) | your page’s origin without a path, for example https://pos.example.com |
| Sprístupnené hlavičky (Exposed headers) | response headers your JavaScript needs to read. Content-Range and Content-Disposition are always exposed. |
| Prístup z privátnej siete (Private network access) | Povolený (Allowed) if a page on a public address calls eKasa on a local address. eKasa then answers the Private Network Access preflight request sent by older versions of Chrome. |
Enter each origin separately. The * wildcard (all origins) is not allowed for security reasons.
Chrome and local network access
From version 142, Chrome blocks pages from the internet from accessing the local network, including localhost,
by default. Until the user allows it, calls to eKasa fail with an error in the browser console, for example:
Access to XMLHttpRequest at 'http://localhost:3010' from origin 'https://www.example.com' has been blocked
by CORS policy: Permission was denied for this request to access the 'unknown' address space.
This is not a CORS configuration error in eKasa. On the first call, Chrome shows a prompt to allow local network access. The cashier has to confirm it, or allow access later in Chrome’s site settings. Plan for this step when installing your software on cash registers.
A page loaded over HTTPS may call http://localhost, but not an HTTP address of another device in the network.
The browser blocks such a call as mixed content. In that case use HTTPS (from version 9.1.0) or Expose.
Login
By default eKasa does not require login. If the service is reachable from the local network, we recommend turning it on. In the web interface, in the Systém → Nastavenia menu, on the Ostatné tab, section Prihlásenie (Login), turn on Vyžadovať prihlásenie (Require login) and add at least one user.
Then send the Authorization header with every request using the HTTP Basic scheme: the word Basic, a space and
the string name:password encoded in Base64. For the name admin and password admin:
Authorization: Basic YWRtaW46YWRtaW4=
Without the header or with wrong credentials, eKasa returns status 401.
You can also set up login through the API, in the settings PUT /api/v1/settings. You send the password in plain
text; eKasa stores it and no longer returns it in responses: they contain "password": null and
"hasPassword": true instead:
{
"authentication": {
"enabled": true,
"users": [
{ "userName": "admin", "password": "admin" }
]
}
}
The request body contains the complete settings. Load them first with GET /api/v1/settings, change the
authentication part and send them back. How masked passwords and the hasPassword flags behave is described in
Migration to version 8.
Over HTTP, the name and password are sent unencrypted. In the local network, send them over HTTPS.
HTTPS in the local network
From version 9.1.0, eKasa can serve HTTPS in addition to HTTP. The settings are in the web interface on the Ostatné tab, section Hosting:
| Setting | Default | Description |
|---|---|---|
| Port (HTTP) | 3010 |
unsecured connection |
| HTTPS → Režim (Mode) | Vypnuté (HTTP only) | Zapnuté (HTTP and HTTPS), Presmerovať HTTP na HTTPS (response 307), Len HTTPS (HTTP off) |
| Port (HTTPS) | 4010 |
secured connection |
| Certifikát (Certificate) | self-signed | or your own certificate in PFX format |
In the local network, eKasa is also available under the name ekasa.local, for example https://ekasa.local:4010.
If there are several eKasa devices in the network, give each its own instance name, for example
pokladna2.ekasa.local.
The self-signed certificate is issued for the names ekasa.local, *.ekasa.local and localhost. Clients do not
trust it by default. Download its public part in the settings with the download button or through the API, and
install it on the clients as a trusted certificate:
GET https://ekasa.local:4010/api/v1/settings/hosting/https/certificates/pfx?format=pem
To connect by IP address, you need your own certificate that contains that address.
Recommended setup for operation in a network: mode Presmerovať HTTP na HTTPS (redirect) or Len HTTPS
(HTTPS only), and in the Prihlásenie section the option Vyžadovať HTTPS pre prihlásenie (Require HTTPS for
login). eKasa then rejects credentials sent over HTTP with status 401 before processing them.