Skip to main content
API docs by Redocly

Comgate Pokladna REST API (1.0)

Interní API pro aplikaci Comgate Pokladna: aktivace zařízení, vydávání krátkodobých tokenů a doručování konfigurace.

Aktivace (jednou za instalaci)
POST /pos/pokladna-api/activate pod bootstrap HTTP Basic přístupem. Fyzický POS se prokáže sériovým číslem (zero-touch), SoftPOS aktivačním kódem vydaným pro propojení obchodu. Odpověď obsahuje dlouhoživotný opaque deviceToken a plnou konfiguraci.

Autentizace (opakovaně)
POST /pos/pokladna-api/authenticate s Authorization: Bearer [deviceToken] vrátí krátkodobý JWT a configVersion.

Konfigurace
GET /pos/pokladna-api/config s Authorization: Bearer [JWT]. Kdykoli se configVersion liší od uložené, stáhněte konfiguraci znovu — změny se doručují bez push notifikací.

Chybové stavy — závazné pravidlo pro klienta
Aplikace se přepne do stavu „deaktivováno“ VÝHRADNĚ na errorCode == 'DEVICE_REVOKED'. TOKEN_EXPIRED znamená jeden refresh tokenu, RATE_LIMITED, 5xx a timeouty znamenají backoff a nic víc — jinak by výpadek internetu zamkl pokladnu.

Pokladna API

Vše, s čím komunikuje samotná pokladna: aktivace, vydávání tokenů, konfigurace, nahrávání transakcí, uzávěrek a logů a katalog položek. Všechno vyžaduje přístupy zařízení.

Health check

Ověření dostupnosti. Vrací HTTP 200 s prázdným tělem.

Responses

Aktivace zařízení

Vydá dlouhoživotný device token a plnou konfiguraci. Fyzický POS se identifikuje sériovým číslem, SoftPOS aktivačním kódem svého propojení obchodu. Opakování volání je bezpečné a nepotřebuje idempotenční klíč — poslední vydaný token vyhrává a předchozí padá, protože aplikace ještě žádný token nedrží. Uložte si connectionId; pokud pozdější aktivace vrátí jiné, aplikace ji musí odmítnout a vyžádat nejdřív vymazání dat.

Authorizations:
basicAuth
Request Body schema: application/json
required
platform
required
string
Enum: "POS" "SOFTPOS"

Musí odpovídat typu terminálu na propojení obchodu.

serialNumber
string

Povinné pro POS, u SOFTPOS musí být prázdné.

activationCode
string

Povinné pro SOFTPOS, u POS musí být prázdné.

appVersion
string <= 64 characters

Nepovinná verze aplikace, drží se pro diagnostiku.

Responses

Response Schema: application/json
deviceToken
string
deviceId
integer
configVersion
integer
connectionState
string
Enum: "ACTIVE" "PENDING_DEACTIVATION"
config
object

Stejná struktura jako GET /pos/pokladna-api/config.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Request samples

Content type
application/json
{
  • "platform": "POS",
  • "serialNumber": "N920WA03787",
  • "activationCode": "A1B2C3D4",
  • "appVersion": "1.4.2 (142)"
}

Response samples

Content type
application/json
{
  • "deviceToken": "cgp_1_9x3Kf7QpZ2mR8vTn1LbY4sHc0eJdWgAu6iOo5r2NkPQ",
  • "deviceId": 1234,
  • "configVersion": 1,
  • "connectionState": "ACTIVE",
  • "config": { }
}

Výměna device tokenu za JWT

Device token předejte v Authorization: Bearer [deviceToken]. Vrací krátkodobý JWT pro ostatní endpointy a configVersion — kdykoli se liší od uložené, stáhněte konfiguraci znovu. Revokovaný nebo překonaný device token vrací 401 DEVICE_REVOKED, což je jediný signál, který aplikaci přepne do stavu „deaktivováno“.

Authorizations:
bearerAuth
Request Body schema: application/json
optional
appVersion
string <= 64 characters

Responses

Response Schema: application/json
token
string
expiry
string
configVersion
integer
catalogVersion
integer

Nejvyšší verze položky v katalogu zařízení. Když se liší od uložené, stáhněte katalog položek znovu.

connectionState
string
Enum: "ACTIVE" "PENDING_DEACTIVATION"
minAppVersionCode
integer or null

Nejnižší versionCode aplikace, který smí se zařízením pracovat. Pod ním se aplikace sama uzamkne a vyžádá aktualizaci. null znamená bez zámku, což je i stav, kdy není nic nastaveno. Je to páka pro řízení releasu, takže hodnota je pro všechna zařízení stejná. Vrací ji i authenticate, aby se uzamčená aplikace dozvěděla o odemčení bez stahování konfigurace.

object or null

Je v odpovědi jen tehdy, když si podpora vyžádala diagnostiku z tohoto zařízení. Posbírejte logy za posledních days dní, nahrajte je na /logs s level: DEBUG a do obálky dávky vložte requestId - teprve tím se požadavek označí za vyřízený. Povel se do té doby opakuje v odpovědi na authenticate i v každé sync odpovědi, takže už vyřízené requestId ignorujte.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Request samples

Content type
application/json
{
  • "appVersion": "1.4.2 (142)"
}

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJwb2tsYWRuYToxMjM0In0.dummy-signature",
  • "expiry": "2026-08-06T10:15:00+00:00",
  • "configVersion": 7,
  • "catalogVersion": 47,
  • "connectionState": "ACTIVE",
  • "minAppVersionCode": 142,
  • "requestDebugLogs": {
    }
}

Konfigurace zařízení

Plná konfigurace pro zařízení autentizované JWT. env rozhoduje, se kterou platební aplikací se komunikuje, a nikdy se neodvozuje z prefixu TID. currencies se řídí nastavením obchodu. Revokace se kontroluje na každém volání, takže revokované zařízení přestane konfiguraci číst okamžitě, ne až po vypršení JWT.

Authorizations:
bearerAuth

Responses

Response Schema: application/json
configVersion
integer
connectionId
integer
shopId
integer
platform
string
Enum: "POS" "SOFTPOS"
serialNumber
string or null
env
string
Enum: "PROD" "ACC" "INT"

Prostředí terminálové sítě z propojení obchodu.

terminalId
string
merchantId
string
connectionState
string
Enum: "ACTIVE" "PENDING_DEACTIVATION"
object
Array of objects
object or null

Jak pokladna nabízí spropitné. V odpovědi je jen tehdy, když se nastavilo v administraci - dokud klíč chybí, server názor nemá a rozhoduje volba v zařízení. Na rozdíl od variableSymbol tu není stav napůl: buď je režim nastavený a rozhoduje server včetně procent, nebo se neposílá nic. Nastavení spropitného na propojení patří fyzickému terminálu (stahuje si ho z TMS) a s pokladnou nesouvisí.

receiptPrint
string
Enum: "OFF" "MERCHANT" "CUSTOMER" "MERCHANT_AND_CUSTOMER"

Komu pokladna tiskne prodejní účtenku. Nastavuje se per zařízení, protože na terminálu s Comgate Pokladnou tisk vlastní pokladna - tisk na terminálu se při aktivaci vypíná. U SoftPOSu je vždy OFF, není na čem tisknout.

receiptHeader
string
Enum: "BASIC" "PREMISES" "BILLING"

Které údaje patří do hlavičky účtenky. BASIC = název provozovny, ulice, PSČ a město, bez IČ. PREMISES = název organizace plus celá adresa provozovny, IČ a DIČ. BILLING = název organizace, název provozovny a adresa sídla (merchant.seat*), IČ a DIČ. Je to totéž nastavení, podle kterého skládal účtenku terminál, takže dvě účtenky jednoho obchodníka vypadají stejně.

documentDeviceCode
string or null

Dvojčíslí zařízení v čísle dokladu (T DD RR PPPPP), přiděluje ho server jako volné v rámci organizace a už ho nemění - pořadová část je lokální čítač per kód, takže nový kód rozjede řadu znovu. null znamená nepřidělený (v organizaci není volné dvojčíslí) a kód si volí pokladna sama.

reversalEnabled
boolean

Smí obchodník stornovat karetní platbu? Týká se jen karetních operací - refundaci QR platby neomezuje.

refundEnabled
boolean

Smí obchodník refundovat karetní platbu (návrat, i částečný)? Je to jiné oprávnění než reversalEnabled a drží se per obchod, ne per propojení. Týká se jen karetních operací.

object

Kdy si obchodník přeje automatickou uzávěrku. Pokladna ji musí udělat sama: terminál v režimu ECR - a Comgate Pokladna ECR vždy potřebuje - má vlastní plánovač uzávěrky vypnutý.

qrMoreOptions
boolean

Smí pokladna nabídnout u nepotvrzené QR platby další možnosti (vydat zboží bez potvrzení, požadovat jiný způsob platby)? Vypnuto znamená, že obsluha jen čeká do expirace platby. Nastavuje se per zařízení.

object or null

Pravidla pro variabilní symbol, který smí obsluha zadat. V odpovědi je jen tehdy, když se nastavil v administraci - dokud klíč chybí, server názor nemá a rozhoduje přepínač v zařízení. type NUMERIC znamená jen číslice (max 10, naše numerická klávesnice), ALPHANUMERIC volný text a zařízení ukáže systémovou klávesnici. mode OFF zadání schová, OPTIONAL ho nabídne, REQUIRED vyžaduje. Obojí vynucuje aplikace: upload, který je poruší, se přesto uloží a jen zaloguje, aby se neztratil reálný prodej. Typ je pokyn pro klávesnici, ne pro ukládání - text server přijme tak i tak.

minAppVersionCode
integer or null

Nejnižší versionCode aplikace, který smí se zařízením pracovat. Pod ním se aplikace sama uzamkne a vyžádá aktualizaci. null znamená bez zámku, což je i stav, kdy není nic nastaveno. Je to páka pro řízení releasu, takže hodnota je pro všechna zařízení stejná. Vrací ji i authenticate, aby se uzamčená aplikace dozvěděla o odemčení bez stahování konfigurace.

object
Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response samples

Content type
application/json
{
  • "configVersion": 7,
  • "connectionId": 136602,
  • "shopId": 16692,
  • "platform": "POS",
  • "serialNumber": "N920WA03787",
  • "env": "PROD",
  • "terminalId": "GT102626",
  • "merchantId": "G2016692",
  • "connectionState": "ACTIVE",
  • "merchant": {
    },
  • "currencies": [
    ],
  • "tip": {
    },
  • "receiptPrint": "MERCHANT_AND_CUSTOMER",
  • "receiptHeader": "BILLING",
  • "documentDeviceCode": "24",
  • "reversalEnabled": true,
  • "refundEnabled": true,
  • "autoClosing": {
    },
  • "qrMoreOptions": false,
  • "variableSymbol": {
    },
  • "minAppVersionCode": 142,
  • "qrApi": {}
}

Nahrání transakcí

Nahraje dávku maximálně 50 transakcí. Identita záznamu je klientské id a server podle něj upsertuje, takže opakované nahrání záznamu, který se po synchronizaci změnil (storno, refundovaná částka, orazítkování uzávěrkou, výdej dokladu), je očekávané — pošlete ho znovu s vyšší syncVersion. Záznam s nižší syncVersion, než je uložená, se zahodí, ale i tak se ackne, protože z pohledu klienta je vyřízený.

Dávka se nikdy neodmítá celá kvůli jednomu záznamu. Vadný záznam je v rejected a NEackne se, takže příští dávka obsahuje už jen jeho; všechno ostatní se ackne a odejde z fronty. Neznámý type nebo status se coercuje na UNKNOWN, nerozparsovatelný saleJson/rawJson se uloží verbatim jako JSON string. Dávka nad limit se zpracuje do limitu a odpoví truncated: true.

Sémantika acku: za synchronizované označte jen ID vrácená v accepted. Částky jsou integery v minoritních jednotkách, měna je alfabetický kód.

Authorizations:
bearerAuth
Request Body schema: application/json
required
pendingCount
integer or null

Celkový počet nesynchronizovaných řádků na zařízení (transakce + uzávěrky) v momentě stavby dávky. Zobrazuje se v administraci; bez něj si čítač drží předchozí hodnotu.

required
Array of objects

Responses

Response Schema: application/json
accepted
Array of strings

ID, která server přijal. Za synchronizovaná označte JEN tato.

Array of objects
truncated
boolean

Dávka přesáhla limit a zpracovala se jen do něj. Zbytek pošlete dalším voláním — není to chyba.

configVersion
integer

Aktuální verze konfigurace, přepočítaná při každém syncu. Když se liší od uložené, stáhněte konfiguraci znovu.

object or null

Je v odpovědi jen tehdy, když si podpora vyžádala diagnostiku z tohoto zařízení. Posbírejte logy za posledních days dní, nahrajte je na /logs s level: DEBUG a do obálky dávky vložte requestId - teprve tím se požadavek označí za vyřízený. Povel se do té doby opakuje v odpovědi na authenticate i v každé sync odpovědi, takže už vyřízené requestId ignorujte.

catalogVersion
integer

Nejvyšší verze položky v katalogu zařízení. Když se liší od uložené, stáhněte katalog položek znovu - mění se jak uploadem ze zařízení, tak editací obsluhou v administraci.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Request samples

Content type
application/json
{
  • "pendingCount": 63,
  • "records": [
    ]
}

Response samples

Content type
application/json
{
  • "accepted": [
    ],
  • "rejected": [
    ],
  • "truncated": false,
  • "configVersion": 7,
  • "requestDebugLogs": {
    },
  • "catalogVersion": 47
}

Nahrání uzávěrek

Nahraje uzávěrky — jeden záznam na měnu jedné uzávěrky. Uzávěrka je immutable součet, takže opakované nahrání téhož id jen přepíše totály a žádnou verzi nepotřebuje.

Částečný ack je tady normální. Klient posílá všechny pending uzávěrky bez limitu, takže server zpracuje 200 z nich, ackne je a odpoví truncated: true; zbytek dorazí dalším voláním. Odmítnout celou dávku by znamenalo, že zařízení s víc než 200 uzávěrkami nikdy neprojde.

Uzávěrka se samými nulami je legitimní — dostane ji měna, ve které byla jen storna, jinak by se její transakce nikdy neorazítkovaly.

Authorizations:
bearerAuth
Request Body schema: application/json
required
pendingCount
integer or null
required
Array of objects

Responses

Response Schema: application/json
accepted
Array of strings
Array of objects
truncated
boolean
configVersion
integer
object or null

Je v odpovědi jen tehdy, když si podpora vyžádala diagnostiku z tohoto zařízení. Posbírejte logy za posledních days dní, nahrajte je na /logs s level: DEBUG a do obálky dávky vložte requestId - teprve tím se požadavek označí za vyřízený. Povel se do té doby opakuje v odpovědi na authenticate i v každé sync odpovědi, takže už vyřízené requestId ignorujte.

catalogVersion
integer

Nejvyšší verze položky v katalogu zařízení. Když se liší od uložené, stáhněte katalog položek znovu - mění se jak uploadem ze zařízení, tak editací obsluhou v administraci.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Request samples

Content type
application/json
{
  • "pendingCount": 5,
  • "records": [
    ]
}

Response samples

Content type
application/json
{
  • "accepted": [
    ],
  • "rejected": [
    ],
  • "truncated": false,
  • "configVersion": 7,
  • "requestDebugLogs": {
    },
  • "catalogVersion": 47
}

Download katalogu položek

Vrátí katalog položek zařízení. S parametrem since, do kterého patří poslední známý catalogVersion, přijdou jen položky změněné po něm; bez since přijde celý katalog. Nerozparsovatelné since se bere jako chybějící a vrátí se celý katalog — stáhnout ho znovu je vždy bezpečné, kdežto 400 by vzalo jedinou cestu, jak se ke katalogu dostat.

Smazané položky se vracejí s active: false, nikdy se nevynechávají — klient je musí zneaktivnit i u sebe.

Authorizations:
bearerAuth
query Parameters
since
integer <int64>
Example: since=41

Poslední známý catalogVersion.

Responses

Response Schema: application/json
catalogVersion
integer

Nejvyšší verze položky v katalogu zařízení. Uložte si ji a posílejte zpátky jako since.

Array of objects
Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response samples

Content type
application/json
{
  • "catalogVersion": 47,
  • "items": [
    ]
}

Delta upload katalogu položek

Nahraje změněné položky — deltu, ne kompletní stav. Konflikt řeší updatedAt: vyhrává vyšší hodnota, nižší se zahodí, ale i tak se ackne.

Mazání je active: false. Položka v katalogu zůstává, takže uložená účtenka, která se na ni odkazuje, si zachová smysl.

Sémantika acku je stejná jako u transakcí: za synchronizované označte jen ID vrácená v accepted.

⚠ catalogVersion v této odpovědi je nejvyšší verze vlastních zápisů, případně 0, když se nezapsalo nic. Je to hodnota k porovnání, nikdy cursor: since smí posunout jen odpověď na GET /items. Uložením téhle hodnoty jako since byste přeskočili změnu z administrace s nižší verzí, kterou zařízení ještě nestáhlo — a nikdo si o ni už nikdy neřekne.

Authorizations:
bearerAuth
Request Body schema: application/json
required
required
Array of objects <= 200 items
Array (<= 200 items)
id
required
string <= 128 characters

Klientský identifikátor položky, unikátní v rámci zařízení.

name
required
string
price
required
integer

Cena s DPH v minoritních jednotkách.

currency
string or null <= 128 characters
vatRatePercent
integer or null
active
boolean

False znamená smazanou položku. Hard delete neexistuje — položka v katalogu zůstává a nenabízí se, takže účtenka, která se na ni odkazuje, si zachová smysl.

sortOrder
integer or null
updatedAt
integer or null <int64>

Čas poslední změny na zařízení, epoch milisekundy. Rozhoduje konflikty — vyhrává vyšší hodnota. Nižší se zahodí, ale i tak se ackne, protože z pohledu klienta je vyřízená.

Responses

Response Schema: application/json
accepted
Array of strings
Array of objects
truncated
boolean
configVersion
integer
object or null

Je v odpovědi jen tehdy, když si podpora vyžádala diagnostiku z tohoto zařízení. Posbírejte logy za posledních days dní, nahrajte je na /logs s level: DEBUG a do obálky dávky vložte requestId - teprve tím se požadavek označí za vyřízený. Povel se do té doby opakuje v odpovědi na authenticate i v každé sync odpovědi, takže už vyřízené requestId ignorujte.

catalogVersion
integer

Nejvyšší verze vlastních zápisů, 0 když se nezapsalo nic. Hodnota k porovnání, nikdy cursor — since smí posunout jen GET /items.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Request samples

Content type
application/json
{
  • "records": [
    ]
}

Response samples

Content type
application/json
{
  • "accepted": [
    ],
  • "rejected": [
    ],
  • "truncated": false,
  • "configVersion": 7,
  • "requestDebugLogs": {
    },
  • "catalogVersion": 48
}

Upload logů ze zařízení

Nahraje provozní logy ze zařízení, aby podpora mohla dohledávat na dálku bez přístupu k telefonu. Dávka maximálně 200 řádků.

Nic se tady neodmítá kvůli obsahu. Chybějící level znamená INFO, neznámý se coercuje na INFO, nerozparsovatelný context se uloží verbatim a message nad 4000 znaků se zkrátí a označí — nikdy neodmítne. Diagnostika nesmí umět zaseknout frontu.

Každý řádek potřebuje vlastní id: ack je per ID a idempotence při retry na něm stojí. Řádek je append-only — opakované nahrání téhož id ponechá to, co došlo poprvé.

⚠ Do logu se nesmí dostat device token, JWT ani přístupy k QR API. Server to ověřit nemůže, je to požadavek na klienta.

Authorizations:
bearerAuth
Request Body schema: application/json
required
required
Array of objects <= 200 items
requestId
string or null <= 128 characters

requestDebugLogs.requestId, na který tato dávka odpovídá. Označí požadavek za vyřízený a zastaví opakování povelu. Neznámá nebo už vyřízená hodnota nic nezmění a není to chyba.

Responses

Response Schema: application/json
accepted
Array of strings
Array of objects
truncated
boolean
configVersion
integer
object or null

Je v odpovědi jen tehdy, když si podpora vyžádala diagnostiku z tohoto zařízení. Posbírejte logy za posledních days dní, nahrajte je na /logs s level: DEBUG a do obálky dávky vložte requestId - teprve tím se požadavek označí za vyřízený. Povel se do té doby opakuje v odpovědi na authenticate i v každé sync odpovědi, takže už vyřízené requestId ignorujte.

catalogVersion
integer

Nejvyšší verze položky v katalogu zařízení. Když se liší od uložené, stáhněte katalog položek znovu - mění se jak uploadem ze zařízení, tak editací obsluhou v administraci.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Request samples

Content type
application/json
{
  • "records": [
    ],
  • "requestId": "9f1c4e2b7a8d4f10b3c5d6e7f8a9b0c1"
}

Response samples

Content type
application/json
{
  • "accepted": [
    ],
  • "rejected": [
    ],
  • "truncated": false,
  • "configVersion": 7,
  • "requestDebugLogs": {
    },
  • "catalogVersion": 47
}

Pokladní doklady

Veřejný doklad pro plátce, který si otevře z QR kódu zobrazeného pokladnou po zaplacení. Záměrně bez autentizace a s jiným publikem než zbytek API - plátce žádné přístupy zařízení nemá.

Doklad pro plátce

Veřejná stránka s dokladem pro plátce, kterou si otevře z QR kódu zobrazeného pokladnou po zaplacení. Bez autentizace - plátce žádné přístupy zařízení nemá. Token vyrábí aplikace v okamžiku platby a nahraje ho spolu s transakcí; je neuhodnutelný a neprozradí nic o jiných transakcích.

Neznámý token není 404. QR kód vidí plátce hned po zaplacení, ale řádek dorazí na server až synchronizací - v offline provozovně klidně za hodinu. Stránka proto odpoví 200 s informací doklad se připravuje a sama se obnoví. Vedlejší efekt je, že nedoručený a vymyšlený token jsou k nerozeznání.

QR kód nese holou URL bez parametrů, protože její délka řídí hustotu kódu; volbu jazyka a stažení PDF nabídne až stránka sama.

path Parameters
token
required
string
Example: 1234-Rt5bQw7Kx2Lm9Np4Vs1Zc3

Token dokladu ve tvaru deviceId-náhoda, který vyrobí aplikace a pošle jako receiptToken spolu s transakcí.

query Parameters
format
string
Default: "html"
Enum: "html" "pdf"

html vykreslí stránku, pdf vrátí tentýž doklad jako soubor ke stažení.

type
string
Enum: "receipt" "invoice" "cancel_confirmation"

receipt je stvrzenka o platbě, invoice účtenka o prodeji. Business to drží odděleně a aplikace taky. cancel_confirmation je lístek nepotvrzená QR platba, který pokladna vydá při volbě „Zrušit platbu a vydat potvrzení“ - není to doklad o platbě a je dostupný jen ke zrušené QR platbě, jinak je odpověď 400.

Bez parametru si podobu určí server sám: zrušená QR platba dostane cancel_confirmation, všechno ostatní receipt. QR kód nese holou URL, takže rozhodnout to nemá co jiného.

lang
string
Default: "cs"
Enum: "cs" "sk" "en"

Jazyk dokladu. Užší výčet než zbytek brány záměrně - doklad má vlastní sadu řetězců.

Responses

Response Schema: application/json
errorMessage
string

Chybová zpráva pro člověka.

errorCode
string
Enum: "INVALID_REQUEST" "UNAUTHORIZED" "TOKEN_EXPIRED" "DEVICE_REVOKED" "ACTIVATION_BLOCKED" "CONNECTION_DEACTIVATED" "CONNECTION_NOT_READY" "DEVICE_NOT_REGISTERED" "ACTIVATION_CODE_UNKNOWN" "ACTIVATION_CODE_USED" "AMBIGUOUS_INPUT" "RATE_LIMITED" "INTERNAL_ERROR"

Strojově čitelný kód chyby. Do stavu „deaktivováno“ smí aplikaci přepnout jedině DEVICE_REVOKED. Nevalidní JSON tělo je odmítnuto před dispatchem a vrací 400 bez errorCode — berte ho jako INVALID_REQUEST.

Response samples

Content type
application/json
{
  • "errorMessage": "Device is not registered",
  • "errorCode": "DEVICE_NOT_REGISTERED"
}