• View
• Edit
• History
• Print

Working with API history methods

• General principles
  • API-methods
  • General principles of working with API history methods
• History fields description
  • Source of change
  • Information on key, which made changes
  • Information on orders combining
  • Old and new values
    • String
    • Number
    • Boolean
    • Date and time

General principles

API-methods

This section describes features of working with the following API history methods:

• /api/v3/orders/packs/history
• /api/v4/orders/packs/history
• /api/v4/customers/history
• /api/v4/orders/history
• /api/v5/orders/packs/history
• /api/v5/customers/history
• /api/v5/orders/history

Note Pay attention that working with method /api/v3/orders/history is built on the other principles.

General principles of working with API history methods

API history change method is used for applying of changes made in system on the side of other information system. The following cases are the examples:

• Application of orders change on the web-store side for displaying in customer account
• Application of changes in order packing process on the side of warehouse system for automatic items reservation
• Synchronization of information on customers with loyality system

Algorithm of working with changes history is (on example /api/v4/orders/packs/history):

1. If API history method is called for the first time, then needs to refer method without additional parameters. If it is called not the first time, then add parameter sinceId with specification of id, saved from the last processing.
2. Read the chandes history and apply it.
3. View the contents of parameter pagination in response. If number of pages pagination.totalPageCount more than 1 (for example, 5), you should successively call the method with parameter page=N, processing the remaining pages from 2 to 5, reading changes and applying it.
4. Save id of the last history record for using it in subsequent history processing in parameter sinceId.

This algorithm should be set on periodic run once in 5-15 minutes.

History fields description

Source of change

Field source keeps code of change source. Possible values:

• api change made by API
• code change made automatically by system
• user change made by user
• rule change made by trigger action
• combine change made as a result of merger
• split change made as a result of split

In case if the field source has value equal to user, then in the history record will be field user. Field format user:

"user": {
    "id": 123, // Internal iser id
}

Information on key, which made changes

apiKey field keeps the object with information on key, under which the change was made. It presences only for changes made through api.

"apiKey": {
    "current": true, // Change was made under the currect key
}

Information on orders combining

combinedTo field contains information on order, into which the current order was combined. It presences only for /api/v4/orders/history and for orders, which were deleted when combining.

"combinedTo": {
    "id": 123, 
    "externalId": "ee-22-xx",
    "site": "mishki-online",
}

Information about copying and splitting orders

The ancestor field contains information about the order from which the copying or splitting was made.

"ancestor": {
    "id": 123, 
    "externalId": "ee-22-xx",
    "site": "mishki-online",
    "managerId": 6,
    "status": "availability-confirmed"
}

Old and new values

Old and new values are accordingly in fields oldValue and newValue. One of these field may be absent if the value of changed field was absent or removed while changing. Format of field value oldValue and newValue depends on type of field field, for which a change in the history was recorded. You may see below possible field types and value format in history for them.

String

Examples of string type fields: street street, phone phone, comment to status statusComment.

{
    ...
    "field": "statusComment",
    "newValue": "Items arrival is expected tomorrow",
    ...
}

Number

These include fields containing either integer or fractional number. Examples: item price price, order discount discount, items quantity quantity.

{
    ...
    "field": "discount",
    "oldValue": 250.50,
    "newValue": 260,
    ...
}

Boolean

These include fields containing values true/false. Examples: shipment of items shipped, order shipment shipped, order expired expired.

{
    ...
    "field": "expired",
    "oldValue": false,
    "newValue": true,
    ...
}

Date and time

Examples: delivery date deliveryDate, shipment date shipmentDate.

{
    ...
    "field": "deliveryDate",
    "newValue": "2015-03-25 12:15:00", // in format yyyy-MM-dd HH:MM:SS
    ...
}

Directory-object

These include objects from the following reference books:

• Order status status
• Order type orderType
• Order method orderMethod
• Delivery type deliveryType
• Delivery service deliveryService
• Payment type paymentType
• Payment status paymentStatus
• Store site
• Customer segment segments
• Item status status
• Warehouse store

For fields type Directory-object in oldValue/newValue will be returned structure with symbolic code of object inside code.

{
    ...
    "field": "status",
    "oldValue": {
        "code": "new"
    },
    "newValue": {
        "code": "completed"
    },
    ...
}

For reference book Item status may be additionally specified parameter cancel: true, in case if the cancellation status was set:

{
    ...
    "field": "status",
    "oldValue": {
        "code": "new"
    },
    "newValue": {
        "code": "out-of-stock",
        "cancel": true
    },
    ...
}