OpenAPI - Get started

khoa.nguyen · February 5, 2024, 7:35am

1. Overview

Onix Work OpenAPI has a Swagger interface, which offers developers a quick view of all available APIs. Developers can use Swagger interface to test, and we recommend developers to test on the Sandbox environment.

Production environment:

Onix Work URL: https://prod.onix.com/
OpenAPI URL: https://openapi.onix.com/
Swagger URL: Swagger UI

Sandbox environment:

Onix Work URL: https://sandbox.onix.com/
OpenAPI URL: https://openapi-sandbox.onix.com/
Swagger URL: Swagger UI

Data exchange format: JSON.

Secured by: Token (see Authentication).

2. API requests and responses

Requests

Onix Work OpenAPI APIs use JSON format to communicate. All available public APIs can be found on our Swagger page.

Action	Field value	Comment
Create	`null`	The endpoint notes section specifies the behavior of null value for that field. Otherwise, the Onix Work system will use default value for that field.
Update	`null`	The endpoint notes section specifies the behavior of null value for that field. Otherwise, the Onix Work system will ignore that field, so the underlying data remains unchanged.
Update	`""` (empty string)	Use to clear string-field data if the minimum length constraint can be equal to 0.

Success responses

Always have HTTP status of 200 OK, and the body contains JSON-formatted data. Some common response types in JSON format:

An integer.
A boolean.
A single string.
Key-value pair list – key and value types are both string type.

Note: Parsing may be needed when using them in different types for specific endpoints.

Error responses

Status code	Description
`400`	Bad request. Please check your request’s parameters and body. See examples of bad request’s response below this table.
`401`	Unauthorized request. Please check if you are: • Missing a token. • Missing or using incorrect scheme: Bearer for short-lived token, Key for long-lived token.
`500`	System errors. If you encounter any issues or have questions, contact Onix Support for assistance.

An example of standard bad requests response:

Validation error response: Request field contains incorrect format or invalid values.

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-301ec3c5a9ce095960f403c21865b69d-7a1a2d1c823e7f70-00",
  "errors": {
    "source": [
      "Source is invalid"
    ],
    "erpOrderDate": [
      "ErpOrderDate wrong format"
    ]
  }
}

Logic/state error response:

[
  {
    "memberNames": [
      "workflowStatusId"
    ],
    "errorMessage": "Invalid Workflow Status Id"
  }
]

3. Authentication

Onix Work OpenAPI uses token-based authentication. There are two types: short-lived tokens and long-lived tokens.

Short-lived tokens use Bearer scheme. Their expiration time is set to 60 minutes.
Long-lived tokens use Key scheme. They don’t have an expiration time and won’t change overtime.

To use the token in Swagger:

Click Authorize button to open the dialog.
Input your token including the authorization scheme.
Click Authorize again to finish. You are now ready to use Onix Work APIs.

Acquire and use short-lived tokens

To acquire a short-lived token, make a POST request to the following endpoint:

POST /v1/Account/token

with the following request body:

{
  "username": "your_email",
  "password": "your_password"
}

Where:

username: your Onix Work’s account email address.
password: your Onix Work’s account password.

Response:

Status code	Response body	Comment
`200`	A single JSON string.	A token in JSON string format, and it will expire in 60 minutes.
`400`	Error response object with title “Bad request” and status 400.	Incorrect user credentials or incorrect request body object.

To use short-lived token, add the HTTP Authorization header with Bearer scheme:

Authorization: Bearer <token>

Example: Make request to POST /v1/Account/token with body:

{
  "username": "your_email",
  "password": "your_password"
}

If the account exists, the response status will be 200, and the response body should look like this:

"eyJhbGciOiJSUzI1NiIsImtpZCI6Ijg5QzVCMDYwM0U0MjkxRDhEQkFDOUFGNUI3MzFGNDVBIiwidHlwIjoiYXQrand0In0.eyJuYmYiO*(...snipped)*"

If the credentials are incorrect, the response status will be 400, and the response body will look like:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "traceId": "00-44498d7f86769d75ed0ae336b6424d14-107b755ce0b78d35-00"
}

Otherwise, contact your organization administrator or contact Support for further assistance.

After acquiring the security token successfully, attach the token in the authorization header for every request, using Bearer scheme. Replace <your_token_here> with your acquired token:

Authorization: Bearer <your_token_here>

Acquire and use the long-lived token

To acquire the long-lived token, first, open the Onix Work URL on the browser and log in with your credentials. Then:

Go to Settings → Navigate to External Data-Sources.
Click on API Configuration → Click “Copy token” to copy the long-lived token.

After acquiring the security token successfully, attach the token in the authorization header for every request using Key scheme. Replace <your_token_here> with your acquired token:

Authorization: Key <your_token_here>

The Key scheme can be omitted.

4. API best practices

We recommend these practices:

Refresh short-lived tokens: Periodically refresh short-lived tokens to ensure continuous access.
Safeguard your tokens: Treat tokens as sensitive information and store them securely.

Important: The long-lived token is specific to your company and stays the same, ensuring ongoing stability. Please prioritize the security of this special token.

5. Terminology

The Onix Work OpenAPI or OpenAPI — the modern version of the API designed for interacting with Onix Work efficiently.
The Onix Work Web API or Web API — the earlier version of the API for interacting with Onix Work. Deprecated.
Production environment — the main environment, and it contains your company’s data. Data here is stored permanently.
Sandbox environment — the playground environment, we recommend developers to test on this environment. Please be advised that the data within the sandbox environment is temporary and undergoes periodic restoration from the production environment in accordance with Onix Work’s scheduled processes.
The Onix Work system or the system — represents the Onix Work OpenAPI or Onix Work in general.
Your system — represents you or your software using Onix Work OpenAPI.
Onix Work — represent the Onix Work platform, typically Onix Work website via Onix Work URL (see Overview).
Order — a container that holds multiple order lines. The objective is to create multiple equipment units once the order is delivered (processed).
Order line — contains information to create equipment which has the same product type, properties, …

Language codes — integer numbers represent languages used in Onix Work system. This is useful if you are developing multilingual software. When an endpoint has languageCode as an optional query parameter/field, the Onix Work system will use English as the default language. Supported languages with language codes:
- Norwegian – 0.
- English – 1.
- Swedish – 3.
- Danish – 4.
- Spanish – 7.

Company links — your company’s custom definition list to map between your system’s internal IDs (external IDs in Onix Work) for your customer companies and the Onix Work company IDs. There are two types of links: supplier and customer. When specifying IDs in the request body, make sure that the provided external ID exists in the company links with the correct link type.
To manage company links, open Onix Work on a browser, then navigate to: Settings module > External linking > Company links tab.
Contact links — same as company links, but for contacts.
To manage contact links, open Onix Work on a browser, then navigate to:
Settings module> External linking > Contact links tab.
External ID — a term used by Onix Work typically referring to your system’s internal ID.
Workflow — a workflow is a customized set of steps defined by your company to track specific progress. Currently, there are two types of workflows: order and order line. You can manage the workflows of your company by navigating to the Onix Work using the Onix Work URL (see section 1. Overview), then: Settings module> Workflow > Order/Order line tab.
Orders module — one of the main modules in Onix Work, the main purpose is to create and manage orders and order lines.
Settings module — one of the main modules in Onix Work, it helps users control different types of preferences for their company.
Your company — current user logged in the company via tokens.
Customer company (in order endpoints) — refer to your system’s customer company.
Unique equipment — a class of equipment that is not non-unique (see below), countable, distinctive, and reusable. Borrowed equipment must be returned to the warehouse.
Non-unique equipment — a class of equipment that is either consumable goods, stock goods or part.
Consumable goods — uncountable items, such as liquids or gases, that cannot be returned to the warehouse. Consumable goods doesn’t have a serial number or a batch number.
Stock goods — countable items, often small and trivial, such as nails and screws, and are usually not intended to return to the warehouse. Stock goods doesn’t have a serial number or a batch number.
Part — countable items, often components that can combine with other parts to create a complete product.
Main equipment — it is formed by combining multiple sub equipment.
Sub equipment — component equipment, that can combine with other sub equipment (in main equipment) to create complete equipment (main equipment).
Process (an order line property) — corresponds to the Process field on an order line on Onix Work. It defines the action when processing the order or the order line on Onix Work. Supported values are:
- No action – 1
- Create equipment – 2.
- Create equipment and job – 3.
- Create equipment and file job – 4.

6. Linked articles

The order APIs

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.

Other APIs

If you encounter any issues or have questions, kindly describe your concern and:

Send an email to support@onix.com; OR

Create a topic in Q&A to receive assistance from all Community members.

Topic		Replies	Views
OpenAPI - Transfer documents Knowledge base official , openapi	0	210	December 25, 2023
Retire Old Web API and introduce the new Open API platform Retired official , openapi	1	119	September 27, 2024
OpenAPI – Transfer products Knowledge base official , openapi	0	11	September 27, 2024
OpenAPI - Transfer orders (part 3/4) - Migrate from Web API to OpenAPI Knowledge base official , openapi	0	173	February 5, 2024
Job API extension In progress openapi	1	37	November 21, 2024