OpenAPI – Transfer products

phuong.duong · September 27, 2024, 12:11pm

1. Overview

The product APIs allow you to create a large number of products with significantly less effort compared to manually creating them in Onix Work. Here is how to create an product using Onix Work OpenAPI:

Initially, create the product by making a POST request to the endpoint:
POST /v1/company/products (see section 2. Create or update a product)
If successful, the system will return a unique productId.
Proceed to add properties into the product using:
POST /v1/company/products/properties (see section 3. Add or update product’s properties)
Proceed to add forms into the product using:
POST /v1/company/products/forms (see section 4. Add or update product’s forms.)
Proceed to update forms’ properties in the product using:
POST /v1/company/products/form-properties (see section 5. Update forms’ properties.)

Here’s a table showing models used by the endpoints:

Endpoint	Model
`POST /v1/company/products`	ProductInfo
`POST /v1/company/products/properties`	ProductPropertiesInfoDto
`POST /v1/company/products/forms`	ProductFormInfoDto
`POST /v1/company/products/form-properties`	ProductFormPropertiesInfoDto

2. Create order update a product

API overview


Endpoint	`POST /v1/company/products`
Description	Create or update a product
Usage	Call this API to create a product and obtain productId from the Onix Work system.
Return	The Onix Work system ID of newly created/updated product ID. Return type: int.

Prerequisite

It must retrieve the control category through the endpoint: GET /v1/company/control-categories

Request parameters and body

Differences between create and update mode:

Create: To create a product, omit the productId field and provide a unique productNo. The importId is optional.
Update: To update an order, provide either the orderId, importId, or productNo. These values must already existed in the Onix Work system for your company.

When a field value is null, it follows the rules explained in API requests and responses, if no specific rules are mentioned.

The corresponding request body type can be found at Swagger UI, model ProductInfo.

Field	Data type	Required	Description & Constraints
`productId`	int	No*	The Onix Work system’s product ID. To update a product, either the `productId`, `importId`, or `productNo` must be provided with the following priority: `productId` > `importId` > `productNo`
`importId`	string	No*	Constraint: length ≤ 50. Your system’s product ID (optional). This field can be used to identify the product in the Onix Work system. Typically used for creating or updating products.
`productNo`	string	Yes	Constraint: length ≤ 250. Your system’s product number. This field can be used to identify the product in the Onix Work system. Typically used for creating or updating products.
`statusId`	int	No	`statusId` is the enum with values: 1 – Dynamic 2 – Draft 3 – Approved 4 – New from ERP
`status`	string	No	The description of the specified `statusId` value, translated by the user login language when displaying in the UI. If this field has a value in the body request, ignore it.
`active`	boolean	No	The active status of product. There are 2 states: true or false
`controlCategoryId`	int	No	The ID of control category. Get this value from API: `GET /v1/company/control-categories` Note that the Open API won’t support removing this field’s data, but users can do it manually if needed.
`controlCategoryDescription`	string	No	The description of the specified `controlCategoryId` value, translated by the user login language when displaying in the UI. If this field has a value in the body request, ignore it.
`controlcategoryDescAndComment`	string	No	The description & comment of the specified `controlCategoryId` value, translated by the user login language when displaying in the UI. If this field has a value in the body request, ignore it.
`placement`	string	No	Constraint: length ≤ 50. The placement of the product
`type`	string	No	Constraint: length ≤ 50. The equipment type.
`model`	string	No	Constraint: length ≤ 100. The equipment model. If the `model` doesn’t include in the body request or include with a null value. When creating a new product, the `model` will be obtained from the from `description` field. When updating the existing product, the `model` will be unchanged whether the `description` field has value or not.
`description`	string	No	Constraint: length ≤100. The original ERP description. When creating a new product that is also the Model.
`wll`	string	No	Constraint: length ≤ 50. The Working load limit (WLL) of product.
`swl`	string	No	Constraint: length ≤ 50. The Safety working load (SWL) of product.
`comment`	string	No	Constraint: length ≤ 4000. Comment on equip.
`dealer`	string	No	Constraint: length ≤ 100. The dealer of product.
`prodAccTo`	string	No	Constraint: length ≤ 250. The produced acc. to of product.
`producer`	string	No	Constraint: length ≤ 100. The producer of product.
`prodYear`	string	No	Constraint: length ≤ 10. The production year of product.
`quantityUsage`	int	No	`quantityUsage` is the enum with values: 0 – Indicate the Unique equipment or Part 1 – Indicate the Stock goods 2 – Indicate the Consumable goods
`productGroup`	boolean	No	Whether the current product is a product group. There are 2 states: true or false
`connectedProductGroupId`	int	No	The product group ID of this product
`productClassId`	int	No	`productClassId` is the enum with values: 0 – Indicate the Unique equipment 1 – Indicate the Stock goods 2 – Indicate the Consumable goods 3 – Indicate the Part
`downloadToOnixInspect`	boolean	No	There are 2 states: There are 2 states: true or false
`useFromEquipment`	boolean	No	There are 2 states: There are 2 states: true or false
`testedAccTo`	string	No	Constraint: length ≤ 100. The test acc. to of product.
`ProcessId`	int	No	`processId` is the enum with values: 1 - Indicate the No action 2 - Indicate the Create equipment 3 - Indicate the Create equipment and job 4 - Indicate the Create equipment and file job
`jobComment`	string	No	Constraint: length ≤ 4000. The comment on job.

Response

Status code	Response body	Description
200	A 32-bit integer.	A product has been created or updated successfully. The integer in the response body is the Onix Work system’s `productId`.
400	The system’s standard error response object.	See examples of error responses in API requests and responses.

Examples

We will use Swagger UI to create a product.

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/P0001",
    "productNo": "ERP_Import/P0001",
    "statusId": 1,
    "active": true,
    "controlCategoryId": 127
  }

The system responsed with status code of 200, the response body is the system’s productId:

We will use these values for examples in the next sections:

importId: “ERP_Import/P0001”.
productNo: “ERP_Import/P0001”.
productId: 214011.

The product has been created successfully. Let’s check the product: Navigate to Onix Work, use the productNo value in the request above to search in the Product no. search field. The first result is our newly created product.

Integrating suggestions

Based on the prerequisite & API design, we suggest integrating the functionality to create or update a product using the key productNo as illustrated in the UML diagram below.

GET control category list
POST to create a product
POST to update a product if needed.

3. Add or update properties for a product

API overview


Endpoint	`POST /v1/company/products/properties`
Description	Add or update properties for a product
Usage	Call this API to add or update properties for a product.
Return	Return type: boolean.

Prerequisite

Products have been already created. Refer to section 2. Create or update a product for further details.
It must retrieve properties through the endpoint: GET /v1/company/properties

Request parameters and body

The corresponding request body type can be found at the Swagger UI, model ProductPropertiesInfoDto for the main request body and PropertyInfo for the properties model.

Differences between add and update mode:

Add: If the properties are not yet included in the product but exist in the properties list in Onix Work, they will be added.
Update: If the properties were previously included in the product, their values will be updated based on the corresponding data in the request.

When a field value is null, it follows the rules explained in API requests and responses, if no specific rules are mentioned.

The corresponding request body type can be found at the Swagger UI, model ProductPropertiesInfoDto.

Field	Data type	Required	Description & Constraints
`productId`	int	No*	The Onix Work system’s product ID. To add or update properties for a product, either the `productId`, `importId`, or `productNo` must be provided with the following priority: productID > importId > productNo
`importId`	string	No*	Constraint: length ≤ 50. Your system’s product ID. Typically used for adding or updating properties for a product.
`productNo`	string	No*	Constraint: length ≤ 250. Your system’s product number. Typically used for adding or updating properties for a product.
`properties[index].languageCode`	Int	No	The language of the property in the product. Available values: 0, 1, 3, 4, 6, 7, 9 where: 0: Norwegian 1: English 3: Swedish 4: Danish 6: Deutsch 7: Spanish 9: Portuguese
`properties[index].description`	string	Yes	The description of properties. When adding or updating the properties, the system will find all properties that match their names and translated names according to the `languageCode` specified in the request description.
`properties[index].value`	string	No	The property value.

Response

Status code	Response body	Description
200	A boolean.	Properties in the product have been added or updated successfully.
400	The system’s standard error response object.	See an examples of error responses in API requests and responses.

Examples

Let’s use one of the following keys: productId, importId, or productNo to add or update properties for a product.

importId: “ERP_Import/P0001”.
productNo: “ERP_Import/P0001”.
productId: 214011.

First, let’s examine the properties that the product has been using for better visualization:
Currently, the* product only has a property called ABAX Serial Number.

And in the properties list, it has a property called Color

To add/ update the product’s properties, make a request with the request body below, with languageCode is English (see OpenAPI terminology). In this example, we use the key productNo

{
  "productNo": ERP_Import/P0001,
  "properties": [
    {
      "languageCode": 1,
      "description": "Color",
      "value": "Red"
    },
    {
      "languageCode": 1,
      "description": "ABAX Serial Number”,
      "value": "SN-4521"
    }
  ]
}

The system responsed with status code of 200, the response body indicates where the request was successful or not:

true

The properties have been added or updated successfully. Let’s check the results in Onix Work: Navigate to the product we have just created in section 2 and open Properties tab. The properties have been added/ updated according to the request.

Integrating suggestions

Based on the prerequisite & API design, we suggest integrating the functionality to add or update properties for a product using the key productNo as illustrated in the UML diagram below.

4. Add or update a product’s forms

API overview


Endpoint	`POST /v1/company/products/forms`
Description	Add or update forms for a product
Usage	Call this API to add/ update forms for a product.
Return	Return type: boolean.

Prerequisite

Products were created. Refer to section 1. Create or update a product for further details.
It must retrieve forms through the endpoint: GET /v1/company/forms
It must retrieve job types through the endpoint: GET /v1/company/job-types

Request parameters and body

The corresponding request body type can be found at the Swagger UI, model ProductFormInfoDto for the main request body and FormInfoDto for the forms model.

Differences between add and update mode:

Add: If the forms are not yet included in the product but exist in the forms list in Onix Work, they will be added.
Update: If the forms were previously included in the product, their values will be updated based on the corresponding data in the request.

When a field value is null, it follows the rules explained in API requests and responses, if no specific rules are mentioned.

The corresponding request body type can be found at the Swagger UI, model ProductFormInfoDto.

Field	Data type	Required	Description & Constraints
`productId`	int	No*	The Onix Work system’s product ID. To add or update forms for a product, either the `productId`, `importId`, or `productNo` must be provided with the following priority: productID > importId > productNo
`importId`	string	No*	Constraint: length ≤ 50. Your system’s product ID. Typically used for adding or updating forms for a product.
`productNo`	string	No*	Constraint: length ≤ 250. Your system’s product number. Typically used for adding or updating forms for a product.
`forms[index].formId`	Int	Yes	The form ID. Get this value from API: `GET /v1/company/forms`
`forms`[index].languageCode	Int	No	The language of the form in the product. Available values: 0, 1, 3, 4, 6, 7, 9 where: 0: Norwegian 1: English 3: Swedish 4: Danish 6: Deutsch 7: Spanish 9: Portuguese
`forms[index].jobTypeId`	Int	No	The job type of the form in the product. Get this value from API: `GET v1/company/job-types`

Response

Status code	Response body	Description
200	A boolean.	Forms in the product have been added or updated successfully.
400	The system’s standard error response object.	See an examples of error responses in API requests and responses.

Examples

Let’s use one of the following keys: productId, importId, or productNo to add or update forms for a product.

importId: “ERP_Import/P0001”.
productNo: “ERP_Import/P0001”.
productId: 214011.

First, let’s examine the forms that the product has been using for better visualization:

Currently, the product only has a form Inspection report.
In the forms list, it has a form called Declaration of Conformity that you would like to add to the corresponding product.

To add/ update the product’s forms, make a request with the request body below, with languageCode is English (see OpenAPI terminology). In this example, we use the key productNo

{
  "productNo": ERP_Import/P0001,
  "forms": [
    {
      "formId": 1,   // Inspection report
      "languageCode": 1,  // English
      "jobTypeId":  2 // 
    },
    {
      "formId": 34,   // EKH certificate
      "languageCode": 1,  // English
      "jobTypeId":  1 // Initial control
    }
  ]
}

The system responsed with status code of 200, the response body indicates where the request was successful or not:

true

The forms have been added or updated successfully. Let’s check the results in Onix Work: Navigate to the product we have just created in section 2 and click on the tab Forms. The forms have been added or updated according to the request.

5. Update forms’ properties of a product

API overview


Endpoint	POST /v1/company/products/form-properties
Description	Update properties of forms in a product
Usage	Call this API to properties of forms in a product.
Return	Return type: boolean.

Prerequisite

Products have already been created. Refer to section 2. Create or update a product for further details.
Forms were added into the product. Refer to section 4. Add or update forms for a product for further details.
It must retrieve forms’ properties through the endpoint: GET /v1/company/form-properties

Request parameters and body

The corresponding request body type can be found at the Swagger UI, model ProductFormPropertiesInfoDto for the main request body and FormPropertyKeyValueInfo for the forms’ properties model.

When a field value is null, it follows the rules explained in API requests and responses, if no specific rules are mentioned.

The corresponding request body type can be found at the Swagger UI, model ProductFormPropertiesInfoDto.

Field	Data type	Required	Description & Constraints
`productId`	int	No*	The Onix Work system’s product ID. To update forms’ properties for a product, either the `productId`, `importId`, or `productNo` must be provided with the following priority: productID > importId > productNo
`importId`	string	No*	Constraint: length ≤ 50. Your system’s product ID. Typically used for adding or updating forms’ properties for a product.
`productNo`	string	No*	Constraint: length ≤ 250. Your system’s product number. Typically used for adding or updating forms’ properties for a product.
`properties[index].key`	string	Yes	Key of the form property. Get it through this endpoint: `GET /v1/company/form-properties`
`properties[index].value`	string	No	Value of the form property.

Response

Status code	Response body	Description
200	A boolean.	Forms’ properties of the product have been updated successfully.
400	The system’s standard error response object.	See an examples of error responses in API requests and responses.

Examples

Let’s use one of the following key: productId, importId, or productNo to update forms for a product.

importId: “ERP_Import/P0001”.
productNo: “ERP_Import/P0001”.
productId: 214011.

First, let’s examine the forms that the product has been using for better visualization. Currently, the product has a form Declaration of Conformity.

To update the forms’ properties in the product, make a request with the request body below. In this example, we use the key productNo

{
  "productNo": ERP_Import/P0001,
  "properties": [
    {
      "key": "ApiKey_ResponsibleTechnical",
      "value": "Thomas"
    },
    {
      "key": "ApiKey_TypeApprovalCertificateNo",
      "value": "4324"
    }
  ]
}

The system responsed with status code of 200, the response body indicates where the request was successful or not:

true

The forms’ properties have been updated successfully. Let’s check the results in Onix Work: Navigating to the product we have just created in section 2 and click on the tab Forms.
The forms’ properties in the product have been updated according to the request.

Integrating suggestions

Based on the prerequisite & API design, we suggest integrating the functionality to update forms’ properties in a product using the key productNo as illustrated in the UML diagram below.

Topic	Replies	Views
OpenAPI - Transfer orders (part 1/4) - Create an order or order line Knowledge base official , openapi	186	February 5, 2024
Product's fields are empty because of missing API endpoints In progress openapi	40	June 12, 2024
Job API extension In discussion openapi	25	September 10, 2024
OpenAPI - Transfer documents Knowledge base official , openapi	204	December 25, 2023
OpenAPI - Get started Knowledge base official , openapi	281	February 5, 2024

OpenAPI – Transfer products

1. Overview

2. Create order update a product

API overview

Prerequisite

Request parameters and body

Response

Examples

Integrating suggestions

3. Add or update properties for a product

API overview

Prerequisite

Request parameters and body

Response

Examples

Integrating suggestions

4. Add or update a product’s forms

API overview

Prerequisite

Request parameters and body

Response

Examples

5. Update forms’ properties of a product

API overview

Prerequisite

Request parameters and body

Response

Examples

Integrating suggestions

Related Topics