The Orderportal is the interface between your supplier service and your customers KORONA POS account. You are able to create master lists of products that your customers can easily adopt into their database. With these products, customers can create stock orders that you can pull and then update the status of in your service. Once orders are complete, the customer can easily see the completion status and then receive stock into their KORONA inventory.
The OpenAPI specification can be found here:
https://orderportal.koronacloud.com/supplier.yaml
The endpoint URL is:
https://orderportal.koronacloud.com/supplier
Integrating With the KORONA Orderportal
Note
If you’d like to see the steps the customer takes, please see this manual page
If you’d like to integrate with the Orderportal, send an email to our support team at support@koronapos.com with the name your customers know you by and, optionally, your logo. These will appear on the KORONA.appcenter, where customers first add you to their Orderportal.
After we receive your email, we will provide you with your supplier ID and credentials that you can authenticate. With the provided user credentials, you need to fetch a token for further interaction with the API. You can get a token by POSTing the credentials to the /auth endpoint with the following body:
{
"username": "string",
"password": "string"
}
The received token will be valid for about 10 hours and needs to be passed as a bearer token, e.g., Auth: Bearer $Token.
General Usage
The API generally allows you to fetch (GET), update (PATCH), or delete (DELETE) specific items by ID, retrieve a filtered list of items (GET), and add or insert multiple items (POST).
When fetching lists, you will receive an object containing paging information, the first page starts at 1. Pages (page) and page sizes (size) can be passed as query parameters, along with some filtering and sorting options.
{
"currentPage": 1,
"pagesTotal": 2,
"resultsOfPage": 10,
"resultsTotal": 18,
"results": [
...
]
}
Products
Products are the same for all customers, it is however possible to set a purchase prices for customer groups. These groups must be created prior to specifying them with the customerPrices property via the /suppliers/{supplierId}/priceGroups endpoint.
Basic product item (code, orderNumber and suggestedRetailPrice are optional):
[
{
"number": "test-1",
"name": "Test Product 1",
"assortment": {
"name": "Example range"
},
"commodityGroup": {
"name": "Example category"
},
"sectorType": "STANDARD",
"containers": [
{
"orderNumber": "A2",
"code": "123456789444",
"quantity": 1,
"price": {
"amount": 10.00
},
"suggestedRetailPrice": {
"amount": 8.00
}
}
]
}
]
A product can be ordered in different containers with different order numbers, product codes, prices and quantities. For boxing and deposit calculation, there must be at least one container with container size (quantity) = 1, it does not need to be orderable though. If you do not want a container to be orderable you can omit the orderNumber.
You can specify a deposit on a container in two ways. With type SPECIFIED, you have to set a monetary amount, and with type BY_PRODUCT, you have to reference another product.
Assortments and commodity groups will either be matched with existing entities or created in KORONA.studio, either name or number must be provided.
The sectorType refers to a tax type. This can be either ZERO, REDUCED or STANDARD and will be manually associated to a sector in KORONA.studio by the customer. An example would be in locations where food is tax-free, it would have ZERO for the sectorType.
If a product has a stableNumber, this will be the primary number to match products by in case the order number on the product changes, e.g. on product updates or importing dispatch notifications. Stable numbers should be unique.
Stock Orders
Stock orders created in the Orderportal in KORONA.studio will be forwarded to the Orderportal service once they are explicitly sent by the user.
Example Response:
{
"id": "32500975-5145-46af-92bf-ad0ae4c72477",
"number": "10001121",
"customerNumber": "1213131",
"createTime": "2023-01-09T16:42:39Z",
"supplierItems": [
{
"quantity": 20.00000,
"productDescription": "Lucky Strike Authentic Red OP..",
"productCode": "4031300267059",
"orderNumber": "123456",
"price": {
"amount": 10.00000
},
"itemQuantity": 20.00000,
"containerQuantity": 1.00000
},
{
"quantity": 32.00000,
"productDescription": "Pall Mall Red Giga 10,00€",
"productCode": "4031300280058",
"orderNumber": "654321",
"price": {
"amount": 0.00000
},
"itemQuantity": 32.00000,
"containerQuantity": 4.00000
}
],
"customerId": "ff16c5c5-075c-4354-913c-9b74ed02fbdd",
"processingState": "NEW"
}
The processingState indicates the state of the order, the KORONA.studio will query this state and display the processingState to the user when they open the order. There are four states, initially the orders have the flag NEW. When polling for new orders, query (GET) stock orders with the parameter “processingState” to NEW, you can also query for orders of specific customers. Afterward, you should update (PATCH) the processingState of these orders as follows:
- REJECTED: There has been an error processing this order, or it cannot be fulfilled.
- PROCESSED: The order has been processed but is not yet accepted.
- ACCEPTED: The order has been accepted and the items have been shipped.
When updating or adding a stock order, you need to provide the customerId (as seen above).
Dispatch notifications
Dispatch notifications notify the customer that the ordered items have been shipped. These are optional, as the customer can convert their Stock Order to a Stock Receipt to receive the product quantity into their warehouse.
Minimal dispatch notification:
[
{
"number": "4",
"customerNumber": "123456",
"supplierItems": [
{
"quantity": 123,
"orderNumber": "120823",
"productNumber": "918673893"
}
],
"processingState": "NEW"
}
]
The customer must be identifiable by either customerNumber, customerId or by the customer referenced on the associated stock order. A stock order can either be set via stockOrderNumber or stockOrderId. If a customer cannot be determined, the creation of the dispatch notification will fail. If you want to express that e.g. 200 items are going to be delivered, and these are packaged in 10 boxes with 20 items, pass boxSize with the value 20 and quantity with 10. When the dispatch notifications are pulled by KORONA.studio, it tries to associate the supplier items to products present in either KORONA.studio or Orderportal by any supplier order number, product number or code. If an item is not found, the customer can either manually associate it to an existing product or create one when booking the dispatch notification in KORONA.studio. A processingState must be set, use “NEW” when creating new notifications, once the cloud has processed them, the property will be set to “PROCESSED”.
Product update
When productUpdate is set, the data included can be used to either update or create the product in the KORONA.studio.
On booking dispatch notification in the cloud, product code/containers will be updated. EAN-prices will be added if updatePrices is set to true, this is mostly used for adding new cigarette prices.
Sector, commodity group and assortment will only be used when creating a new product in the cloud which does not exist in the Orderportal.
Supplier prices will be updated once the customer has created and booked a stock receipt.
Additional information
Addresses, descriptions, and remarks are informational only and will be passed to the KORONA.studio.
