Documentation
Data structures

Data structures

A list of data structures, which are used for data exchange between POS and Qerko. We provide JSON schemas (opens in a new tab) for comfortable validation.

Bill

Bill structure is part of the getTableContents, getBill and payment methods.

PropertyTypeRequiredDescription
additionalDataanyNoPOS can use this for any additional data. Qerko will not modify it and you can use it in the payment process. You will receive it in Payment.additionalData.
createdstringNoTimestamp of the bill creation in ISO 8601 (opens in a new tab) extended format. Example: 2019-04-13T00:22:57+01:00
currencystringYesUsed currency in ISO 4217 format. All prices in this structure must use the same currency. Example: CZK
denyDiscountsbooleanNoWhether Qerko can apply another discount. Set it to TRUE when there already is an internally applied discount by POS and other discounts are unwanted. This is related to discounts provided by restaurant owners only. Discounts paid by Qerko or third parties (sponsors like breweries) aren't affected by this property.
FALSE ‒ Qerko can apply a discount. TRUE ‒ Qerko can’t apply a discount.
allowTipbooleanNoCan the customer add a tip? Default: true
allowPartialPaymentbooleanNoCan the customer pay only a subset of the items? Default: true
discountOfferBillDiscountOfferNoDiscount offered to the guest by the restaurant owner. Qerko has many sources of discounts, so Qerko's list will be extended by this offer.
idstringYesUnique identifier of the bill from POS. This identifier is used in payment structure when Qerko returns the whole or part of the bill to be paid.
itemsBillItem[]YesUnpaid items on the bill.
namestringNoName of the bill to be shown to the customer. If not provided, Qerko will try to generate some.
upchargesBillUpcharge[]NoUnpaid upcharges on the bill.

BillDiscountOffer

POS sends this structure as a part of the Bill structure. It carries info about a discount offer. It is used as a discount offer from POS, specifically from the restaurant. The customer will probably accept it, unless he has a better offer from another source (loyalty program, Qerko, etc.).

PropertyTypeRequiredDescription
additionalDataanyNoPOS can use this for any additional data. Qerko will not modify it and you can use it in the payment process. If the customer decides to accept the offer, you will receive it in Payment.discount.additionalData.
namestringYesHuman readable name. It will be visible on the receipt and in a Qerko app.
percentstringYesDiscount value percentage. It is not possible to offer other types of discounts, because of difficulties with paying only a part of the bill. Example: 5 means 5% discount, 7.5 means 7.5% discount

BillItem

POS sends this structure as a part of Bill structure and receives it as a part of Payment structure. It carries info about an item on a bill or item related to a payment.

PropertyTypeRequiredDescription
additionalDataanyNoPOS can use this for any additional data. Qerko will not modify it and you can use it in the payment process. You will receive it in Payment
idstringnoPOS identifier of bill item. This value is just returned by Qerko when the same bill item is used (fully or partially). In other words POS sends it in bill structure and Qerko returns it in payment structure.
minQuantitystringnoMinimum payable quantity. It also defines the quantity precision. Qerko will allow only multiples of minQuantity as split quantity. If minQuantity = 0, then the item cannot be split. If quantity is divisible by minQuantity then Qerko will make it possible to split the item, else the item will be passed through Qerko with unchanged quantity. Example: If minQuantity = 1 and quantity is integer, then the item can be split into lower integer quantities. If minQuantity = 1 and quantity is decimal, then the item cannot be split. Example: 0.001, 1,... Default: 1
namestringYesHuman readable name of bill item. It will be visible on the receipt and in a Qerko app. Example: The Two-Hand Burger
pricestringYesTotal price for bill items including taxes. Price can be zero, or negative. Example: 110.00
quantitystringYesSold amount. It can be decimal and negative. Example: 5 (5✕ beer), 0.7 (child portion)
tagsstring[]NoSomething identifying groups of products or categories of products, etc. categorization. Can be used for loyalty programs, discounts or something else. Used values depend on the relation between POS and Qerko configuration. Used in discount definition, ex: "10% off for coffee if a tag:dessert is ordered as well" Example: ["burger", "beef", "meat"]
subItemsBillSubItem[]NoThe list of subitems that are added to this item. They can’t be paid separately.

BillSubItem

This structure represents a part of an item that is added to the parent item. Price to pay is the sum of the BillItem price and all its subItems.

PropertyTypeRequiredDescription
idstringYesPOS identifier of bill sub item. This value is just returned by Qerko when the same bill subitem is used. In other words POS sends it in bill subitem structure and Qerko returns it in payment structure.
namestringYesHuman readable name of bill subitem.
pricestringYesPrice which will be added to BillItem in application.

BillUpcharge

PropertyTypeRequiredDescription
idstringYesUnique identifier of the upcharge from POS.
namestringYesHuman readable name of upcharge. It will be visible in the Qerko app. Example: Service fee for drinks
typestringYesOptions: POS_CALCULATED

ReceiptUpcharge

PropertyTypeRequiredDescription
idstringYesUnique identifier of the upcharge from POS.
namestringYesHuman readable name of upcharge. It will be visible on the receipt. Example: Service fee for drinks
pricestringYesTotal price for bill upcharge. Price can be zero. Example: 110.00

CalculatedBillUpcharge

PropertyTypeRequiredDescription
idstringYesUnique identifier of the upcharge from POS.
pricestringYesTotal price for bill upcharge. Price can be zero. Example: 110.00
additionalDataanyNoPOS can use this for any additional data. Qerko will not modify it and you can use it in the payment process. You will receive it in Payment

Discount

This structure is used as part of the Payment structure. It carries info about a discount that was applied to the payment. Splitting the discount among bill items is completely up to POS. POS must include the discount into Receipt.taxInfo.

PropertyTypeRequiredDescription
additionalDataanyNoIf source=pos this property will contain whatever data POS has sent in the BillDiscountOffer structure.
namestringYesHuman readable text for the receipt
sourcestringYesThe source of the discount: POS ‒ Discount from POS, sent in Bill ‒ Discount from Qerko, Qerko will pay the costs PROMO ‒ Discount was set up in web administration (opens in a new tab) LOYALTY ‒ Discount was set up in web administration (opens in a new tab) as a part of a loyalty program.
valuestringYesThe absolute value of the discount. Currency is from the payment. Example: 100 when the discount was one hundred

Error

This structure is used in various situations to report an error.

PropertyTypeRequiredDescription
messagestringYesHuman readable text describing the error. It is never presented to the customer.
codestring nullNoWhen the error occurs in Qerko server it contains one of Error codes or null.
When the error occurs in POS, it can have a special effect, which is defined by the respective method.

FiscalInfo

POS sends this structure as a part of the Receipt structure. It carries info about a fiscal report related to the receipt. This object is treated as template data. Feel free to add any relevant info that the restaurant might want to print on the receipt. It will be possible to have a per-restaurant template in the future. If you implement for a country which is not documented here, send us your requirements, we will make them the standard for the country in this document.

Czechia

PropertyTypeRequiredDescription
footerLinesstring[]NoAdditional lines to print on the receipt below eet* parameters.
footerTextstringNoAdditional text to print on the receipt below footerLines.
headerLinesstring[]NoAdditional lines to print on the receipt above headerText.
headerTextstringNoAdditional lines to print on the receipt above eet* parameters.

Slovakia

PropertyTypeRequiredDescription
footerLinesstring[]NoAdditional lines to print on the receipt below the uid parameter.
footerTextstringNoAdditional text to print on the receipt below footerLines.
headerLinesstring[]NoAdditional lines to print on the receipt above headerText.
headerTextstringNoAdditional lines to print on the receipt above the uid parameter.
uidstringNoSlovakian unique identifier of the receipt
(unikátny identifikátor pokladničného dokladu)
bkpstringNoSlovakian BKP which will appear on the receipt when the uid is not sent.

Austria

PropertyTypeRequiredDescription
footerLinesstring[]NoAdditional lines to print on the receipt below the uid parameter.
footerTextstringNoAdditional text to print on the receipt below footerLines.
headerLinesstring[]NoAdditional lines to print on the receipt above headerText.
headerTextstringNoAdditional lines to print on the receipt above the uid parameter.
qrDatastringYesAn utf-8 string data, which is used to create a QR code for the lower part of the receipt.

Germany

PropertyTypeRequiredDescription
footerLinesstring[]NoAdditional lines to print on the receipt below the uid parameter.
footerTextstringNoAdditional text to print on the receipt below footerLines.
headerLinesstring[]NoAdditional lines to print on the receipt above headerText.
headerTextstringNoAdditional lines to print on the receipt above the uid parameter.
qrDatastringYesAn utf-8 string data, which is used to create a QR code for the lower part of the receipt.

Hungary (work-in-progress)

Restaurant save username and password or token for the Szamlazz service in the Qerko Admin. POS returns required data for Szamlazz service and Qerko sends it to the Szamlazz service. Samlazz returns the receipt in PDF format and Qerko give it to the customer.

PropertyTypeRequiredDescription
footerLinesstring[]NoAdditional lines to print on the receipt below the uid parameter.
footerTextstringNoAdditional text to print on the receipt below footerLines.
headerLinesstring[]NoAdditional lines to print on the receipt above headerText.
headerTextstringNoAdditional lines to print on the receipt above the uid parameter.
qrDatastringYesAn utf-8 string data, which is used to create a QR code for the lower part of the receipt.
szamlazzSzamlazzYesInformations for fiscal service.

Szamlazz

PropertyTypeRequiredDescription
itemsSzamlazzItem[]YesItems (max 500)
sellerSzamlazzSellerNoDetails about seller.

SzamlazzItem

PropertyTypeRequiredDescription
namestringYesName of item on invoice. (1 - 255 length)
quantitystringYesFor more info find "mennyiseg" in szamlazz doc.
unitstringYesFor more info find "mennyisegiEgyseg" in szamlazz doc. (1 - 16 length)
vatstringYesFor more info find "afakulcs" in szamlazz doc.
vatValuestringYesFor more info find "afaErtek" in szamlazz doc.
grossValuestringYesFor more info find "bruttoErtek" in szamlazz doc.
netValuestringYesFor more info find "nettoErtek" in szamlazz doc.
netUnitPricestringYesFor more info find "nettoEgysegar" in szamlazz doc.
commentstringNoFor more info find "megjegyzes" in szamlazz doc.

SzamlazzSeller (optional)

PropertyTypeRequiredDescription
namestringNoName of item on invoice. For more info find "bank" in szamlazz doc. (1 - 255 length)
accountNumberstringNoFor more info find "bankszamlaszam" in szamlazz doc. (1 - 128 length)
replyToAddressstringNoFor more info find "emailReplyto" in szamlazz doc. (valid email)
subjectstringNoFor more info find "emailTargy" in szamlazz doc. (1 - 255 length)
messagestringNoFor more info find "emailSzoveg" in szamlazz doc. (1 - 255 length)
issuerNamestringNoFor more info find "alairoNeve" in szamlazz doc. (1 - 255 length)

MethodCallRequest

POS receives this structure, although it is called request, in a response from the long-polling endpoint. It requests the POS to call a method.

PropertyTypeRequiredDescription
uuidstringNoIdentifier of the method call. If not provided, then the sender does not expect the receiver to send a response.
methodstringYesThe name of the method to call. See Methods.
argsany[]YesArray of method arguments.

MethodCallResponse

POS sends this structure, in a request to the long-polling endpoint, although it is called response. It carries the result of a method call. It is sent as a reaction to receiving a MethodCallRequest.

PropertyTypeRequiredDescription
uuidstringYesIdentifier of the method call which was in the MethodCallRequest.
errorErrorNoError which has occured, ifany.
resultanyNoResult of the corresponding method call.
calledMethodstring nullNoMethod which produced this response. Qerko sends this every time. POS can ignore it. Provided for easier statelessness.

Payment

POS receives this structure for paymentStart(...) method or as a response to getPayment(...) or from the payment endpoint. Total price is: sum(items[i].price) + tipBrutto - discount.value

PropertyTypeRequiredDescription
additionalDataanyNoAdditional data from the Bill structure.
currencystringYesCurrency code in ISO 4217 (opens in a new tab)format.
discountDiscountNoDiscount applied to the payment.
idstringYesIdentifier of the payment. Qerko generates it for every
idBillstringYesIdentifier of the related bill.
idCustomerstringYesUnique identifier of the customer who pays. For the loyalty program on the POS side. POS can identify the user when there was a previous call to method pairCustomer. Else the POS can track users activity, but the user remains anonymous.
itemsBillItem[]YesList of items, which are paid by the payment.
statestringYesSTARTED ‒ The payment process has just started PROCESSING ‒ The payment is processed. PAID ‒ The payment is paid. It is the final state. CANCELLED ‒ The payment is cancelled. It is the final state. ERROR ‒ The payment ended with an error. Manual action must be taken to solve this error and manually switch the transaction to CANCELED.
partsPaymentPart[]YesThis is an array which holds info for splitting the payment among payment providers.
tipBruttostringYesTip for the restaurant personnel.
tipNettostringYesQerko might take a tip commission, so there will be a tip after the commission subtraction. This will be based on the agreement with the restaurant. POS should show this value to the restaurant personnel.
upchargesCalculatedBillUpcharge[]NoList of upcharges, which are paid by the payment.

PaymentPart

POS receives this structure as a part of the Payment structure. It holds information about a part of payment which has been paid using a payment provider.

PropertyTypeRequiredDescription
providerPaymentProviderYesThis is the payment provider that was used to fulfill this payment part.
totalstringYesThis is how much was paid using this payment provider.

PaymentProvider

POS receives this structure as a part of PaymentPart structure. It holds information about used payment provider. Each provider can be enabled/disabled per restaurant on the Qerko web page. There might be different rules for different types according to local laws.

PropertyTypeRequiredDescription
idstringYesA unique identifier of this payment provider.
namestringYesA human readable provider name Example: Qerko, A meal ticket, Ltd., Some smart card, Ltd., etc.
typestringYesThis is for description of the type of the transaction, so POS can apply correct rules according to local laws. CARD This means online payment using card BANK_TRANSFER - This means payment by bank transfer INVOICE - This means exchange of funds based on an invoice VOUCHER - This includes vouchers, coupons and other pre-paid types. MEAL_TICKET - This means payment by meal tickets

Receipt

POS sends this structure as a response to the paymentProcessed(...) method. It carries info for generating the receipt.

PropertyTypeRequiredDescription
receiptInfoReceiptInfoNoObject with properties containing information about the bill or the receipt.
itemsReceiptItemYesItems printed on the receipt. If relevant, include the Payment, or any discount. The total amount on the receipt will be the sum of items prices.
taxInfoTaxInfoYesCalculated tax. TaxInfo is verified. Sum of all TaxInfo.base plus sum of all TaxInfo.vat must be equal to related Payment.total. If not equal, the related payment is canceled.
fiscalInfoFiscalInfoNoFiscal reports such as czech EET and others
receiptDeliveryTypestringNoThis parameter is used to determine whether the receipt is generated by Qerko, sent by email or will be received later via method getPostponedReceipt. Allowed values: QERKO_GENERATED, EMAIL, POSTPONED, EMAIL_HTML_BODY_AS_RECEIPT

Email addresses:

ReceiptInfo

POS sends this structure as a part of the Receipt structure. It carries general info about the receipt. This object is treated as template data. Feel free to add any relevant info that the restaurant might want to print on the receipt. It will be possible to have a per-restaurant template in the future.

PropertyTypeRequiredDescription
billNamestringNoThe name of the bill
businessPremisestringNoAn identifier of the business premise
cashBoxstringNoAn identifier of the cashbox
footerLinesstring[]NoAdditional lines to print on the receipt below items.
headerLinesstring[]NoAdditional lines to print on the receipt above items.
serialstringNoSerial number or another identifier
timestampstringNoTimestamp in ISO 8601 (opens in a new tab) extended format
waiterWaiterNoThe waiter who was serving the customer

ReceiptItem

POS sends this structure as a part of the Receipt structure. It carries info about an item to be printed on the receipt. This object is treated as template data. Feel free to add any relevant info that the restaurant might want to print on the receipt. It will be possible to have a per-restaurant template in the future.

PropertyTypeRequiredDescription
namestringYesThe name of the item
quantitystringNoThe quantity of the item
pricestringYesThe total price for the item(s)
taxNamestringNoThe tax in which this item is included. Related to TaxInfo.name. As suggested here: Receipt (opens in a new tab)

Table

POS sends this structure in the list of tables as a response to the getTableList(...) method. It carries info about a table.

PropertyTypeRequiredDescription
idstringYesIdentifier of the table.
namestringNoHuman readable name of the table. if not provided, id will be used instead. Example: The table by the door, or Garden 1
storestringNoIdentification of establishment for better filtering tables in restaurant-admin.
areastringNoIdentification of room for better filtering tables in restaurant-admin

TaxInfo

This structure is used as part of the Receipt structure. It carries info about tax.

PropertyTypeRequiredDescription
namestringNoTax name. Related to ReceiptItem.taxName. As suggested here: Receipt (opens in a new tab) Example: A
ratestringYesTax rate percentage. Example: 15 means 15%, 12.5 means 12.5%, etc.
basestringYesTax base. Example: 100.00
taxstringYesTax value. Example: 15.00

Waiter

This structure is used as part of the Receipt structure. It carries info about a waiter, who has served the customer.

PropertyTypeRequiredDescription
idstringYesIdentifier of the waiter. Unique in the restaurant.
namestringYesName of the waiter. Can’t be an empty string. Example: John Doe