Fundamentals

This is the starting point for developing a UTD Integration.

This document will give you a general view of the different integration strategies so that you can choose the one that better fits your needs.

Integration Strategy

UTD integration can be achieved in the following ways:

through a DLL Call
through a Web Service Call

DLL Integration

Windows Applications must load TkReceiptManager.dll.

TkReceiptManager.dll only exposes 1 method: PROCESS

This method receives an XML Document and outputs an XML Document and an Error Message text.

The DLL parameters are the following:

Name	Type	Passed by	Description
aXml	WideString	Value	Input XML
aOutput	Widestring	Reference	Output XML
aErrorMessage	Widestring	Reference	Error Message Text

The DLL Return Value is an integer as by the following table

Value	Mnemonic	Description
0	errrpm_Ok	Ok
-1	errrpm_UnknownError	Error Returned by the Driver or unknown internal error
-2	errrpm_LoadError	Error while loading Xml input Document
-3	errrpm_DocumentEmpty	Xml Document is empty
-4	errrpm_WrongRootNode	Root Node name is wrong. A ReceiptPrinterManager configuration document must have "ReceiptPrinterManager" as Root Node.
-5	errrpm_DriverNodeMissing	Driver node missing in Xml Document
-6	errrpm_MethodNodeMissing	Method node missing in Xml Document
-7	errrpm_LoadLibraryError	Unable to Load Driver Library (based on driver node content)
-8	errrpm_MethodNotFound	Unable to Get Method Address (based on method node content)

Web Services Integration

Web Services Integration is done using UTD Server.

UTD Server is a Windows Service that expose an HTTP service to which it is possible to send UTD Server Documents.

A UTD Server Document is an XML document composed by a Root Node and a list of XML Nodes, each one represents a complete UTD XML Document

For further information read UTD Server documentation.

XML Structure

All messages are encapsulated in XML documents.

Request:

The XML document has some nodes that are common to all messages plus one optional node, specific for each method

The standard/common nodes are:

Level	Node Name	Node Value(s)	Notes
0	ReceiptPrinterManager		Root Node Attributes: Version="1.0"
1	Type	PAYMENT	Identify the Type of Device
1	Driver	<string>	Name of the driver that will process the request
1	LogId	<string>	Prefix of the log files
1	Method	<string>	Method to execute. Common Methods are: OPEN, CLOSE, VERSION. Each Message Type will then provide its own methods
1	Connection
2	Type	SERIAL HTTP TCP DLL OPOS COM SPOOL	Connection Type
2	SerialPort	COM1..COM99	Only if Type=SERIAL
2	Speed	<integer>	Serial Port Speed Only if Type=SERIAL
2	DataBits	7 8	Only if Type=SERIAL
2	Parity	NONE EVEN ODD	Only if Type=SERIAL
2	StopBits	0 1 2	Only if Type=SERIAL
2	URL	<string>	Only if Type=HTTP
2	AuthType	NONE BASIC DIGEST	Only if Type=HTTP
2	User	<string>	Only if Type=HTTP
2	Password	<password>	Only if Type=HTTP
2	Address	<string>	Only if Type=TCP
2	Port	<integer>	Only if Type=TCP
2	DeviceName	<string>	Only if Type=OPOS
2	LibraryName	<string>	DLL Name Only if Type=DLL
2	PrinterName	<string>	Only if Type=SPOOL
2	ConnectTimeout	1..300	Connect Timeout in seconds
2	ReadTimeout	1..300	Read Timeout in seconds
1	Parameters		Additional parameters, specific for each driver. Children nodes name specify the parameter name and the nodes value their value
1	Handle	<integer>	Not used in OPEN. All other messages MUST contain the Handle returned by the OPEN method.

Example:

XML

<ReceiptPrinterManager Version="1.0">
  <Type>PAYMENT</Type>
  <Driver>TKPA_KPAY_10</Driver>
  <LogId>XXX-001</LogId>
  <Connection>
    <Type>DLL</Type>
    <LibraryName>kpay-eft-lib-c-2.5.3.0.dll</LibraryName>
  </Connection>
  <Parameters>
    <HexLog>False</HexLog>
    <ConfigFileName>c:\kpay\eft.ini</ConfigFileName>
  </Parameters>
  <Method>OPEN</Method>
</ReceiptPrinterManager>

Response

The XML document has some nodes that are common to all messages plus several other optional nodes, specific for each method

The standard/common nodes are:

Level	Node Name	Node Value(s)	Notes
0	ReceiptPrinterManagerResponse		Root Node
1	Error	<boolean>	True: Error Found False: No errors
1	ErrorText	<string>	In case of Error, it reports the error message
1	LogFileName	<string>	The Log File Name where the operation has been logged

Example:

XML

<ReceiptPrinterManagerResponse>
  <Handle>1</Handle>
  <Error>False</Error>
  <ErrorText></ErrorText>
  <LogFileName>C:\UTD\LogFiles\FiscalPrinter\TKRP_EPSFPXML_10_103-001_20200602.log</LogFileName>
</ReceiptPrinterManagerResponse>