Блог Горошко Андрея 1C-Битрикс,Bitrix24 Добавить обработчик кассы sale.cashbox.handler.add

Добавить обработчик кассы sale.cashbox.handler.add

goroshckogoroshcko| Нет комментария|
Рубрики:

Эффективная интеграция и кастомизация функционала в Битрикс24 часто требует работы на уровне API. Сегодня мы подробно рассмотрим «Добавить обработчик кассы sale.cashbox.handler.add». Вы узнаете экспертные методики работы с sale.cashbox.handler.add и научитесь избегать типичных ошибок начинающих разработчиков.

Добавить обработчик кассы sale.cashbox.handler.add

> Scope: sale, cashbox
>
> Кто может выполнять метод: администратор CRM (право «Разрешить изменять настройки»)

Метод добавляет REST-обработчик кассы.

Параметры метода

Название
тип		Описание
CODE
string		Код REST-обработчика. Должен быть уникальным среди всех обработчиков
NAME
string		Название REST-обработчика
SORT
integer		Сортировка. Значение по умолчанию: 100
SUPPORTS_FFD105
string		Поддерживает ли касса формат фискальных данных версии 1.05. Возможные значения:
— Y — да
— N — нет

Значение по умолчанию: N

SETTINGS
object		Настройки обработчика (подробное описание приведено ниже)

Параметр SETTINGS {#settings}

Название
тип		Описание
PRINT_URL
string		Адрес, на который отправляются данные для печати чека
CHECK_URL
string		Адрес, по которому происходит проверка статуса чека
HTTP_VERSION
string		Версия протокола HTTP, используемая для запросов. Возможные значения: 1.0, 1.1.

Если параметр не заполнен, то для запросов используется HTTP 1.0

CONFIG
object		Структура настроек (подробное описание приведено ниже), которые пользователь сможет устанавливать и изменять на странице редактирования кассы, а также при добавлении или обновлении кассы через REST.

Каждый ключ в этом параметре задает один раздел на странице настроек, ключ является кодом раздела. Значения объекта описывают раздел и содержащиеся в нем настройки

Параметр SETTINGS\[CONFIG] {#settingsconfig}

Название
тип		Описание
LABEL
string		Заголовок раздела
ITEMS
object		Список настроек раздела (подробное описание приведено ниже).

Ключ является кодом настройки, значение — описанием настройки

Параметр SETTINGS\[CONFIG]\[код раздела]\[ITEMS] {#settingsconfigitems}

Название
тип		Описание
TYPE
string		Тип настройки. Возможные значения:

— STRING — строка
— NUMBER — число с плавающей точкой
— Y/N — строка, принимающая значения Y или N
— ENUM — список строковых значений
— DATE — дата

LABEL
string		Название настройки
REQUIRED
string		Является ли настройка обязательной. Возможные значения:

— Y — да
— N — нет

DISABLED
string		Отключена ли возможность редактирования настройки. Возможные значения:

— Y — да
— N — нет

Значение по умолчанию: N

MULTIPLE
string		Является ли настройка множественной. Возможные значения:

— Y — да
— N — нет

Значение по умолчанию: N

MULTILINE
string		Является ли поле многострочным. Используется для типа STRING. Возможные значения:

— Y — да
— N — нет

Значение по умолчанию: N

OPTIONS
object		Список возможных значений свойства. Используется для типа ENUM.

Ключ объекта — значение свойства, значение ключа — название значения, отображаемое в интерфейсе

TIME
string		Есть ли возможность выбрать время. Используется для типа DATE. Возможные значения:

— Y — да
— N — нет

Значение по умолчанию: N

Примеры кода

  • cURL (Webhook)
    -X POST \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"CODE":"restcashbox01","NAME":"REST-касса 01","SORT":100,"SUPPORTS_FFD105":"Y","SETTINGS":{"PRINT_URL":"http://example.com/rest_print.php","CHECK_URL":"http://example.com/rest_check.php","HTTP_VERSION":"1.1","CONFIG":{"AUTH":{"LABEL":"Авторизация","ITEMS":{"KEYWORD":{"TYPE":"STRING","LABEL":"Кодовое слово"},"PREFERENCE":{"TYPE":"ENUM","LABEL":"Множественный выбор","REQUIRED":"Y","OPTIONS":{"FIRST":"Первый","SECOND":"Второй","THIRD":"Третий"}}}},"INTERACTION":{"LABEL":"Настройки взаимодействия с кассой","ITEMS":{"MODE":{"TYPE":"ENUM","LABEL":"Режим работы с кассой","OPTIONS":{"ACTIVE":"боевой","TEST":"тестовый"}}}}}}}' \
    https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webbhook_here**/sale.cashbox.handler.add
  • cURL (OAuth)
    -X POST \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"CODE":"restcashbox01","NAME":"REST-касса 01","SORT":100,"SUPPORTS_FFD105":"Y","SETTINGS":{"PRINT_URL":"http://example.com/rest_print.php","CHECK_URL":"http://example.com/rest_check.php","HTTP_VERSION":"1.1","CONFIG":{"AUTH":{"LABEL":"Авторизация","ITEMS":{"KEYWORD":{"TYPE":"STRING","LABEL":"Кодовое слово"},"PREFERENCE":{"TYPE":"ENUM","LABEL":"Множественный выбор","REQUIRED":"Y","OPTIONS":{"FIRST":"Первый","SECOND":"Второй","THIRD":"Третий"}}}},"INTERACTION":{"LABEL":"Настройки взаимодействия с кассой","ITEMS":{"MODE":{"TYPE":"ENUM","LABEL":"Режим работы с кассой","OPTIONS":{"ACTIVE":"боевой","TEST":"тестовый"}}}}}},"auth":"**put_access_token_here**"}' \
    https://**put_your_bitrix24_address**/rest/sale.cashbox.handler.add
  • JS
    try
    {
    	const response = await $b24.callMethod(
    		"sale.cashbox.handler.add",
    		{
    			"CODE": "restcashbox01",
    			"NAME": "REST-касса 01",
    			"SORT": 100,
    			"SUPPORTS_FFD105": "Y",
    			"SETTINGS":
    			{
    				"PRINT_URL": "http://example.com/rest_print.php",
    				"CHECK_URL": "http://example.com/rest_check.php",
    				"HTTP_VERSION": "1.1",
    				"CONFIG":
    				{
    					"AUTH": {
    						"LABEL": "Авторизация",
    						"ITEMS": {
    							"KEYWORD": {
    								"TYPE": "STRING",
    								"LABEL": "Кодовое слово"
    							},
    							"PREFERENCE": {
    								"TYPE": "ENUM",
    								"LABEL": "Множественный выбор",
    								"REQUIRED": "Y",
    								"OPTIONS": {
    									"FIRST": "Первый",
    									"SECOND": "Второй",
    									"THIRD": "Третий",
    								}
    							}
    						}
    					},
    					"INTERACTION": {
    						"LABEL": "Настройки взаимодействия с кассой",
    						"ITEMS": {
    							"MODE": {
    								"TYPE": "ENUM",
    								"LABEL": "Режим работы с кассой",
    								"OPTIONS": {
    									"ACTIVE": "боевой",
    									"TEST": "тестовый"
    								}
    							}
    						}
    					}
    				}
    			}
    		}
    	);
    	
    	const result = response.getData().result;
    	console.dir(result);
    }
    catch(error)
    {
    	console.error(error);
    }
  • PHP
    try {
        $response = $b24Service
            ->core
            ->call(
                'sale.cashbox.handler.add',
                [
                    'CODE'          => 'restcashbox01',
                    'NAME'          => 'REST-касса 01',
                    'SORT'          => 100,
                    'SUPPORTS_FFD105' => 'Y',
                    'SETTINGS'      => [
                        'PRINT_URL'    => 'http://example.com/rest_print.php',
                        'CHECK_URL'    => 'http://example.com/rest_check.php',
                        'HTTP_VERSION' => '1.1',
                        'CONFIG'       => [
                            'AUTH'       => [
                                'LABEL' => 'Авторизация',
                                'ITEMS' => [
                                    'KEYWORD'    => [
                                        'TYPE'  => 'STRING',
                                        'LABEL' => 'Кодовое слово',
                                    ],
                                    'PREFERENCE' => [
                                        'TYPE'     => 'ENUM',
                                        'LABEL'    => 'Множественный выбор',
                                        'REQUIRED' => 'Y',
                                        'OPTIONS'  => [
                                            'FIRST'  => 'Первый',
                                            'SECOND' => 'Второй',
                                            'THIRD'  => 'Третий',
                                        ],
                                    ],
                                ],
                            ],
                            'INTERACTION' => [
                                'LABEL' => 'Настройки взаимодействия с кассой',
                                'ITEMS' => [
                                    'MODE' => [
                                        'TYPE'    => 'ENUM',
                                        'LABEL'   => 'Режим работы с кассой',
                                        'OPTIONS' => [
                                            'ACTIVE' => 'боевой',
                                            'TEST'   => 'тестовый',
                                        ],
                                    ],
                                ],
                            ],
                        ],
                    ],
                ]
            );
    
        $result = $response
            ->getResponseData()
            ->getResult();
    
        echo 'Success: ' . print_r($result, true);
        console.dir($result);
    
    } catch (Throwable $e) {
        error_log($e->getMessage());
        echo 'Error adding cashbox handler: ' . $e->getMessage();
    }
  • BX24.js
    BX24.callMethod(
        "sale.cashbox.handler.add",
        {
            "CODE": "restcashbox01",
            "NAME": "REST-касса 01",
            "SORT": 100,
            "SUPPORTS_FFD105": "Y",
            "SETTINGS":
            {
                "PRINT_URL": "http://example.com/rest_print.php",
                "CHECK_URL": "http://example.com/rest_check.php",
                "HTTP_VERSION": "1.1",
                "CONFIG":
                {
                    "AUTH": {
                        "LABEL": "Авторизация",
                        "ITEMS": {
                            "KEYWORD": {
                                "TYPE": "STRING",
                                "LABEL": "Кодовое слово"
                            },
                            "PREFERENCE": {
                                "TYPE": "ENUM",
                                "LABEL": "Множественный выбор",
                                "REQUIRED": "Y",
                                "OPTIONS": {
                                    "FIRST": "Первый",
                                    "SECOND": "Второй",
                                    "THIRD": "Третий",
                                }
                            }
                        }
                    },
                    "INTERACTION": {
                        "LABEL": "Настройки взаимодействия с кассой",
                        "ITEMS": {
                            "MODE": {
                                "TYPE": "ENUM",
                                "LABEL": "Режим работы с кассой",
                                "OPTIONS": {
                                    "ACTIVE": "боевой",
                                    "TEST": "тестовый"
                                }
                            }
                        }
                    }
                }
            }
        },
        function(result)
        {
            if(result.error())
                console.error(result.error());
            else
                console.dir(result.data());
        }
    );
  • PHP CRest
    require_once('crest.php');

    $result = CRest::call(
        'sale.cashbox.handler.add',
        [
            'CODE' => 'restcashbox01',
            'NAME' => 'REST-касса 01',
            'SORT' => 100,
            'SUPPORTS_FFD105' => 'Y',
            'SETTINGS' =>
            [
                'PRINT_URL' => 'http://example.com/rest_print.php',
                'CHECK_URL' => 'http://example.com/rest_check.php',
                'HTTP_VERSION' => '1.1',
                'CONFIG' =>
                [
                    'AUTH' =>
                    [
                        'LABEL' => 'Авторизация',
                        'ITEMS' =>
                        [
                            'KEYWORD' =>
                            [
                                'TYPE' => 'STRING',
                                'LABEL' => 'Кодовое слово'
                            ],
                            'PREFERENCE' =>
                            [
                                'TYPE' => 'ENUM',
                                'LABEL' => 'Множественный выбор',
                                'REQUIRED' => 'Y',
                                'OPTIONS' =>
                                [
                                    'FIRST' => 'Первый',
                                    'SECOND' => 'Второй',
                                    'THIRD' => 'Третий',
                                ]
                            ]
                        ]
                    ],
                    'INTERACTION' =>
                    [
                        'LABEL' => 'Настройки взаимодействия с кассой',
                        'ITEMS' =>
                        [
                            'MODE' =>
                            [
                                'TYPE' => 'ENUM',
                                'LABEL' => 'Режим работы с кассой',
                                'OPTIONS' =>
                                [
                                    'ACTIVE' => 'боевой',
                                    'TEST' => 'тестовый'
                                ]
                            ]
                        ]
                    ]
                ]
            ]
        ]
    );

    echo '<PRE>';
    print_r($result);
    echo '</PRE>';
  • [](../../../tutorials/sale/cashbox-add-example)

Обработка ответа

HTTP-статус: 200

{
    "result": 5,
    "time": {
        "start": 1712132792.910734,
        "finish": 1712132793.530359,
        "duration": 0.6196250915527344,
        "processing": 0.032338857650756836,
        "date_start": "2024-04-03T10:26:32+02:00",
        "date_finish": "2024-04-03T10:26:33+02:00",
        "operating_reset_at": 1705765533,
        "operating": 3.3076241016387939
    }
}

Возвращаемые данные

Название
тип		Описание
result
sale_cashbox_handler.ID		Идентификатор созданного обработчика
time
time		Информация о времени выполнения запроса

Обработка ошибок

HTTP-статус: 400, 403

{
    "error": "ERROR_HANDLER_ALREADY_EXIST",
    "error_description": "Handler already exists!"
}

Возможные коды ошибок

КодОписаниеСтатус
ACCESS_DENIEDНедостаточно прав для добавления обработчика403
ERROR_CHECK_FAILUREНе указано значение обязательного поля либо значение одного из полей указано неверно400
ERROR_HANDLER_ALREADY_EXISTОбработчик с кодом, указанным в параметре CODE, уже существует в системе400
ERROR_HANDLER_ADDПрочие ошибки. Более подробную информацию об ошибке можно найти в error_description400

Страница PRINT_URL {#print_url}

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

Пример данных, отправляемых на PRINT_URL

{
    "type": "sell",
    "calculated_sign": "income",
    "unique_id": 85,
    "items": [
        {
            "name": "Товар",
            "base_price": 12000.0,
            "price": 9600.0,
            "sum": 9600.0,
            "currency": "RUB",
            "quantity": 1,
            "measure_code": "796",
            "vat": 3,
            "vat_sum": 1600.0,
            "payment_object": "commodity_marking",
            "nomenclature_code": "DM �Yߠ�Q:4H7/3f^7fZ1",
            "marking_code": "011390002199781321Q:4H7/3f^7fZ1",
            "barcode": "1234567890",
            "discount": {
                "discount": 2400.0
            },
            "payment_method": "full_payment"
        }
    ],
    "date_create": 1712235417,
    "payments": [
        {
            "type": "cash",
            "is_cash": "Y",
            "sum": 1000,
            "currency": "RUB"
        }
    ],
    "client_email": "client@example.com",
    "client_phone": "+123456789",
    "total_sum": 9600.0,
    "uuid": "check|example.com|85",
    "operation": "income",
    "number_kkm": "",
    "service_email": "admin@example.com",
    "cashbox_params": {
        "AUTH": {
            "LOGIN": "user123",
            "PASSWORD": "top_secret!"
        },
        "COMPANY": {
            "INN": "123"
        },
        "INTERACTION": {
            "MODE": "ACTIVE"
        }
    }
}

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

Название
тип		Описание
type
string		Тип чека. Значения:
— sell — полная оплата
— sellreturncash — полный возврат наличными
— sellreturn — полный возврат безналичными
— advancepayment — аванс
— advancereturn — возврат аванса безналичными
— advancereturncash — возврат аванса наличными
— creditpayment — оплата кредита
— creditpaymentreturn — возврат оплаты кредита безналичными
— creditpaymentreturncash — возврат оплаты кредита наличными
— credit — покупка в кредит
— creditreturn — возврат покупки в кредит
— prepayment — частичная предоплата
— prepaymentreturn — возврат частичной предоплаты безналичными
— prepaymentreturncash — возврат частичной предоплаты наличными
— fullprepayment — 100% предоплата
— fullprepaymentreturn — возврат 100% предоплаты безналичными
— fullprepaymentreturncash — возврат 100% предоплаты наличными
operation
string		Признак прихода/расхода. Значения:
— income — приход
— consumption — расход
calculated
string		Аналогично operation (для совместимости)
unique_id
integer		ID чека в базе данных портала
items
object		Массив товаров в чеке (подробное описание приведено ниже)
date_create
integer		Дата создания чека (timestamp)
payments
object		Массив оплат (подробное описание приведено ниже)
client_email
string		E-mail клиента (при наличии)
client_phone
string		Номер телефона клиента (при наличии)
total_sum
float		Общая сумма по чеку
uuid
string		Идентификатор документа во внешней системе (портал Битрикс24)
service_email
string		Email (из настроек кассы)

Параметр items {#items}

Название
тип		Описание
name
string		Название товара
base_price
float		Цена товара без учета скидок и наценок
price
float		Цена продажи
sum
float		Сумма позиции
quantity
float		Количество товара
vat
int		Идентификатор налога. Он может быть использован в методе catalog.vat.get для получения информации по налогу
vat_sum
float		Cумма налога
barcode
string		Штрихкод. Используется при включенном складском учете и передаче товара с уникальным штрихкодом
nomenclature_code
string		Код товарной номенклатуры в двоичном представлении (при наличии)
marking_code
string		Код товарной номенклатуры (при наличии)
payment_object
string		Признак предмета расчета. Стандартные значения:
— commodity — товар
— commodity_marking — товар, подлежащий маркировке и имеющий код маркировки
— service — услуга
— payment — платеж
payment_method
string		Признак способа расчета. Значения:
— full_payment — полный расчет
— advance — аванс
— prepayment — предоплата
— full_prepayment — 100% предоплата
— credit — покупка в кредит
— credit_payment — оплата кредита
supplier_info
array		Агентские реквизиты при использовании агентских схем (подробное описание приведено ниже)
discount
array		Скидка на товар. Ключ является устаревшим и больше не используется.
В массиве передается параметр discount (float) — размер скидки в денежном выражении

##### Параметр supplier_info {#supplier_info}

Название
тип		Описание
phones
string[]		Номера телефонов
name
string		Название поставщика
inn
string		ИНН поставщика

Параметр payments {#payments}

Название
тип		Описание
type
string		Тип оплаты. Значения:
— cash — оплата наличными
— cashless — безналичный расчет
is_cash
string		Производится ли оплата наличными (Y/N). Ключ является устаревшим, вместо него рекомендуется использовать type
sum
float		Сумма оплаты
currency
string		Валюта оплаты

Страница CHECK_URL {#check_url}

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

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

Пример данных, отправляемых на CHECK_URL

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

Структура POST-параметров, отправляемых на CHECK_URL

Название
тип		Описание
uuid
string		Идентификатор чека
  • [](./sale-cashbox-handler-update)
  • [](./sale-cashbox-handler-list)
  • [](./sale-cashbox-handler-delete)
  • [](./sale-cashbox-add)
  • [](./sale-cashbox-update)
  • [](./sale-cashbox-list)
  • [](./sale-cashbox-delete)
  • [](./sale-cashbox-check-apply)
  • [](../../../tutorials/sale/cashbox-add-example)

💡 Экспертное мнение и рекомендации

Советы эксперта по интеграции:

  • Всегда используйте кэширование при частых запросах к sale.cashbox.handler.add, чтобы разгрузить базу данных.
  • Соблюдайте стандарты PSR при написании обработчиков для «Добавить обработчик кассы sale.cashbox.handler.add».
  • Регулярно проводите аудит производительности системы с помощью встроенного монитора 1С-Битрикс.

Похожая задача в бизнесе?

Помогу автоматизировать процессы и внедрить ИИ

Меня зовут Андрей Горошко. Я Full-stack разработчик и эксперт по 1С-Битрикс. Настраиваю CRM Битрикс24, разрабатываю защищенные API и создаю умных ИИ-агентов для автоматизации рутины.

Related Post

Как использовать метод SDK crm.company.contact.delete в Битрикс24Как использовать метод SDK crm.company.contact.delete в Битрикс24

25.05.202625.05.2026| goroshckogoroshcko| Нет комментария|

Каждый PHP-разработчик, работающий с экосистемой Bitrix Framework, должен глубоко понимать работу её ключевых компонентов. В этой статье мы проведем подробный аудит темы «Как использовать метод SDK crm.company.contact.delete в Битрикс24», проанализируем

Читать далееЧитать далее

Как использовать метод SDK userfieldtype.update в Битрикс24Как использовать метод SDK userfieldtype.update в Битрикс24

25.05.202625.05.2026| goroshckogoroshcko| Нет комментария|

Каждый PHP-разработчик, работающий с экосистемой Bitrix Framework, должен глубоко понимать работу её ключевых компонентов. В этой статье мы проведем подробный аудит темы «Как использовать метод SDK userfieldtype.update в Битрикс24», проанализируем

Читать далееЧитать далее

Разработка интернет-магазина спортивного питания и экипировки на 1С-БитриксРазработка интернет-магазина спортивного питания и экипировки на 1С-Битрикс

22.08.202622.08.2026| goroshckogoroshcko| Нет комментария|

Создание современного интернет-магазина спортивного питания и экипировки на платформе 1С-Битрикс позволяет автоматизировать продажи, обеспечить высокую конверсию и бесшовную интеграцию с учетными системами. Для ниши «спортивного питания и экипировки» критически важны

Читать далееЧитать далее