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

Pokladna API

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"
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"
}

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
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": {
    },
  • "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.

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,
  • "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
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,
  • "catalogVersion": 47
}

pokladna

pokladna

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
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,
  • "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
Array (<= 200 items)
id
required
string <= 128 characters

Klientský identifikátor řádku, unikátní v rámci zařízení. Stojí na něm idempotence při retry.

createdAt
required
integer <int64>
message
required
string
level
string or null
Enum: "ERROR" "WARN" "INFO" "DEBUG"

Chybějící nebo neznámá hodnota znamená INFO.

tag
string or null
context
string or null

Strukturovaný kontext jako JSON string. Uloží se verbatim i když je nerozparsovatelný.

appVersion
string or null

Responses

Response Schema: application/json
accepted
Array of strings
Array of objects
truncated
boolean
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 - 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": [
    ]
}

Response samples

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