retailCRM Documentation

Working with API history methods

General principles

API-methods

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

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:

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:

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

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:

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
    },
    ...
}

PrintEditHistory
Page last modified on October 20, 2017, at 11:08 AM