Раздел API

Банковский терминал

Оплата картой и по СБП, возврат, отмена, сверка итогов, аварийная отмена, отчёты и слип; QR-код картинкой для оплаты по СБП. Продажу с чеком удобнее проводить одной операцией — POST /api/v1/checkouts.

POST	`/api/v1/terminals/{id}/settlements`	Сверка итогов
POST	`/api/v1/terminals/{id}/reports`	Отчёт терминала
POST	`/api/v1/terminals/{id}/refunds`	Возврат на карту
POST	`/api/v1/terminals/{id}/payments`	Оплата картой
POST	`/api/v1/terminals/{id}/emergency-reversals`	Аварийная отмена последней операции
POST	`/api/v1/terminals/{id}/cancellations`	Отмена оплаты
GET	`/api/v1/terminals/{id}/last-slip`	Последний слип терминала
GET	`/api/v1/qr`	QR-код картинкой PNG

Сверка итогов#

POST/api/v1/terminals/{id}/settlements

Операция

Закрытие дня на терминале; слип — в результате

Параметры

Имя	Где	Тип	Описание
`id`обязательный	path	integer int32	номер устройства из `GET /api/v1/devices`
`Idempotency-Key`обязательный	header	string
`Prefer`	header	string

Ответ 200 application/json

Поля · Operation

idstring uuid
typestring
idempotencyKeystring
resourcesмассив string
statusstring
значения: QUEUED RUNNING SUCCEEDED FAILED UNKNOWN
stagestring
createdAtstring date-time
startedAtstring date-time
finishedAtstring date-time
resultлюбое значение
errorOperationError
3 поля · OperationError
- codestring
- messagestring
- detailsлюбое значение
warningsмассив string

Ошибки — problem+json с полем code, см. коды ошибок.

Пример запроса

curl

curl -X POST 'http://localhost:7790/api/v1/terminals/1/settlements' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/terminals/1/settlements' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30'

Отчёт терминала#

POST/api/v1/terminals/{id}/reports

Операция

Операции смены без сверки с банком; full=true — по каждой операции. Слип — в результате

Параметры

Имя	Где	Тип	Описание
`id`обязательный	path	integer int32	номер устройства из `GET /api/v1/devices`
`Idempotency-Key`обязательный	header	string
`Prefer`	header	string
`full`	query	boolean

Ответ 200 application/json

Поля · Operation

idstring uuid
typestring
idempotencyKeystring
resourcesмассив string
statusstring
значения: QUEUED RUNNING SUCCEEDED FAILED UNKNOWN
stagestring
createdAtstring date-time
startedAtstring date-time
finishedAtstring date-time
resultлюбое значение
errorOperationError
3 поля · OperationError
- codestring
- messagestring
- detailsлюбое значение
warningsмассив string

Ошибки — problem+json с полем code, см. коды ошибок.

Пример запроса

curl

curl -X POST 'http://localhost:7790/api/v1/terminals/1/reports' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/terminals/1/reports' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30'

Возврат на карту#

POST/api/v1/terminals/{id}/refunds

Операция

По оплате прошлых дней, после сверки итогов

Параметры

Имя	Где	Тип	Описание
`id`обязательный	path	integer int32	номер устройства из `GET /api/v1/devices`
`Idempotency-Key`обязательный	header	string
`Prefer`	header	string

Тело запроса application/json обязательное

Поля · ReversalRequest

amountinteger int64
paymentRefstringобязательное
от 1

JSON

{
  "amount": 1,
  "paymentRef": "string"
}

Ответ 200 application/json

Поля · Operation

idstring uuid
typestring
idempotencyKeystring
resourcesмассив string
statusstring
значения: QUEUED RUNNING SUCCEEDED FAILED UNKNOWN
stagestring
createdAtstring date-time
startedAtstring date-time
finishedAtstring date-time
resultлюбое значение
errorOperationError
3 поля · OperationError
- codestring
- messagestring
- detailsлюбое значение
warningsмассив string

Ошибки — problem+json с полем code, см. коды ошибок.

Пример запроса

curl

curl -X POST 'http://localhost:7790/api/v1/terminals/1/refunds' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"amount":1,"paymentRef":"string"}'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/terminals/1/refunds' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"amount":1,"paymentRef":"string"}'

Оплата картой#

POST/api/v1/terminals/{id}/payments

Операция

Параметры

Имя	Где	Тип	Описание
`id`обязательный	path	integer int32	номер устройства из `GET /api/v1/devices`
`Idempotency-Key`обязательный	header	string
`Prefer`	header	string

Тело запроса application/json обязательное

Поля · PaymentRequest

amountinteger int64

JSON

{
  "amount": 1
}

Ответ 200 application/json

Поля · Operation

idstring uuid
typestring
idempotencyKeystring
resourcesмассив string
statusstring
значения: QUEUED RUNNING SUCCEEDED FAILED UNKNOWN
stagestring
createdAtstring date-time
startedAtstring date-time
finishedAtstring date-time
resultлюбое значение
errorOperationError
3 поля · OperationError
- codestring
- messagestring
- detailsлюбое значение
warningsмассив string

Ошибки — problem+json с полем code, см. коды ошибок.

Пример запроса

curl

curl -X POST 'http://localhost:7790/api/v1/terminals/1/payments' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"amount":1}'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/terminals/1/payments' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"amount":1}'

Аварийная отмена последней операции#

POST/api/v1/terminals/{id}/emergency-reversals

Операция

Когда касса не получила результат оплаты (обрыв связи, зависание): терминал отменяет свою последнюю операцию

Параметры

Имя	Где	Тип	Описание
`id`обязательный	path	integer int32	номер устройства из `GET /api/v1/devices`
`Idempotency-Key`обязательный	header	string
`Prefer`	header	string

Тело запроса application/json обязательное

Поля · EmergencyReversalRequest

amountinteger int64
paymentRefstring

JSON

{
  "amount": 1,
  "paymentRef": "string"
}

Ответ 200 application/json

Поля · Operation

idstring uuid
typestring
idempotencyKeystring
resourcesмассив string
statusstring
значения: QUEUED RUNNING SUCCEEDED FAILED UNKNOWN
stagestring
createdAtstring date-time
startedAtstring date-time
finishedAtstring date-time
resultлюбое значение
errorOperationError
3 поля · OperationError
- codestring
- messagestring
- detailsлюбое значение
warningsмассив string

Ошибки — problem+json с полем code, см. коды ошибок.

Пример запроса

curl

curl -X POST 'http://localhost:7790/api/v1/terminals/1/emergency-reversals' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"amount":1,"paymentRef":"string"}'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/terminals/1/emergency-reversals' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"amount":1,"paymentRef":"string"}'

Отмена оплаты#

POST/api/v1/terminals/{id}/cancellations

Операция

В тот же день, до сверки итогов; деньги не списываются с карты

Параметры

Имя	Где	Тип	Описание
`id`обязательный	path	integer int32	номер устройства из `GET /api/v1/devices`
`Idempotency-Key`обязательный	header	string
`Prefer`	header	string

Тело запроса application/json обязательное

Поля · ReversalRequest

amountinteger int64
paymentRefstringобязательное
от 1

JSON

{
  "amount": 1,
  "paymentRef": "string"
}

Ответ 200 application/json

Поля · Operation

idstring uuid
typestring
idempotencyKeystring
resourcesмассив string
statusstring
значения: QUEUED RUNNING SUCCEEDED FAILED UNKNOWN
stagestring
createdAtstring date-time
startedAtstring date-time
finishedAtstring date-time
resultлюбое значение
errorOperationError
3 поля · OperationError
- codestring
- messagestring
- detailsлюбое значение
warningsмассив string

Ошибки — problem+json с полем code, см. коды ошибок.

Пример запроса

curl

curl -X POST 'http://localhost:7790/api/v1/terminals/1/cancellations' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"amount":1,"paymentRef":"string"}'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/terminals/1/cancellations' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"amount":1,"paymentRef":"string"}'

Последний слип терминала#

GET/api/v1/terminals/{id}/last-slip

Слип последней успешной операции из журнала (оплата, возврат, отмена, сверка, продажа) — чтобы напечатать его ещё раз

Параметры

Имя	Где	Тип	Описание
`id`обязательный	path	integer int32	номер устройства из `GET /api/v1/devices`

Ответ 200 application/json

Тип: словарь → любое значение

Ошибки — problem+json с полем code, см. коды ошибок.

Пример запроса

curl

curl 'http://localhost:7790/api/v1/terminals/1/last-slip'

curl

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

QR-код картинкой PNG#

GET/api/v1/qr

text — что закодировать, например payload из события qr; size — сторона в пикселях (100–1200)

Параметры

Имя	Где	Тип	Описание
`text`обязательный	query	string
`size`	query	integer int32

Ответ 200

Файл.

Ошибки — problem+json с полем code, см. коды ошибок.

Пример запроса

curl

curl 'http://localhost:7790/api/v1/qr?text=text'

curl

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