Requirements to the development of peripheral equipment drivers

Requirements version: 1.3.

Change history

This table lists the changes introduced to this document after version 1.2.

Version Section Changes
1.3 Receipt printer driver requirements New section.
1.3 Fiscal printer driver requirements New method: OpenShift.

Introduction

The model used for connecting peripheral equipment to 1C:Enterprise-based automated systems minimizes the number of intermediate components between the device and 1C:Enterprise configuration, which ensures high reliability.

The peripheral equipment driver requirements describe the standard methods and properties used by both the configuration and the equipment driver. The integration library configuration component interacts with low-level equipment drivers using standard commands, which ensures predictable results (see figure 1).

Figure 1. Peripheral equipment interaction model

The equipment is connected to the system using a driver based on the add-in creation technology. The technology defines the interface for the interaction between the platform and the driver. You can implement a driver using either standard component objects for Windows (COM interface) or the proprietary 1C technology NativeAPI (a dynamic library for Windows and Linux). The NativeAPI provides tools for the development of add-ins compatible with both client applications and 1C:Enterprise server (including their Linux versions).

The add-in interface requirements consist of four parts:

  • The first part defines the general driver requirements and driver architecture requirements.
  • The second part is the system part, which defines a set of service functions and methods related to peripheral equipment driver functioning. This includes setting up the driver, getting its description, testing it, and handling errors.
  • The third part is the functional part, which defines sets of mandatory peripheral equipment-specific functions and methods.
  • The fourth part defines the requirements for connecting drivers that comply with the 1C:Compatible standard to 1C:Enterprise configurations.

1. General driver requirements and driver architecture requirements

The driver must meet the following requirements.

  1. The driver is implemented as an add-in based on the add-in development technology described in the Add-in Development Technology article.
  2. The add-in that communicates with peripheral equipment contains a single object that implements a 1C:Enterprise script extension and has the RegisterExtensionAs method, which returns the extension name that matches the second part of the add-in ProgId. For example, if the ProgId is "Addin.Scanner", the function returns "Scanner". The extension name cannot contain spaces or inadmissible characters (according to 1C:Enterprise object name generation rules).
  3. For add-ins implemented using the COM technology, objects are implemented as unmanaged components (written in unmanaged code).
  4. Functionality required for a specific peripheral equipment type is fully implemented (all of the methods are implemented and they function as described in this document). If a function is not supported by the equipment, it returns "False" and the error message retrieved using the GetLastError method states that the function is not supported by the equipment.
  5. The driver supports the parallel work of multiple devices (is capable of calling procedures on each of the connected devices).
  6. If an error occurs, the driver provides a detailed error description that explains the cause of the error to the user and includes troubleshooting options.
  7. The driver must handle abnormal situations correctly (this includes incorrect user actions, absence of a called procedure of function, passing invalid values, and so on). The driver does not shut down unexpectedly and does not perform any other actions that might impact the user experience.
  8. The driver accepts and returns value tables in XML format (XML text in UTF-8 encoding passed in a STRING parameter). This method of sending complex data structures is chosen because it is independent of the driver implementation technology (Windows COM or NativeAPI).
  9. The driver supports the SetLocale method and sets up its environment language (text labels, messages, and more) according to the received locale code. The driver includes environment localization for the local region code, as well as English localization of the environment. If the received locale code is not supported, the driver sets its environment locale to English. For more information on the usage of the SetLocale method, see the Add-in Development Technology.

You can choose from the following driver architecture options:

  • Single-component driver. It is delivered as a single file intended for use solely with 1C:Enterprise software system. All of the runtime libraries and other files required by the driver must be statically included in the driver because they might not be available on the end-user computer, or the end-user might have different versions of these files installed. The recommended development technology for a single-component driver is NativeAPI.
  • Multicomponent driver. A hardware and software complex intended for use with both 1C:Enterprise and third-party solutions. It consists of two parts:
    • Integration library. A library intended to integrate the main driver delivery with 1C:Enterprise. The library interface complies with the general driver requirements and the add-in development technology, but the library does not implement the peripheral equipment driver functionality. The integration library implements search for installed main driver delivery, driver initialization, and call redirection. All of the runtime libraries and other required files are statically included in the component.
    • Main driver delivery. A driver implemented by a vendor as a custom file set using any available technology. The protocol used for communication between the driver and the integration library is not regulated by this document. The driver is installed from a vendor distribution package.

2. Mandatory functions and methods related to peripheral equipment driver functioning

This section lists the mandatory functions and methods related to peripheral equipment driver functioning, which include setting up the driver, getting its description, testing it, and handling errors.

The driver supports two operation scenarios:

  • Equipment registration and setup
  • Regular equipment operation

Equipment registration and setup

  1. Get driver description by calling the GetDescription method.
  2. Get driver setup parameters by calling the GetParameters method.
  3. Generate driver setup form based on the list of parameters.
  4. Save driver parameters in the configuration database.

Regular equipment operation

  1. Initialize device with the parameters stored in the database by calling the SetParameter method.
  2. Connect to the device by calling the Open method using the parameter values that were previously set by the SetParameter method. The Open method returns the device ID.
  3. Call functions and methods that are mandatory for this equipment type with the device ID passed as a parameter.
  4. Get error code and description by calling the GetLastError method (if an error occurs).
  5. Disconnect from the device by calling the Close method with the device ID passed as a parameter.
Attention! All values of interface elements (names, descriptions, captions, messages, and so on) must be displayed in the language specified in the locale code. See item 9 in section "General driver requirements and driver architecture requirements" earlier in this document.

Method name
Parameters
Return value type
Method description
Name
Type
Description
GetVersion

-

-

-

STRING

Returns the driver version number.
GetDescription Name STRING [OUT] Driver name

BOOL

Returns driver information (name, description, supported equipment type, and so on).
Description STRING [OUT] Driver description
EquipmentType STRING [OUT] String that stores the equipment type*
InterfaceRevision LONG [OUT] Supported version of requirements** for this equipment type
IntegrationLibrary BOOL [OUT] Shows whether the component is an integration library or a standalone driver
MainDriverInstalled BOOL [OUT] Shows whether the main driver delivery is installed (for integration libraries only)
GetDownloadURL STRING [OUT] Returns an empty string or the vendor web site address with a URL for downloading the main driver delivery or any other information about the driver. If it is an empty string, the installation of the main driver delivery is not performed.
GetLastError ErrorDescription

STRING [OUT]

Error description

LONG

Returns the code and description of the latest error.
GetParameters TableParameters, an XML table

STRING [OUT]

Parameter list

BOOL

Returns the list of driver parameters with their types, default values, and available values.
SetParameter Name

STRING [IN]

Parameter name

BOOL

Sets a parameter value by parameter name.
Value

VARIANT [IN]

Parameter value
Open DeviceID

STRING [OUT]

Device ID

BOOL

Connects to the equipment using the parameter values that were previously set by the SetParameter function. Returns the connected device ID.
Close DeviceID STRING [IN] Device ID

BOOL

Disconnects from the equipment.
DeviceTest Description STRING [OUT] Test result

BOOL

Attempts connection to the device and sends a request to the device using the parameter values that were previously set by the SetParameter method. If the connection is established, returns the device information as the test result.
DemoModeIsActivated STRING [OUT] In the demo mode returns the description of mode limitations, otherwise returns an empty value. Example: "You need a dongle key to unlock the full driver functionality".
GetAdditionalActions TableActions,
an XML table

STRING [OUT]

Additional action list

BOOL

Gets the list of actions that will be displayed as additional menu items in the equipment setup form, which is available to administrators. If no actions are available, returns an empty string.
DoAdditionalActions ActionName STRING [IN] Action name

BOOL

Executes an additional action with the specified name.

* The string that stores the equipment type can have one of the following values: "BarcodeReader", "MagneticCardReader", "FiscalPrinter", "ReceiptPrinter", "CustomerDisplay", "DataCollectionTerminal", "POSTerminal", "ElectronicScale", "ScaleWithLabelPrinting", or "OfflineCashRegister".

** The version of requirements is the version of this document (for version 1.00, specify 1000; for version 1.12, specify 1012; for the current version 1.3, specify 1003).

TableParameters

The table of parameters has XML format. It is passed in a STRING parameter. It stores the descriptions of all driver parameters and the description of the graphic interface of the driver setup.

For each parameter, the table can define its position (tab and group within the tab) on the 1C:Enterprise configuration form. Tabs and groups can have names, which are displayed on the form. Parameters can have predefined value sets that will form drop-down selection lists. Parameters that depend on other parameters can be made available when needed.

Attribute name
Mandatory/
Optional
Data type
Attribute description
Name Mandatory
STRING Name of parameter linked to an input field. It cannot contain spaces or inadmissible characters (according to 1C:Enterprise object name generation rules), and it must be unique within the parameter table.
Caption Mandatory STRING Custom text before the input field.
Description Optional
STRING Parameter description. It is displayed in a tooltip.

TypeValue

Mandatory STRING One of the following data types: "String", "Number", or "Boolean".
FieldFormat Optional
STRING Format string of the parameter value.
DefaultValue Optional STRING Default parameter value.
ReadOnly Optional BOOL Shows whether the parameter is read-only.
ChoiceList Optional LIST List of parameter values available for selection.
PageCaption Optional STRING Name of the tab where the input field is located.
GroupCaption Optional STRING Name of the group where the input field is located.
MasterParameterName Optional STRING Name of the parameter that defines whether the field is available.
MasterParameterOperation Optional STRING The operation used for comparison with the master parameter: Equal or NotEqual.
MasterParameterValue Optional STRING The master parameter value used with the MasterParameterOperation condition. When the condition is true, the input field is available. If
MasterParameterName and MasterParameterOperation are not defined, the field is always available.

The following is an example of an XML text that describes driver parameters.

 <?xml version="1.0" encoding="UTF-8" ?>
 <Settings>
     <Page Caption="Options"> 
         <Group Caption="Connection settings">
             <Parameter Name="Model" Caption="Model" TypeValue="Number"/> 
             <Parameter Name="Port" Caption="Port" TypeValue="Number" DefaultValue="0">
                 <ChoiceList>
                     <Item Value="0">Keyboard</Item>
                     <Item Value="1">COM1</Item>
                     <Item Value="2">COM2</Item>
                 </ChoiceList>
             </Parameter>
             <Parameter Name="Parity" Caption="Parity" TypeValue="Boolean" DefaultValue="True"/>
             <Parameter Name="Speed" Caption="Speed" TypeValue="Number" FieldFormat="" 
                 DefaultValue="1" MasterParameterName="" MasterParameterOperation="" MasterParameterValue=""/>
         </Group>
     </Page>
 </Settings> 

The following form is generated based on the XML description.

TableActions

The table of actions has XML format. It is passed in a STRING parameter. It stores the descriptions of additional driver setup and management actions available in the equipment setup form, which is available to administrators.

In the equipment setup form, the actions are added to the Functions menu, after the Test equipment item. Selecting any of these menu items calls the DoAdditionalAction method with the ActionName parameter that matches the menu item. During the action execution, the driver can create additional dialog boxes as described in Add-in Development Technology.

Attribute name Mandatory/
Optional
Data type Attribute description
Name Mandatory STRING Name of the action linked to the menu item. It cannot contain spaces or inadmissible characters (according to 1C:Enterprise object name generation rules), and it must be unique within the table of actions.
Caption Mandatory STRING Menu item name.

The following is an example of an XML text that describes additional actions.

 <?xml version="1.0" encoding="UTF-8" ?>
 <Actions>
     <Action Name="SettingLog" Caption="Logging options" /> 
 </Actions>

The following menu items are generated in the setup form based on the XML description.

3. Peripheral equipment-specific methods

3.1. Electronic scale driver requirements

Configurations support the following online scale functionalities:

  1. Entering the tare weight before weighing a packed item.
  2. Getting the item weight after subtracting the tare weight.
Method name Parameters Return value type Method description
Name
Type Description
Calibrate DeviceID

STRING [IN]

Device ID

BOOL

Sets the tare weight. If this parameter is set to 0, the weight currently registered by the scale is taken as the tare weight.
TareWeight

DOUBLE [IN]

Tare weight
GetWeight DeviceID

STRING [IN]

Device ID

BOOL

Gets the weight of the item being weighed.
Weight

DOUBLE [IN]

Item weight

3.2. Electronic scale with offline label printing driver requirements

For scales with label printing, uploading a table of goods is supported. The table is based on the database data, it is generated using 1C:Enterprise configuration tools. The procedure of uploading a table to an electronic scale must support multiple upload iterations by subsequent calls of the UploadGoods method with data packages of specific size (for example, 100 records each), which have the package status parameter specified ("first", "last", or "regular" for packages that are neither first nor last).

Method name Parameters Return value type Method description
Name Type Description
UploadGoods DeviceID

STRING [IN]

Device ID

BOOL

Uploads the list of goods to the scale.
GoodsTable,
an XML table

STRING [IN]

Table of goods
PackageStatus

STRING [IN]

Package status*
ClearGoods DeviceID

STRING [IN]

Device ID

BOOL

Clears the list of goods in the scale.

* The string that stores the package status can have one of the following values: "first", "regular", or "last".

GoodsTable

The table of goods has XML format. It is passed in a STRING parameter.

Attribute name Mandatory/
Optional
Data type Attribute description
PLU Mandatory LONG PLU number (a number used to identify the product)
Code Mandatory LONG Barcode prefix for variable-weight items
Name Mandatory STRING Product name
Price Mandatory DOUBLE Price per kilogram (example: if the price is 1 dollar and 50 cents, set this parameter to 1.50)
Description Optional STRING Text description of the product (parts, ingredients, and so on)
ShelfLife Optional LONG Shelf life/period of validity, in days

The following is an example of an XML text that describes a table of goods.

 <?xml version="1.0" encoding="UTF-8"?>
 <Table>
     <Record PLU="1" Code="1003" Name="Apple Golden Delicious" Price="95.50" ShelfLife="7"/>
     <Record PLU="2" Code="1023" Name="Corn Salad" Price="500.00" 
         Description="Ingredients: corn, tomatoes, sweet peas, cucumber, onion, pimentos, mayonnaise, salt, pepper" ShelfLife="1"/>
 </Table>

3.3. Customer display driver requirements

While a purchase is being registered, related data can be displayed on a customer display. The structure of the displayed data is defined in the configuration. Multiline displays and display windows are supported.

Method name Parameters Return value type Method description
Name Type Description
StringOutputOnCustomerDisplay DeviceID

STRING [IN]

Device ID

BOOL

Displays the passed strings on the customer display. Each string matches a single display row. If a passed string is empty, the displayed text is not changed.
Strings

STRING [IN]

Strings that contain data to be displayed
ClearCustomerDisplay DeviceID

STRING [IN]

Device ID

BOOL

Clears the customer display.
GetOutputOptions DeviceID

STRING [IN]

Device ID

BOOL

Gets the customer display size.
DeviceColumns

LONG [OUT]

Returns the number of columns on the display (the number of characters in a row)
DeviceRows

LONG [OUT]

Returns the number of display rows

3.4. Data collection terminal driver requirements

For data collection terminals, uploading a table of goods and downloading a table of selected goods are supported. The table of goods is based on the database data, it is generated using 1C:Enterprise configuration tools. The procedure of uploading a table to a data collection terminal must support multiple upload iterations by subsequent calls of the UploadTable method with data packages of specific size (for example, 100 records each), which have the package status parameter specified ("first", "last", or "regular" for packages that are neither first nor last). The procedure of downloading a table is performed by a single call of the DownloadTable method.

Method name Parameters Return value type Method description
Name Type Description
UploadTable DeviceID STRING [IN] Device ID BOOL Uploads a table of goods to the data collection terminal.
GoodsTable,
an XML table
STRING [IN] Table being uploaded
PackageStatus STRING [IN] Package status*
DownloadTable DeviceID STRING [IN] Device ID BOOL Downloads a table from the data collection terminal.
DownloadTable,
an XML table
STRING [OUT] Table being downloaded
ClearTable DeviceID STRING [IN] Device ID BOOL Clears a previously uploaded table of goods.

* The string that stores the package status can have one of the following values: "first", "regular", or "last". If all the data fits a single package, assign "last" to it.

GoodsTable

The table of goods has XML format. It is passed in a STRING parameter.

Attribute name Mandatory/
Optional
Data type Attribute description
BarCode Mandatory STRING Product barcode
Name Optional STRING Product name
UnitOfMeasurement Optional STRING Product measurement unit
CharacteristicOfNomenclature Optional STRING Product characteristic (a set of product properties, for example, shoe size and color)
SeriesOfNomenclature Optional STRING Product part number
Quality Optional STRING Product quality grade
Price Optional DOUBLE Price
Quantity Optional DOUBLE Product quantity

The following is an example of an XML text that describes a table.

<?xml version="1.0" encoding="UTF-8"?> 
<Table>
    <Record BarCode="4008110271538" Name="Notebook" UnitOfMeasurement="pcs" CharacteristicOfNomenclature="" 
        SeriesOfNomenclature="" Quality="" Price="25.30" Quantity="7"/>
    <Record BarCode="2900001355643" Name="Can (tinned) dates fruit" UnitOfMeasurement="pcs" CharacteristicOfNomenclature="" 
        SeriesOfNomenclature="" Quality="Green" Price="95.50" Quantity="7">
</Table>
DownloadTable

The table has XML format. It is passed in a STRING parameter.

 Attribute name Mandatory/
Optional
Data types Attribute description
BarCode Mandatory STRING Product barcode
Quantity Mandatory DOUBLE Product quantity

The following is an example of an XML text that describes a table.

<?xml version="1.0" encoding="UTF-8"?> 
<Table>
    <Record BarCode="4008110271538" Quantity="4"/> 
    <Record BarCode="2900001355643" Quantity="2"/> 
</Table>

3.5. Offline cash register driver requirements

For offline cash registers, uploading a table of goods and downloading a table of sales registered during the current shift are supported. The table of goods is based on the database data, it is generated using 1C:Enterprise configuration tools. The procedure of uploading a table to a cash register must support multiple upload iterations by subsequent calls of the UploadGoods method with data packages. The procedure of downloading a table is performed by a single call of the DownloadReport method.

Method name Parameters Return value type Method description
Name Type Description
UploadGoods DeviceID STRING [IN] Device ID
BOOL Uploads the list of goods to the cash register.
GoodsTable,
an XML table
STRING [IN] A value table that contains goods data
DownloadReport DeviceID STRING [IN] Device ID BOOL Downloads the sales report from the cash register.
ReportTable,
an XML table
STRING [OUT] A value table that contains sales data
LoadSuccess DeviceID STRING [IN] Device ID BOOL The flag is set to "True" if the report was processed successfully. Otherwise it is set to "False".
StateFlag BOOL [IN] Shows whether the report is processed successfully
ClearTable DeviceID STRING [IN] Device ID BOOL Clears the list of goods in the cash register.

GoodsTable

The table has XML format. It is passed in a STRING parameter.

Attribute name Mandatory/
Optional
Data type Attribute description
Code Mandatory LONG Product code
BarCode Mandatory STRING Barcode (or several barcodes separated by commas)
Name Mandatory STRING Product name
Article Optional STRING Product article
UnitOfMeasurement Optional STRING Product measurement unit
CharacteristicOfNomenclature Optional STRING Product characteristic (a set of product properties, for example, shoe size and color)
SeriesOfNomenclature
Optional STRING Product part number
Quality Optional STRING Product quality grade
Price Mandatory DOUBLE Price
Remainder Optional DOUBLE Product balance
IsWeightGoods Optional BOOL Shows whether it is a variable-weight product

The following is an example of an XML text that describes a table.

<?xml version="1.0" encoding="UTF-8"?> 
<Table> 
    <Record Code="402" BarCode="4008110271538" Name="Notebook" Group="Miscellaneous" UnitOfMeasurement="pcs" 
        CharacteristicOfNomenclature="" SeriesOfNomenclature="" Quality="" Price="25.30" Remainder="7" /> 
    <Record Code="423" BarCode="2900001355643,2900001355679" Name="Apple Golden Delicious" Group="Fruits" UnitOfMeasurement="pcs" 
        CharacteristicOfNomenclature="" SeriesOfNomenclature="" Quality="Green" Price="95.50" Remainder="7" IsWeightGoods="True"/> 
</Table>
ReportTable

The table has XML format. It is passed in a STRING parameter.

Attribute name Mandatory/
Optional
Data type Attribute description
Code Mandatory LONG Product code
Price Mandatory DOUBLE Actual sale price
Quantity Mandatory DOUBLE Product quantity
Discount Mandatory DOUBLE Discount percentage
Amount Mandatory DOUBLE Total product price after applying all discounts and extra charges

The following is an example of an XML text that describes a table.

<?xml version="1.0" encoding="UTF-8"?> 
<Table>
    <Record Code="40" Price="20" Quantity="2" Discount="0" Amount="40"/> 
    <Record Code="423" Price="100" Quantity="1" Discount="5" Amount="95"/> 
</Table>

3.6. Fiscal printer driver requirements

Configurations support the following fiscal printer functionalities:

  • Printing receipts for cash deposits and withdrawals
  • Printing cash register receipts
  • Printing shift reports with reset (Z-reports) or without reset (X-reports)
Cash register receipt printing algorithm

To generate a cash register receipt, the system issues a command to open a new receipt. Depending on the passed parameter, the receipt is opened in fiscal or nonfiscal mode.

Then, while the receipt is open, fiscal or nonfiscal lines are printed. The fiscal line print procedure includes discount calculation. If the value calculated by the formula Price*Quantity - Line amount is not 0, the absolute monetary value of the discount is printed on the receipt. If the discount value is negative, the "Extra charge" string is displayed instead of "Discount".

Canceling open receipts (by using the CancelOpenedCheck parameter of the OpenCheck method) is supported.

Printing barcodes in open receipts is supported, provided that the equipment supports this functionality.

Once all of the receipt lines are printed, the payment in accordance with the receipt is registered. Multiple payment options are supported. For fiscal receipts, totals and payment amounts are printed.

Method name Parameters Return value type Method description
Name Type Description
OpenShift DeviceID STRING [IN] Device ID BOOL Opens a new shift.
OpenCheck DeviceID STRING [IN] Device ID
BOOL Opens a new receipt.
IsFiscalCheck BOOL [IN] Shows whether the receipt is fiscal
IsReturnCheck

BOOL [IN]

Shows whether it is a purchase return receipt
CancelOpenedCheck BOOL [IN] Shows whether a previously opened receipt is being canceled
CheckNumber LONG [OUT] New receipt number
SessionNumber LONG [OUT] Shift number
PrintFiscalString DeviceID STRING [IN] Device ID BOOL Prints a commodity item line with the specified attributes.
Name STRING [IN] Product name
Quantity DOUBLE [IN] Product quantity
Price DOUBLE [IN] Product price per unit (example: if the price is 1 dollar and 50 cents, set this parameter to 1.50)
Amount DOUBLE [IN] The total commodity item price after applying all discounts and extra charges (example: if the price is 1 dollar and 50 cents, set this parameter to 1.50)
Department LONG [IN] Store department
Tax DOUBLE [IN] VAT percentage (a value from 0 to 99.99)
PrintNonFiscalString DeviceID STRING [IN] Device ID
BOOL Prints a custom text string in the receipt.
TextString STRING [IN] Custom text string
PrintBarCode DeviceID STRING [IN] Device ID BOOL Prints a barcode, which is autosized and aligned centrally. The barcode type can have one of the following values: EAN8, EAN13, or CODE39. If the connected equipment does not support barcode printing, an error is reported.
BarcodeType STRING [IN] String that defines barcode type
Barcode STRING [IN] Barcode value
CloseCheck DeviceID STRING [IN] Device ID BOOL Closes a receipt. The total of all payment types must be greater than the total receipt amount.
Cash DOUBLE [IN] Cash payment amount
PayByCard DOUBLE [IN] Card payment amount
PayByCredit DOUBLE [IN] Credit payment amount
PayByCertificate DOUBLE [IN] Certificate payment amount
CancelCheck DeviceID STRING [IN] Device ID BOOL Cancels a previously opened receipt (requires administrative rights).
CashInOutcome DeviceID STRING [IN] Device ID BOOL Prints a check for a deposited or withdrawn amount. Nonnegative amounts are treated as deposits; negative amounts are treated as withdrawals.
Amount DOUBLE [IN] Deposited or withdrawn amount (example: if the amount is 1 dollar and 50 cents, set this parameter to 1.50)
PrintXReport DeviceID STRING [IN] Device ID BOOL Prints a shift report without reset (without closing the shift)
PrintZReport DeviceID STRING [IN] Device ID BOOL Prints a shift report with reset (closes the shift, requires administrative rights).
OpenCashDrawer DeviceID STRING [IN] Device ID BOOL Opens the cash drawer connected to the fiscal printer.
GetLineLength DeviceID STRING [IN] Device ID BOOL Gets the maximum receipt line length (in characters).
LineLength LONG [OUT] Line length, in characters.

3.7. Receipt printer driver requirements

Configurations support the following receipt printer functionalities:

  • Printing text receipts
  • Printing barcodes
  • Opening cash drawer
Receipt printing algorithm

When connecting to a device using the Open method, the driver initializes the printer. This includes defining the encoding for printing receipts.

During the receipt generation, the configuration calls the OpenDocument command to open a new document on the receipt printer, and then calls the PrintString command in a loop to print each line of the document. Printing a barcode in an open receipt using the PrintBarcode command is supported, provided that the device model supports this functionality.

The CloseDocument command closes the document. This can also include sending a command to the cutter when necessary, provided that the device model supports this functionality.

Method name Parameters Return value type Method description
Name Type Description
OpenDocument DeviceID STRING [IN] Device ID BOOL Opens a new document. The driver can check the availability of the device and paper and return False if the document cannot be printed.
PrintString DeviceID STRING [IN] Device ID BOOL Prints a text string.
TextString STRING [IN] Custom text string
PrintBarCode DeviceID STRING [IN] Device ID BOOL Prints a barcode, which is autosized and aligned centrally. The barcode type can have one of the following values: EAN8,EAN13, or CODE39. If the connected equipment does not support barcode printing, an error is reported.
BarcodeType STRING [IN] String that defines barcode type

 

Barcode

STRING [IN] Barcode value
CloseDocument DeviceID STRING [IN] Device ID BOOL Closes a previously opened document and sends the command to the cutter when necessary.
OpenCashDrawer DeviceID STRING [IN] Device ID BOOL Opens the cash drawer connected to the receipt printer.
GetLineLength DeviceID STRING [IN] Device ID BOOL Gets the maximum receipt line length (in characters).
LineLength LONG [OUT] Line length, in characters.

3.8. Input device (barcode reader, magnetic card reader, and so on) driver requirements

Input readers automatically read data encoded in a variety of formats and asynchronously send it to 1C:Enterprise configuration. Drivers of input devices do not have equipment-specific methods that can be called from configurations.

Configurations support the following driver operations:

  1. During the add-in object initialization, a pointer to 1C:Enteprise interface (which can be used for calling the HRESULT ExternalEvent(BSTR bstrWho, BSTR bstrWhat, BSTR bstrData) method) is passed to the object.
  2. On each successful reading performed by a reader or a scanner, the driver calls the HRESULT ExternalEvent(BSTR bstrWho, BSTR bstrWhat, BSTR bstrData) method.
  3. The read data is added to the message queue. The messages are only processed after all 1C:Enterprise system messages are processed. In the event of queue overflow, new messages are ignored.

The following methods can be called asynchronously from the driver*.

Method name Parameters Return value type Method description
Name Type Description
ExternalEvent bstrWho BSTR [IN] Unique ID of the connected device**

HRESULT

Puts data received from the scanner or reader to the message queue.
bstrWhat BSTR [IN] Message/data type***
bstrData BSTR [IN] Data read by the device
SetEventBufferDepth lDepth BSTR [IN] Maximum number of messages in the queue

HRESULT

Sets the message queue length.

* For descriptions of the rest of the functions that can be called from the driver, see Add-in Development Technology.

** The bsrtWho parameter contains the unique ID of the connected device.

*** The bsrtWhat parameter specifies the event type. For scanners, it must contain the "Barcode" string. For magnetic card readers, it must contain the "TracksData" string. In the event of an error, it must contain the "DriverError" value and the bstrData parameter must contain the error description.

3.9. POS terminal driver requirements

Configurations support the following POS operations:

  • Card payment
  • Card payment reversal
  • Card payment return
  • Freezing funds on the card account
  • Debiting frozen funds from the card account
  • Unfreezing funds on the card account
  • Emergency transaction cancellation
  • Receiving end-of-day card data
Card payment

For card payment, the platform calls the PayByPaymentCard method with the payment amount and the read card number passed as parameters. If the card number will be read on a bank terminal or a PIN pad, an empty string is passed instead of the card number. The driver returns the function execution result, the RRN code, the authorization code, and the slip text. The slip text can be printed on the built-in terminal printer or on a fiscal printer (this is defined by the PrintSlipOnTerminal method). Once the function is executed, the card number read on a bank terminal or a PIN pad is returned in the card number parameter*.

Card payment reversal

For card payment reversal, the platform calls the CancelPaymentByPaymentCard method with the payment amount, the read card number, the RRN code of the transaction being reversed, and the authorization code passed as parameters. The driver returns the function execution result. If the card number will be read on a bank terminal or a PIN pad, an empty string is passed instead of the card number. Once the function is executed, the card number read on a bank terminal or a PIN pad is returned in the card number parameter*.

 Card payment return

For card payment return, the platform calls the ReturnPaymentByPaymentCard method with the payment amount, the read card number, the RRN code of the payment transaction being returned, and the authorization code passed as parameters. The driver returns the function execution result and provides the RRN code and the authorization code as output parameters. If the card number will be read on a bank terminal or a PIN pad, an empty string is passed instead of the card number. Once the function is executed, the card number read on a bank terminal or a PIN pad is returned in the card number parameter*.

Freezing funds on the card account

For freezing funds on a card account, the platform calls the AuthorisationByPaymentCard method with the amount being frozen and the read card number passed as parameters. If the card number will be read on a bank terminal or a PIN pad, an empty string is passed instead of the card number. The driver returns the function execution result, the RRN code, the authorization code, and the slip text. The slip text can be printed on the built-in terminal printer or on a fiscal printer (this is defined by the PrintSlipOnTerminal method). Once the function is executed, the card number read on a bank terminal or a PIN pad is returned in the card number parameter*.

Debiting frozen funds from the card account

For debiting frozen funds from the card account, the platform calls the AuthConfirmationByPaymentCard method with the amount being debited, the read card number, the RRN code of the freeze transaction, and the authorization code passed as parameters. If the card number will be read on a bank terminal or a PIN pad, an empty string is passed instead of the card number. The driver returns the function execution result, the RRN code, the authorization code, and the slip text. The slip text can be printed on the built-in terminal printer or on a fiscal printer (this is defined by the PrintSlipOnTerminal method). Once the function is executed, the card number read on a bank terminal or a PIN pad is returned in the card number parameter*.

Unfreezing funds on the card account

For unfreezing funds on the card account, the platform calls the CancelAuthorisationByPaymentCard method with the payment amount being unfrozen, the read card number, the RRN code of the freeze transaction, and the authorization code passed as parameters. If the card number will be read on a bank terminal or a PIN pad, an empty string is passed instead of the card number. The driver returns the function execution result, the RRN code, the authorization code, and the slip text. The slip text can be printed on the built-in terminal printer or on a fiscal printer (this is defined by the PrintSlipOnTerminal method). Once the function is executed, the card number read on a bank terminal or a PIN pad is returned in the card number parameter*.

Emergency transaction cancellation

If the payment transaction completed successfully and a slip should be printed on a fiscal printer (this is defined by the PrintSlipOnTerminal method) but a print error occurred, the card transaction must be canceled.

Receiving end-of-day card data

For receiving end-of-day card data, the platform calls the Settlement method. The driver returns the function execution result and the report text.

* If the bank regulations prohibit providing full card numbers, digits in the parameter value are partially replaced by asterisks.

Method name Parameters Return value type Method description
Name Type Description
PayByPaymentCard DeviceID STRING [IN] Device ID
BOOL Performs card payment authorization.
CardNumber STRING [IN/OUT] Card number/Card data*
Amount DOUBLE [IN] Payment amount
ReceiptNumber STRING [IN/OUT] Receipt number
RRNCode STRING [OUT] Unique RRN code of the transaction
AuthorizationCode STRING [OUT] Authorization code of the transaction
Slip STRING [OUT] Slip text generated by POS software**
ReturnPaymentByPaymentCard DeviceID STRING [IN] Device ID BOOL Performs card payment reversal.
CardNumber STRING [IN/OUT] Card number/Card data*
Amount DOUBLE [IN] Payment amount
ReceiptNumber STRING [IN/OUT] Receipt number
RRNCode STRING [IN/OUT] Unique RRN code of the transaction
AuthorizationCode STRING [IN/OUT] Authorization code of the transaction
Slip STRING [OUT] Slip text generated by POS software**
CancelPaymentByPaymentCard DeviceID STRING [IN] Device ID BOOL Performs card payment return.
CardNumber STRING [IN/OUT] Card number/Card data*
Amount DOUBLE [IN] Payment amount
ReceiptNumber STRING [IN/OUT] Receipt number
RRNCode STRING [IN/OUT] Unique RRN code of the transaction
AuthorizationCode STRING [IN/OUT] Authorization code of the transaction
Slip STRING [OUT] Slip text generated by POS software**
AuthorisationByPaymentCard DeviceID STRING [IN] Device ID BOOL Performs preauthorization (freezes funds on the card account).
CardNumber STRING [IN/OUT] Card number/Card data*
Amount DOUBLE [IN] Payment amount
ReceiptNumber STRING [IN/OUT] Receipt number
RRNCode STRING [OUT] Unique RRN code of the transaction
AuthorizationCode STRING [OUT] Authorization code of the transaction
Slip STRING [OUT] Slip text generated by POS software**
AuthConfirmationByPaymentCard DeviceID STRING [IN] Device ID BOOL Completes preauthorization (debits the frozen funds from the card account).
CardNumber STRING [IN/OUT] Card number/Card data*
Amount DOUBLE [IN] Payment amount
ReceiptNumber STRING [IN/OUT] Receipt number
RRNCode STRING [IN] Unique RRN code of the transaction
AuthorizationCode STRING [IN] Authorization code of the transaction
Slip STRING [OUT] Slip text generated by POS software**
CancelAuthorisationByPaymentCard DeviceID STRING [IN] Device ID BOOL Cancels preauthorization (unfreezes funds on the card account).
CardNumber STRING [IN/OUT] Card number/Card data*
Amount DOUBLE [IN] Payment amount
ReceiptNumber STRING [IN/OUT] Receipt number
RRNCode STRING [IN] Unique RRN code of the transaction
AuthorizationCode STRING [IN] Authorization code of the transaction
Slip STRING [OUT] Slip text generated by POS software**
EmergencyReversal DeviceID STRING [IN] Device ID BOOL Cancels the last transaction.
Settlement DeviceID STRING [IN] Device ID BOOL Performs end-of-day settlement.
Slip STRING [OUT] Slip text generated by POS software**
PrintSlipOnTerminal

-

-

-

BOOL

The return value shows whether the terminal prints slips on its built-in printer.

* When card data is passed from a 1C:Enterprise configuration to a POS system, this value must match the POS system requirements. In addition to the card number, it might contain other data read from the card.

** If you need to print multiple documents, use [cut] as a separator.

4. Connecting drivers that comply with the 1C:Compatible standard to 1C:Enterprise configurations

The integration library component must provide the following functionality:

  • Loading a driver delivered an add-in archive to the Infobase
  • Loading a driver delivered as a vendor distribution kit to the Infobase
  • Using a driver that is previously installed on a local computer

4.1. Preparing a driver for loading to an integration library

Preparing a driver delivered as an add-in archive

Preparing a driver delivered as an add-in archive for loading to an integration library is performed according to section Preparing add-ins for loading them to configurations of the "Add-in Development Technology" document. The archive must also include the INFO.XML file, which contains data required for loading the driver.

The XML file must have the following structure:

Attribute name Mandatory/
Optional
Data type Attribute description
progid Mandatory STRING Driver object ID.
type Mandatory STRING Driver types, one of the following: "BarcodeReader", "MagneticCardReader", "FiscalPrinter", "ReceiptPrinter", "CustomerDisplay", "DataCollectionTerminal", "POSTerminal", "ElectronicScale", "ScaleWithLabelPrinting", or "OfflineCashRegister".
name Mandatory STRING Driver name displayed to users.
version Mandatory STRING Driver version.

The following is an example of the INFO.XML file.

<?xml version="1.0" encoding="UTF-8"?>
<drivers>
    <component progid="AddIn.EmulatorFP1C" type="FiscalPrinter" name="1C:Fiscal printer emulator" version="1.0.21.1"/>
</drivers>

Preparing a driver delivered as a vendor distribution kit

Provide the driver installation package in a ZIP archive. The installer executable file must be named setup.exe. You can add any other files required by the installer to the archive. The archive must also include the INFO.XML file, which contains data required for loading the driver. The file format is described in the previous section.

Next page: Administration

Be the first to know tips & tricks on business application development!

A confirmation e-mail has been sent to the e-mail address you provided .

Click the link in the e-mail to confirm and activate the subscription.