Delivery Plugin integration

Orsys order integration API documentation

Test access

To test the connection, you need a test API key, which you can request from us by email. Please write to info@orsys.hu and include the following details in your request:

  • The name of the software or service being connected,
  • Details of the development company or individual,
  • Phone and email contact details.

Authentication

Every API request sent to Orsys must include an X-API-Key header containing the API key for the integration.

X-API-Key: "COPY API KEY HERE"

Submitting an order

Use this endpoint to submit a finalized order to Orsys.

Endpoint: https://api.orsys.hu/webhook/plugin/delivery

Send the data as JSON in the body of a POST request. The code example shows a sample JSON request.

{
	"remoteId": "22636",
    "cancelled": false,
	"paymentType": "CASH",
	"scheduledTime": "2023-09-13T18:17:30+02:00",
	"takeAway": false,
	"customer": {
		"name": "Nagy Árpád",
		"phone": "+36201234567",
		"email": "nagy.arpad@mintaemail.hu"
	},
	"customerNote": "Kérem csörögjön a futár ha itt van.",
	"deliveryAddress": {
		"zip": "1101",
		"city": "Budapest",
		"address": "Mongol utca",
		"number": "75",
		"building": "B",
		"staircase": "",
		"floor": "4",
		"apartment": "23",
		"intercom": "Nagy Árpád, 23",
		"additional": "Piros ajtó a lifttől balra",
		"position": {
			"lat": 47.4713559,
			"lon": 19.1310685
		}
	},
	"itemsTotal": 6590,
	"deliveryFee": 500,
	"packagingFee": 300,
	"depositFees": {
		0.0: 50,
		27.0: 150
	},
	"itemsDiscount": 0,
	"orderDiscount": 1000,
	"grandTotal": 6390,
	"paidAmount": 0,
	"orderAcceptedUrl": "https://ipn.sajatdomain.hu/success/22636",
	"orderRejectedUrl": "https://ipn.sajatdomain.hu/storno/22636",
	"orderItems": [
		{
			"skuId": "AAA-011",
			"name": "Jalapenos pizza (32 cm)",
			"quantity": 2,
			"unitPrice": 2100,
			"note": "",
			"toppings": [
				{
					"skuId": "AAR-002",
					"name": "Bacon",
					"quantity": 1,
					"unitPrice": 300
				},
				{
					"skuId": "AAR-006",
					"name": "Feta sajt",
					"quantity": 1,
					"unitPrice": 250
				}
			]
		},
		{
			"skuId": "AAZ-001",
			"name": "Sajtburger",
			"quantity": 1,
			"unitPrice": 1290,
			"note": "Kérem a húst jól süssék át."
		}
	]
}

Detailed field descriptions

The structure of a complete order.

FieldSubfieldTypeRequiredDescription
remoteIdStringyesOrder identifier unique within the restaurant
cancelledBooleannoSet to true when cancelling a previously submitted order. In this case, only remoteId needs to be filled in; all other fields may be null.
paymentTypeStringyesPayment method. For online payments, paidAmount must also be set.
scheduledTimeDateTimenoThe requested time for a scheduled order. Use ISO_OFFSET_DATE_TIME format (ISO 8601 with a time zone, e.g. 2023-09-13T18:17:30+02:00).
takeAwayBooleannoMust be true for a takeaway order.
customerArrayyesAn array containing the customer details.
nameStringyesThe full name of the customer.
phoneStringyesThe customer phone number. Expected format: +36205230949
emailStringnoThe customer email address. Required when a VAT invoice is requested.
customerNoteStringnoA note for the entire order.
deliveryAddressArrayyesRequired for delivery orders. This information does not need to be provided for takeaway orders.
countryStringnoThe country as a two-character ISO 3166 code.
stateStringnoCounty.
cityStringyesCity.
zipStringnoPostal code.
addressStringyesFull street name.
numberStringyesHouse number.
buildingStringnoBuilding.
staircaseStringnoStaircase.
floorStringnoFloor.
apartmentStringnoApartment number.
intercomStringnoDoorbell.
additionalStringnoAdditional notes for the address.
position.latDoublenoGPS coordinate.
position.lonDoublenoGPS coordinate.
billingAddressArraynoBilling details
countryStringnoThe country as a two-character ISO 3166 code.
stateStringnoCounty.
cityStringyesCity.
zipStringnoPostal code.
addressStringyesFull street name.
numberStringyesHouse number.
buildingStringnoBuilding.
staircaseStringnoStaircase.
floorStringnoFloor.
apartmentStringnoApartment number.
intercomStringnoDoorbell.
additionalStringnoAdditional notes for the address.
position.latDoublenoGPS coordinate.
position.lonDoublenoGPS coordinate.
vatNumberStringyesTax number.
firstNameStringnoFirst name.
lastNameStringnoLast name.
companyNameStringnoCompany name.
itemsTotalDoubleyesThe total price of all products after discounts.
deliveryFeeDoublenoDelivery fee, if any.
packagingFeeDoublenoPackaging fee, if any.
depositFeesDictionarynoReturn and deposit fees for the order. The key is the VAT rate and the value is the amount payable.
itemsDiscountDoublenoThe total product discounts for the order. Checks:
-must not be negative
-the total must equal the discounts applied to the products
orderDiscountDoubleyesA fixed amount discount for the order.
grandTotalDoubleyesGrand total.
paidAmountDoubleyesThe amount already paid. Usually 0 (for cash or terminal payments), or equal to grandTotal (when paid in full online). The courier will collect [grandTotal - paidAmount] on delivery.
orderAcceptedUrlStringyesA URL that Orsys calls when the order is accepted.
orderRejectedUrlStringyesA URL that Orsys calls when the order is rejected.
orderPreparedUrlStringnoA URL that Orsys calls when the ordered items are ready (when the food can be collected for takeaway orders). The reported time may be inaccurate for some partner restaurants, as it depends on how they use the POS system.
orderPickedUpUrlStringnoA URL that Orsys calls when the courier departs. The reported time may be inaccurate for some partner restaurants, as it depends on how they use the POS system.

orderCompletedUrl

StringnoA URL that Orsys calls when the order is completed (including takeaway orders). The reported time may be inaccurate for some partner restaurants, as it depends on how they use the POS system.
orderItemsArrayyesOrdered products and items. Detailed descriptions below.

Ordered products

The structure of the products in an order.

FieldTypeRequiredDescription
skuIdStringnoThe product identifier in Orsys. Optional, but recommended for NTAK reporting and partner statistics to work.
nameStringyesThe full product name. This is displayed in the POS interface.
noteStringnoProduct note.
quantityIntnoOrdered quantity.
discountUnitPriceDoublenoThe discounted unit price of the product. Omit if there is no discount. Checks:
-must not be negative
unitPriceDoubleyesThe full price of one product. Excludes toppings and discounts.
toppingsArraynoToppings ordered for the product.
vatPercentDoublenoVAT percentage (0/5/18/27), if it differs from the menu value or skuId is not provided.
ntakCategoryStringnoNTAK category, if it differs from the menu value or skuId is not provided.
unitTypeStringnoUnit of measure, if it differs from the menu value or skuId is not provided.
amountInUnitDoublenoAmount, if it differs from the menu value or skuId is not provided.

Product extras and toppings

Toppings ordered with the products.

FieldTypeRequiredDescription
skuIdStringnoThe product identifier in Orsys.
nameStringyesThe full product name. This is displayed in the POS interface.
quantityIntnoOrdered quantity.
discountUnitPriceDoublenoThe discounted price of one unit. Omit if there is no discount. Checks:
-must not be negative
unitPriceDoubleyesThe full price of one unit, including toppings and extras.
vatPercentDoublenoVAT percentage (0/5/18/27), if it differs from the menu value or skuId is not provided.
ntakCategoryStringnoNTAK category, if it differs from the menu value or skuId is not provided.
unitTypeStringnoUnit of measure, if it differs from the menu value or skuId is not provided.
amountInUnitDoublenoAmount, if it differs from the menu value or skuId is not provided.

Available payment methods

Only the following payment methods can be submitted:

  • CASH - Cash
  • CASH_EUR - Cash in euros
  • CASH_LARGE_BILLS - Cash in large denominations
  • SZEP_CARD_ONLINE - SZÉP card payment completed online
  • SZEP_CARD_TERMINAL - SZÉP card payment to the courier
  • CREDIT_CARD_ONLINE - Bank card payment completed online
  • CREDIT_CARD_TERMINAL - Bank card payment to the courier
  • VOUCHER - Voucher

Server response

The server returns the following response after an order is submitted.

Successful processing

On successful processing, the system returns status 200 with an empty body.

Errors

On error, it returns 400 Bad Request with details of the error in the body.

{
	"exceptionMessage": "exc_invalid_field",
	"additionalInfo": "Missing remoteId!"
}

Callbacks

After processing an order, the system notifies the sender at the provided URLs based on the actions taken by the restaurant.

IN THE TEST SYSTEM: the test system sends an automatic callback 60 seconds after receiving the order. The result is random, with a 50% chance of success and a 50% chance of failure. This is provided so that you can easily test callbacks too.

All webhook calls have the same body structure.

{
	"remoteId": "22360",
	"status": "ACCEPTED",
	"acceptanceTime": "2023-09-13T18:17:30+02:00",
	"rejectReason": Null
}

Rejection reasons

CodeDescription
ADDRESS_INCOMPLETE_MISSTATED
BAD_WEATHERCannot fulfil the order due to bad weather
BLACKLISTEDThe customer is blacklisted, so the order will not be fulfilled
CARD_READER_NOT_AVAILABLEThe restaurant currently has no card terminal
CLOSEDThe restaurant is closed
CONTENT_WRONG_MISLEADINGThe order contents are misleading or unclear
FOOD_QUALITY_SPILLAGEThe customer had a problem with the food
FRAUD_PRANKFake or fraudulent order
ITEM_UNAVAILABLEThe ordered item is currently unavailable
LATE_DELIVERYThe customer refused the order because of late delivery
MENU_ACCOUNT_SETTINGSThe restaurant has a problem with the submitted products
MOV_NOT_REACHEDThe order value is too low for fulfilment
NO_COURIERNo courier is available for delivery
NO_PICKERTakeaway orders are not available
NO_RESPONSENo response to the order processing
OUTSIDE_DELIVERY_AREAThe order is outside the delivery area
TECHNICAL_PROBLEMThe order cannot be fulfilled due to a technical problem
TEST_ORDERTest order
TOO_BUSYCannot fulfil the order because there are too many orders
UNABLE_TO_FINDThe customer could not be found and the order could not be handed over
UNABLE_TO_PAYThe customer cannot pay for the order
UNPROFESSIONAL_BEHAVIOURThe order cannot be fulfilled due to inappropriate behaviour
WILL_NOT_WORK_WITHThe restaurant does not work with this provider
WRONG_ORDER_ITEMS_DELIVEREDThe customer refused the order because the wrong products were delivered