Customer API development

Initialisation and data exchange with the partner application

Example binding

<binding name="API300Soap" closeTimeout="00:10:00" openTimeout="00:10:00"

receiveTimeout="00:10:00" sendTimeout="00:10:00" allowCookies="false"

bypassProxyOnLocal="false" hostNameComparisonMode="StrongWildcard"

maxBufferPoolSize="2147483647" maxBufferSize="2147483647" maxReceivedMessageSize="2147483647"

textEncoding="utf-8" transferMode="Buffered" useDefaultWebProxy="true"

messageEncoding="Text">

</binding>

Example code

string CusToken = "15343D17-****-*****-****-************";

string AuthToken = "5AF7B0AE-****-*****-****-************";

API300.API300SoapClient Service = new API300.API300SoapClient("API300Soap", "https://api.myhypersoft.de/Service/API300.asmx");

API300.APIGeneralResponse Result = Service.ServerDateTime(CusToken, AuthToken);

System.Console.WriteLine("Response: " + Result.Status.ServerDateTime);

Turnover data "Get Revenue

Via our revenue interface, you can call up items and turnover data via our portal area.

The prerequisite for retrieving turnover data is an Enterprise Reports licence per location.

Valid CUS and AUTH tokens are required to retrieve turnover information, which you will receive from our development department during the connection phase.

In live operation, your company is listed in our interfaces in the portal so that joint customers can independently create the required tokens by activating the interface.

Currently, the information is uploaded from the POS to our portal every 15 minutes. This value cannot be adjusted.

Item and invoice information is also grouped to 15 minutes.

API documentation: https://b2b.myhypersoft.de/APIDoc.aspx

End point: https://b2b.myhypersoft.de/Service/API300.asmx

The following data retrieval functions are available:

function	statement
GetStations	This function provides you with information on the available stations. This transfers the current data without history.
GetProfitCenter	This function provides you with information on the available ProfitCenters. This transfers the current data without history.
GetRevenue	This function provides you with information on the bookings. The parameter TtaDate determines corresponding bookings for the day. The FullMonth provides the full month. (Different variants are available). The channel information can also be queried via "GetRevenue": CatSubGroup, ChannelName, SubChannelName, DeliveryTypeName.
GetExtraRevenue	This function provides you with information on the booked extras. The parameter TtaDate determines corresponding extras bookings for the day. The FullMonth provides the full month. (Different variants are available)
GetTransactions	This function provides you with the information on the operations. The parameter TtaDate determines corresponding operations for the day. The FullMonth provides the full month. The order of the records is important. By the TTA (theoretical end of day) date which is e.g. at 6 o'clock, the dates of the time are in this order 900, 1000,... 2300, 0, 100, 200 (at 6 o'clock the new day does not start at 0 o'clock). This means that ascending sorting is not possible for the time. The order in which the data is output is crucial. (Different variants are available)
GetPayments	This function provides you with information on the payments made.
GetStockTaking	Functions for retrieving inventory/inventory data.

Supplementary eSolutions information...

Since 09.2022, the API also contains extended turnover data to query order types, subgroups and channels. The information is listed within the API documentation.

3rd Party Shopping Basket "Set Webshop2 Basket

Via our "3rd party shopping cart" interface, you can attach predefined shopping carts to a reservation and transfer them to our webshop 2.0. The transferred items must have been retrieved beforehand via the function "GetWebshop2Articles".

Example application...

In an external system (e.g. a homepage or an external reservation system), articles (in this case tickets for a boat trip) were booked, which are then transmitted to our shop for further processing (order process, customer data, payment, dispatch of tickets, processing at the POS, transmission of invoices).

Example Automatically deliverable ticket...

The prerequisite for the transfer of shopping baskets is a Licensed Webshop 2.0, no further licences are required. Valid CUS and AUTH tokens are required for the transfer of shopping baskets, which you will receive from our development department during the connection phase. In live operation, your company will be listed in our interfaces in the portal (if desired), so that joint customers can independently create the required tokens by activating the interface.

Entry URL...

The call of a "3rd-Prty shopping cart" is done via an entry URL, which calls up the predefined shopping cart. This also means that the user can no longer change the shopping basket; this can only be triggered by the third-party application. (The user must click on "back" for this)

Example of an entry URL:

https://demo.myhypersoftapp.de/shop/?lng=de&token=%3dBD1sYpDS3ao%3d&hash=26936fbe5d1bef09e70d1d40d6314368816b14bbc6f52105bc70f3c37cea9d12

Normal URL + language + APIToken + hash value

Note: The hash value calculation is a security feature and is not listed in our documentation.

Note: The "jump-in URL" can be used in parallel to a "normal" shop URL. The standard functions and order types of the shop are called up via the normal URL, while the "3rd party shopping cart" functions are called up via the entry URL. Users cannot switch between these two variants within an order process.

Note: If a webshop is called up by means of a predefined shopping basket via "Entry URL", only the following functions are available:

Register
Log in
User area
Order process
payment
Back to the external application

Customer data of the shopping cart...

For "3rd party shopping cart" orders, the customer data settings of the order type "web vouchers" are used.

Note: Contrary to the order type "web vouchers", "3rd party shopping baskets" can also be paid with the payment type "web vouchers", provided this has been activated and set up.

API and functions

API documentation: https://api.myhypersoft.de/APIDoc.aspx

The following data retrieval functions are available:

function	statement
GetWebshop2Articles	Retrieving the items for a customer number Structure of the retrieved item data: https://api.myhypersoft.de/APIDoc.aspx#APIWebshopArticle
GetWebshop2Baskets	Retrieving baskets of multiple reservations
SetWebshop2Baskets	Set shopping baskets of reservations
SetWebshop2BasketPaid	This function can be used to set a basket to 'paid' with a Paymenttype 45. In addition, all fields of the associated reservation are filled with sample data as if the basket was paid for via the webshop.

Onboarding

If a webshop 2.0 already exists, only the tokens and hash value calculation are needed from Hypersoft development. The shop remains in the standard despite the "Entry URL".

All items transferred to the webshop must correspond to the respective webshop assortment. Before this, a successful item synchronisation with the shop must take place at least once.

Webhook required...

For the use of the 3rd party shopping basket, it is mandatory to set up the webhook function: https://api.myhypersoft.de/APIDoc.aspx#SetReservationsWebhook2

A webhook function can fail, which is why the function "GetReservation2" should be called for changes approx. every 2 hours.

API Tickets "Online Tickets

All ticket items sold via the Webshop 2.0 automatically become eSolution tickets (online tickets). For this purpose, the ticket items must receive the property "Ticket" in the item master. Here, the portal is the leading system that assigns the ticket numbers. In this case, the portal generates a 14-digit ticket number at the time of sale, which is composed as follows:

49 (Country Code) 95 (Online Ticket) 1234567890 (10 randomly generated digits).

Example: 49 95 1234567890 (As QR code)

This allows 1.7 million ticket numbers to be created per brand owner (or head office).

The prerequisite is an established master token per location.

Setup...

A ticket centre must be defined to set up the ticket system. This is typically the customer number of the head office.

This can currently only be defined by Hypersoft's development department, but does NOT require project work).

Workflow...

Ticket items with the property "Ticket" are sold via Webshop 2.0.
The portal generates a 14-digit ticket number.
The order including the ticket number is transferred to the POS.
After ordering and processing at the POS, the user receives the ordered tickets via download and email.
Optionally, the invoice can be sent to the user by e-mail using NoCOO.
When redeeming, the POS will query the respective ticket number for validity in the portal.
The portal gives the feedback "Valid" or "Not valid".
If the ticket was valid, the POS sends the information "has been redeemed" to the portal so that the ticket is validated.

Sold tickets can be viewed in the order overview in the portal and optionally downloaded:

Restrictions and limitations...

It is currently not possible to create multiple tickets, which can be redeemed 3 times, for example.

Currently, no specific ticket quotas can be managed; the standard item availability system of the webshop applies (exception: an external system can ensure the availabilities via the "3rd party shopping baskets" function).

Customer data "Get Customers

Via our "GetCustomers" interface, you can retrieve and edit customer data via our portal area.

The prerequisite for retrieving customer data is a "customer base 2.0" licence per location.

Valid CUS and AUTH tokens are required for querying customer data, which you will receive from our development department during the connection phase.

In live operation, your company is listed in our interfaces in the portal so that joint customers can independently create the required tokens by activating the interface.

Customer data can also be matched using the "webhook" method to enable synchronisation between two systems.

API documentation: https://api.myhypersoft.de/APIDoc.aspx

The following data retrieval functions are available:

function	statement
GetCustomers2	You can obtain customer records via this function. The query is limited by the ChangesSince parameter to records that have been modified as of the DateTime value passed. Enter the MinValue here to get the complete customer base. With the CustomerTokens parameter, you can query specific data records by specifying CusTokens.
SetCustomers2	Changes the transferred clients. The identification token indicates which record is being changed. If no identification token is given, a new record is created.
GetCustomersWebhook2	Retrieve the currently stored webhook for the customer master.
SetCustomersWebhook2	Save/update the webhook for the customer master. The webhook is triggered automatically when a record is changed. The changed data can then be retrieved with ChangesSince, from the last retrieval. (Attention: If changes are made through this interface, the webhook will also be triggered.) The webhook is a POST and expects a status code 200 'OK' from the webhookserver as confirmation for the successful processing. The answer must be given within 5 seconds. It is recommended to save the information, send the response and then start processing. The body content is a JSON object '{'Type': 'Customer2', 'ServerTime': string (Current server time in ISO 8601 format) (Optional)[, 'ExtraData': string (Deposited ExtraData)]}'. The head of the webhook contains Host: {Host}, Content-Type: application/json; charset=utf-8, Content-Length: {Body Content Length}, Connection: Close, Accept: /, Accept-Encoding: gzip, Expect: 100-continue and optionally x-hypersoft-signature: {Signature Hex-String}.

Reservation "Get Reservations"

Through our "Get Reservations" interface, you can exchange reservation information via our portal area.

The prerequisite for exchanging reservation data is a "Reservation 2.0" licence per location.

Valid CUS and AUTH tokens are required for the exchange of reservation information, which you will receive from our development department during the connection phase.

In live operation, your company is listed in our interfaces in the portal so that joint customers can independently create the required tokens by activating the interface.

Note: The reservation information is retrieved from the portal by the POS and returned every 30 seconds.

API documentation: https://api.myhypersoft.de/APIDoc.aspx

The following data retrieval functions are available:

function	statement
GetReservations2	Returns reservations. The query is limited by the ChangesSince parameter to records that have been modified as of the DateTime value passed. Enter the MinValue here to receive all reservations. You can use the ReservationTokens parameter to query specific records by specifying ReservationTokens.
SetReservations2	Changes the transferred reservations. The identification token indicates which record is being changed. If no identification token is given, a new record is created.
GetReservation2objects	Returns reservation objects. The query is limited by the ChangesSince parameter to records that have been modified as of the DateTime value passed. If you enter the MinValue here, you will receive all reservation objects. You can use the ReservationobjectTokens parameter to query specific records by specifying ReservationobjectTokens.
GetReservationsWebhook2	Retrieve from the currently stored webhook for the reservation.
SetReservationsWebhook2	Save/update the webhook for the reservation. The webhook is triggered automatically when a record is changed. The changed data can then be retrieved with ChangesSince, from the last retrieval. (Attention: If changes are made through this interface, the webhook will also be triggered.) The webhook is a POST and expects a status code 200 'OK' from the webhookserver as confirmation for the successful processing. The answer must be given within 5 seconds. It is recommended to save the information, send the response and then start processing. The body content is a JSON object '{'Type': 'Reservation2', 'ServerTime': string (Current server time in ISO 8601 format) (Optional)[, 'ExtraData': string (Deposited ExtraData)]}'. The head of the webhook contains Host: {Host}, Content-Type: application/json; charset=utf-8, Content-Length: {Body Content Length}, Connection: Close, Accept: /, Accept-Encoding: gzip, Expect: 100-continue and optionally x-hypersoft-signature: {Signature Hex-String}.

NoCOO Digital Invoices API

Via our "NoCOO" interface, you can retrieve transaction, price and item information.

The NoCOO interface can currently only be used in conjunction with the reservation interface.

The prerequisite for retrieving item information is a NoCOO licence per location.

Valid CUS and AUTH tokens are required to query item information, which you will receive from our development department during the connection phase.

In live operation, your company is listed in our interfaces in the portal so that joint customers can independently create the required tokens by activating the interface.

NoCOO item information is only available after the transaction has been completed at the POS.

API documentation: https://nocoo.myhypersoft.de/APIDoc.aspx

End point: https://nocoo.de/Service/API300.asmx

The following data retrieval functions are available:

function	statement
NoCOO booking data	Transaction and invoice information
GetNoCOOByReservation	Reads the NoCOO data for a reservation

The following details per operation are available in the details:

variable	statement
NoCOOCode	The NoCOOCode
HypersoftCustomernumber	Hypersoft customer number
StationNo	Station number
StationName	Station name
InvoiceNo	invoice number
InvoiceDateTime	Invoice date
Canceled	Cancelled (status)
Gross Double	Total gross
OnlineOrderNo	Online order number
TableNo	Table number (or general transaction number)
CustomerNo	customer number
CustomerToken	Customer ID
CardNo	card number
RoomNo	room number
ReservationToken	Reservation ID
PaymentType	Payment Type
Channel	Channel (the Order Channel)
ChannelType	ChannelType (what kind like 3rd party, webshop or similar)
LastChangeAt	Last upload of NoCOO data
Items	Individual positions
PDF	Invoice PDF

Back to the parent page: 3rd Party Customers, Reservation, Tickets API