OpenAPI - Transfer orders (part 3/4) - Migrate from Web API to OpenAPI

khoa.nguyen · February 5, 2024, 2:30pm

This article is part of a series - click to read part 1, part 2 and part 4.

Overview

The Web API (deprecated) is soon to be retired. We strongly recommend organizations to migrate their usage to our the Onix Work OpenAPI today.

Onix Work OpenAPI provides flexible APIs for interacting with the Onix Work system. This results in simpler requests, faster response times, improved security, and better support.

Here’s the guide for developers on migrating from the Web API for transfering or creating orders.

Reference links for Web API documentation on transfering orders:

Production: https://onixwork.com/api/Doc/#/order/transferOrder
Sandbox: https://onixwork.com/api-sandbox/Doc/#/order/transferOrder

Model mapping

The Web API’s ERPOrder contains all the information to create an order, order lines, number order lines and update all their properties.

Model mapping notes:

ERPOrder (Web API) model is similar to OrderInfo (OpenAPI) model, except OrderInfo (OpenAPI) does not contain order lines information: Orderlines field (ERPOrderline type).
ERPOrderline (Web API) model is similar to OrderLineInfo (OpenAPI) model, except OrderInfo (OpenAPI) has type field and does not contain:
- SerialNumber: default serial number for the current order line.
- BatchNo: default batch number for the current order line.
- ERPSerials: information to number the current order line.
- ERPFields: information for the Web API system can update respective fields, usually properties and form properties, but those fields must be predefined and very limited.
ERPSerials (Web API) is similar to OrderLineItemSerialInfo (OpenAPI) used in items field in OrderLineItemsInfo model. This is used for numbering the current order line.
ERPFields (Web API) is used for predefined fields. OpenAPI does not support this field. Use endpoint update properties and form properties in part 2 instead.
If you have trouble migrating this field, please Contact Support.

Mapping table for ERPOrder (Web API) into OrderInfo (OpenAPI) model:

Web API Field	OpenAPI Field	Comment
`ERPOrderID`	`erpOrderId`	Identical values.
`ERPOrderDate`	`erpOrderDate`	A significant difference in date format: Web API date format: `yyyy.MM.dd`, e.g.: 2024.01.31 OpenAPI date format: `yyyy-MM-dd`, e.g.: 2024-01-31
`ERPCustomerOrderNo`	`erpCustomerOrderNo`	Identical values.
`WorkflowStatusId`	`workflowStatusId`	Identical values.
`ERPCustomerId`	`erpCustomerId`	Identical values.
`ERPCustomerDescription`	`erpCustomerDescription`	Identical values.
`ERPCustomerAddress`	`erpCustomerAddress`	Identical values.
`ERPCustomerPostalCode`	`erpCustomerPostalCode`	Identical values.
`ERPCustomerWeb`	`erpCustomerWeb`	Identical values.
`ERPCustomerOrgNumber`	`erpCustomerOrgNumber`	Identical values.
`ERPCustomerCountryCode`	`erpCustomerCountryCode`	Identical values.
`ERPCustomerContactId`	`erpCustomerContactId`	Identical values.
`ERPCustomerContactName`	`erpCustomerContactName`	Identical values.
`ERPSupplierId`	`erpSupplierId`	Identical values.
`ERPSupplierDescription`	`erpSupplierDescription`	Identical values.
`ERPSupplierContactId`	`erpSupplierContactId`	Identical values.
`ERPSupplierContactName`	`erpSupplierContactName`	Identical values.
`Source`	`source`	Identical values. OpenAPI support additional value: 3 — Manually.
`Orderlines`	`-`	See the mapping table for `ERPOrderline` below.

Mapping table for ERPOrderline (Web API) model into OrderLineInfo (OpenAPI).
Note: OpenAPI supports additional field type when creating/updating order lines.
Continuing from the field Orderlines in above table:

Web API Field	OpenAPI Field	Comment
`ERPArticleNo`	`erpArticleNo`	Identical values.
`Quantity`	`quantity`	Identical values.
`ExternalLineNo`	`externalLineNo`	Identical values.
`WorkflowStatusId`	`workflowStatusId`	Identical values.
`ERPParent`	`parentOrderLineImportId`	Identical values.
`ERPInternalId`	`orderLineImportId`	Identical values.
`BatchNo`	`N/A`	OpenAPI does not support this field when creating/updating an order line. This field in Web API is used as the default value in numbering items in an order line. Use numbering requests instead.
`SerialNumber`	`N/A`	OpenAPI does not support this field when creating/updating an order line. This field in Web API is used as the default value in numbering items in an order line. Use numbering requests instead.
`CertificateString`	`certificateString`	Identical values.
`TypeInfo`	`model`	Identical values.
`ERPTypeInfo`	`erpModel`	Identical values.
`WLL`	`wll`	Identical values.
`Comment`	`comment`	Identical values.
`JobComment`	`jobComment`	Identical values.
`ERPSerials`	`-`	See the mapping table for `ERPSerials` below.
`ERPFields`	`-`	OpenAPI does not support this field. See the information for `ERPFields` below.

The ERPFields (Web API) is used to update order line form properties with a fixed set of keys, but its support is limited and and there is no equivalent model in OpenAPI.

OpenAPI provides PropertyInfo and FormPropertyKeyValueInfo[] for updating respective properties and form properties in place of ERPFields (Web API) in a more intuitive way.

We strongly suggest switching to OpenAPI for a more flexible and powerful way to update properties and form properties using two endpoints:

POST /v1/order-lines/properties to update the order line’s properties.
POST /v1/order-lines/form-properties to update the order line’s form properties.

Examples

Here’s an example that shows how to create an order using the Web API, combining information from different sections:

{
  "ERPOrderID": "ERP_Order/0001",
  "ERPCustomerOrderNo": "ERP_CustomerOrder/0001",
  "ERPCustomerId": "ERP_Customer/0382",
  "Orderlines": [
    {
      "ERPArticleNo": "ERP_Product/0001",
      "Quantity": 5,
      "ERPInternalId": "ERP_OrderLine/0001",
      "TypeInfo": "OL1: ERP model",
      "ERPTypeInfo": "OL1: ERP erpModel",
      "WLL": "OL1: WLL",
      "Comment": "OL1: My Comment",
      "JobComment": "OL1: My job comment",
      "ERPSerials": [
        {
          "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"
        }
      ],
      "ERPFields": [
        {
          "Field": "FE_AntallProvetS",
          "Value": "field value"
        }
      ]
    }
  ]
}

Note that OpenAPI does not supportERPFields field.
The above request is combined from all examples in all other sections. It can split into 5 requests (steps) in OpenAPI:

Create the order using the endpoint POST /v1/orders. Notice that the importId field is required in.

{
  "importId": "ERP_Import/0001",
  "erpOrderId": "ERP_Order/0001",
  "erpCustomerOrderNo": "ERP_CustomerOrder/0001",
  "erpCustomerId": "ERP_Customer/0382"
}

Create order lines by making a request for each order line using the endpoint:
POST /v1/order-lines

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

Numbering order lines by making a request for each order line using the endpoint:
POST /v1/order-lines/items

{
  "orderImportId": "ERP_Import/0001",
  "orderLineImportId": "ERP_OrderLine/0001",
  "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"
    }
  ]
}

Update properties for order lines by making a request for each order line using the endpoint:
POST /v1/order-lines/properties

{
  "orderImportId": "ERP_Import/0001",
  "orderLineImportId": "ERP_OrderLine/0001",
  "properties": [
    {
      "key": "ApiKey_Proofload",
      "value": "Test value"
    },
    {
      "key": "ApiKey_DateOfTest",
      "value": "2024.31.01"
    }
  ]
}

Update form properties for order lines by making a request for each order line using the endpoint:
POST /v1/order-lines/form-properties

{
  "orderImportId": "ERP_Import/0001",
  "orderLineImportId": "ERP_OrderLine/0001",
  "properties": [
    {
      "key": "ApiKey_Proofload",
      "value": "Test value"
    },
    {
      "key": "ApiKey_DateOfTest",
      "value": "2024.31.01"
    }
  ]
}

And that concludes the process – you’ve successfully created an entire order.

Topic		Replies	Views
OpenAPI - Transfer orders (part 1/4) - Create an order or order line Knowledge base official , openapi	0	193	February 5, 2024
OpenAPI - Transfer orders (part 2/4) - Update order line's properties and form properties Knowledge base official , openapi	0	143	February 5, 2024
Version 1.9.1.0 - Release date: 15.03.2024 OpenAPI changelogs official , openapi	0	86	March 13, 2024
Version 1.10.2.0 - Release date: 05.07.2024 OpenAPI changelogs official , openapi	0	12	July 5, 2024
Retire Old Web API and introduce the new Open API platform Retired official , openapi	1	119	September 27, 2024

OpenAPI - Transfer orders (part 3/4) - Migrate from Web API to OpenAPI

Overview

Model mapping

Examples

Related articles

Related topics