# Экспорт регистраций клиентов

Метод запускает экспорт регистраций клиентов. Результат выгружается в файл формата CSV, JSON или XML — в зависимости от настроек операции. Доступен [экспорт на FTP/SFTP-сервер](https://developers.mindbox.ru/docs/export-ftps-sftp). Общие сведения об экспортах, включая сроки хранения файлов и разбивку по частям, описаны в [обзоре экспортов](https://developers.mindbox.ru/docs/exports-overview).

## Предварительная настройка

В интерфейсе Mindbox настройте [операцию](https://help.mindbox.ru/docs/%D0%BE%D0%BF%D0%B5%D1%80%D0%B0%D1%86%D0%B8%D0%B8-v-%D0%BE%D1%81%D0%BD%D0%BE%D0%B2%D0%BD%D1%8B%D0%B5-%D1%81%D0%B2%D0%B5%D0%B4%D0%B5%D0%BD%D0%B8%D1%8F) с шагом **«Экспорт — Выгрузить регистрации клиентов»**. В настройках шага выберите:

* формат файла: CSV, JSON или XML;
* поля регистрации, данные клиента и данные связанного действия, которые нужно выгрузить, — подробнее в разделе [Состав выгрузки](#состав-выгрузки);
* сегмент клиентов, если нужно выгружать регистрации только клиентов из этого сегмента. Сегмент также можно передать в запросе.

Для доступа к файлу экспорта нужно право «Экспорт регистраций клиентов».

:::note

Если в настройках шага отмечено **«Запись регистрации → Связанное действие»**, в блоке **«Действия регистрации → Базовая информация»** должно быть выбрано хотя бы одно поле. По умолчанию выбран **«Шаблон действия»**. Если снять все поля, операцию не получится сохранить.

:::

## Запрос

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

**URL**

`POST https://{Домен API}/v3/operations/sync?endpointId={Идентификатор точки интеграции}&operation={Название операции}`

**Заголовки**

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

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

```json title="JSON"
{
  "exportId": "<Идентификатор экспорта>",
  "sinceDateTimeUtc": "<Начальная дата и время в UTC>",
  "tillDateTimeUtc": "<Конечная дата и время в UTC>",
  "brand": {
    "ids": {
      "systemName": "<Системное имя бренда>"
    }
  },
  "segment": {
    "ids": {
      "externalId": "<Внешний идентификатор сегмента клиентов>"
    }
  },
  "pointsOfContact": [
    {
      "ids": {
        "externalId": "<Внешний идентификатор точки контакта>",
        "systemName": "<Системное имя точки контакта>"
      }
    }
  ],
  "pointOfContactChannels": [
    {
      "ids": {
        "externalId": "<Внешний идентификатор канала>",
        "systemName": "<Системное имя канала>"
      }
    }
  ]
}
```

### Параметры тела запроса

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

| Параметр | Обязательный | Описание |
| --- | --- | --- |
| `exportId` | ❌ | Идентификатор экспорта. Обязателен при повторном запросе для проверки статуса |
| `sinceDateTimeUtc` | ❌ | Начальная дата и время периода (UTC, формат `YYYY-MM-DD hh:mm:ss.fff`). Граница включается |
| `tillDateTimeUtc` | ❌ | Конечная дата и время периода (UTC, формат `YYYY-MM-DD hh:mm:ss.fff`). Граница не включается |
| `brand.ids.systemName` | ❌ | Системное имя бренда. Выгрузятся только регистрации в этом бренде |
| `segment.ids.externalId` | ❌ | Внешний идентификатор сегмента клиентов. Выгрузятся регистрации только клиентов из этого сегмента. Учитывается, если сегмент не выбран в настройках шага операции |
| `pointsOfContact[].ids.externalId` | ❌ | Внешний идентификатор точки контакта |
| `pointsOfContact[].ids.systemName` | ❌ | Системное имя точки контакта. Можно передать вместо внешнего идентификатора |
| `pointOfContactChannels[].ids.externalId` | ❌ | Внешний идентификатор канала |
| `pointOfContactChannels[].ids.systemName` | ❌ | Системное имя канала. Можно передать вместо внешнего идентификатора |

Период отбирается по дате создания регистрации в системе (`creationDateTimeUtc`). Это дата, когда Mindbox обработал регистрацию. Фактически регистрация могла произойти в другое время — эта дата выгружается в `dateTimeUtc`. Учитывайте это, когда задаете период в запросе.

Регистрация попадает в выгрузку, если:

`sinceDateTimeUtc` ≤ дата создания регистрации в системе < `tillDateTimeUtc`

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

:::caution

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

:::

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

Запрос выгружает регистрации за сентябрь 2026 года, которые появились в одной из двух точек контакта: первая указана внешним идентификатором, вторая — системным именем.

```json title="JSON"
POST https://api.mindbox.ru/v3/operations/sync?endpointId=Website&operation=Export.CustomerRegistrations

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

{
  "sinceDateTimeUtc": "2026-09-01 00:00:00.000",
  "tillDateTimeUtc": "2026-10-01 00:00:00.000",
  "pointsOfContact": [
    { "ids": { "externalId": "Android" } },
    { "ids": { "systemName": "Website" } }
  ]
}
```

## Ответ

### Параметры ответа

| Параметр | Описание |
| --- | --- |
| `status` | Результат выполнения запроса. Возможные значения — в разделе [Значения `status`](#значения-status) |
| `exportId` | Идентификатор экспорта. Передайте его в следующем запросе для получения статуса или результата |
| `isDuplicate` | `true` — экспорт с аналогичными настройками уже запущен |
| `exportResult` | Результат экспорта. Присутствует, если обработка завершена или отменена |
| `exportResult.processingStatus` | Статус готовности файла. Возможные значения — в разделе [Значения `processingStatus`](#значения-processingstatus) |
| `exportResult.cancellationReason` | Причина отмены экспорта. Заполняется, если экспорт отменен |
| `exportResult.urls` | Массив ссылок на файлы с результатом экспорта |

### Пример ответа

* Первый запрос — экспорт поставлен в очередь:

```json title="JSON"
{
  "status": "Success",
  "exportId": "23764"
}
```

* Запрос с такими же параметрами, пока предыдущий экспорт еще формируется, — новый экспорт не ставится в очередь, возвращается идентификатор уже запущенного:

```json title="JSON"
{
  "status": "Success",
  "exportId": "23764",
  "isDuplicate": true
}
```

* Повторный запрос с `exportId` — файл готов:

```json title="JSON"
{
  "status": "Success",
  "exportResult": {
    "processingStatus": "Ready",
    "urls": [
      "export.csv"
    ]
  }
}
```

### Значения `status`

| Значение | Описание |
| --- | --- |
| `Success` | Запрос выполнен успешно |
| `ValidationError` | Ошибка валидации входных данных |
| `ProtocolError` | Ошибка интеграции, например не найдена операция или точка интеграции |
| `InternalServerError` | Внутренняя ошибка сервера. Повторите запрос позже |

### Значения `processingStatus`

| Значение | Описание |
| --- | --- |
| `NotReady` | Файл формируется. Повторите запрос с `exportId` позже |
| `Ready` | Файл готов. Ссылки доступны в `exportResult.urls` |
| `Cancelled` | Экспорт отменен. Причина указана в `exportResult.cancellationReason` |

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

:::info

Подробнее — в статье [Обработка ошибок](https://developers.mindbox.ru/docs/error_processing).

:::

## Состав выгрузки

Формат файла (CSV, JSON или XML) зависит от настроек операции. Одна запись в файле — одна регистрация клиента.

**В выгрузку всегда включаются:**

* Mindbox ID клиента (`customer.ids.mindboxId`);
* бизнес-дата и время регистрации (`dateTimeUtc`).

**Опционально выгружаются поля, выбранные в настройках шага.** В блоке **«Запись регистрации»**:

* **«Дата и время создания в системе»** — дата и время создания регистрации в системе;
* **«Бренд»**;
* **«Механика регистрации (тип, ID, название)»** — механика, в рамках которой появилась регистрация;
* **«Персонал»** — логин сотрудника, который зарегистрировал клиента;
* **«Связанное действие»** — действие, в котором у клиента появился контакт или идентификатор.

В блоке **«Данные клиентов»** — базовая информация, email и телефон, внешние идентификаторы клиентов, последняя активированная карта, дополнительные поля. Поля могут отсутствовать, если они пустые в карточке клиента.

В блоке **«Действия регистрации»** — базовая информация, связанные продукты и категории продуктов, изменения баланса, связанные промокоды, дополнительные поля, состояние заказа, статус дисконтной карты, персонал, связанные клиенты. Блок доступен, если отмечено **«Связанное действие»**. Поля действия описаны в статье [Экспорт действий клиентов](https://developers.mindbox.ru/docs/export-customer-actions). Например, для регистрации из импорта заказов в `customerAction.order` выгружается связанный заказ с позициями.

### Механика регистрации

В `mechanics.type` выгружается системное имя типа механики, в рамках которой появилась регистрация, например:

| Значение | Механика |
| --- | --- |
| `Operation` | Операция |
| `PopMechanicPopup` | Попап |
| `Quiz` | Квиз |
| `WorkItem` | Задача, например импорт |
| `AdminSite` | Интерфейс Mindbox |

Список не полный: регистрация может появиться и в других механиках.

:::info

Если регистрация появилась без действия клиента, блок `customerAction` в записи отсутствует.

:::

### Структура данных

```json title="JSON"
{
  "customerRegistrations": [
    {
      "customer": {
        "ids": {
          "mindboxId": "<Идентификатор клиента в Mindbox>",
          "<системное_имя_идентификатора>": "<Внешний идентификатор>"
        },
        "lastName": "<Фамилия>",
        "firstName": "<Имя>",
        "middleName": "<Отчество>",
        "email": "<Адрес электронной почты>",
        "mobilePhone": "<Номер мобильного телефона>",
        "customFields": {
          "<системное_имя_поля>": "<Значение дополнительного поля>"
        },
        "lastActivatedCard": {
          "ids": {
            "number": "<Номер дисконтной карты>"
          }
        }
      },
      "dateTimeUtc": "<Бизнес-дата и время регистрации в UTC>",
      "creationDateTimeUtc": "<Дата и время создания регистрации в системе в UTC>",
      "brand": {
        "ids": {
          "systemName": "<Системное имя бренда>"
        }
      },
      "mechanics": {
        "type": "<Системное имя типа механики>",
        "id": "<Идентификатор механики>",
        "name": "<Название механики>"
      },
      "staff": {
        "userName": "<Логин сотрудника>"
      },
      "customerAction": {
        "ids": {
          "mindboxId": "<Идентификатор действия в Mindbox>"
        },
        "actionTemplate": {
          "ids": {
            "systemName": "<Системное имя шаблона действия>"
          }
        },
        "dateTimeUtc": "<Дата и время действия в UTC>"
      }
    }
  ]
}
```

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

Названия колонок CSV собираются из пути к полю в JSON с префиксом `CustomerRegistration`. Например, `customer.ids.mindboxId` → `CustomerRegistrationCustomerIdsMindboxId`.

| Поле | Описание |
| --- | --- |
| `CustomerRegistrationCustomerIdsMindboxId` | Mindbox ID клиента |
| `CustomerRegistrationCustomerIds{СистемноеИмя}` | Внешний идентификатор клиента, созданный на проекте |
| `CustomerRegistrationCustomerLastName` | Фамилия клиента |
| `CustomerRegistrationCustomerFirstName` | Имя клиента |
| `CustomerRegistrationCustomerMiddleName` | Отчество клиента |
| `CustomerRegistrationCustomerEmail` | Адрес электронной почты клиента |
| `CustomerRegistrationCustomerMobilePhone` | Номер мобильного телефона клиента |
| `CustomerRegistrationCustomerCustomFields{СистемноеИмя}` | Дополнительное поле по сущности «Клиент», созданное на проекте |
| `CustomerRegistrationCustomerLastActivatedCardIdsNumber` | Номер последней активированной дисконтной карты клиента |
| `CustomerRegistrationDateTimeUtc` | Бизнес-дата и время регистрации в UTC. Выгружается всегда |
| `CustomerRegistrationCreationDateTimeUtc` | Дата и время создания регистрации в системе в UTC |
| `CustomerRegistrationBrandIdsSystemName` | Системное имя бренда регистрации |
| `CustomerRegistrationMechanicsType` | Системное имя типа механики, в рамках которой появилась регистрация |
| `CustomerRegistrationMechanicsId` | Идентификатор механики |
| `CustomerRegistrationMechanicsName` | Название механики |
| `CustomerRegistrationStaffUserName` | Логин сотрудника, который зарегистрировал клиента |
| `CustomerRegistrationCustomerAction…` | Поля связанного действия, например `CustomerRegistrationCustomerActionIdsMindboxId` или `CustomerRegistrationCustomerActionActionTemplateIdsSystemName` |