Requirements to the development of peripheral equipment drivers

Requirements version: 1.3.

• Change history
• Introduction
• General driver requirements and driver architecture requirements
• Mandatory functions and methods related to peripheral equipment driver functioning
• Peripheral equipment-specific methods
  • Electronic scale driver requirements
  • Electronic scale with offline label printing driver requirements
  • Customer display driver requirements
  • Data collection terminal driver requirements
  • Offline cash register driver requirements
  • Fiscal printer driver requirements
  • Receipt printer driver requirements
  • Input device (barcode reader, magnetic card reader, and so on) driver requirements
  • POS terminal driver requirements
• Connecting drivers that comply with the 1C:Compatible standard to 1C:Enterprise configurations
  • Preparing a driver for loading to an integration library
    • Preparing a driver delivered as an add-in archive
    • Preparing a driver delivered as a vendor distribution kit

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