Mindbox
Сегментации

Массовый импорт статических сегментаций продуктов

Описание метода

Метод Retail.StaticProductSegments.Import позволяет массово добавлять и удалять продукты в статических сегментах через загрузку CSV-файла.

Метод используется, когда нужно:

  • наполнить статический сегмент большим количеством продуктов;
  • удалить продукты из сегмента (и, как следствие, из сегментации);
  • обновить состав нескольких сегментов одной сегментации за один вызов.

Ограничения

  • Не более 60 импортов в час на проект.
  • Максимальный размер файла — 200 МБ.

URL и параметры запроса

Подробнее о работе с V3 API, URL запросов и заголовках: Документация V3 API.

JSONCode
POST <https://api.mindbox.ru/v3/operations/bulk?endpointId=>{Идентификатор точки интеграции}&operation=Retail.StaticProductSegments.Import&csvCodePage=65001&transactionId={Уникальный идентификатор запроса GUID}

Доменapi.mindbox.ru зависит от домена API вашего проекта. Как определить домен — см. Домен API Mindbox.

Дополнительные параметры запроса

  • csvCodePage — идентификатор кодовой страницы Windows для CSV-файла. Предпочтительно использовать 65001 (UTF-8).
  • csvColumnDelimiter — символ, использующийся для разделения колонок в CSV-файле.
  • csvTextQualifier — символ, опционально добавляющийся в начале и в конце значения колонки, позволяя использовать в нем символы, обычно не разрешенные.
  • transactionId — ключ идемпотентности в формате GUID (рекомендуется версия 4), позволяющий избежать повторного выполнения запроса. Для повторных запросов c повторяющимся ключом в ответ вернется статус TransactionAlreadyProcessed.

Заголовки запроса

ЗаголовокЗначение
AuthorizationSecretKey {секретный_ключ_точки_интеграции}
Content-Typetext/csv; charset=utf-8
Acceptapplication/json

Тело запроса

Тело запроса — CSV-файл в кодировке UTF-8 без BOM, разделитель столбцов — ;.

Поля файла

При вызове необходимо передать одно поле идентификации продукта (Product{системное_имя_внешней_системы} или ProductGroup{системное_имя_внешней_системы}) и внешний идентификатор сегментации.

Системное имя внешней системы можно посмотреть в разделе Настройки → Продукты и заказы → Внешние системы.

ПолеОбязательноеОписание
Product{системное_имя_внешней_системы}ДаВнешний идентификатор продукта в указанной внешней системе. Системное имя внешней системы
ProductGroup{системное_имя_внешней_системы}НетВнешний идентификатор группы продуктов в указанной внешней системе
SegmentationExternalIdДаВнешний идентификатор сегментации, в которой обновляется состав сегментов
SegmentExternalIdНетВнешний идентификатор сегмента, в который добавляется продукт. Если поле пустое — продукт удаляется из сегмента

Важно

Данные по одному продукту в рамках одной сегментации должны быть переданы одной записью. Дублирование строк с одинаковой парой Product + SegmentationExternalId приводит к непредсказуемому поведению.

Пример запроса

Code
POST https://api.mindbox.ru/v3/operations/bulk?endpointId=>demo.Website&operation=Retail.StaticProductSegments.Import&csvCodePage=65001&transactionId={уникальный идентификатор запроса GUID}

Content-Type: text/csv;charset=utf-8
Accept: application/json
Authorization: SecretKey {секретный_ключ_точки_интеграции}

Product1C;SegmentationExternalId;SegmentExternalId
1001;loyalty;gold
1002;loyalty;silver
1003;loyalty;

В примере:

  • продукт 1001 добавляется в сегмент gold сегментации loyalty;
  • продукт 1002 добавляется в сегмент silver сегментации loyalty;
  • продукт 1003 удаляется из сегментации loyalty (поле SegmentExternalId пустое).

Ответ

В случае успеха API возвращает номер задачи импорта workItemId и идентификатор импорта importId. Прогресс выполнения можно посмотреть в разделе Настройки → Задачи по workItemId или запросить по API по importId — см. Получение статуса импорта.

JSONCode
{
    "status": "Success",
    "data": {
        "workItemId": 10099,
        "importId": "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b"
    }
}

Обработка ошибок

  • Общие ошибки API (авторизация, формат запроса, доступность) — см. Обработка ошибок.
  • Ошибки, возникающие при обработке строк CSV-файла (несуществующий продукт, неверный SegmentationExternalId и т.п.), отображаются в файле результата задачи в разделе Настройки → Задачи.
Last modified on
Массовый импорт статических сегментаций клиентовОформление заказа