Online orders API

Transporting orders from e-shops or food delivery platforms to the PORTOS application.

Glossary
Term
Definition
Term
Definition
PORTOS
The cash register solution developed by Nine Digit, s.r.o.
External system
The 3rd party system (such as e-shop or food delivery platform) from which unprocessed orders are imported to PORTOS.
Venue
The restaurant processing the order.
Cashier
The Venue personnel
Customer
User who orders the goods trough external system.
Order
The purchase request made by customer trough the external system, containing data about products, delivery address, etc.
Unprocessed order
Order accepted by external system, but not yet confirmed nor rejected by PORTOS.
Processed order
Order confirmed or rejected by PORTOS.
Product
The product (such as food or drink) that is ordered by customer.
How it works
The online orders API is a mechanism that allows importing online orders from "external system" (such as e-shops or food delivery platforms) to the PORTOS system.
The PORTOS system acts as an "client" initiating HTTP requests targeting the external system, that acts as an "server" and handles the following requests:
1.Fetch unprocessed orders
2.Process order
After unprocessed order is fetched, cashier is requested to process (either accept or reject) the order trough the PORTOS application. After cashier confirms or rejects the order, PORTOS application will initiate second request (process order) to the external system.
The PORTOS system expects that responses from external system follows data format described below. 
get
{external-system}
{unprocessed-orders-url}
Fetch unprocessed orders
post
{external-system}
{process-order-url}
Process order
Data model
The data model of online orders exchange is described below.
All prices include taxes.
Order
Order represents purchase request made by customer trough the external system, containing data about products, delivery address, etc.
Name
Type
Required
Description
externalId
string
The unique identifier of order, generated by the external system.
type
string (please see allowed values)
The type of order. Contains one of following values:delivery (products will be delivered to customers address), takeAway(customer will pick up the order at the venue) ordineIn(customer will eat at the venue, e.g. table reservation). If type is not specified, delivery is used.
delivery
​OrderDelivery​
Information about the order delivery. Required, when type is delivery. Otherwise must be null (or not specified at all).
createdAt
string
The ISO_8601 formatted date and time of order creation (when the order has been created in external system).
scheduledAt
string
The optional  ISO_8601 formatted date and time of scheduled order. If not specified, order should be delivered ASAP. This field is required when order type is dineIn.
customer
​Customer​
Customer contact information.
products
​Product[]​
The collection of products. Must contain at least one product.
currency
string
Currency code (in ISO 4217
 standard) for order price information. 
payment
​Payment​
The information about payment.
wrappingFee
number
Wrapping fee (not applicable in Slovak republic due to Slovak legislation).
packagingDeposit
number
Packaging deposit (associated with 0% TAX rate)
tip
number
Tip
totalPrice
number
Total price of order, including all products, product additions, delivery and wrapping fee. Precision up to 2 decimal places.
note
string
Optional comment related to the order.
OrderDelivery
Order delivery information.
Name
Type
Required
Description
address
​Address​
The delivery address.
fee
number
The cost of delivery. Precision up to 2 decimal places. If not specified, zero value will be used.   
Address
The customer's address.
Name
Type
Required
Description
line1
string
1st line of delivery address (e.g. street name, building number)
line2
string
Optional 2nd line of delivery address.
city
string
Name of the city.
zipCode
string
The ZIP code (postal code).
note
string
Optional comment related to the address or delivery.
Customer
The customer's contact information.
Name
Type
Required
Description
Name
Type
Required
Description
name
string
Yes
Name of customer.
phone
string
Yes
Phone number.
email
string
No
E-mail address.
Product
The product (such as food or drink).
Name
Type
Required
Description
id
string
The product identifier in PORTOS system. If this field will not be provided, the processing of order will not affect stock quantity of the material in PORTOS stock management system.
name
string
Name of product.
quantity
int
Positive, non-zero integer quantity of the product (e.g. 1, 2, ...).
baseUnitPrice
number
The base unit price of product (product additions are not included).
note
string
The optional product-related comment, provided by customer.
additions
​ProductAddition[]​
The product additions (modifiers). If product quantity is greater than 1, each one will have same additions applied.

Example #1: if customer orders two burgers with fries for each burger, order will contain product with name "Burger", quantity equal to 2 and addition with name "Fires" and quantity equal to one.
​
Example #2: if customer orders two burgers, one with fries and second with salad. In this case, order will contain two separate products - first with quantity equal to one and fries in additions; second with quantity equal to one and salad in additions.  
ProductAddition
The product addition (option, modifier) that adds more information about how the product should be prepared. 
Name
Type
Required
Description
Name
Type
Description
id
string
The product identifier in PORTOS system. If this field will not be provided, the processing of order will not affect stock quantity of the material in PORTOS stock management system.
name
string
Name of product.
quantity
int
Positive, non-zero integer quantity of the product option (e.g. 1, 2, ...).
unitPrice
number
The unit price of product option. Value may be positive or negative, if affects the price of product. Value also may be equal to zero, if product price is not affected (e.g. steak doeness).
note
string
The optional attribute-related comment, provided by customer.
Payment
The product payment information.
Name
Type
Required
Description
isSettled
boolean
true, if payment has already been completed (e.g. transaction has been transferred), false otherwise.
method
string (please see allowed values)
One of following: cash, card
​
The description of payment method that was used (when isSettledis true) or will be used (when isSettled is false).
Configuration
To communicate with external system properly, the external system administrators must provide values stated below to the venue owners or PORTOS support.
Value
Type
Description
Value
Type
Description
External system unprocessed orders URL
string
The URL hosted by external system, that will be requested by PORTOS to fetch the unprocessed orders.
External system process order URL
string
The URL hosted by external system, that will be requested by PORTOS to process (confirm or reject) order.
API key
string
The venue-specific API key (authorization token) that will be placed in the key query parameter of all HTTP requests.
Fetch period
int
The period (in seconds) that specifies, how often will PORTOS system invoke the "fetch unprocessed orders" API call. Default value is 15seconds.
Example
In all request examples below, we will assume following configuration: 
external system unprocessed orders URL: https://the-foo-bar.sk/unprocessed_orders
external system process order URL: https://the-foo-bar.sk/process_order
API key is: my-token
Step 1: Fetching unprocessed orders
The PORTOS will request following URL:
GET https://the-foo-bar.sk/unprocessed_orders?version=1&key=my-token
The external system returns following payload as an response:
[
  {
    "externalId": "b478396ad654",
    "type": "delivery",
    "delivery": {
      "address": {
        "line1": "Kresankova 12",
        "line2": "",
        "city": "Bratislava",
        "zipCode": 84105,
        "note": "Please knock twice"
      },
      "fee": 1.99
    },
    "createdAt": "2021-02-01T12:01:00.000Z",
    "scheduledAt": null,
    "customer": {
      "name": "John Doe",
      "phone": "+421 900 123 456",
      "email": "[email protected]"
    },
    "products": [
      {
        "id": "1234",
        "name": "Burger",
        "quantity": 1,
        "baseUnitPrice": 8.99,
        "note": "",
        "additions": [
          {
            "id": "11002",
            "name": "No cheese",
            "quantity": 1,
            "unitPrice": 0.00,
            "note": ""
          },
          {
            "id": "11002",
            "name": "Extra bacon",
            "quantity": 1,
            "unitPrice": 1.99,
            "note": ""
          }
        ]
      }
    ],
    "currency": "EUR",
    "payment": {
      "isSettled": true,
      "method": "card"
    },
    "wrappingFee": 0,
    "tip": 0,
    "totalPrice": 12.97,
    "note": null
  },
  {
    "externalId": "6a2ad048e32d",
    "type": "takeAway",
    "delivery": null,
    "createdAt": "2021-02-01T12:01:00.000Z",
    "scheduledAt": "2021-02-01T13:00:00.000Z",
    "customer": {
      "name": "John Doe",
      "phone": "+421 900 123 456",
      "email": "[email protected]"
    },
    "products": [
      {
        "id": "2345",
        "name": "Fries",
        "quantity": 2,
        "baseUnitPrice": 4.99,
        "note": "",
        "additions": [
          {
            "id": "11024",
            "name": "Ketchup",
            "quantity": 1,
            "unitPrice": 1.99,
            "note": ""
          }
        ]
      }
    ],
    "currency": "EUR",
    "payment": {
      "isSettled": false,
      "method": null
    },
    "wrappingFee": 0,
    "packagingDeposit": 0,
    "tip": 0,
    "totalPrice": 13.96,
    "note": null
  }
]
As we can see, the external systems returns two unprocessed orders.
Step 2: Order acceptation
The PORTOS will mark first order as accepted by requesting following URL:
POST https://the-foo-bar.sk/process_order?version=1&key=my-token&externalId=b478396ad654&status=accepted&estimatedCompletionAt=2021-02-01T13%3A01%3A00.000Z
Please note that all query parameters are URL encoded. In URL above, the estimatedCompletionAt query parameter value 2021-02-01T13:01:00.000Z is URL encoded as 2021-02-01T13%3A01%3A00.000Z.
Step 3: Fetching unprocessed orders
The PORTOS will request unprocessed requests again:
GET https://the-foo-bar.sk/unprocessed_orders?version=1&key=my-token
The external system returns following payload as an response:
[
  {
    "externalId": "6a2ad048e32d",
    "type": "takeAway",
    "delivery": null,
    "createdAt": "2021-02-01T12:01:00.000Z",
    "scheduledAt": "2021-02-01T13:00:00.000Z",
    "customer": {
      "name": "John Doe",
      "phone": "+421 900 123 456",
      "email": "[email protected]"
    },
    "products": [
      {
        "id": "2345",
        "name": "Fries",
        "quantity": 2,
        "baseUnitPrice": 4.99,
        "note": "",
        "additions": [
          {
            "id": "11024",
            "name": "Ketchup",
            "quantity": 1,
            "unitPrice": 1.99,
            "note": ""
          }
        ]
      }
    ],
    "currency": "EUR",
    "payment": {
      "isSettled": false,
      "method": null
    },
    "wrappingFee": 0,
    "packagingDeposit": 0,
    "tip": 0,
    "totalPrice": 13.96,
    "note": null
  }
]
The recently accepted order no longer appears in unprocessed orders collection.
Step 4: Order rejection
The PORTOS will mark remaining order as rejected by requesting following URL:
POST https://the-foo-bar.sk/process_order?version=1&key=my-token&externalId=6a2ad048e32d&status=rejected&rejectionReason=The%20food%20is%20out%20of%20stock.
Please note that all query parameters are URL encoded. In URL above, the  rejectionReason query parameter value The food is out of stock. is URL encoded as The%20food%20is%20out%20of%20stock..
Step 5: Fetching unprocessed orders
The PORTOS will request unprocessed requests again:
GET https://the-foo-bar.sk/unprocessed_orders?version=1&key=my-token
All requests has been processed (rejected or accepted). The external system returns empty collection as an response.
[]
Changelog
Version 1.3 (2022-12-07)
New packagingDeposit field added.
Supported in PORTOS Pokladňa version 4.0.25 or later.
Supported in PORTOS Online Objednávky version 3.3.8 or later.
Version 1.2 (2022-08-12)
New tip field added.
Supported in PORTOS Pokladňa version 4.0.9 or later.
Version 1.1 (2022-03-17)
New note field added.
Supported in PORTOS Online Objednávky version 1.0.15 or later.
Version 1.0
Initial version

Term	Definition
Term	Definition
PORTOS	The cash register solution developed by Nine Digit, s.r.o.
External system	The 3rd party system (such as e-shop or food delivery platform) from which unprocessed orders are imported to PORTOS.
Venue	The restaurant processing the order.
Cashier	The Venue personnel
Customer	User who orders the goods trough external system.
Order	The purchase request made by customer trough the external system, containing data about products, delivery address, etc.
Unprocessed order	Order accepted by external system, but not yet confirmed nor rejected by PORTOS.
Processed order	Order confirmed or rejected by PORTOS.
Product	The product (such as food or drink) that is ordered by customer.

Name	Type	Description
`externalId`	`string`	The unique identifier of order, generated by the external system.
`type`	`string` (please see allowed values)	The type of order. Contains one of following values:`delivery` (products will be delivered to customers address), `takeAway`(customer will pick up the order at the venue) or`dineIn`(customer will eat at the venue, e.g. table reservation). If type is not specified, `delivery` is used.
`delivery`	`OrderDelivery`	Information about the order delivery. Required, when `type` is `delivery`. Otherwise must be `null` (or not specified at all).
`createdAt`	`string`	The ISO_8601 formatted date and time of order creation (when the order has been created in external system).
`scheduledAt`	`string`	The optional ISO_8601 formatted date and time of scheduled order. If not specified, order should be delivered ASAP. This field is required when order type is `dineIn`.
`customer`	`Customer`	Customer contact information.
`products`	`Product[]`	The collection of products. Must contain at least one product.
`currency`	`string`	Currency code (in ISO 4217 standard) for order price information.
`payment`	`Payment`	The information about payment.
`wrappingFee`	`number`	Wrapping fee (not applicable in Slovak republic due to Slovak legislation).
`packagingDeposit`	`number`	Packaging deposit (associated with 0% TAX rate)
`tip`	`number`	Tip
`totalPrice`	`number`	Total price of order, including all products, product additions, delivery and wrapping fee. Precision up to 2 decimal places.
`note`	`string`	Optional comment related to the order.

Name	Type	Required	Description
`address`	`Address`		The delivery address.
`fee`	`number`		The cost of delivery. Precision up to 2 decimal places. If not specified, zero value will be used.

Name	Type	Description
`line1`	`string`	1st line of delivery address (e.g. street name, building number)
`line2`	`string`	Optional 2nd line of delivery address.
`city`	`string`	Name of the city.
`zipCode`	`string`	The ZIP code (postal code).
`note`	string	Optional comment related to the address or delivery.

Name	Type	Required	Description
Name	Type	Required	Description
`name`	`string`	Yes	Name of customer.
`phone`	`string`	Yes	Phone number.
`email`	`string`	No	E-mail address.

Name	Type	Description
`id`	`string`	The product identifier in PORTOS system. If this field will not be provided, the processing of order will not affect stock quantity of the material in PORTOS stock management system.
`name`	`string`	Name of product.
`quantity`	`int`	Positive, non-zero integer quantity of the product (e.g. 1, 2, ...).
`baseUnitPrice`	`number`	The base unit price of product (product additions are not included).
`note`	`string`	The optional product-related comment, provided by customer.
`additions`	`ProductAddition[]`	The product additions (modifiers). If product `quantity` is greater than 1, each one will have same `additions` applied. Example #1: if customer orders two burgers with fries for each burger, order will contain product with name "Burger", quantity equal to 2 and addition with name "Fires" and quantity equal to one. Example #2: if customer orders two burgers, one with fries and second with salad. In this case, order will contain two separate products - first with quantity equal to one and fries in additions; second with quantity equal to one and salad in additions.

Name	Type	Description
Name	Type	Description
`id`	`string`	The product identifier in PORTOS system. If this field will not be provided, the processing of order will not affect stock quantity of the material in PORTOS stock management system.
`name`	`string`	Name of product.
`quantity`	`int`	Positive, non-zero integer quantity of the product option (e.g. 1, 2, ...).
`unitPrice`	`number`	The unit price of product option. Value may be positive or negative, if affects the price of product. Value also may be equal to zero, if product price is not affected (e.g. steak doeness).
`note`	`string`	The optional attribute-related comment, provided by customer.

Name	Type	Required	Description
`isSettled`	`boolean`		`true`, if payment has already been completed (e.g. transaction has been transferred), `false` otherwise.
`method`	`string` (please see allowed values)		One of following: `cash`, `card` The description of payment method that was used (when `isSettled`is `true`) or will be used (when `isSettled` is `false`).

Value	Type	Description
Value	Type	Description
External system unprocessed orders URL	`string`	The URL hosted by external system, that will be requested by PORTOS to fetch the unprocessed orders.
External system process order URL	`string`	The URL hosted by external system, that will be requested by PORTOS to process (confirm or reject) order.
API key	`string`	The venue-specific API key (authorization token) that will be placed in the `key` query parameter of all HTTP requests.
Fetch period	`int`	The period (in seconds) that specifies, how often will PORTOS system invoke the "fetch unprocessed orders" API call. Default value is `15`seconds.

3rd Party Integrations - Previous

Introduction

Next - 3rd Party Integrations

Rewards API

Last modified 3mo ago