3rd party eSolution development
The status from one's own perspective serves to coordinate the expectation. If there is a perfectly, Hypersoft assumes that the function is strong in Hypersoft and perfectly supported in the interface, so that a 3rd party can use it to solve all requirements for this area. This and other things thus serve as orientation for you.
Best practice example for paying for existing operations
For all functions that require a Company and SerialNumber parameter, please always use the defaults given to you by Hypersoft.
First steps to pay for existing operations (tables)...
The following methods are available for the workflow of a payment of the table:
List of all bookings...
With the method "GetOpenTable" you get a list of all bookings from all open transactions.
Lister of all bookings of a transaction...
With the method "GetOpenTableBySelection" you get the same data as with "GetOpenTable", but then only for the table that you have passed in the SelectionTable parameter, e.g. "2" for table 2.
We assume that the table number is known to your APP (via the QR code) and therefore only the method "GetOpenTableBySelection" is used.
Calculate operation total...
Adding up the "quantity" * "price" of each item gives the transaction total.
Pay process...
With the method "BookTransaction" or "BookTransactionStr" this open table transaction can be passed as paid, e.g.:
BookTransactionStr("MyCompany", "MySerialNumber", "TNR:2|ZA:47=MyPayment")
If the total under MyPayment corresponds to the transaction total, the transaction is settled by the POS system. In the event of an overpayment (more payment than transaction total), the difference is booked as a tip (the tip is assigned in Hypersoft to the operator with transaction responsibility). Any payment less than the transaction total is saved as an interim payment in the transaction and the transaction with the remaining amount remains open (this allows you to make partial payments that are not assigned to specific item entries).
Billing information...
In the feedback, you will receive the DeliveryID with which you can then, if necessary, send a message. be able to retrieve the billing information. For this purpose, please use the method "GetDeliveryInfo".
The ID 47 from the example is internally fixed to "Pay per App" for the payment type. This payment type can always be used if separation of the actual payment type is not desired. Otherwise, the method "GetMyPaymentMethod" can be used to determine the available payment methods from the POS system.
E.g. 20 = ec, 25 = VISA, 26 = Mastercard, 49 = Sofortüberweisung etc.
Within the Hypersoft system your programme is integrated as a channel, via this channel the bookings are evaluated as >"your solution" Payment<.
Please refer to the documentation for the data structure of the parameters and the feedback of all available methods.
Item and processes with 3rd parties
The items texts are provided in varying degrees, the standard item name is the Bontext 1. There is a method for additional languages regarding the short text and an HTML formatted detail text. Further information such as allergens, ingredients and energy values can also be retrieved.
Another essential point are the adjustments of an item when ordering (modifiers). These can be booked in the form of queries (forced queries) or at the POS and mPOS also by free attachments. Queries have an enormous impact on the master data of an item.
Structure and IDs of the item data...
A steak with salad or garlic bread cannot be a fixed item, but consists of the steak and the choice made, and thus of two out of three items. The lettuce is created once in the master data at the steak level and if this lettuce is to be sold individually, this is its ID (ProductID). If there are several items that have lettuce as a selection, the lettuce receives an additional unique ID (RezID) for each assignment, which is valid for exactly this assignment. The salad with the entrecôte thus has a different unique ID (RezID) than the same salad with the filet mignon. This method not only enables the historical evaluation of master data changes (required in Germany by GDPdU), but also represents the possibility to adapt the supplements and queries for stock management per possible item combination and different in-house and out-of-house recipes.
Basically, all saleable items can be found in the table SYS_Artikel and stored there with the ProductID. In this table, each item (each ProductID) exists only once. In addition, the items are also listed in their corresponding table of the group. The toppings/inserts/queries can be found in the tables SYS_Abfragen and SYS_ArtikelAbfragenNoVK where you can find the corresponding queries/inserts with the Link_ProductID. The RezID from these tables is then necessary for booking.
Go to Internal IDs Print to see how you can print out the master data with the IDs.
Item queries (modifier)
In the Hypersoft system, items can be modified by queries. Informative "without salt", "medium" or regarding the entire configuration and price "with salad -> dressing selection" +4,-. Thus, items in the item master receive pre-configured queries.
The table SYS_Query contains the queries that appear for an item. For example, the query "rare / medium / well done" appears for a steak.
The queries for an item from the table ART_XXX are linked via the column Link_Article_No. When booking an item from the table ART_XXX, it must therefore be checked whether data records with the corresponding Link_Artikel_NR exist in the table SYS_Query.
The column Sort is the display order of the queries requested by the client.
A query on Hypersoft is "16-step", so up to 16 queries can appear in a row. This is realised by the columns "AB1" to "AB16". First, all items with a "1" in "AB1" are displayed. If an item has been selected, all items of the second level "AB2" are displayed first, etc. There is a special feature here:
If an item has only one item in a query level ("AB1-16"), then this item is automatically booked (without query).
Further documentation:
Basic Knowledge 4: Components and Queries
Sub-queries and sub-components
Code Example:
DataSet Typ1: Table name SYS_Abfragen:
Item App Description
In the item master there is an integrated text editor for the app description. The text at the site is saved in RTF format.
The eSolutions interface automatically converts the text into HTML format.
Further documentation: Area App Description
Free fields for further item data (properties)
Additional fields (maximum 64) are available for items, which can optionally also be used in the item interface. The types interface1 to interface10are used for this purpose. A distinction between 1 and 10 is not currently made.
Further documentation: Special features.
Item designations Bontexts
The item names can have different maximum lengths and functions. Bontext 1 is the most important text for the items at the POS system. See the items master at Item description and item receipt texts.
Offer item conditionally
In the Hypersoft Suite there are several options for not selling items under certain conditions, see Offer item conditionally.
The eSolutions interface provides the list of blocked articles (blacklist).
Before posting one of these items, the partner can check whether it is on the blocking list and, if necessary, issue a note. If an item on the blacklist arrives via the eSolutions interface, it will still be booked.
The eSolutions interface provides the Restricted bookable times from the article master in the article data. The partner can therefore check and take into account the time before posting an item. However, if an item arrives at a restricted time as a booking via the eSolutions interface, it will still be booked.
The eSolutions interface provides a list of the availability items including the current stocks (availability manager). The stock of one or more items can also be called up. The partner can thus call up the current stock level before posting one of these items in order to issue a note if necessary. If one of these items arrives as a booking via the eSolutions interface and the stock is insufficient, it will still be booked.
Code example Function to retrieve all availability items..
Further documentation:
Item Storage locations and stock levels of the basic articles
In order to be able to work with stock levels of the basic items, the licence for the controller is required.
Before working with stocks here, you need to understand the meaning of stock levels and other conditional offering of items. For this, please read the corresponding references in the chapter Offer item conditionally. However, if you are sure that you really want to work with "pure stock of basic items" read on here:
You can call up the storage locations of the basic items, find out the current stock quantities, and update the stock quantities.
Code example Function to retrieve the stock.
Code example Function to retrieve the stock as JSON string.
Code Example SetProdStock For the time being, this function is deactivated for security reasons.:
Code Example Function to retrieve the stock:
Further documentation: Choosing the optimal inventory management system.
Item Portion size
Since a typical "size management" for items (pizza small / medium / large) would exceed the possibilities of recipe management and can also only be maintained by users in a very confusing way, Hypersoft offers an alternative.
Hypersoft offers 3 item texts for this ("Item name", "Receipt text1" and "Receipt text2")
Several sizes of an item are identified by the same item name.
The Bontext2 represents the size variant.
Example:
Product Name: Pizza Hawaii Bontext1: Pizza Hawaii small Bontext2: small, 24 cm
Product Name: Pizza Hawaii Bontext1: Pizza Hawaii medium Bontext2: medium, 36 cm
Product Name: Pizza Hawaii Bontext1: Pizza Hawaii big Bontext2: large, 48 cm
The grouping of the items is done here via the item name. Further information on Item designations for 3rd parties.
Out-of-home status and service call
The hypersoft system provides the status External. This must be used by the eSolutions Partner (ECP).
In the standard system, table numbers can be transferred and retrieved for the Full-Service.
Further documentation: Initialise web service
If you work with Quick Service, Digital Service (also Limited Service) or Takeaway, you can also pass a pager number or order number. The following rules are used for this purpose:
You use 10000 for the first operation number, 10000 for the second 11000, then 12000 and start again with 10000 after 99000 at the latest.
If you are working with pager numbers or other document numbers, use the last three digits. Example Pager 25 for the first operation 10025.
The transaction number is displayed on the order receipt and on the Kitchen Displays and is also printed on the service receipt of the Kitchen Monitor. Also the information for out of house (optional also in the house).
Validity check for items
Example using an order via Online Order: The internal unique ID, which is already part of the item master data when uploading (for example to Deliverect), is also part of each individual booking that we receive with the order. This unique ID is used to check whether the item is known in the POS system.
If the item is not known, it gets a status as an unknown item and the item name transferred to the online order is used to display the order process at the checkout (differentiated by color from the known articles, see for example Deliverect).
If the item is known and the price does not match, it will be given the status Price unknown (also differentiated by colour, see for example Deliverect).
If an item is known, the current item text from the cash register is always used with priority.
Item sorting
Items can also be sorted in the Hypersoft system using the freely selectable item number (as this number is hardly ever used at the POS these days).
A 3rd party provider can use this number for sorting.
Customer data with 3rd parties
In the Hypersoft system there are different methods to book on customers.
-
You can call up a customer from the customer database as a customer and post to it as if it were a transaction. You book "on this customer". The customer steps here instead of a possible table number, so that there could be no additional table number.
-
You can simply add customer data to a transaction - even if this customer would exist in the customer database, you do not book to this customer from the database point of view. A table number can also be used here.
-
There are other possibilities.
Determination of a customer
Example from Deliverect, as well as from third party orders (eSolutions): From Deliverect and other online order systems we receive customer information consisting of customer name, company name, telephone number and e-mail address, optionally also street, house number, postcode and city.
On the basis of this data it is checked in the following order whether the customer is already identifiable in Hypersoft customer master:
It is first checked against the telephone number and if this is not known, then against the email address.
If neither of these is known, a new customer data record is created with the transferred data.
The different versions of the Hypersoft customer base are taken into account (offline customer base, customer base 1.0 or customer base 2.0).
Customers from Webshop 1.0 and Webshop 2.0:
When using Webshop 1.0 or 2.0, the offline customer master is not possible, so the customer is already created in the shop (customer master 1.0 or 2.0) and the unique customer ID is transferred to the eSolutions interface with the order. It is therefore not necessary to record the customers here. The customer data record is retrieved from the portal by the eSolutions interface using the ID provided and assigned to the order.
DeliveryID
The DeliveryID is the unique process related to the Online Order System and all optional integrations.
We urge you to use the possibility of images from the item master for the item data and to refrain from contributing image data externally or anchoring them statically in your connection, as this is disadvantageous in processing and can lead to further problems (e.g. during checks). Please see 3rd Party eSolution fiscal requirements.
If their use requires special formats, these can usually be entered in one of the available channels of the item master.
If required, the transmission of channels 2-9 can be activated manually in the sub-channel of the Online Order Connector.
The item master has several image channels. All image channels can be called up in the eSolutions interface. See the chapter Image processing with eSolutions.
Please note, especially with resources such as images, that you can place an unnecessary load on the customer system or also the Hypersoft servers by making too large or too frequent queries. The responsibility for not negatively influencing the system lies with you as the 3rd party. Should we find this out, we will come back to you. In this context, we reserve the right to block your access without further notice in the event of repeated problems.
If you need media data from areas other than the item master, we will be happy to check the possibilities on request.
NoCOO digital invoice directory for 3rd parties
NoCOO (no Co²) stands for a digital invoice directory that can be optionally booked by Hypersoft customers. If digital receipts are to be transmitted to the 3rd party, NoCOO is the solution. See the programme description at NoCOO - Digital Billing. Access and PIN are transmitted via the interface.
Price levels have several important functions in Hypersoft and control VAT in addition to different prices per item. Sentences and the status In-house / Out-of-house, there is also the topic Out-of-house service call. By the way, an item can have more than one fixed VAT rate in the Hypersoft system . Own set.
Hypersoft has an extensive discount system. For 3rd parties, this information can be used from the item data:
-
Item may or may not be discounted
-
Minimum price of the item (this must not be undercut even if the percentage discount would result in this arithmetically.
If necessary, we recommend that you retrieve and apply the set rounding parameters.
See everything on discounts from Apply discounts.
Please do not use Old method: Additional language for itemsin the near future. Please use Languages: Hypersoft Multilingual.
Multi-Object transactions with eCOm API
If the multi-object operation option is active, all online order operations are saved with location numbers and location information. Thus, the first free seat number is used (as is usual in the Hypersoft system) and the first name and surname of the customer, for example, are saved as object information.
Cash terminal Responsibility and equipment
As a rule, the cash register station on which the necessary Hypersoft eSolutions web service has been set up takes over the processing of bookings and transactions. Alternatively, a 3rd party interface can transmit a POS number (station number), which is then responsible for the bookings and transactions. This is also indicated if several eSolutions connections are running simultaneously on a POS system and may need to be set up differently (web shop, order app, etc.). Just by looking at the different headings on order slips or forms, they can give clues about the channel of the order.
One (or more) cash register subsystem(s) can be set up on a cash register station to apply individual settings for incoming bookings and transactions. On a server or a device without Hypersoft POS cashier mode a cashier instance without cashier mode can be set up (as for Orderman control systems) and optionally further subsystems.
The POS terminal or subsystem in question processes the postings and creates the order receipts and invoices/forms according to its settings.
A so-called overview receipt is often set up in connection with the eSolutions interface. For complex preparation tasks, Hypersoft recommends the combination with the Kitchen Monitor System.
Also 3rd party stations, if they are part of the system, should be set up as such at the location of the respective system.
Cancellations with 3rd parties
The Hypersoft system includes a distinctive cancellation management system, with which we offer our customers numerous options and they select the options that suit them best. This is described in the section Cancellation and loss management and the associated chapters such as Cancellations with integrated eSolutions. For the different international locations of the POS system, Hypersoft provides a secure tool to provide correct bookings, reports and exports in case of audits. The 3rd party partners also benefit from this in their daily cooperation. We were able to establish that it was not necessary to provide a function for cancellation via the eSolutions interface in the previous cooperation and can therefore also largely assess systems with an active 3rd party eSolutions connection during audits. We then expect the same from auditors who assess the overall system.
We therefore ask the 3rd parties and our customers to use the existing cancellation functions of the overall system and to continue to do without a cancellation option in the 3rd party eSolutions area. So far, everyone has been able to design a very good workflow with this and at the same time rely on the security of the Hypersoft world. Thank you for your understanding.
In the Hypersoft Suite there is a sophisticated system for changing days. Use the time of the so-called /TTA The theoretical end of day (TTA) applies the calendar day change at a time specified by you (default setting 6:00 a.m.). The programme can automatically perform closures, updates and maintenance at this time. A new sales day then begins with the first POS booking of the day. , if necessary, to reset things in their system, empty orphaned shopping baskets or change the day. See here the section Daily closing, daily change and TTA.
Individual item bookings can be made by different operators. Hypersoft works with operation responsibility, which is always assigned to a specific operator (for example, the first operator to open a table). The tip is automatically assigned to this operator by Hypersoft. You don't have to worry about it.
If you create operations as a 3rd party and the system is set up accordingly, you can be given operation responsibility as a virtual operator and the tip could then be handled or distributed further. See all tips on how to Book a tip.
Two methods to trigger tip bookings
-
You can book an item with the corresponding amount that is defined as a tip item in the Hypersoft system.
-
You can increase the payment amount of the transaction, Hypersoft will book the overpayment as a tip.
Configuration for the treatment of overpayments...
With the option switch Book TRINKGELD on overpayment you can set a behaviour for the API specifically for your channel. This allows you to decide whether, in the case of an overpayment in connection with a transaction closure, the surplus is booked as a tip or as a refund. If the counter is off and a higher payment amount is handed over with the transaction closure, the POS treats the "overpayment" as change. This part is therefore not included in the cash balance and is also not listed as a tip in the operator's statement.
Tax treatment of tips...
Overpayments are booked as tax-free tips in the standard system. For tip items, taxation can be defined by settings.
In Germany, tipping is not generally tax-free. Many 3rd parties cause the tax liability of tips in general or in connection with uncoordinated workflows. Therefore, if in doubt, always book taxable tips.
Commodity groups with 3rd parties
Hypersoft has a three-tier commodity group concept.
Further documentation:
Further documentation:
eSolution 3rd Party API Translations
Back to the parent page: 3rd Party eSolution API