Working with API methods of history

Copy the link to the article

Copied

General principles

API methods

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

/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

Please note that working with the /api/v3/orders/history method is based on different principles.

General principles of working with API methods of history

API methods of history of changes are designed to apply changes made in the system on the side of another information system. An example is the following cases:

Applying changes to orders on the side of the online store for displaying in the customer's personal account

Applying changes to assembling order products on the side of the warehouse system to automatically reserve products for orders

Synchronisation of customer information with the loyalty system

The algorithm for working with the history of changes is as follows (on the example of /api/v4/orders/packs/history):

• If we call the API method of history for the first time, then we call the method without additional parameters. If we call it not in the first one, then add the parameter sinceId and specify id saved during the last processing.

• We read the history of changes and apply them.

• Look at the contents of the pagination parameter in the response, if the number of pages pagination.totalPageCount is greater than 1 (for example, 5), then sequentially call the method with the page=N parameter, bypassing the remaining pages from 2 to 5, reading the changes and applying them.

• Save the id of the last record of the history to use it in the subsequent processing of the history in the sinceId parameter.

We configure this algorithm to run periodically in 5-15 minutes.

Description of history fields

Source of change

The source field stores the code of the source of change. Possible values:

api change made via API

code changed automatically by the system

user modified by user

rule changed as part of a trigger execution

combine change made when combining

split change made when splitting

If the source field has a value equal to user, then the user field is displayed in the history record. Format of the field user:

"user": {
 "id": 123, // Internal identifier of the user
}

Information about the key under which the change was madej

The apiKey field stores an object with information about the key under which the change was made. It is only present for changes made by api.

"apiKey": {
 "current": true, // The change was made under the current key
}

Information about combining orders

The combinedTo field contains information about the order into which the current order was combined. It is only present for /api/v4/orders/history and for orders that are deleted when combining orders.

"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 copy or split was made.

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

Old and new values ​​

The old and new values of the change ​​are contained in the oldValue and newValue fields respectively. One of the two fields may be missing if the value of the field that is being changed was missing or was deleted when changing. The format of the values ​​of the fields oldValue and newValue depends on the type of field field, for which the change in history is recorded. Below are the possible types of fields and the format of the values ​​in history for them.

String

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

{
 ...
 "field": "statusComment",
 "newValue": "The product is expected to arrive tomorrow",
 ...
}

Number

This includes fields that store both integer and floating point. Examples of fields: product price price, order discount discount, product quantity quantity.

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

Boolean value

This includes fields storing the values ​​true/false. Examples of fields: shipment of product package shipped, shipment of order shipped, order is expired expired.

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

Date and time

Examples of such fields are delivery date deliveryDate, shipment date shipmentDate.

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

Object-data book

This includes objects from the following data 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

'Product status' status

'Warehouse' store

For fields of the type Object-databook in oldValue / newValue, a structure is returned, within which the symbolic code of the object code is transferred.

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

For the 'Product status' data book, the cancel: true parameter may additionally be specified, if the cancellation status was set:

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