Раздел API

Продажа

Продажа или возврат целиком: оплата на терминале → чек на ККТ → слип. Если чек не вышел, агент сам отменяет оплату (PAYMENT_CANCELLED).

POST /api/v1/checkouts Продажа или возврат с чеком

Продажа или возврат с чеком#

POST/api/v1/checkouts

Операция

Порядок: операция по карте на терминале (если есть оплата CARD) → чек на ККТ → слип на ККТ. Если чек не напечатался после оплаты картой, оплата отменяется на терминале (ошибка PAYMENT_CANCELLED); если и отмена не прошла — PAYMENT_NOT_CANCELLED с данными оплаты в error.details. Результат: { receipt: фискальный документ, payment: операция по карте }.

Параметры

Имя	Где	Тип	Описание
`Idempotency-Key`обязательный	header	string
`Prefer`	header	string

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

Поля · CheckoutRequest

registerIdinteger int32
terminalIdinteger int32
receiptReceiptобязательное
11 полей · Receipt
- typestringобязательное
  значения: SELL SELL_RETURN BUY BUY_RETURN
- taxationstring
  значения: OSN USN_INCOME USN_INCOME_OUTCOME ESHN PATENT
- operatorOperator
  2 поля · Operator
  - namestringобязательное
    от 1
  - innstring
- customerCustomer
  3 поля · Customer
  - contactstring
  - namestring
  - innstring
- headerмассив TextLine
  4 поля · TextLine
  - kindstringобязательное
    значения: TEXT PAIR SEPARATOR
  - textstring
  - rightstring
  - alignstring
    значения: LEFT CENTER RIGHT
- itemsмассив ReceiptItemобязательное
  от 1
  9 полей · ReceiptItem
  - namestringобязательное
    от 1
  - priceinteger int64
    от 0
  - quantitynumberобязательное
  - amountinteger int64
    от 0
  - vatstringобязательное
    значения: NONE VAT0 VAT5 VAT7 VAT10 VAT20 VAT22 VAT105 VAT107 VAT110 VAT120 VAT122
  - paymentMethodstringобязательное
    значения: FULL_PREPAYMENT PREPAYMENT ADVANCE FULL_PAYMENT PARTIAL_PAYMENT CREDIT CREDIT_PAYMENT
  - paymentObjectstringобязательное
    значения: COMMODITY EXCISE JOB SERVICE GAMBLING_BET GAMBLING_PRIZE LOTTERY LOTTERY_PRIZE INTELLECTUAL_ACTIVITY PAYMENT AGENT_COMMISSION COMPOSITE ANOTHER
  - departmentinteger int32
  - markingMarking
    4 поля · Marking
    codestringобязательное
    от 1
    fractionstring
    шаблон: \d+/\d+
    measurestring
    значения: PIECE GRAM KILOGRAM TON CENTIMETER DECIMETER METER SQUARE_CENTIMETER SQUARE_DECIMETER SQUARE_METER MILLILITER LITER CUBIC_METER KILOWATT_HOUR GKAL DAY HOUR MINUTE SECOND KILOBYTE MEGABYTE GIGABYTE TERABYTE OTHER
    industryPropsstring
- paymentsмассив ReceiptPaymentобязательное
  от 1
  2 поля · ReceiptPayment
  - typestringобязательное
    значения: CASH CARD PREPAID CREDIT OTHER
  - amountinteger int64
- footerмассив TextLine
  4 поля · TextLine
  - kindstringобязательное
    значения: TEXT PAIR SEPARATOR
  - textstring
  - rightstring
  - alignstring
    значения: LEFT CENTER RIGHT
- electronicboolean
- senderEmailstring
- settlementPlacestring
originalPaymentRefstring
printSlipboolean

JSON

{
  "registerId": 1,
  "terminalId": 1,
  "receipt": {
    "type": "SELL",
    "taxation": "OSN",
    "operator": {
      "name": "string",
      "inn": "string"
    },
    "customer": {
      "contact": "string",
      "name": "string",
      "inn": "string"
    },
    "header": [
      {}
    ],
    "items": [
      {}
    ],
    "payments": [
      {}
    ],
    "footer": [
      {}
    ],
    "electronic": false,
    "senderEmail": "string",
    "settlementPlace": "string"
  },
  "originalPaymentRef": "string",
  "printSlip": false
}

Ответ 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/checkouts' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"registerId":1,"terminalId":1,"receipt":{"type":"SELL","taxation":"OSN","operator":{"name":"string","inn":"string"},"customer":{"contact":"string","name":"string","inn":"string"},"header":[{}],"items":[{}],"payments":[{}],"footer":[{}],"electronic":false,"senderEmail":"string","settlementPlace":"string"},"originalPaymentRef":"string","printSlip":false}'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/checkouts' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' \
  --data '{"registerId":1,"terminalId":1,"receipt":{"type":"SELL","taxation":"OSN","operator":{"name":"string","inn":"string"},"customer":{"contact":"string","name":"string","inn":"string"},"header":[{}],"items":[{}],"payments":[{}],"footer":[{}],"electronic":false,"senderEmail":"string","settlementPlace":"string"},"originalPaymentRef":"string","printSlip":false}'