1. Overview
The order and order line APIs allow suppliers to create a massive amount of equipment with less effort compared to manual creation in Onix Work.
Here is how to create an order using Onix Work OpenAPI:
-
Initially, create the order by making a POST request to the endpoint:
POST /v1/orders
(see section 2. Create or update an order).
If successful, the system will assign a unique order ID. -
Proceed to create order lines based on one of the following:
- The received
orderId
as the key to represent the order in Onix Work, or orderImportId
as the key to represent the order in your system. The prerequisite for using this key is that the corresponding value must be included in the order in the Onix Work.
Use thePOST /v1/order-lines
(see section 3. Create or update an order line).
If successful, the system will return a uniqueorderLineId
.
- The received
-
Number the items within each order line using:
POST /v1/order-lines/items
(see section 4. Numbering an order line’s items.) -
Update properties of the order lines, using:
POST /v1/order-lines/properties
(see part 2. Update an order line’s properties.) -
Update form properties of the order lines, using:
POST /v1/order-lines/form-properties
(see part 2. Update an order line’s form properties.) -
Finally, navigate to Onix Work via Onix Work URL and perform any necessary final adjustments then complete the order.
This article is divided into three parts, read part 2 and part 3 here.
If you want to migrate from the Web API to the OpenAPI, please read OpenAPI migration guides for guidelines.
Here’s a table showing models used by the endpoints:
Endpoint | Model |
---|---|
POST /v1/orders |
OrderInfo |
POST /v1/order-lines |
OrderLineInfo |
POST /v1/order-lines/items |
OrderLineItemsInfo |
POST /v1/order-lines/properties |
OrderLinePropertiesInfo |
POST /v1/order-lines/form-properties |
OrderLineFormPropertiesInfo |
2. Create or update an order
API overview
Endpoint | POST /v1/orders |
Description | Create or update an order. |
Usage | Call this API to create an order and obtain orderId from the Onix Work system. |
Return | The Onix Work system ID of newly created/updated order ID. Return type: int . |
Prerequisite
It must retrieve the workflow order status through the endpoint: GET /v1/company/issue-statuses
.
Request parameters and body
Differences between create and update mode:
- Create: To create an order, omit
orderId
field and provide a uniqueimportId
. - Update: To update an order, provide either
orderId
orimportId
and they also must exist in the Onix Work system for your company.
When a field value is null, it follows the rules explained in section API requests and responses, if no specific rules are mentioned.
The corresponding request body type can be found at the Swagger page (see OpenAPI overview), model OrderInfo
.
Field | Type | Required | Description |
---|---|---|---|
orderId |
int |
No* | The Onix Work system’s order ID. Either orderId or importId must be provided.orderId has higher priority than importId . When orderId is present, importId is optional.This can only be used to update the order data. This is the only way to update importId . |
importId |
string |
No* | Constraint: length ≤ 50. Your system’s order ID. Either orderId or importId must be provided.This field can be used to identify the order in the Onix Work system. Typical usage of this field is for creating or updating orders. |
erpOrderId |
string |
Yes | Constraint: length ≤ 100. The order number used for this job. This field can be used to locate the document in Onix Work. |
erpOrderDate |
string |
No | Constraint: date format: yyyy-MM-dd .(e.g.: 2024-01-31). Default value : today. The order’s date. The system will use the default value when the field is empty. |
erpCustomerOrderNo |
string |
No | Constraint: length ≤ 100. The customer’s order number for this job. This field can be used to locate the document in the Onix Work. |
workflowStatusId |
int |
No | Constraint: order workflow IDs in the Onix Work belonged to your company. Default value : the default workflow status sets in your company settings in the Onix Work. The order workflow IDs can be get from the endpoint: GET /company/order-statuses (optional languageCode query parameter, see OpenAPI terminology).The response type is in key-value pair list (see common response types API requests and responses). To manage your company’s order workflow IDs, navigate to the Onix Work URL (see OpenAPI overview) > Settings > Workflow > Order tab. Note: if the workflow status is marked as: 1. Closed for numbering: you can no longer call numbering request for all order lines in this order. 2. Closed: you can no longer update information on this oder. |
erpCustomerId |
string |
No | Constraint: length ≤ 50. Your system’s internal ID for the customer company. The order will be automatically mapped to a customer if the value matches with a company link on the Onix Work system. See company links in section OpenAPI terminology. The field value will be ignored after creating the order - can only be updated directly from Onix Work. |
erpCustomerDescription |
string |
No | Constraint: length ≤ 100. Your system’s internal description for the customer company. |
erpCustomerAddress |
string |
No | Constraint: length ≤ 100. Your system’s customer company’s address. Used for visual mapping purposes. |
erpCustomerPortalCode |
string |
No | Constraint: length ≤ 100. Your system’s customer company’s postal code. Used for visual mapping purposes. |
erpCustomerWeb |
string |
No | Constraint: length ≤ 250. Your system’s customer company’s web address/site. Used for visual mapping purposes. |
erpCustomerOrgNumber |
string |
No | Constraint: length ≤ 50. Your system’s customer company’s entity number. Used for visual mapping purposes. |
erpCustomerCountryCode |
string |
No | Constraint: length ≤ 10. Your system’s customer company’s country code. Used for visual mapping purposes. |
erpCustomerContactId |
string |
No | Constraint: length ≤ 250. Your system’s internal ID for the contact from customer company. This ID must be existed/created upfront in the Onix Work, see contact links in section OpenAPI terminology. If the ID does not exist in contact links, the system will set this field to null. |
erpCustomerContactName |
string |
No | Constraint: length ≤ 100. Your system’s customer company’s contact name. |
erpSupplierId |
string |
No | Constraint: length ≤ 50. Your system’s internal ID for the supplier company. This ID must be existed/created upfront in the Onix Work, see company links in section OpenAPI terminology. If the ID does not exist in company links with link type as supplier, the system will set this field to null. |
erpSupplierDescription |
string |
No | Constraint: length ≤ 100. Name of the supplier where the order comes from. |
erpSupplierContactId |
string |
No | Constraint: length ≤ 250. Your system’s internal ID for the supplier contact. This ID must be existed/created upfront in the Onix Work, see contact links in section OpenAPI terminology. If the ID does not exist in contact links, the system will set this field to null. |
erpSupplierContactName |
string |
No | Constraint: length ≤ 100. Your system’s supplier company’s contact name. |
source |
int |
No | Default value : 1 — ERP. A static value defines where the order comes from: • ERP — 1. • Point Of Sale — 2. • Manually — 3. |
Response
Status code | Response body | Description |
---|---|---|
200 |
A 32-bit integer. | An order has been created or updated successfully. The integer in the response body is the Onix Work system’s orderId . |
400 |
The system’s standard error response object. | See an examples of error responses in secion API requests and responses. |
Examples
We will use Swagger UI to create an order.
First, obtain a security token and authorize the Swagger requests. See Authentication for more information.
Next, make a request to the endpoint, the request body looks like:
{
"importId": "ERP_Import/0001",
"erpOrderId": "ERP_Order/0001",
"erpCustomerOrderNo": "ERP_CustomerOrder/0001",
"erpCustomerId": "ERP_Customer/0382"
}
The system responsed with status code of 200, the response body is the system’s orderId
:
546804
We will use these values for examples in the next sections:
importId
: “ERP_Import/0001”.orderId
: 546804.
The order has been created successfully. Let’s check the order by navigating to Onix Work (using the URL in OpenAPI overview), and use the erpOrderId
value in the request above to type in the “Order no.” text box then click “Search”:
The first result is our newly created order.
The customer is automatically filled because of the erpCustomerId
matched with the “External ID” in company links, see “Company links” section OpenAPI terminology.
You can find all other additional information related to your customer and/or your supplier (if any) will be presented in “ERP customer” in “Customer” section and “ERP supplier” in “Supplier” section.
Integrating suggestions
Based on the prerequisite & API design, we suggest integrating the functionality to create or update an order using the importId
as the key to represent the order in your system, as illustrated in the UML diagram below.
- GET order statuses list
- POST to create the order
- POST to update the order if needed.
3. Create or update an order line
API overview
Endpoint | POST /v1/orders-lines |
Description | Create or update an order line of the order. |
Usage | Create new or update existing order lines. The product number field – erpArticleNo will affect the order line’s properties and form properties. Make sure to use the correct product number, since erpArticleNo field cannot be updated.Note: Attempting to modify sub order lines after referencing an existing main order line (field parentOrderLineImportId ) in its creation request will result in an error. |
Return | The Onix Work system ID of newly created/updated order line ID. Return type: int. |
Prerequisite
- Products were created. Refer to Open API – Transfer products for further details.
- The order was created. Refer to section 2. Create or update an order for further details.
- It must retrieve the workflow order status through the endpoint: GET /v1/company/issue-statuses
Request parameters and body
Differences between create and update mode:
- Create: when
orderLineImportId
is null/empty or does not exist in the system. - Update: when
orderLineImportId
exists in the system.
When a field value is null, it follows the rules explained in section API requests and responses, if no specific rules are mentioned.
The corresponding request body type can be found at the Swagger page (see OpenAPI overview), model OrderLineInfo
.
Field | Type | Required | Description |
---|---|---|---|
orderImportId |
string |
Yes | Constraint : length ≤ 50 and must exist in the system. Your system’s order ID and corresponding with importId field in endpoint: POST /v1/orders .This field can be used to identify the order in Onix Work. |
orderLineImportId |
string |
No | Constraint : length ≤ 50. Your system’s order line ID. This field can be used to identify the order in Onix Work. If the orderLineImportId exists, it will be updated instead.This field cannot be updated. |
erpArticleNo |
string |
Yes (create) No (update) |
Constraint : length ≤ 250. Your system’s product number. This field is required only when creating an order line. If the product number: 1. Does not exist: the system will create a new product in the product module in Onix Work, based on data from this request. 2. Exists: it must have product type of unique equipment. See OpenAPI terminology for unique and non-unique equipment. This field cannot be updated. |
quantity |
int |
Yes (create) No (update) |
Constraint : value > 0. The number of items for this order line. This field cannot be updated. |
externalLineNo |
string |
No | Constraint : length ≤ 50. The customer’s order number for this job. This field can be used to locate the document in the Onix Work. |
workflowStatusId |
int |
No | Constraint : order line workflow IDs in the Onix Work belonged to your company. Default value : the default workflow status set in your company settings in the Onix Work. The order line workflow IDs can be get from the endpoint: GET /v1/company/order-line-statuses (optional languageCode query parameter, see OpenAPI terminology).The response type is in key-value pair list (see common response types API requests and responses). To manage your company’s order line workflow IDs, navigate to the Onix Work URL (see OpenAPI overview) > Settings > Workflow > Order line tab. Note: if the workflow status is marked as: 1. Closed for numbering: you can no longer call numbering request for this order line. 2. Closed: you can no longer update this order line. |
parentOrderLineImportId |
string |
No | Constraint : length ≤ 50. Default value: null. The order line’s parent order line ID in your system. Usually used to create links parent – child between order lines. The referenced order line will serve as the parent order line, while the current order line will be the child order line. The parent order lines will create main equipment. The child order lines will create sub equipment. Note : 1. Creating cyclic references between order lines is not recommended, as it may result in system errors. 2. Attempting to modify sub order lines after referencing an existing main order line (field parentOrderLineImportId ) in its creation request will result in an error.This field cannot be updated. |
certificateString |
string |
No | Constraint : length ≤ 50. The order line’s certificate information. |
model |
string |
No | Constraint : length ≤ 100. The equipment model – detail description. |
erpModel |
string |
No | Constraint : length ≤ 100. Additional equipment description. |
wll |
string |
No | Constraint : length ≤ 50. The equipment’s working load limit (WLL). |
comment |
string |
No | Constraint : length ≤ 4000. Comments for generated equipment. |
jobComment |
string |
No | Constraint : length ≤ 4000. Comments for generated certificates. |
type |
string |
No | Constraint : length ≤ 50. The order line’s type. |
process |
int |
No | Default values: 1 — No Action. Defines the action when processing the order or the order line on Onix Work. See OpenAPI terminology. This field is related to the erpArticleNo . If the product number:1. Does not exist: a new product is created with the provided value as the product’s order action value. 2. Exists and no value was provided or invalid: the action from the product will be used for this field. 3. Exists and a valid value was provided: the value is updated to the provided value. |
Response
Status code | Response body | Description |
---|---|---|
200 |
A 32-bit integer. | An order line has been created or updated successfully. The integer in the response body is the Onix Work system’s orderLineId . |
400 |
The system’s standard error response object. | See an examples of error responses in secion API requests and responses. |
Examples
After creating the order line successfully in Create and update order examples, let’s create order lines for this order, using:
- The order’s
importId
: “ERP_Import/0001” asorderImportId
.
to make a request with request body with a quantity of 5 equipment units:
{
"orderImportId": "ERP_Import/0001",
"orderLineImportId": "ERP_OrderLine/0001",
"erpArticleNo": "ERP_Product/0001",
"quantity": 5,
"model": "OL1: ERP model",
"erpModel": "OL1: ERP erpModel",
"wll": "OL1: WLL",
"comment": "OL1: My Comment",
"jobComment": "OL1: My job comment"
}
The system responsed with status code of 200, the response body is the system’s orderLineId
:
3998608
The order line has been created successfully. Let’s check the order line in Onix Work by navigating to the order we have just been created in Create and update order examples and click on the tab “Order lines”. Our newly created order line is the only one on the list.
Note: we used the product with product number “ERP_Product/0001” which existed before we created this order line. The product is configured with type, model, properties, and forms (contains form properties).
Notice the type of the order line and the type of the product: “Default type - ERP_Product/0001”. Since we did not specify the type
field in the request, the system will pick up nescessary information from the product and apply for it.
We will use these values for examples in the next sections:
orderLineImportId
: “ERP_OrderLine/0001”.orderLineId
: 3998606.
Integrating suggestions
Based on the prerequisite & API design, we suggest integrating the functionality to create or update an order line using the key pair orderImportId
& orderLineImportId
as illustrated in the UML diagram below.
- GET order line statuses list
- POST to create the order line
- POST to update the order line if needed.
4. Numbering an order line’s items
API overview
Endpoint | POST /v1/orders-lines/items |
Description | Fills information for each item in the order line. |
Usage | Make a request to this endpoint to numbering items in the order line. The latest request overwrites all numbering. If there are more entries than items, extras are ignored; if not enough, the rest are set to empty. |
Return | Returns a boolean value indicating the success of the numbering process. |
Prerequisite
- Products were created. Refer to Open API – Transfer products for further details.
- The order was created. Refer to section 2. Create or update an order for further details.
- The order line was created. Refer to section 2. Create or update an order line for further details.
Request parameters and body
The corresponding request body type can be found at the Swagger page (see OpenAPI overview), model OrderLineItemsInfo
for the main request body and OrderLineItemSerialInfo
for the items
model.
There are two ID pairs:
orderId
andorderImportId
.orderLineId
andorderLineImportId
.
Despite those fields being nullable, the system requires the request body must contains at least one field for each pair.
Field precedence for ID pairs:
orderId
has higher priority thanorderImportId
.orderLineId
has higher priority thanorderLineImportId
.
When a higher priority field is present, the lower priority field will be ignored.
When a field value is null, it follows the rules explained in section API requests and responses, if no specific rules are mentioned.
Field | Type | Required | Description |
---|---|---|---|
orderId |
int |
No* | The Onix Work system’s order ID. Either orderId or orderImportId must be provided.See field precendence above. |
orderImportId |
string |
No* | Constraint : length ≤ 50. Your system’s order ID. Either orderId or orderImportId must be provided.See field precendence above. |
orderLineId |
int |
No* | The Onix Work system’s order line ID. Either orderLineId or orderLineImportId must be provided.See field precendence above. |
orderLineImportId |
string |
No* | Constraint : length ≤ 50. Your system’s order line ID. Either orderLineId or orderLineImportId must be provided.See field precendence above. |
items |
OrderLineItemSerialInfo[] |
Yes | Constraint: length > 0. The list of numbering items. The latest request overwrites all numbering. If there are more entries than items, extras are ignored; if not enough, the rest are set to empty. See the table below for more information. |
Model OrderLineItemSerialInfo
fields table:
Field | Type | Required | Description |
---|---|---|---|
serialNumber |
string |
No | Constraint : length ≤ 100. Serial number of the item. |
batchNo |
string |
No | Constraint : length ≤ 30. Batch number of the item. |
ownersEquipmentID |
string |
No | Constraint : length ≤ 50. Owner equipment ID of the item. |
prodYear |
string |
No | Constraint : length ≤ 10. Production year of the item. |
globalID |
string |
No | Constraint : length ≤ 50. Global ID of the item. It is recommended to use a globally unique ID for each item. This field is corresponding to EPC field in Onix Work. |
Response
Status code | Response body | Description |
---|---|---|
200 |
A boolean. | The numbering request process status. |
400 |
The system’s standard error response object. | See an examples of error responses in section API requests and responses. |
Examples
Let’s use the orderId
and orderLineId
to number the order line that’s just created in above examples:
orderId
: 546804.orderLineId
: 3998608.
You can also use orderImportId
and orderLineImportId
to number an order line.
And then make a request with the request body below, since we the order line has a quantity of 5 equipment units, 5 items in the items
field is sufficient:
{
"orderId": 546804,
"orderLineId": 3998608,
"items": [
{
"serialNumber": "EQ.ERP.01",
"batchNo": "B2024.01",
"prodYear": "2024"
},
{
"serialNumber": "EQ.ERP.02",
"batchNo": "B2024.01",
"prodYear": "2024"
},
{
"serialNumber": "EQ.ERP.03",
"batchNo": "B2024.01",
"prodYear": "2024"
},
{
"serialNumber": "EQ.ERP.04",
"batchNo": "B2024.01",
"prodYear": "2024"
},
{
"serialNumber": "EQ.ERP.05",
"batchNo": "B2024.01",
"prodYear": "2024"
}
]
}
The system responsed with status code of 200, the response body indicates where the request was successful or not:
true
The numbering request has been processed successfully. Let’s check the results in Onix Work by navigating to the order we have just been created in Create and update order examples and click on the tab “Numbering” and click on our order line on the list.
Integrating suggestions
Based on the prerequisite & API design, we suggest integrating the functionality to update order line items (numbering) using the key pair orderImportId
& orderLineImportId
as illustrated in the UML diagram below.
All the items have been numbered with provided information in the request.
This order line uses the product containing properties, let’s go to the next step: update its properties - part 2.
5. Related articles
- OpenAPI - Get started
- Part 1: create and update an order, an order line and numbering an order line.
- Part 2: update an order line’s properties and form properties.
- Part 3: how to migrate from Web API to OpenAPI.
- Part 4: create and update grouped order lines.