TPAPI-POS

Interface description

version 2.13

TPAPI 2 Version History

TPAPI POS version 1 Interface Description can be found in separate document

               What’s new in version 2.0

• New requests (2.27 and above)
• New extras available in GetClientsExRequest

Table Of Contents

TPAPI 2 Version History

What’s new in version 2.0

1. Architecture Overview

1.1. Control Flow

1.2. TPAPI Entry Point

1.3. Enabling TPAPI in unTill

1.4. Enabling waiter to be available in TPAPI

1.5. TPAPI versions compatibility

2. unTill POS API

2.1. Ordering Overview

2.2. GetArticles - Brief list of active articles in database

2.2.1. GetArticlesRequest

2.2.2. GetArticlesResponse

2.3. GetArticlesInfo - The detailed list of active articles in database

2.3.1. GetArticlesInfoRequest

2.3.2. GetArticlesInfoResponse

2.4. GetOptionsInfo - The list of active options in database

2.4.1. GetOptionsInfoRequest

2.4.2. GetOptionsInfoResponse

2.5. GetDepartmentsInfo - The list of active departments in database

2.5.1. GetDepartmentsInfoRequest

2.5.2. GetDepartmentsInfoResponse

2.6. GetGroupsInfo - The list of active food groups in database

2.6.1. GetGroupsInfoRequest

2.6.2. GetGroupsInfoResponse

2.7. GetCategoriesInfo - The list of active categories in database

2.7.1. GetCategoriesInfoRequest

2.7.2. GetCategoriesInfoResponse

2.8. GetPricesInfo - The list of active prices

2.8.1. GetPricesInfoRequest

2.8.2. GetPricesInfoResponse

2.9. GetPaymentsInfo - The list of available payment types

2.9.1. GetPaymentsInfoRequest

2.9.2. GetPaymentsInfoResponse

2.10. GetSalesAreasInfo - The list of active sales areas

2.10.1. GetSalesAreasInfoRequest

2.10.2. GetSalesAreasInfoResponse

2.11. GetActiveOrders - List of active orders within sales-areas

2.11.1. GetActiveOrdersRequest

2.11.2. GetActiveOrdersResponse

2.12. CreateOrder - Creates order

2.12.1. CreateOrderRequest

2.12.2. CreateOrderResponse

2.13. CloseOrder - Close order and pay with specified payment type

2.13.1. CloseOrderRequest

2.13.2. CloseOrderResponse

2.14. PosRestart - Restarts POS

2.14.1. PosRestartRequest

2.14.2. PosRestartResponse

2.15. GetUsersInfo - Get list of active users

2.15.1. GetUsersInfoRequest

2.15.2. GetUsersInfoResponse

2.16. GetTimeAttendanceReport - Read Time&Attendance Report

2.16.1. GetTimeAttendanceRequest

2.16.2. GetTimeAttendanceResponse

2.17. GetTurnoverReport - Read Turnover Report

2.17.1. GetTurnoverReportRequest

2.17.2. GetTurnoverReportResponse

2.18. GetDetailedTurnoverReport - Read Detailed Turnover Report

2.18.1. GetDetailedTurnoverReportRequest

2.18.2. Available extra fields

2.18.3. GetDetailedTurnoverReportResponse

2.19. GetClients - Read The List of Clients.

2.19.1. GetClientsRequest

2.19.2. GetClientsResponse

2.20. GetVersion - Read Current TPAPI Protocol Version

2.20.1. GetVersionRequest

2.20.2. GetVersionResponse

2.21. GetCancelledItemsReport - Read List of Cancelled Items

2.21.1. GetCancelledItemsReportRequest

2.21.2. GetCancelledItemsReportResponse

2.22. ClientDeposit - Makes Deposit to Client Account

2.22.1. ClientAccountDepositRequest

2.22.2. ClientAccountDepositResponse

2.23. UpdateClients  - Create or Update clients in database.

2.23.1. UpdateClientsRequest

2.23.2. UpdateClientsResponse

2.24. GetClientsEx - Returns the list of clients using additional filters

2.24.1. GetClientsExRequest

2.24.2. GetClientsResponse - ref. response for GetClients method. Clients sorted by number.

2.25. NextCourse - Apply next course to table

2.25.1. NextCourseRequest

2.25.2. NextCourseResponse

2.26. SetTableCourse - Apply course to certain table

2.26.1. SetTableCourseRequest

2.26.2. SetTableCourseResponse

2.27. GetActiveTableInfo - Information about open table

2.27.1. GetActiveTableInfoRequest

2.27.2. GetActiveTableInfoResponse

2.28. FindTransactions - Find transactions in database

2.28.1. FindTransactionsRequest

2.28.2. FindTransactionsResponse

2.29. GetServerInfo - Get Server Information

2.29.1. GetServerInfoRequest

2.29.2. GetServerInfoResponse

2.30. GetBOStatus - Get Current Backoffice Status

2.30.1. GetBOStatusRequest

2.30.2. GetBOStatusResponse

2.31. Pay - Make payment on table with specified payment type

2.31.1. PayRequest

2.31.2. PayResponse

2.32. GetDepositsReport - Read List of Cancelled Items

2.32.1. GetDepositsReportRequest

2.32.2. GetDepositsReportResponse

2.33. GetInOutCashReport - Read “In/Out Cash Report”

2.33.1. GetInOutCashReportRequest

2.33.2. GetInOutCashReportResponse

2.34. PrintProforma - Print proforma for a table

2.34.1. PrintProformaRequest

2.34.2. PrintProformaResponse

2.35. GetCountries - Return list of countries

2.35.1. GetCountriesRequest

2.35.2. GetCountriesResponse

2.36. UpdateCountries - Add or update countries

2.36.1. UpdateCountriesRequest

2.36.2. UpdateCountriesResponse

2.37. PrintReport - Print report

2.37.1. PrintReportRequest

2.37.2. PrintReportResponse

ArticleInfo

ArticleShort

CancelledItem

CategoryInfo

Client

Country

Credential

DepartmentInfo

DepositItem

ExtraInfo

GroupInfo

HourlyWageItem

InOutCashItem

ItemPrice

KeyValue

Language

OptionInfo

OrderInfo

OrderItem

PriceInfo

PaymentInfo

SalesAreaInfo

TableRange

TimeAttendanceRecord

TurnoverBill

TurnoverBillItem

TurnoverTransaction

TransactionBillReprint

TransactionProforma

TransactionOrder

TransactionOrderItem

TransactionBill

TransactionBillPayment

UserGroup

UserInfo

App 2. Return codes

App 3. Constants

App 4. SOAP Examples

1. Architecture Overview

unTill server provides SOAP interface for 3rd party applications which may be used for remotely working with POS: reading configuration, making orders, etc (TPAPI-POS API)

1.1. Control Flow

• 3rd party software calls SOAP functions, provided by untillsrv;
• unTill Server communicates to special instance of unTill.exe which runs in background
• unTill.exe performs required actions and sends back results

1.2. TPAPI Entry Point

TPAPI POS WSDL can be obtained from running untillsrv instance using HTTP address like:

http://<host-name>:<port>/wsdl/ITPAPIPOS

URL example:http://localhost:3063/wsdl/ITPAPIPOS

WSDL can be used to generate client for TPAPI web-service on any programming language.

1.3. Enabling TPAPI in unTill

To enable TPAPI interface, untill.ini must contain the following information:

[common]

;enable SOAP server.

soapport=3063  

[TPAPI]

;enable TPAPI

UntillDatabaseName=[Untill_Database_Name]

On=1

Where [Untill_Database_Name] – is a short name of Untill database, f.e. regression.gdb

To make TP API unavailable, parameter “On” should be to “0”.

Note. “soapport” setting defines TCP port for listening incoming SOAP connections. Normally you should specify N+3 where N is the number defined by “port” setting in untill.ini. Do not specify other values in the range N..N+5, because they can be blocked by other unTill services, but N+3 is always reserved for TPAPI.

1.4. Enabling waiter to be available in TPAPI

Each call to SOAP includes waiter name and TPAPI Password. To allow waiter be used in TPAPI calls, special “TPAPI Password” field must be specified in unTill BO for this waiter. Additional field is introduced since Passwords are normally very simple and can be easily hacked. Also, when configuring TPAPI user, ensure that “POS password” contains only digits.

1.5. TPAPI versions compatibility

Normally TPAPI POS protocol versions are backwards-compatible, so you can update unTill and do not take care that something will be broken in newer TPAPI version. If you are working with web-service using stub class generated by WSDL it also work in most cases. However it was found that stubs generated for Java (AXIS) are unable to work with an updated web-service if there were any change. This is known AXIS issue. For applications using AXIS stubs, you should take care of current TPAPI version, and update stub code each time protocol version is changed.

MS.NET clients does not produces any problem on webservice update.

2. unTill POS API

unTIll POS API provides set of functions which may be used for requesting info abot POS configuration and executing actions like creating order, closing order, etc.

The following functions available in unTIll POS API:

• GetArticles - brief list of active articles
• GetArticlesInfo - detailed list of active articles
• GetOptionsInfo - active options
• GetDepartmentsInfo - active departments
• GetGroupsInfo - active groups
• GetCategoriesInfo - active categories
• GetPricesInfo - list of active prices
• GetPaymentsInfo - list of available payment types
• GetSalesAreasInfo - list of active sales areas
• GetActiveOrders - information about tables within sales-areas
• CreateOrder - create order on non-occupied table
• CloseOrder - close and pay order with certain payment type
• PosRestart - restart TPAPI POS
• GetUsersInfo - get list of users
• GetTimeAttendanceReport - get “Time and attendance” report
• GetTurnoverReport - get turnover report
• GetDetailedTurnoverReport - get detailed turnover report
• GetVersion - get current TPAPI protocol version
• GetCancelledItemsReport - get cancelled items report
• ClientDeposit - Makes deposit to client account
• UpdateClients - Create or Update clients in database
• GetClientsEx - Returns the list of clients using additional filters
• NextCourse - Apply next course to table
• SetTableCourse - set course for certain table containing active order
• GetActiveTableInfo - returns info about open table
• FindTransactions -  Find transactions in database
• GetServerInfo - Get Server Information
• GetBOStatus - Get Current Backoffice Status
• Pay - Make payment on table with specified payment type
• GetDepositsReport - Read List of Cancelled Items
• GetInOutCashReport - Read “In/Out Cash Report”
• PrintProforma - Print proforma for a table
• GetCountries - Read list of countries
• UpdateCountries - Add/update countries
• PrintReport - Print report to printer or return as plain text

The POS configuration should be read with the following algorythm:

1. Read the list of sales areas with GetSalesAreasInfo
2. Read the list of prices with GetPricesInfo
3. Read the list of options with GetOptionsInfo
4. Read the list of articles with GetArticlesInfo
5. Read the list of payments with GetPaymentsInfo

This sequence may be repeated from time to time to keep POS configuration up-to-date on a client side.

After configuration received, GetActiveOrders may be called at any time to get current availability of tables. Use CreateOrder for creating new order, and CloseOrder for paying and closing existing order.

Some functions require TableNumber and TablePart, where TablePart is a letter in a range from “a” to “f”. Other values not accepted.

2.1. Ordering Overview

The following articles and option types can be ordered with TPAPI:

• regular articles (BO: Articles)
• supplements for an article (articles from an option specified in BO: Department / Supplement)
• condiments for an article (articles from an option specified in BO: Department / Condiment)
• must-have options for an article (articles from an options listed in BO: Articles / tab “Options”)
• free-option for an article (articles from an option specified in BO: Articles / tab “Options” / field “Free Option”)
• menu items. If certain article is a menu (Checkbox “Menu” in BO: Articles), the list of “must have” options for this article acts as a list of article-groups. Client may order one article per each option, this article will be included into order as “menu item”
• article messages: some text which may be informative either for certain order item, the order part or the complete order.

To identify item type, there is “order_item_type” field in OrderItem structure. It is not required to specify in CreateOrder request if certain article has “menu” enabled: only requirement is to identify it’s menu items.

Below there are few examples. Order items shown hierarchically just for convenience. In the list of items they follow one after another.

1. List of regular articles: order_item_type = 0 used for all items
2. Article with “must-have” options:

• article 1: order_item_type = 0

• option1_article1 : order_item_type = 1
• option1_article2 : order_item_type = 1
• …

3. Article with different types of options:

• article 1: order_item_type = 0

• option1_article1 : order_item_type = 1 (must-have option)
• option1_article2 : order_item_type = 1 (must-have option)
• free_option_article1 : order_item_type = 2 (free option)
• condiment_article1: order_item_type = 4 (condiment)
• supplement_article1: order_item_type = 3 (supplement)
• supplement_article2: order_item_type = 3 (supplement)

4. Menus:

• menu 1: order_item_type = 0 (article, with “menu” enabled)

• option1_article1 : order_item_type = 5 (menu item)
• option2_article1 : order_item_type = 5 (menu item)
• option3_article1 : order_item_type = 5 (menu item)

5. Each menu item may also have different types of options:

• menu 1: order_item_type = 0 (article, with “menu” enabled)

• option1_article1 : order_item_type = 5 (menu item)
• option2_article1 : order_item_type = 5 (menu item)

1. optionA_article1: order_item_type = 1 (must have option)
2. optionB_article1: order_item_type = 1 (must have option)

• option3_article1 : order_item_type = 5 (menu item)

2.2. GetArticles - Brief list of active articles in database

2.2.1. GetArticlesRequest

2.2.2. GetArticlesResponse

2.3. GetArticlesInfo - The detailed list of active articles in database

Returns the list of articles with their options. Each article represented by ArticleInfo structure. Condiment, supplement and free options returned in separate fields, and “mist have” options returned as a list of Ids. If article is a menu, it returns “true” in its is_menu field.

If ArticleId specified, only one article returned.

If SalesAreaId specified in request, only those articles returned, which is available in this sales area.

2.3.1. GetArticlesInfoRequest

* Extra fields available for using in request:

• course_id - ID of course
• “DailyStock=1” - additionally return information about daily stock status for each article. Data returned in “ArticleInfo.Extra” field with keys “daily_stock_active” and “daily_stock_qty”. By default daily stock information is not returned.

2.3.2. GetArticlesInfoResponse

* The following extra fields returned:

• course_id  - Course ID
• info - Article info (tab 9 of the article settings in back-office)
• daily_stock_active - 1/0 (if DailyStock=1 was specified in request’s Extra fields)
• daily_stock_qty - Daily stock quantity (if DailyStock=1 was specified in request’s Extra fields)

2.4. GetOptionsInfo - The list of active options in database

2.4.1. GetOptionsInfoRequest

2.4.2. GetOptionsInfoResponse

2.5. GetDepartmentsInfo - The list of active departments in database

2.5.1. GetDepartmentsInfoRequest

2.5.2. GetDepartmentsInfoResponse

2.6. GetGroupsInfo - The list of active food groups in database

2.6.1. GetGroupsInfoRequest

2.6.2. GetGroupsInfoResponse

2.7. GetCategoriesInfo - The list of active categories in database

2.7.1. GetCategoriesInfoRequest

2.7.2. GetCategoriesInfoResponse

2.8. GetPricesInfo - The list of active prices

2.8.1. GetPricesInfoRequest

2.8.2. GetPricesInfoResponse

2.9. GetPaymentsInfo - The list of available payment types

2.9.1. GetPaymentsInfoRequest

2.9.2. GetPaymentsInfoResponse

2.10. GetSalesAreasInfo - The list of active sales areas

2.10.1. GetSalesAreasInfoRequest

2.10.2. GetSalesAreasInfoResponse

2.11. GetActiveOrders - List of active orders within sales-areas

2.11.1. GetActiveOrdersRequest

2.11.2. GetActiveOrdersResponse

2.12. CreateOrder - Creates order

2.12.1. CreateOrderRequest

(*) Table parts usage::

1. “a” to “f” table parts available
2. If no parts occupied - you can only order at "a"
3. If only 1 part (X) occupied on table - then it is possible to make order at this part, or at table part (X + 1), if available
4. If more than 1 part occupied, then you can make order on any

(**) The following extra fields accepted:

• “extraNN” where NN is 1 to 10. These fields available in unTill datasets “Order” (screens/tickets), “Bills” (reports). The same values will be returned in GetActiveOrders response in “extra” field.
• “OifDate” (syntax is “YYYYMMDD-HHNN”) - when specified, it creates “Order In Future”.

2.12.2. CreateOrderResponse

2.13. CloseOrder - Close order and pay with specified payment type

2.13.1. CloseOrderRequest

2.13.2. CloseOrderResponse

2.14. PosRestart - Restarts POS

2.14.1. PosRestartRequest

2.14.2. PosRestartResponse

2.15. GetUsersInfo - Get list of active users

2.15.1. GetUsersInfoRequest

2.15.2. GetUsersInfoResponse

2.16. GetTimeAttendanceReport - Read Time&Attendance Report

2.16.1. GetTimeAttendanceRequest

2.16.2. GetTimeAttendanceResponse

2.17. GetTurnoverReport - Read Turnover Report

Returns the list of transactions with ordered items included

2.17.1. GetTurnoverReportRequest

2.17.2. GetTurnoverReportResponse

2.18. GetDetailedTurnoverReport - Read Detailed Turnover Report

Returns the detailed list of transactions over specified period. For each transaction list of orders and list of bills returned.

2.18.1. GetDetailedTurnoverReportRequest

2.18.2. Available extra fields

• OnlyPaid: True - includes only order items which has been paid during this period. By default this property is “False”
• TaxesPerBill: True - return information about extra taxes in TurnoverTransaction.ExtraFields:

• service_charge_amount
• vat_on_service_charge_amount
• service_tax_amount
• service_tax_on_service_charge_amount

• TaxesPerOrderItem: True - return information about extra taxes in TransactionOrderItem.ExtraFields:

• service_charge_amount
• vat_on_service_charge_amount
• service_tax_amount
• service_tax_on_service_charge_amount

• DiscountReason: True - name of discount reason returned in TransactionOrderItem.ExtraFields (Key=“discount_reason”)
• ModificationDates: True - transaction modification dates returned in TurnoverTransaction.ExtraFields (Key=”modified”)
• IncludeReopen: True - re-opened bills included in transactions (disabled by default). E.g. when bill paid with CASH then re-opened and paid by VISA, all three bills will be included:

• positive CASH
• negative CASH
• positive VISA

2.18.3. GetDetailedTurnoverReportResponse

2.19. GetClients - Read The List of Clients.

2.19.1. GetClientsRequest

2.19.2. GetClientsResponse

2.20. GetVersion - Read Current TPAPI Protocol Version

2.20.1. GetVersionRequest

2.20.2. GetVersionResponse

2.21. GetCancelledItemsReport - Read List of Cancelled Items

Returns the list of items which has been cancelled (added to some order and then removed by “Cancel” or “Void” button)

2.21.1. GetCancelledItemsReportRequest

2.21.2. GetCancelledItemsReportResponse

2.22. ClientDeposit - Makes Deposit to Client Account

2.22.1. ClientAccountDepositRequest

1List of accepted extra fields:

• get_receipt - Instead of printing deposit receipt unTill sends it back in TPAPI ClientAccountDepositResponse as plain text. Value of ExtraInfo with this key doesn’t matter.

2.22.2. ClientAccountDepositResponse

2 Possible extra fields:

• receipt_text - receipt in a form of plain text returned in this ExtraInfo if “get_receipt” has been added in ClientAccountDepositRequest.Extra

2.23. UpdateClients  - Create or Update clients in database.

When ID is greater than 0, client is updated, else new client created.

2.23.1. UpdateClientsRequest

When using this request, fields AccountBalance and SavePoints are not updated. Use ClientDeposit request for updating AccountBalance.

2.23.2. UpdateClientsResponse

1 Extra fields in response:

• result_ids - comma separated IDs of created and/or updated clients. Number of IDs returned is equal to number of Clients sent in request.

2.24. GetClientsEx - Returns the list of clients using additional filters

2.24.1. GetClientsExRequest

1List of available optional extra fields in request:

• id - Search active client by ID (ModifiedSince ignored when this extra added)
• is_active - specifies which clients to select:

• 1 - only active
• 0 - only inactive
• -1 - both inactive and active

2.24.2. GetClientsResponse - ref. response for GetClients method. Clients sorted by number.

2.25. NextCourse - Apply next course to table

If no more courses on table, ReturnCode will be 7, ReturnMessage: “There are no more courses”

2.25.1. NextCourseRequest

2.25.2. NextCourseResponse

2.26. SetTableCourse - Apply course to certain table

When course is not changed because given course is already set, no error will be returned.

If it is unable to set given course for this table, ReturnCode will be 7, ReturnMessage: “Unable to change table course to [...]”

2.26.1. SetTableCourseRequest

2.26.2. SetTableCourseResponse

2.27. GetActiveTableInfo - Information about open table

Returns transaction structure and amounts (total, remaining, extra) by table number

2.27.1. GetActiveTableInfoRequest

2.27.2. GetActiveTableInfoResponse

2.28. FindTransactions - Find transactions in database

Searches and returns transactions by certain conditions specified in “Conditions” field. Conditions is a set of ExtraInfo entities where each condition has key and value.

2.28.1. FindTransactionsRequest

1 Supported conditions:

2.28.2. FindTransactionsResponse

2.29. GetServerInfo - Get Server Information

Returns general TPAPI server information

2.29.1. GetServerInfoRequest

2.29.2. GetServerInfoResponse

2.30. GetBOStatus - Get Current Backoffice Status

Returns the status including BO database signature. Everytime any backoffice data is updated, this signature is changed.

2.30.1. GetBOStatusRequest

2.30.2. GetBOStatusResponse

2.31. Pay - Make payment on table with specified payment type

2.31.1. PayRequest

1Available extra fields for PayRequest:

• external_id - (up to 50 chars) - unique ID may be assigned to the bill made by “CloseOrder”
• get_bill - if added, then unTill does not print the bill and return it in PayResponse.Extra instead, under the key “bill_text”
• bill_layout - Use custom ticket layout. Value is an ID of unTill ticket .

2.31.2. PayResponse

1Available extra fields for PayResponse:

• bill_text - Bill returned in a form of plain text where lines separated with CRLF. Only returned when “get_bill” has been added in PayRequest extra info.

2.32. GetDepositsReport - Read List of Cancelled Items

Returns the list of deposits per time period

2.32.1. GetDepositsReportRequest

2.32.2. GetDepositsReportResponse

2.33. GetInOutCashReport - Read “In/Out Cash Report”

Returns the list of “in/out” cash entries from database per time period

2.33.1. GetInOutCashReportRequest

2.33.2. GetInOutCashReportResponse

2.34. PrintProforma - Print proforma for a table

Allows to print proforma and optionally return proforma text

2.34.1. PrintProformaRequest

2.34.2. PrintProformaResponse

2.35. GetCountries - Return list of countries

Returns the list of countries, declared in backoffice

2.35.1. GetCountriesRequest

1Extra Fields:

• id - select country by ID
• is_active - select by activity flag:

• 0 - only inactive
• 1 - only active
• -1 - both active and inactive

2.35.2. GetCountriesResponse

2.36. UpdateCountries - Add or update countries

Adds or updates countries in database. When Country.ID = 0, country is added, else updated. It is not allowed to add country when the country with same name is already exists.

2.36.1. UpdateCountriesRequest

2.36.2. UpdateCountriesResponse

1 Extra fields in response:

• result_ids - comma separated IDs of created and/or updated countries. Number of IDs returned is equal to number of Countries sent in request.

2.37. PrintReport - Print report

Allows to print report or return it in response as plain text

2.37.1. PrintReportRequest

2.37.2. PrintReportResponse

App 1. Types and Classes

All strings are unicode UTF8 strings. Other classes are listed below:

ArticleInfo