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.
| Field | Subfield | Type | Required | Description |
|---|---|---|---|---|
| remoteId | String | yes | Order identifier unique within the restaurant | |
| cancelled | Boolean | no | Set to true when cancelling a previously submitted order. In this case, only remoteId needs to be filled in; all other fields may be null. | |
| paymentType | String | yes | Payment method. For online payments, paidAmount must also be set. | |
| scheduledTime | DateTime | no | The 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). | |
| takeAway | Boolean | no | Must be true for a takeaway order. | |
| customer | Array | yes | An array containing the customer details. | |
| name | String | yes | The full name of the customer. | |
| phone | String | yes | The customer phone number. Expected format: +36205230949 | |
| String | no | The customer email address. Required when a VAT invoice is requested. | ||
| customerNote | String | no | A note for the entire order. | |
| deliveryAddress | Array | yes | Required for delivery orders. This information does not need to be provided for takeaway orders. | |
| country | String | no | The country as a two-character ISO 3166 code. | |
| state | String | no | County. | |
| city | String | yes | City. | |
| zip | String | no | Postal code. | |
| address | String | yes | Full street name. | |
| number | String | yes | House number. | |
| building | String | no | Building. | |
| staircase | String | no | Staircase. | |
| floor | String | no | Floor. | |
| apartment | String | no | Apartment number. | |
| intercom | String | no | Doorbell. | |
| additional | String | no | Additional notes for the address. | |
| position.lat | Double | no | GPS coordinate. | |
| position.lon | Double | no | GPS coordinate. | |
| billingAddress | Array | no | Billing details | |
| country | String | no | The country as a two-character ISO 3166 code. | |
| state | String | no | County. | |
| city | String | yes | City. | |
| zip | String | no | Postal code. | |
| address | String | yes | Full street name. | |
| number | String | yes | House number. | |
| building | String | no | Building. | |
| staircase | String | no | Staircase. | |
| floor | String | no | Floor. | |
| apartment | String | no | Apartment number. | |
| intercom | String | no | Doorbell. | |
| additional | String | no | Additional notes for the address. | |
| position.lat | Double | no | GPS coordinate. | |
| position.lon | Double | no | GPS coordinate. | |
| vatNumber | String | yes | Tax number. | |
| firstName | String | no | First name. | |
| lastName | String | no | Last name. | |
| companyName | String | no | Company name. | |
| itemsTotal | Double | yes | The total price of all products after discounts. | |
| deliveryFee | Double | no | Delivery fee, if any. | |
| packagingFee | Double | no | Packaging fee, if any. | |
| depositFees | Dictionary | no | Return and deposit fees for the order. The key is the VAT rate and the value is the amount payable. | |
| itemsDiscount | Double | no | The total product discounts for the order. Checks: -must not be negative -the total must equal the discounts applied to the products | |
| orderDiscount | Double | yes | A fixed amount discount for the order. | |
| grandTotal | Double | yes | Grand total. | |
| paidAmount | Double | yes | The 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. | |
| orderAcceptedUrl | String | yes | A URL that Orsys calls when the order is accepted. | |
| orderRejectedUrl | String | yes | A URL that Orsys calls when the order is rejected. | |
| orderPreparedUrl | String | no | A 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. | |
| orderPickedUpUrl | String | no | A 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 | String | no | A 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. | |
| orderItems | Array | yes | Ordered products and items. Detailed descriptions below. |
Ordered products
The structure of the products in an order.
| Field | Type | Required | Description |
|---|---|---|---|
| skuId | String | no | The product identifier in Orsys. Optional, but recommended for NTAK reporting and partner statistics to work. |
| name | String | yes | The full product name. This is displayed in the POS interface. |
| note | String | no | Product note. |
| quantity | Int | no | Ordered quantity. |
| discountUnitPrice | Double | no | The discounted unit price of the product. Omit if there is no discount. Checks: -must not be negative |
| unitPrice | Double | yes | The full price of one product. Excludes toppings and discounts. |
| toppings | Array | no | Toppings ordered for the product. |
| vatPercent | Double | no | VAT percentage (0/5/18/27), if it differs from the menu value or skuId is not provided. |
| ntakCategory | String | no | NTAK category, if it differs from the menu value or skuId is not provided. |
| unitType | String | no | Unit of measure, if it differs from the menu value or skuId is not provided. |
| amountInUnit | Double | no | Amount, if it differs from the menu value or skuId is not provided. |
Product extras and toppings
Toppings ordered with the products.
| Field | Type | Required | Description |
|---|---|---|---|
| skuId | String | no | The product identifier in Orsys. |
| name | String | yes | The full product name. This is displayed in the POS interface. |
| quantity | Int | no | Ordered quantity. |
| discountUnitPrice | Double | no | The discounted price of one unit. Omit if there is no discount. Checks: -must not be negative |
| unitPrice | Double | yes | The full price of one unit, including toppings and extras. |
| vatPercent | Double | no | VAT percentage (0/5/18/27), if it differs from the menu value or skuId is not provided. |
| ntakCategory | String | no | NTAK category, if it differs from the menu value or skuId is not provided. |
| unitType | String | no | Unit of measure, if it differs from the menu value or skuId is not provided. |
| amountInUnit | Double | no | Amount, 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
| Code | Description |
|---|---|
| ADDRESS_INCOMPLETE_MISSTATED | |
| BAD_WEATHER | Cannot fulfil the order due to bad weather |
| BLACKLISTED | The customer is blacklisted, so the order will not be fulfilled |
| CARD_READER_NOT_AVAILABLE | The restaurant currently has no card terminal |
| CLOSED | The restaurant is closed |
| CONTENT_WRONG_MISLEADING | The order contents are misleading or unclear |
| FOOD_QUALITY_SPILLAGE | The customer had a problem with the food |
| FRAUD_PRANK | Fake or fraudulent order |
| ITEM_UNAVAILABLE | The ordered item is currently unavailable |
| LATE_DELIVERY | The customer refused the order because of late delivery |
| MENU_ACCOUNT_SETTINGS | The restaurant has a problem with the submitted products |
| MOV_NOT_REACHED | The order value is too low for fulfilment |
| NO_COURIER | No courier is available for delivery |
| NO_PICKER | Takeaway orders are not available |
| NO_RESPONSE | No response to the order processing |
| OUTSIDE_DELIVERY_AREA | The order is outside the delivery area |
| TECHNICAL_PROBLEM | The order cannot be fulfilled due to a technical problem |
| TEST_ORDER | Test order |
| TOO_BUSY | Cannot fulfil the order because there are too many orders |
| UNABLE_TO_FIND | The customer could not be found and the order could not be handed over |
| UNABLE_TO_PAY | The customer cannot pay for the order |
| UNPROFESSIONAL_BEHAVIOUR | The order cannot be fulfilled due to inappropriate behaviour |
| WILL_NOT_WORK_WITH | The restaurant does not work with this provider |
| WRONG_ORDER_ITEMS_DELIVERED | The customer refused the order because the wrong products were delivered |