Documentation

Example of standard REST API cash register

Adding a cash register handler

Example of adding a cash register handler with option to configure authorization data, company data and cash register mode:

	BX.rest.callMethod(
    "sale.cashbox.handler.add",
    {
        "CODE": "my_rest_cashbox",
        "NAME": "My REST cash register",
        "SORT": 100,
        "SETTINGS":
        {
            "PRINT_URL": "http:\/\/example.com\/rest_print.php",
            "CHECK_URL": "http:\/\/example.com\/rest_check.php",
            "CONFIG":
            {
                "AUTH": {
                    "LABEL": "Authorization",
                    "ITEMS": {
                        "LOGIN": {
                            "TYPE": "STRING",
                            "REQUIRED": "Y",
                            "LABEL": "Login"
                        },
                        "PASSWORD": {
                            "TYPE": "STRING",
                            "REQUIRED": "Y",
                            "LABEL": "Password"
                        },
                    }
                },
                "COMPANY": {
                    "LABEL": "Authorization data",
                    "ITEMS": {
                        "INN": {
                            "TYPE": "STRING",
                            "REQUIRED": "Y",
                            "LABEL": "company TIN"
                        }
                    }
                },
                "INTERACTION": {
                    "LABEL": "Cash register interaction settings",
                    "ITEMS": {
                        "MODE": {
                            "TYPE": "ENUM",
                            "LABEL": "Cash register mode",
                            "OPTIONS": {
                                "ACTIVE": "active",
                                "TEST": "test"
                            }
                        }
                    }
                }
            }
        }
    },
    function(result)
    {
        if(result.error())
            console.error(result.error());
        else
            console.dir(result.data());
    }
);

Added cash register is configured by user via online store settings or Sales Center.

PRINT_URL page

PRINT_URL page - URL address to receive cash receipt print data.

Structure of POST-parameters, sent to PRINT_URL address:

Parameters Description
typeReceipt type. Values:
  • sell - full payment;
  • sellreturncash - full cash return;
  • sellreturn - full cashless return;
  • advancepayment - advance payment;
  • advancereturn - cashless advance payment return;
  • advancereturncash - cash advance payment return;
  • creditpayment - credit payment;
  • creditpaymentreturn - cashless credit payment return;
  • creditpaymentreturncash - cash credit payment return;
  • credit - purchase on credit;
  • creditreturn - purchase on credit return;
  • prepayment - partial prepayment;
  • prepaymentreturn - cashless partial prepayment return;
  • prepaymentreturncash - cash partial prepayment return;
  • fullprepayment - 100% prepayment;
  • fullprepaymentreturn - 100% cashless prepayment return;
  • fullprepaymentreturncash - 100% cash prepayment return.
calculated_signReceipt/expenditure attribute. Values:
  • income - receipt;
  • consumption - expenditure.
unique_idreceipt ID in the account database.
itemsArray with products in receipt. Array element structure:
  • name - product name;
  • base_price - product base price;
  • price - product price;
  • sum - item total;
  • quantity - product quantity;
  • vat - tax ID;
  • vat_sum - tax total;
  • payment_object - payment object attribute. Values:
    • commodity - product;
    • excise - excisable product;
    • job - job;
    • service - service;
    • payment - payment;
    • gambling_bet - gambling bet;
    • gambling_prize - gambling prize;
    • lottery - lottery ticket;
    • lottery_prize - lottery prize;
    • intellectual_activity - intellectual activity results;
    • agent_commission - agent commission;
    • composite - composite calculation object;
    • another - other calculation object;
    • property_right - property right;
    • non-operating_gain - non-operating income;
    • sales_tax - sales tax;
    • resort_fee - resort fee.
  • payment_method - payment method attribute. Values:
    • full_payment - full payment;
    • advance - advance payment;
    • prepayment - prepayment;
    • full_prepayment - 100% prepayment;
    • credit - payment on credit;
    • credit_payment - credit payment.
date_createDate of receipt (timestamp).
paymentsArray with payments. Structure of array items:
  • type - payment type. Values:
    • cash - cash payment;
    • cashless - cashless payment.
  • is_cash - cash payment attribute. Values: Y/N
  • sum - payment total.
client_emailCustomer email.
total_sumTotal receipt payment.
uuidDocument ID in third-party system (Bitrix24 account).
number_kkmCash register external ID (from cash register settings).
service_emailEmail (from cash register settings).
cashbox_paramsArray with cash register settings. Structure is specified by parameter CONFIG of array SETTINGS, specified as method parameter [link=13176582]sale.cashbox.handler.add[/link].

The PRINT_URL parameter processes input data, generates a document and returns print result. Response in case of error is JSON-array as follows:

{
"ERRORS": [
      "Error message",
      "Error message",
      ...
]
}

Upon successful printing, array looks as follows:

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

Example of standard handler:

<?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();
}
 
// necessary actions: user authorization, data processing, receipt registration in the system... 
 
echo json_encode([
  'UUID' => $resultUUID,
]);

CHECK_URL page

CHECK_URL page: URL address for checking receipt printing success.

Query at the address CHECK_URL is performed upon manager request or after some time after successful receipt printing.

Structure of POST-parameters, sent to the address PRINT_URL:

Parameter Description
uuidReceipt ID.

Query to the CHECK_URL must return receipt data, receipt printing error data, or “printing in progress” status.

Example of simple handler:

<?php
 
$uuid = $_REQUEST['uuid'];
 
// necessary actions: check receipt status, ...
 
// when error occurs during receipt printing
if ($result['ERROR'])
{
  echo json_encode([
     'STATUS' => 'ERROR',
     'ERROR' => 'Error message'
  ]);
  die();
}
 
// receipt is not yet printed
if ($result['WAIT'])
{
  echo json_encode([
     'STATUS' => 'WAIT',
  ]);
  die();
}
 
// sending result
 
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,
]);

Data, returned by CHECK_URL is saved into database and used for generating URL for a receipt.


© «Bitrix24», 2001-2022
Up