API section

Self-service kiosk

The Self-service kiosk module: cash acceptance with CCNET bill acceptors and ccTalk coin acceptors up to an amount (escrow, change, customer stop; events cash.accepted and cash.notice), a bill acceptor emulator, browser kiosk mode. Needs the kiosk module in the key (except the emulator).

GET	`/api/v1/kiosk`	Kiosk mode
PUT	`/api/v1/kiosk`	Configure kiosk mode
POST	`/api/v1/kiosk/stop`	Close the kiosk browser
POST	`/api/v1/kiosk/start`	Start the kiosk browser
POST	`/api/v1/cash-acceptors/{number}/insert`	Insert a bill into the emulator
GET	`/api/v1/cash-acceptance`	Running acceptance session
POST	`/api/v1/cash-acceptance`	Accept cash
POST	`/api/v1/cash-acceptance/stop`	Stop accepting
GET	`/api/v1/cash-acceptors`	Bill and coin acceptors

Kiosk mode#

GET/api/v1/kiosk

Settings and whether the kiosk browser is running

Response 200 application/json

Fields · Status

enabledboolean
unlockedboolean

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'http://localhost:7790/api/v1/kiosk'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/kiosk' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Configure kiosk mode#

PUT/api/v1/kiosk

{"enabled":true,"url":"https://kiosk.example.ru","browser":"auto","silentPrint":true,"restartSec":3}. Включённый режим сразу запускает браузер во весь экран и поднимает его с агентом; выключенный — закрывает

Request body application/json required

Fields · Settings

enabledboolean

JSON

{
  "enabled": false
}

Response 200 application/json

Fields · Status

enabledboolean
unlockedboolean

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X PUT 'http://localhost:7790/api/v1/kiosk' \
  -H 'Content-Type: application/json' \
  --data '{"enabled":false}'

curl

curl -X PUT 'https://cloud.hw-connector.ru/agent/api/v1/kiosk' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Content-Type: application/json' \
  --data '{"enabled":false}'

Close the kiosk browser#

POST/api/v1/kiosk/stop

For maintenance: until the next start or agent restart

Response 200 application/json

Fields · Status

enabledboolean
unlockedboolean

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X POST 'http://localhost:7790/api/v1/kiosk/stop'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/kiosk/stop' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Start the kiosk browser#

POST/api/v1/kiosk/start

Response 200 application/json

Fields · Status

enabledboolean
unlockedboolean

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X POST 'http://localhost:7790/api/v1/kiosk/start'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/kiosk/start' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Insert a bill into the emulator#

POST/api/v1/cash-acceptors/{number}/insert

Bill acceptor emulator only: the bill is accepted in the running session

Parameters

Name	In	Type	Description
`number`required	path	integer int32

Request body application/json required

Fields · Insert

valuenumber

JSON

{
  "value": 1.5
}

Response 200

No body.

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X POST 'http://localhost:7790/api/v1/cash-acceptors/1/insert' \
  -H 'Content-Type: application/json' \
  --data '{"value":1.5}'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/cash-acceptors/1/insert' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Content-Type: application/json' \
  --data '{"value":1.5}'

Running acceptance session#

GET/api/v1/cash-acceptance

How much has been accepted; 404 if there is no session

Response 200 application/json

Fields · Result

validboolean
errorsarray of Issue
8 fields · Issue
- codestring
- severitystring
  values: ERROR WARNING
- atstring date-time
- registerinteger int32
- terminalinteger int32
- fdinteger int64
- amountinteger int64
- messagestring
warningsarray of Issue
8 fields · Issue
- codestring
- severitystring
  values: ERROR WARNING
- atstring date-time
- registerinteger int32
- terminalinteger int32
- fdinteger int64
- amountinteger int64
- messagestring

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'http://localhost:7790/api/v1/cash-acceptance'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/cash-acceptance' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Accept cash#

POST/api/v1/cash-acceptance

Operation

Операция cash-acceptance: включает приёмники и ждёт, пока внесут amount (пусто — пока не остановят). Каждая купюра — событие cash.accepted с набранной суммой, отбраковка и сбои — cash.notice. result: received — принято, change — сверх суммы (сдачу выдаёт программа), status — COMPLETED, STOPPED, TIMEOUT или ERROR. Принятые деньги всегда в result, даже если приёмник отказал посреди сеанса. Без ключа модуля — 402 LICENSE_REQUIRED (кроме эмулятора)

Parameters

Name	In	Type	Description
`Idempotency-Key`required	header	string
`Prefer`	header	string

Request body application/json

Fields · Request

originstring
firstAtstring date-time
lastAtstring date-time
requestsinteger int32

JSON

{
  "origin": "string",
  "firstAt": "2026-11-01T19:00:00+03:00",
  "lastAt": "2026-11-01T19:00:00+03:00",
  "requests": 1
}

Response 200 application/json

Fields · Operation

idstring uuid
typestring
idempotencyKeystring
resourcesarray of string
statusstring
values: QUEUED RUNNING SUCCEEDED FAILED UNKNOWN
stagestring
createdAtstring date-time
startedAtstring date-time
finishedAtstring date-time
resultany value
errorOperationError
3 fields · OperationError
- codestring
- messagestring
- detailsany value
warningsarray of string

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X POST 'http://localhost:7790/api/v1/cash-acceptance' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"origin":"string","firstAt":"2026-11-01T19:00:00+03:00","lastAt":"2026-11-01T19:00:00+03:00","requests":1}'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/cash-acceptance' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"origin":"string","firstAt":"2026-11-01T19:00:00+03:00","lastAt":"2026-11-01T19:00:00+03:00","requests":1}'

Stop accepting#

POST/api/v1/cash-acceptance/stop

The customer pressed Done or Cancel: acceptors are disabled and the operation ends with status STOPPED and the accepted amount

Response 200 application/json

Fields · Stopped

stoppedboolean

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X POST 'http://localhost:7790/api/v1/cash-acceptance/stop'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/cash-acceptance/stop' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Bill and coin acceptors#

GET/api/v1/cash-acceptors

Denominations and state; session is the running acceptance session

Response 200 application/json

Fields · AcceptorList

licensedboolean
acceptorsarray of AcceptorInfo
7 fields · AcceptorInfo
- numberinteger int32
- namestring
- typestring
- kindstring
- activeboolean
- denominationsarray of number
- infomap → any value
sessionResult
3 fields · Result
- validboolean
- errorsarray of Issue
  8 fields · Issue
  - codestring
  - severitystring
    values: ERROR WARNING
  - atstring date-time
  - registerinteger int32
  - terminalinteger int32
  - fdinteger int64
  - amountinteger int64
  - messagestring
- warningsarray of Issue
  8 fields · Issue
  - codestring
  - severitystring
    values: ERROR WARNING
  - atstring date-time
  - registerinteger int32
  - terminalinteger int32
  - fdinteger int64
  - amountinteger int64
  - messagestring

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'http://localhost:7790/api/v1/cash-acceptors'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/cash-acceptors' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'