Přeskočit na hlavní obsah
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
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.

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,
  • "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 čítat 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 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": {}
}