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

khoa.nguyen · February 5, 2024, 11:29am

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:

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/order-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:

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 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.

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.

Topic	Replies	Views
Version 1.9.1.0 - Release date: 15.03.2024 OpenAPI changelogs official , openapi	86	March 13, 2024
OpenAPI - Transfer orders (part 2/4) - Update order line's properties and form properties Knowledge base official , openapi	143	February 5, 2024
OpenAPI – Transfer products Knowledge base official , openapi	9	September 27, 2024
OpenAPI - Transfer orders (part 3/4) - Migrate from Web API to OpenAPI Knowledge base official , openapi	171	February 5, 2024
Version 1.10.2.0 - Release date: 05.07.2024 OpenAPI changelogs official , openapi	12	July 5, 2024

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

1. Overview

2. Create or update an order

API overview

Prerequisite

Request parameters and body

Response

Examples

Integrating suggestions

3. Create or update an order line

API overview

Prerequisite

Request parameters and body

Response

Examples

Integrating suggestions

4. Numbering an order line’s items

API overview

Prerequisite

Request parameters and body

Response

Examples

Integrating suggestions

5. Related articles

Related topics