Как изменить баланс клиентов по файлу

Подготовьте файл в корректном формате и загрузите его, чтобы массово начислить или списать баллы клиентам. Импорт изменений баланса используется для миграции балльных счетов из другой системы, начисления бонусов по акциям, корректировки балансов и других задач, когда нет прямой интеграции.

Импорт выполняется в разделе Данные → Импорт. Нажмите «Новый импорт» для перехода к настройкам:

Шаг 1. Выберите действие с данными

Выберите тип импорта — «Лояльность → Балльные счета».
Выберите действие — «Добавить баллы».

Каждая строка файла создает новое изменение балльного счета клиента: баллы начисляются, если сумма положительная (100), и списываются, если отрицательная (-100). Клиент должен существовать в базе, иначе строка не будет обработана.

Шаг 2. Подготовьте и загрузите файл

Определите, какие поля нужно загрузить. В файле должен присутствовать хотя бы один идентификатор клиента или номер дисконтной карты.

Поле	Обязательно	Описание
Идентификатор клиента Номер дисконтной карты	✅ Должен быть указан хотя бы один	При передаче идентификатора клиента, укажите в настройках импорта тип идентификатора (Email, телефон, Mindbox ID или внешний идентификатор)
Внешний идентификатор точки контакта	Да, если не указан в настройках импорта	Точка контакта, с которой связано изменение баланса (например, сайт или магазин)
Системное имя балльного счета	Да, если не указан в настройках импорта	Балльный счет, на котором нужно изменить баланс
Сумма изменения баланса	Да, если не указан в настройках импорта	На сколько баллов изменить баланс. Для списания используйте отрицательное значение, например `-100`
Дата и время начала действия баллов по UTC	❌	Если не передано, баллы становятся доступны с момента начисления
Дата и время сгорания баллов по UTC	❌	Срок действия начисленных баллов. Если не указано, баллы будут доступны без ограничения по сроку. Для списаний не указывается
Системное имя действия изменения баланса	❌	Доступен только шаблон действия с системным именем `UserBalanceChangedFromAdminSite`
Комментарий к изменению баланса	❌	Произвольный текст. Два типа комментария: Причина для клиента (`Comments`) Причина для показа на административном сайте (`AdminSiteComments`)
Дополнительные поля действия	❌	Любые дополнительные поля, настроенные в проекте для сущностей «Действие клиента»

Выгрузите данные из исходной системы и подготовьте файл для загрузки. В первой строке произвольно укажите названия полей.
- Формат — .csv или .txt.
- Рекомендуемая кодировка — UTF-8.
- Проверьте, что значения соответствуют допустимым форматам.
Пример файла импорта изменений баланса

Рекомендации по подготовке и сохранению файла.
Загрузите файл для импорта и нажмите «Продолжить»:

Шаг 3. Сопоставьте поля файла

Система автоматически сопоставляет колонки файла с полями в Mindbox. При необходимости скорректируйте сопоставление:

В колонке «Импорт» отметьте галочками поля, которые нужно загрузить. Колонки без галочки будут пропущены.
В колонке «Поле Mindbox» сопоставьте каждую колонку файла с полями проекта. Необязательные поля без сопоставления будут пропущены.

Если нужного дополнительного поля еще нет на проекте, его можно создать по кнопке «Создать дополнительное поле».
Нажмите «Продолжить»:

Шаг 4. Настройте импорт

На этом шаге задайте параметры изменения баланса, общие для всех строк файла. Любой из параметров можно вынести в файл, чтобы задать индивидуальные значения для каждой строки.

Источник данных — точка интеграции, через которую пришли данные. Влияет на атрибуцию действий клиента.
Точка контакта — определяет канал или интеграцию, к которой будет привязано изменение баланса. По умолчанию определяется автоматически по точке интеграции. Можно указать вручную или передать в файле.
Бренд — доступен для мультибрендовых проектов. Указывает, в рамках какого бренда произошло изменение баланса.
Идентификатор клиента — тип идентификатора, по которому клиент будет найден в базе (Email, мобильный телефон, Mindbox ID или внешний идентификатор). Сами значения передаются в файле в колонке «Идентификатор клиента, переданной в настройках».
Балльный счет — счет, на котором нужно изменить баланс, если не передан в файле.
Изменение баланса — на сколько баллов уменьшить или увеличить баланс, если не передано в файле.
Отрицательный баланс — если настройка включена, баллы будут списаны, даже если баланс клиента станет отрицательным. Если выключена — такое изменение не сохранится.
Указать причины — произвольный текст с причиной, которая будет отображаться клиенту, или причиной, которая будет отображаться только на проекте.
Комментарий — описание импорта, помогает быстрее найти импорт в общем списке.

При уменьшении баланса баллы списываются в порядке даты сгорания, начиная с ближайшей.

Пример:

У клиента остается 50 баллов до 3 декабря и 100 баллов без ограничений по срокам. Баллы с датой сгорания до 1 декабря были использованы в первую очередь.

Шаг 5. Проверьте и запустите импорт

Перед запуском Mindbox показывает первые строки файла с уже примененным сопоставлением. Убедитесь, что данные выглядят ожидаемо: правильные значения попали в правильные поля.

Если все верно — нажмите «Запустить импорт».

Как отслеживать импорт

После запуска импорт появится в списке на странице «Импорт». По каждой задаче отображаются:

дата запуска,
тип импорта,
исходный файл с комментарием,
прогресс загрузки,
количество импортированных строк и ошибок,
кто запустил.

Если в ходе импорта возникли ошибки — часть строк была пропущена. Откройте детали импорта, чтобы посмотреть, какие строки вызвали проблему и почему. Исправьте ошибки в файле и запустите импорт повторно.