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:

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:

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.