Add Cashbox Handler sale.cashbox.handler.add
If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can utilize the official REST documentation.
Scope:
sale, cashboxWho can execute the method: CRM administrator (permission "Allow changing settings")
This method adds a REST cashbox handler.
Method Parameters
Required parameters are marked with *
|
Name |
Description |
|
CODE* |
Code of the REST handler. Must be unique among all handlers |
|
NAME* |
Name of the REST handler |
|
SORT |
Sorting. Default value: |
|
SUPPORTS_FFD105 |
Indicates whether the cashbox supports fiscal data format version 1.05. Possible values:
Default value: |
|
SETTINGS* |
Handler settings (detailed description provided below) |
SETTINGS Parameter
Required parameters are marked with *
|
Name |
Description |
|
PRINT_URL* |
Address to which data for printing the receipt is sent |
|
CHECK_URL* |
Address for checking the status of the receipt |
|
HTTP_VERSION |
Version of the HTTP protocol used for requests. Possible values: If the parameter is not filled, HTTP |
|
CONFIG* |
Structure of settings (detailed description provided below), which the user can set and modify on the cashbox editing page, as well as when adding or updating the cashbox via REST. Each key in this parameter defines one section on the settings page, the key is the section code. The values of the object describe the section and the settings contained within it |
SETTINGS[CONFIG] Parameter
Required parameters are marked with *
|
Name |
Description |
|
LABEL* |
Section header |
|
ITEMS* |
List of settings in the section (detailed description provided below). The key is the setting code, the value is the description of the setting |
SETTINGS[CONFIG][section code][ITEMS] Parameter
Required parameters are marked with *
|
Name |
Description |
|
TYPE* |
Type of setting. Possible values:
|
|
LABEL* |
Name of the setting |
|
REQUIRED* |
Indicates whether the setting is required. Possible values:
|
|
DISABLED |
Indicates whether editing of the setting is disabled. Possible values:
Default value: |
|
MULTIPLE |
Indicates whether the setting is multiple. Possible values:
Default value: |
|
MULTILINE |
Indicates whether the field is multiline. Used for
Default value: |
|
OPTIONS* |
List of possible values for the property. Used for The key of the object is the property value, the value of the key is the name of the value displayed in the interface |
|
TIME |
Indicates whether time selection is possible. Used for
Default value: |
Code Examples
How to Use Examples in Documentation
-X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"CODE":"restcashbox01","NAME":"REST-Cashbox 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":"Authorization","ITEMS":{"KEYWORD":{"TYPE":"STRING","LABEL":"Password"},"PREFERENCE":{"TYPE":"ENUM","LABEL":"Multiple Choice","REQUIRED":"Y","OPTIONS":{"FIRST":"First","SECOND":"Second","THIRD":"Third"}}}},"INTERACTION":{"LABEL":"Interaction Settings with Cashbox","ITEMS":{"MODE":{"TYPE":"ENUM","LABEL":"Cashbox Operating Mode","OPTIONS":{"ACTIVE":"live","TEST":"test"}}}}}}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/sale.cashbox.handler.add
-X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"CODE":"restcashbox01","NAME":"REST-Cashbox 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":"Authorization","ITEMS":{"KEYWORD":{"TYPE":"STRING","LABEL":"Password"},"PREFERENCE":{"TYPE":"ENUM","LABEL":"Multiple Choice","REQUIRED":"Y","OPTIONS":{"FIRST":"First","SECOND":"Second","THIRD":"Third"}}}},"INTERACTION":{"LABEL":"Interaction Settings with Cashbox","ITEMS":{"MODE":{"TYPE":"ENUM","LABEL":"Cashbox Operating Mode","OPTIONS":{"ACTIVE":"live","TEST":"test"}}}}}},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/sale.cashbox.handler.add
try
{
const response = await $b24.callMethod(
"sale.cashbox.handler.add",
{
"CODE": "restcashbox01",
"NAME": "REST-Cashbox 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": "Authorization",
"ITEMS": {
"KEYWORD": {
"TYPE": "STRING",
"LABEL": "Password"
},
"PREFERENCE": {
"TYPE": "ENUM",
"LABEL": "Multiple Choice",
"REQUIRED": "Y",
"OPTIONS": {
"FIRST": "First",
"SECOND": "Second",
"THIRD": "Third",
}
}
}
},
"INTERACTION": {
"LABEL": "Interaction Settings with Cashbox",
"ITEMS": {
"MODE": {
"TYPE": "ENUM",
"LABEL": "Cashbox Operating Mode",
"OPTIONS": {
"ACTIVE": "live",
"TEST": "test"
}
}
}
}
}
}
}
);
const result = response.getData().result;
console.dir(result);
}
catch(error)
{
console.error(error);
}
try {
$response = $b24Service
->core
->call(
'sale.cashbox.handler.add',
[
'CODE' => 'restcashbox01',
'NAME' => 'REST-Cashbox 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' => 'Authorization',
'ITEMS' => [
'KEYWORD' => [
'TYPE' => 'STRING',
'LABEL' => 'Password',
],
'PREFERENCE' => [
'TYPE' => 'ENUM',
'LABEL' => 'Multiple Choice',
'REQUIRED' => 'Y',
'OPTIONS' => [
'FIRST' => 'First',
'SECOND' => 'Second',
'THIRD' => 'Third',
],
],
],
],
'INTERACTION' => [
'LABEL' => 'Interaction Settings with Cashbox',
'ITEMS' => [
'MODE' => [
'TYPE' => 'ENUM',
'LABEL' => 'Cashbox Operating Mode',
'OPTIONS' => [
'ACTIVE' => 'live',
'TEST' => '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.callMethod(
"sale.cashbox.handler.add",
{
"CODE": "restcashbox01",
"NAME": "REST-Cashbox 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": "Authorization",
"ITEMS": {
"KEYWORD": {
"TYPE": "STRING",
"LABEL": "Password"
},
"PREFERENCE": {
"TYPE": "ENUM",
"LABEL": "Multiple Choice",
"REQUIRED": "Y",
"OPTIONS": {
"FIRST": "First",
"SECOND": "Second",
"THIRD": "Third",
}
}
}
},
"INTERACTION": {
"LABEL": "Interaction Settings with Cashbox",
"ITEMS": {
"MODE": {
"TYPE": "ENUM",
"LABEL": "Cashbox Operating Mode",
"OPTIONS": {
"ACTIVE": "live",
"TEST": "test"
}
}
}
}
}
}
},
function(result)
{
if(result.error())
console.error(result.error());
else
console.dir(result.data());
}
);
require_once('crest.php');
$result = CRest::call(
'sale.cashbox.handler.add',
[
'CODE' => 'restcashbox01',
'NAME' => 'REST-Cashbox 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' => 'Authorization',
'ITEMS' =>
[
'KEYWORD' =>
[
'TYPE' => 'STRING',
'LABEL' => 'Password'
],
'PREFERENCE' =>
[
'TYPE' => 'ENUM',
'LABEL' => 'Multiple Choice',
'REQUIRED' => 'Y',
'OPTIONS' =>
[
'FIRST' => 'First',
'SECOND' => 'Second',
'THIRD' => 'Third',
]
]
]
},
'INTERACTION' =>
[
'LABEL' => 'Interaction Settings with Cashbox',
'ITEMS' =>
[
'MODE' =>
[
'TYPE' => 'ENUM',
'LABEL' => 'Cashbox Operating Mode',
'OPTIONS' =>
[
'ACTIVE' => 'live',
'TEST' => 'test'
]
]
]
]
]
]
]
);
echo '<PRE>';
print_r($result);
echo '</PRE>';
Typical use-cases and scenarios
Response Handling
HTTP Status: 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
}
}
Returned Data
|
Name |
Description |
|
result |
Identifier of the created handler |
|
time |
Information about the request execution time |
Error Handling
HTTP Status: 400, 403
{
"error": "ERROR_HANDLER_ALREADY_EXIST",
"error_description": "Handler already exists!"
}
|
Name |
Description |
|
error |
String error code. It may consist of digits, Latin letters, and underscores |
|
error_description |
Textual description of the error. The description is not intended to be shown to the end user in its raw form |
Possible Error Codes
|
Code |
Description |
Status |
|
|
Insufficient permissions to add the handler |
403 |
|
|
Required field value is missing or one of the field values is incorrect |
400 |
|
|
A handler with the code specified in the |
400 |
|
|
Other errors. More detailed information about the error can be found in |
400 |
Statuses and System Error Codes
HTTP Status: 20x, 40x, 50x
The errors described below may occur when calling any method.
|
Status |
Code |
Description |
|
|
|
An internal server error has occurred. Please contact the server administrator or Bitrix24 technical support |
|
|
|
An internal server error has occurred. Please contact the server administrator or Bitrix24 technical support |
|
|
|
The request intensity limit has been exceeded |
|
|
|
The current method is not permitted for calls using batch |
|
|
|
The maximum length of parameters passed to the batch method has been exceeded |
|
|
|
Invalid access token or webhook code |
|
|
|
The HTTPS protocol is required for method calls |
|
|
|
The REST API is blocked due to overload. This is a manual individual block; please contact Bitrix24 technical support to lift it |
|
|
|
The REST API is only available on commercial plans |
|
|
|
The user associated with the access token or webhook used to call the method lacks the necessary permissions |
|
|
|
The manifest is not available |
|
|
|
The request requires higher privileges than those provided by the webhook token |
|
|
|
The provided access token has expired |
|
|
|
The user does not have access to the application. This means that the application is installed, but the portal administrator has restricted access to this application to specific users only |
|
|
|
The public part of the site is closed. To open the public part of the site on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site |
PRINT_URL Page
The PRINT_URL page is the address to which data for printing the receipt is sent.
Example Data Sent to PRINT_URL
{
"type": "sell",
"calculated_sign": "income",
"unique_id": 85,
"items": [
{
"name": "Product",
"base_price": 12000.0,
"price": 9600.0,
"sum": 9600.0,
"currency": "USD",
"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": "USD"
}
],
"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"
}
}
}
Structure of POST Parameters Sent to PRINT_URL
|
Name |
Description |
|
type |
Type of receipt. Values:
|
|
operation |
Indicator of income/expenditure. Values:
|
|
calculated |
Analogous to |
|
unique_id |
ID of the receipt in the database of the account |
|
items |
Array of products in the receipt (detailed description provided below) |
|
date_create |
Date of receipt creation ( |
|
payments |
Array of payments (detailed description provided below) |
|
client_email |
Client's e-mail (if available) |
|
client_phone |
Client's phone number (if available) |
|
total_sum |
Total amount of the receipt |
|
uuid |
Identifier of the document in the external system (Bitrix24 account) |
|
service_email |
Email (from cashbox settings) |
items Parameter
|
Name |
Description |
|
name |
Name of the product |
|
base_price |
Price of the product without discounts and surcharges |
|
price |
Selling price |
|
sum |
Amount of the item |
|
quantity |
Quantity of the product |
|
vat |
Tax identifier. It can be used in the catalog.vat.get method to obtain information about the tax |
|
vat_sum |
Tax amount |
|
barcode |
Barcode. Used when inventory management is enabled and the product is transferred with a unique barcode |
|
nomenclature_code |
Nomenclature code in binary representation (if available) |
|
marking_code |
Nomenclature code (if available) |
|
payment_object |
Indicator of the payment item. Standard values:
|
|
payment_method |
Indicator of the payment method. Values:
|
|
supplier_info |
Agency details when using agency schemes (detailed description provided below) |
|
discount |
Discount on the product. The key is deprecated and is no longer used. |
supplier_info Parameter
|
Name |
Description |
|
phones |
Phone numbers |
|
name |
Name of the supplier |
|
inn |
Supplier's INN |
payments Parameter
|
Name |
Description |
|
type |
Type of payment. Values:
|
|
is_cash |
Is the payment made in cash ( |
|
sum |
Payment amount |
|
currency |
Payment currency |
CHECK_URL Page
The CHECK_URL page is the address for checking the success of receipt printing.
A request to the CHECK_URL address is made either by the manager's request or automatically after some time following the successful printing of the receipt.
Example Data Sent to CHECK_URL
{
"uuid": "00112233-4455-6677-8899-aabbccddeeff"
}
Structure of POST Parameters Sent to CHECK_URL
|
Name |
Description |
|
uuid |
Identifier of the receipt |
Continue Learning
- Update Cash Register Handler sale.cashbox.handler.update
- Get a list of available cash register handlers sale.cashbox.handler.list
- Delete Cashbox Handler sale.cashbox.handler.delete
- Add Cash Register sale.cashbox.add
- Update Existing Cash Register sale.cashbox.update
- Get a list of configured cash registers sale.cashbox.list
- Delete cash register sale.cashbox.delete
- Save the result of printing the receipt sale.cashbox.check.apply
- How to Connect a Cash Register to Bitrix24