OpenAPI - Transfer orders (part 1/4) - Create an order or order line

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 the POST /v1/order-lines (see section 3. Create or update an order line).
      If successful, the system will return a unique orderLineId.
  • 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 unique importId.
  • Update: To update an order, provide either orderId or importId 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.

  1. GET order statuses list
  2. POST to create the order
  3. 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” as orderImportId.

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.

  1. GET order line statuses list
  2. POST to create the order line
  3. 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 and orderImportId.
  • orderLineId and orderLineImportId.

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 than orderImportId.
  • orderLineId has higher priority than orderLineImportId.

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.

image

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.