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

Скопировать ссылку на статью

Скопировано

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

API-методы

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

/api/v5/customers/history

/api/v5/customers-corporate/history

/api/v5/orders/history

/api/v5/orders/packs/history

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

Важно!

С 15.05.23г. в API-методах истории при совместном указании параметров filter[sinceId] и page будет выдаваться ошибка HTTP 400. При последовательном обходе истории следует сдвигать ID в параметре filter[sinceId] вместо использования пагинации через параметр page. Ответ от бекенда в этом случае отдается на порядок быстрее, чем при использовании пагинации, при этом результат будет идентичен.

Подробнее про работу с API-методами истории читайте ниже.

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

• Применение изменений заказов на стороне интернет-магазина для отображения в личном кабинете клиента
• Применение изменений комплектации товаров заказа на стороне складской системы для автоматического резервирования товаров под заказы
• Синхронизация информации о клиентах с системой лояльности

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

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

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

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

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

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

api изменение внесено через API

code изменение внесено автоматически системой

user изменение внесено пользователем

rule изменение внесено в рамках работы триггера

combine изменение внесено при объединении

split изменение внесено при разделении

copy изменение внесено при копировании

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

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

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

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

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

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

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

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

Информация о копировании и разделении заказов

Поле ancestor содержит информацию о заказе из которого было сделано копирование или разделение.

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

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

Старое и новое значение изменения содержатся соответственно в полях 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
    ...
}

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

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

'Статус заказа' status

'Тип заказа' orderType

'Способ оформления заказа' orderMethod

'Тип доставки' deliveryType

'Служба доставки' deliveryService

'Тип оплаты' paymentType

'Статус оплаты' paymentStatus

'Магазин' site

'Сегмент клиента' segments

'Статус товара' status

'Склад' store

Для полей типа Объект-справочник в 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
    },
    ...
}