OpenAPI - Get started

Knowledge base
,
1

Overview

Onix Work OpenAPI has a Swagger interface, this allows developers to 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:

Sandbox environment:

Data exchange format: JSON.

Secured by: Token (see Authentication).

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, refer to our support channels for assistance (see Support).

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"
  }
]

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 and their expiration time set to 60 minutes (see Acquiring and using short-lived tokens).

Long-lived tokens use Key scheme, and they don’t have an expiration time and won’t change overtime (see Acquiring and using the long-lived token).

To use the token in Swagger:

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

Acquiring and using short-lived tokens

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

POST /v1/Account/token

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

Using 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 is existed, the response status will be 200, and the response body should look like:

"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 Onix for further assistance (see Support).

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>

Acquiring and using the long-lived token

To acquire the long-lived token, first, open the Onix Work URL (see Overview) 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.

API best practices

We recommend these practices:

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

  • Refresh short-lived tokens: Periodically refresh short-lived tokens to ensure continuous access.

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 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 type 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 type of equipment that is either consumable goods or stock goods. Non-unique equipment doesn’t have a serial number or a batch number.

Consumable goods — uncountable items, such as liquids or gases, that cannot be returned to the warehouse.

Stock goods — countable items, often small and trivial, such as nails and screws, and are usually not intended to return to the warehouse.

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.

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.

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.