Документация для разработчиков
Темная тема

Пример реализации простой кассы на REST API

Добавление обработчика кассы

Пример добавления обработчика кассы с возможностью настройки данных для авторизации, информации о компании и режиме работы кассы:

BX24.callMethod(
	"sale.cashbox.handler.add",
	{
		"CODE": "my_rest_cashbox",
		"NAME": "Моя REST-касса",
		"SORT": 100,
		"SETTINGS":
		{
			"PRINT_URL": "http:\/\/example.com\/rest_print.php",
			"CHECK_URL": "http:\/\/example.com\/rest_check.php",
			"CONFIG":
			{
				"AUTH": {
					"LABEL": "Авторизация",
					"ITEMS": {
						"LOGIN": {
							"TYPE": "STRING",
							"REQUIRED": "Y",
							"LABEL": "Логин"
						},
						"PASSWORD": {
							"TYPE": "STRING",
							"REQUIRED": "Y",
							"LABEL": "Пароль"
						},
					}
				},
				"COMPANY": {
					"LABEL": "Данные об организации",
					"ITEMS": {
						"INN": {
							"TYPE": "STRING",
							"REQUIRED": "Y",
							"LABEL": "ИНН организации"
						}
					}
				},
				"INTERACTION": {
					"LABEL": "Настройки взаимодействия с кассой",
					"ITEMS": {
						"MODE": {
							"TYPE": "ENUM",
							"LABEL": "Режим работы с кассой",
							"OPTIONS": {
								"ACTIVE": "боевой",
								"TEST": "тестовый"
							}
						}
					}
				}
			}
		}
	},
	function(result)
	{
		if(result.error())
			console.error(result.error());
		else
			console.dir(result.data());
	}
);

Добавленная касса настраивается пользователем через настройки магазина или через Центр продаж. Пример настройки:

  • Вкладка Касса:

  • Вкладка Настройки:

Страница PRINT_URL

Страница PRINT_URL - адрес, на который отправляются данные для печати чека.

Структура POST-параметров, отправляемых на адрес PRINT_URL:

Параметр Описание
typeТип чека. Значения:
  • sell - полная оплата;
  • sellreturncash - полный возврат наличными;
  • sellreturn - полный возврат безналичными;
  • advancepayment - аванс;
  • advancereturn - возврат аванса безналичными;
  • advancereturncash - возврат аванса наличными;
  • creditpayment - оплата кредита;
  • creditpaymentreturn - возврат оплаты кредита безналичными;
  • creditpaymentreturncash - возврат оплаты кредита наличными;
  • credit - покупка в кредит;
  • creditreturn - возврат покупки в кредит;
  • prepayment - частичная предоплата;
  • prepaymentreturn - возврат частичной предоплаты безналичными;
  • prepaymentreturncash - возврат частичной предоплаты наличными;
  • fullprepayment - 100% предоплата;
  • fullprepaymentreturn - возврат 100% предоплаты безналичными;
  • fullprepaymentreturncash - возврат 100% предоплаты наличными.
operationПризнак прихода/расхода. Значения:
  • income - приход;
  • consumption - расход.
unique_idID чека в базе данных портала.
itemsМассив товаров в чеке. Структура элементов массива:
  • name - название товара;
  • base_price - базовая цена товара;
  • price - цена товара;
  • sum - сумма позиции;
  • quantity - количество товара;
  • vat - id налога;
  • vat_sum - сумма налога;
  • payment_object - признак предмета расчёта. Значения:
    • commodity - товар;
    • excise - подакцизный товар;
    • job - работа;
    • service - услуга;
    • payment - платёж;
    • gambling_bet - ставка азартной игры;
    • gambling_prize - выигрыш азартной игры;
    • lottery - лотерейный билет;
    • lottery_prize - выигрыш лотереи;
    • intellectual_activity - предоставление результатов интеллектуальной деятельности;
    • agent_commission - агентское вознаграждение;
    • composite - составной предмет расчета;
    • another - иной предмет расчета;
    • property_right - имущественное право;
    • non-operating_gain - внереализационный доход;
    • sales_tax - торговый сбор;
    • resort_fee - курортный сбор.
  • payment_method - признак способа расчёта. Значения:
    • full_payment - полный расчёт;
    • advance - аванс;
    • prepayment - предоплата;
    • full_prepayment - 100% предоплата;
    • credit - покупка в кредит;
    • credit_payment - оплата кредита.
date_createДата создания чека (timestamp).
paymentsМассив оплат. Структура элементов массива:
  • type - тип оплаты. Значения:
    • cash - оплата наличными;
    • cashless - безналичный расчёт.
  • is_cash - производится ли оплата наличными. Значения: Y/N
  • sum - сумма оплаты.
client_emailE-mail клиента.
total_sumОбщая сумма по чеку.
uuidИдентификатор документа во внешней системе (портал Битрикс24).
number_kkmВнешний идентификатор кассы (из настроек кассы).
service_emailEmail (из настроек кассы).
cashbox_paramsМассив настроек кассы. Структура задаётся параметром CONFIG массива SETTINGS, указанного в качестве параметра метода sale.cashbox.handler.add.

По адресу PRINT_URL происходит обработка входных данных, формирование документа и возвращение результата печати. Ответом в случае ошибки служит JSON-массив вида:

{
"ERRORS": [
      "Сообщение об ошибке",
      "Сообщение об ошибке",
      ...
]
}

При успешной печати массив имеет вид:

{
"UUID": "00112233-4455-6677-8899-aabbccddeeff"
}

Пример реализации простого обработчика:

<?php
 
$login = $_REQUEST['cashbox_params']['AUTH']['LOGIN'];
$password = $_REQUEST['cashbox_params']['AUTH']['PASSWORD'];
 
if (empty($login) || empty($password))
{
  echo json_encode([
     'ERRORS' => [
        'Authorization data is missing',
     ]
  ]);
  die();
}
 
// произведение необходимых действий: авторизация пользователя, обработка данных, регистрация чека в системе, ...
 
echo json_encode([
  'UUID' => $resultUUID,
]);

Страница CHECK_URL

Страница CHECK_URL - адрес, по которому происходит проверка успешности печати чека.

Запрос по адресу CHECK_URL производится по запросу менеджера либо спустя некоторое время после успешной печати чека.

Структура POST-параметров, отправляемых на адрес PRINT_URL:

Параметр Описание
uuidИдентификатор чека.

Запрос по адресу CHECK_URL должен возвращать данные о чеке, данные об ошибке, возникшей при печати, либо статус “в ожидании печати”.

Пример реализации простого обработчика:

<?php
 
$uuid = $_REQUEST['uuid'];
 
// произведение необходимых действий: проверка статуса чека, ...
 
// при печати чека произошла ошибка
if ($result['ERROR'])
{
  echo json_encode([
     'STATUS' => 'ERROR',
     'ERROR' => 'Сообщение об ошибке'
  ]);
  die();
}
 
// чек ещё не напечатан
if ($result['WAIT'])
{
  echo json_encode([
     'STATUS' => 'WAIT',
  ]);
  die();
}
 
// отправка результата
 
echo json_encode([
  'STATUS' => 'DONE',
  'UUID' => $uuid,
  'REG_NUMBER_KKT' => '000111222333',
  'FISCAL_DOC_ATTR' => '33445500',
  'FISCAL_DOC_NUMBER' => 123,
  'FISCAL_RECEIPT_NUMBER' => 10,
  'FN_NUMBER' => '0011223344556677',
  'SHIFT_NUMBER' => 12,
  'PRINT_END_TIME' => 1609452000,
]);

Данные, возвращаемые CHECK_URL, сохраняются в базу данных и используются для генерации ссылки на чек.


Пользовательские комментарии

Мы будем рады, если разработчики добавят свои комментарии по практическому использованию методов системы.

Для этого нужно всего лишь авторизоваться на сайте

Но помните, что Пользовательские комментарии, несмотря на модерацию, не являются официальной документацией. Ответственность за их использование несет сам пользователь.

Также Пользовательские комментарии не являются местом для обсуждения функционала. По подобным вопросам обращайтесь на форумы.
0
Станислав Еременко
Сообщение не промодерировано, возможны ошибки и неточности.
Цитата
пишет:
В чем разница полей 'type' и 'is_cash' в массиве оплат 'payments'?
В коде класса SaleCheck поле 'type' формируется на основе значения 'is_cash'.
Возможно, оставлено для совместимости?
0
Станислав Еременко
Сообщение не промодерировано, возможны ошибки и неточности.
Цитата
пишет:
Какие еще бывают STATUS кроме DONE? Что они значат?

Просмотрел, в примере кода указаны статусы WAIT и ERROR для CHECK_URL
0
Станислав Еременко
Сообщение не промодерировано, возможны ошибки и неточности.
Цитата
пишет:
В ответе обработчика CHECK_URL, что обозначает "SHIFT_NUMBER"?
Какие еще бывают STATUS кроме DONE? Что они значат?
Если сопоставить с обработчиком Атол и заглянуть в описание их API:

SHIFT_NUMBER - Тег 1038 Номер смены.
0
Станислав Еременко
Сообщение не промодерировано, возможны ошибки и неточности.
В чем разница полей 'type' и 'is_cash' в массиве оплат 'payments'?
0
Станислав Еременко
Сообщение не промодерировано, возможны ошибки и неточности.
В ответе обработчика CHECK_URL, что обозначает "SHIFT_NUMBER"?
Какие еще бывают STATUS кроме DONE? Что они значат?
© «Битрикс», 2001-2024, «1С-Битрикс», 2024