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

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

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

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

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

## Ограничения

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

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

:::info

Подробнее о работе с V3 API, URL запросов и заголовках: [Документация V3 API](https://developers.mindbox.ru/docs/v3).

:::

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

:::info

Домен`api.mindbox.ru` зависит от домена API вашего проекта. Как определить домен — см. [Домен API Mindbox](https://developers.mindbox.ru/docs/v3#domain-api-mindbox).

:::

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

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

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

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

## Тело запроса

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

### Поля файла

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

:::info

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

:::

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

:::warning{title="Важно"}

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

:::

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

```csv
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` — см. [Получение статуса импорта](https://developers.mindbox.ru/docs/import-status).

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

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

* Общие ошибки API (авторизация, формат запроса, доступность) — см. [Обработка ошибок](https://developers.mindbox.ru/docs/error_processing).
* Ошибки, возникающие при обработке строк CSV-файла (несуществующий продукт, неверный `SegmentationExternalId` и т.п.), отображаются в файле результата задачи в разделе **Настройки → Задачи**.