# Импорт персональных предложений ## Виды операций Поддерживается два вида операций импорта персональных предложений (ПП): * Установка персональных предложений (ImportFavoriteList) - предложения устанавливаются согласно логике валидации установки следующего ПП, когда периоды действия новых ПП не должны пересекаться с уже установленными ПП и действовать от текущей даты или в будущем * Переустановка персональных предложений (OverwriteFavoriteList) - все действующие ПП останавливаются, а будущие отменяются, устанавливаются новые ПП с текущей датой начала или в будущем ## Описание метода Импорт персональных предложений осуществляется с помощью POST-запроса. Необходимые параметры URL и возможные поля запроса можно посмотреть в административной панели Mindbox в разделе "Клиенты-Импорт-Изменить персональное предложение". Импорт: Установка персональных предложений Импорт: Переустановка персональных предложений ```csv POST https://api.mindbox.ru/v3/operations/bulk?endpointId={Системное имя точки контакта}&operation=ImportFavoriteList&favoriteListSystemName={Системное имя персонального предложения}&csvCodePage=65001&transactionId={Значение ключа идемпотентности в формате GUID} Accept: application/json Content-Type: text/csv;charset=utf-8 Authorization: SecretKey {Секретный ключ} ``` ```csv POST https://api.mindbox.ru/v3/operations/bulk?endpointId={Системное имя точки контакта}&operation=OverwriteFavoriteList&favoriteListSystemName={Системное имя персонального предложения}&csvCodePage=65001&transactionId={Значение ключа идемпотентности в формате GUID} Accept: application/json Content-Type: text/csv;charset=utf-8 Authorization: SecretKey {Секретный ключ} ``` * csvCodePage - идентификатор кодовой страницы Windows для CSV-файла. Предпочтительно использовать 65001 (UTF-8). * csvColumnDelimiter - символ, использующийся для разделения колонок в CSV-файле. * csvTextQualifier - символ, опционально добавляющийся в начале и в конце значения колонки, позволяя использовать в нём символы, обычно не разрешённые. * transactionId - ключ идемпотентности, позволяющий избежать повторного выполнения запроса. Ключ идемпотентности обязательно создавать в формате GUID (рекомендуется версия 4). Для повторных запросов c повторяющимся ключом в ответ вернется статус `TransactionAlreadyProcessed`. * ключ авторизации - это строка вида username:password, закодированная в base64. * данный сервис разрешает поставить не более 60 импортов в час. После превышения порога вы будете получать 429 Too Many Requests до тех пор, пока количество поставленных задач за час не опустится ниже 60. * максимальный размер принимаемого файла 200мб. В случае, если необходимо загрузить больший объем данных, данные нужно разбить на несколько файлов. ## Описание полей Персональное предложение может хранить или не хранить скидку в списке. Если скидка хранится в списке, значит, она каждый раз задаётся заново из полей импорта. Если она не хранится в списке, значит, она задаётся в промоакции и в запросе не передаётся. | Заголовок | Описание | Храним скидку в списке | Не храним скидку в списке | |---------------------|----------|-------------------------|----------------------------| | CustomerWebsiteid | Идентификатор клиента на сайте или в любой другой системе (например, MindboxId). Может быть заменено любым другим способом идентификации клиента (например, почтой или телефоном). | Необходим хотя бы 1 идентификатор клиента. | Необходим хотя бы 1 идентификатор клиента. | | ProductId | Id продукта в соответствующей ему внешней системе (например, для системы MsSite на тестовом проекте это ProducttestSystemTestSystem). | Необходимое поле. | Необходимое поле. | | OfferValue | Размер скидки/цены/начисления баллов/списания баллов (числовой параметр). Значение должно задаваться в соответствии с типом бенефита. | Необходимое поле. | Не передаётся. | | DiscountType | Тип бенефита. Может выражаться в процентах, абсолютное значение скидки/баллов или специальной ценой на продукт: Percent/Absolute/Price соответственно. Price актуально только для скидочных бенефитов | Необходимое поле. | Не передаётся. | | startDateTimeUtc | Дата и время начала действия персонального предложения в формате 2022-11-13T09:04:04.00Z. Если не передано, устанавливается текущая дата при импорте конкретной строки персонального предложения | Необязательное поле. | Необязательное поле. | | endDateTimeUtc | Дата и время окончания действия персонального предложения в формате 2022-11-13T09:04:04.00Z. Если не передано, дата не устанавливается - предложение считается бессрочным | Необязательное поле. | Необязательное поле. | ## Пример запроса ```csv title="Импорт персональных предложений" CustomerMindboxId;ProductTestSite;startDateTimeUtc;DiscountValue;DiscountType;LimitAmount;LimitType;LimitPeriod 3450;33171;2022-11-13T09:04:04.00Z;10;Percent;1;quantity;FixedDays ``` В тело ответа придёт Id задачи на импорт, по которому её можно будет отследить. ## Пример ответа ```json title="Импорт персональных предложений" { "status": "Success", "data": { "workItemId": 6019, "importId": "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b" } } ``` * workItemId — номер задачи импорта. По нему можно найти задачу в административной панели и посмотреть ее статус. * importId — идентификатор импорта. По нему можно запросить статус импорта по API — см. [Получение статуса импорта](https://developers.mindbox.ru/docs/import-status). ## Обновление персонального предложения Актуально для Установки ПП (ImportFavoriteList) * Для того, чтобы добавить позицию в персональное предложение или изменить данные об уже имеющихся позициях (кроме их удаления), достаточно запустить новый импорт того же самого персонального предложения с изменёнными данными - они перезапишутся; * Для того, чтобы удалить позицию из списка персональных предложений, необходимо запустить новый импорт, где дата окончания действия предложения на нужную позицию проставлена в максимально близком будущем (например через минуту после осуществления запроса к сервису).