How to use Open API

In the Summer 2 Release 2023, the Open API platform welcomes two new API collections: Transfer Orders and Transfer Products, which help with:

  • Data integrity: Ensuring data accuracy to prevent unexpected errors.
  • Input format and validation: Mitigating unnecessary formatting requirements.
  • Complex transactions: Reducing excessive records, such as Transfer Orders, that can lead to unexpected issues and bad data.

In this guide, you can learn how to navigate and use these APIs to effectively manage orders, associated order lines and products within the Onix system.

1. ACCESSING THE APIs

  • Open the Swagger API Documentation.
  • For Transfer Orders: Locate the Orders and OrderLines sections for the available API endpoints.

  • For Transfer Products: Locate the Company section for use.

2. AUTHENTICATION AND AUTHORIZATION

Same with Old API platform, you need to ensure to have the necessary authentication credentials to access the APIs. To get the credential:

  • Navigate to Onix Work’s Settings module → External data-sources → API configuration → API token.
  • Copy the credential.

  • Use the copied credential for authentication in Open API page or any other places.

3. USING PRODUCTS API

  • Using this API, you can create or update products in Onix Worker faster.
    • For more details, please refer to the Schema and description of the API.

4. USING ORDERS API

  • Get/ v1/company/order-statuses: Retrieve the list of order statuses in Onix Work.
    • For more information, please refer to the description of Onix Open API.

  • Get/ v1/company/order-line-statuses: Retrieve the list of order line statuses in Onix Work.
    • For more information, please refer to the description of Onix Open API.

  • POST/ v1/orders: To Create or Update Order by sending the required payload. Please ensure you provide accurate orderID or importID which will be an input for other POST endpoints (create/update orderlines, orderline’s items, orderline’s form properties).

  • In case you would like to understand clearly the meaning of each field and how to use it, please use Schema as an official reference.

5. USING ORDERLINES APIs

4 new APIs have been created to offer higher flexibility and control in creating Orderlines and other following items, properties or form-properties.

  • POST/v1/ order-lines: Create or Update order line by sending the required payload.
    • Use the following mapping to create Orderline under your created Order correctly.

Order Orderlines Note
orderId orderImportId
importId orderImportId
  • POST/v1/ order-lines/items: Create or Update list of items of Orderlines.
    • Use the following mapping to create Orderlines items.

Order Orderlines Orderline items/properties/form-properties Note
orderId orderId Higher priority than " orderImportId”
importId orderImportId
orderLineImportId orderLineId
orderLineImportId orderLineImportId
  • POST/v1/ order-lines/properties: Update properties of Orderlines.
    • The mapping is the same with POST/v1/ order-lines/items.

  • POST/v1/ order-lines/form-properties: Update order line’s form properties.

  • To help you input the value of “key” and “value” correctly, we also created GET/v1/company/form-properties to retrieve the key of each form property.

6. USING DOCUMENTS API

In the Winter 2024, the Open API platform welcomes one new API collections: Transfer Documents, which helps you effectively manage documents associated with jobs or equipment within Onix system.

6.1. Accessing the APIs

  • Open Swagger API documentation.

  • For “Transfers Documents”: Locate the Jobs and Equipment for the available API endpoints

  • To check the necessary information for Job types and forms: Locate the Common and Company for the available API endpoints



6.2. Using Transfer Documents endpoint

  • GET/v1/company/job-types: Return list of job type supported in Onix Work. For more information, please refer to the description of Onix Open API.

  • GET/v1/company/forms: Return the list of forms which is enabled by your company in Onix Work. For more information, please refer to the description of Onix Open API.

  • POST/v1/jobs: Import job for equipment

    • To create or update a job by sending the required payload. Please ensure that you provide accurate mandatory information*: jobType, jobForm, filed, equipment.*
    • Some of the information needs to be get from get endpoints
      • locationID – Get/v1/company/{companyOwner}/locations
      • jobType – Get/v1/company/job-types
      • jobForm – Get/v1/company/forms

For more information about each field’s meaning and use guide, please use Schema as an official reference.


  • POST/v1/jobs/{jobId}/documents: Import document for job

    • To create (upload) a document for job by sending the required payload. Please ensure that you provide accurate mandatory information: description, documentType, contentType, data.
    • The data is base64 string format; therefore please convert your documents into this format for using this endpoint.
    • For more information about each field’s meaning and use guide, please use Schema as an official reference.
  • POST/v1/equipment/{equipment-id}/documents: Import documents to equipment

    • To create (upload) a document for equipment by sending the required payload, please ensure that you accurately provide the following mandatory information: description, documentType, contentType, data.
    • The data is base64 string format; therefore please convert your documents into this format for using this endpoint.
    • For more information about each field’s meaning and use guide, please use Schema as an official reference.