retailCRM Документация

Работа с API-методами истории

Общие принципы

API-методы

В данном разделе описаны особенности работы со следующими API-методами истории:

Примечание Обращаем внимание, что работа с методом /api/v3/orders/history строится по другим принципам.

Общие принципы работы с API-методами истории

API-методы истории изменений предназначены для применения изменений, совершенных в системе, на стороне другой информационной системы. Примером могут служить следующие кейсы:

Алгоритм работы с историей изменений следующий (на примере /api/v4/orders/packs/history):

  1. Если API-метод истории вызываем в первый раз, то производим обращение к методу без дополнительных параметров. Если вызываем не в первый, то добавляем параметр sinceId с указанием id, сохраненного во время прошлой обработки.
  2. Производим считывание истории изменений и применяем их.
  3. Смотрим содержимое параметра pagination в ответе, если количество страниц pagination.totalPageCount больше 1 (например, 5), то последовательно вызываем метод с параметром page=N, обходя оставшиеся страницы со 2 по 5, считывая изменения и применяя их.
  4. Сохраняем id последней записи истории, чтобы использовать его при последующей обработке истории в параметре sinceId.

Данный алгоритм настраиваем на периодический запуск в 5-15 минут.

Описание полей истории

Источник изменения

Поле source хранит код источника изменения. Возможные значения:

В случае, если поле source имеет значение равное user, то в записи истории выводится поле user. Формат поля user:

"user": {
    "id": 123, // Внутренний идентификатор пользователя
}

Информация о ключе под которым было совершено изменение

Поле apiKey хранит объект с информацией о ключе под которым было совершено изменение. Оно присутствует только для изменение совершенных через api.

"apiKey": {
    "current": true, // Изменение совершено под текущим ключём
}

Информация об объединении заказов

Поле combinedTo содержит информацию о заказе в который был объединен текущий заказ. Оно присутствует только для /api/v4/orders/history и для заказов которые удалены при объединении заказов.

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

Старое и новое значения

Старое и новое значение изменения содержатся соответственно в полях oldValue и newValue. Одно из двух полей может отсутствовать если значение изменяемого поля отсутствовало или было удалено при изменении. Формат значений полей oldValue и newValue зависит от типа поля field, для которого зафиксировано изменение в истории. Ниже приведены возможные типы полей и формат значений в истории для них.

Строка

Примеры полей типа строка: улица street, телефон phone, комментарий к статусу statusComment.

{
    ...
    "field": "statusComment",
    "newValue": "Поступление товара ожидается завтра",
    ...
}

Число

Сюда относятся поля, хранящие как целое число, так и с плавающей точкой. Примеры полей: цена товара price, скидка на заказ discount, количество товара quantity.

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

Логическое значение

Сюда относятся поля, хранящие значения true/false. Примеры полей: отгрузка упаковки товара shipped, отгрузка заказа shipped, заказ просрочен expired.

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

Дата и время

Примеры таких полей: дата доставки deliveryDate, дата отгрузки shipmentDate.

{
    ...
    "field": "deliveryDate",
    "newValue": "2015-03-25 12:15:00", // в формате yyyy-MM-dd HH:MM:SS
    ...
}

Объект-справочник

Сюда относятся объекты из следующих справочников:

Для полей типа Объект-справочник в oldValue/newValue возвращается структура, внутри которой передается символьный код объекта code.

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

Для справочника Статус товара может дополнительно указываться параметр cancel: true, в случае, если был выставлен статус отмены:

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

Редакция от 17.07.2017 19:08