# Получение данных клиента

:::warning

 В инструкции описаны **примеры** POST-запросов. Интеграция с Mindbox не будет работать, если использовать запросы из примеров ниже без редактирования.

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

:::

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

Осуществляется с помощью POST-запроса. Название операции настраивается в системе Mindbox. Подробней про вызов методов в Mindbox API можно прочитать [здесь](https://developers.mindbox.ru/docs/v3).

Метод возвращает данные клиента в зависимости от настроек в системе.

## Формат запроса

<CodeTabs syncKey="language">

```xml title="XML"
POST https://api.mindbox.ru/v3/operations/{синхронная/асинхронная операция}?endpointId={уникальный идентификатор сайта/мобильного приложения/и т.п.}&operation={название операции}&deviceUUID={уникальный идентификатор устройства}

Accept: application/xml
Content-Type: application/xml
Authorization: SecretKey {секретный_ключ_точки_интеграции}

<operation>
  <customer>
    <ids>
      <webSiteUserId>{Идентификатор клиента}</webSiteUserId>
    </ids>
  </customer>
</operation>
```

```json title="JSON"
POST https://api.mindbox.ru/v3/operations/{синхронная/асинхронная операция}?endpointId={уникальный идентификатор сайта/мобильного приложения/и т.п.}&operation={название операции}&deviceUUID={уникальный идентификатор устройства}

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

{
  "customer": {
    "ids": {
      "webSiteUserId": "{Идентификатор клиента}"
    }
  }
}
```

```js title="JavaScript"
mindbox('sync', {
  operation: '<Название операции>',
  data: {
    customer: {
      ids: {
        mindboxId: <Идентификатор в mindbox>,
      	<Идентификатор>: '<Значение идентификатора>',
      },
      mobilePhone: '<Мобильный телефон клиента>',
      email: '<Email клиента>'
    }
  },
  onSuccess: <Функция, вызываемая в случае успеха>,
  onError: <Функция, вызываемая в случае ошибки>
});
```

</CodeTabs>

:::info

В ответе возвращаются только заполненные поля клиента
:::

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

<CodeTabs syncKey="language">

```xml title="XML"
POST https://api.mindbox.ru/v3/operations/sync?endpointId=MindboxRu&operation=getCustomer

Accept: application/xml
Content-Type: application/xml
Authorization: SecretKey {секретный_ключ_точки_интеграции}


<operation>
  <customer>
    <ids>
      <webSiteUserId>5384275</webSiteUserId>
    </ids>
  </customer>
</operation>
```

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

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

{
  "customer": {
    "ids": {
      "webSiteUserId": "5384275"
    }
  }
}
```

```javascript title="Получение данных по сессии (JS)"
mindbox('sync', {
  operation: 'GetCustomerDataBySession',
  onSuccess: function(response) {
    console.log(response.customer.ids.mindboxId);
    console.log(response.customer.ids.webSiteId);
  }
});
```

```javascript title="Получение данных по Id сайта (JS)"
mindbox('sync', {
  operation: 'GetCustomerDataByWebSiteId',
  data: {
    customer: {
      ids: {
      	webSiteId: '123'
      }
    }
  },
  onSuccess: function(response) {
    console.log(response.customer.ids.mindboxId);
  }
});
```

</CodeTabs>

## Ответ

Ответ может содержать несколько независимых узлов на корневом уровне в зависимости от настроек операции:

* `customer` — данные клиента;
* `retailOrderStatistics` - сумма заказов клиента из сегментации;
* `balances` - балльный баланс клиента (см. [Получение баланса клиента](https://developers.mindbox.ru/docs/get-customer-bonus-balance));
* `discountCards` - дисконтные карты клиента;
* `endpoints` — список мобильных приложений и устройств клиента. Возвращается, только если у клиента есть устройства (см. [Мобильные приложения и устройства клиента](https://developers.mindbox.ru/docs/get-customer-data#%D0%BC%D0%BE%D0%B1%D0%B8%D0%BB%D1%8C%D0%BD%D1%8B%D0%B5-%D0%BF%D1%80%D0%B8%D0%BB%D0%BE%D0%B6%D0%B5%D0%BD%D0%B8%D1%8F-%D0%B8%D1%83%D1%81%D1%82%D1%80%D0%BE%D0%B9%D1%81%D1%82%D0%B2%D0%B0-%D0%BA%D0%BB%D0%B8%D0%B5%D0%BD%D1%82%D0%B0));
* `personalOffers` - актуальные персональные предложения; 
* `productList` - данные о продуктах в списке продуктов.

### Клиент найден


<CodeTabs syncKey="language">

```xml title="XML"
<result>
  <status>Success</status>
  <customer>
    <processingStatus>Found</processingStatus>
    <ids>
      <mindboxId>{ID клиента в БД mindbox}</mindboxId>
      <myWebSiteId>{ID пользователя на сайте}</myWebSiteId>
    </ids>
    <sex>{пол - male/female}</sex>
    <email>{Email клиента}</email>
    <isEmailInvalid>{Email клиента невалиден - true/false}</isEmailInvalid>
    <isEmailConfirmed>{Email клиента подтвержден - true/false}</isEmailConfirmed>
    <pendingEmail>{Email, ожидающий подтверждения после смены}</pendingEmail>
    <mobilePhone>{Мобильный телефон}</mobilePhone>
    <isMobilePhoneInvalid>{Мобильный телефон невалиден - true/false}</isMobilePhoneInvalid>
    <isMobilePhoneConfirmed>{Мобильный телефон подтвержден - true/false}</isMobilePhoneConfirmed>
    <pendingMobilePhone>{Мобильный телефон, ожидающий подтверждения после смены}</pendingMobilePhone>
    <lastName>{Имя клиента}</lastName>
    <firstName>{Фамилия клиента}</firstName>
    <birthDate>{Дата рождения в формате YYYY-MM-DD}</birthDate>
    <area>
      <ids>
        <externalId>{Идентификатор географической зоны клиента}</externalId>
      </ids>
      <name>{Название географической зоны клиента}</name>
    </area>
    <subscriptions>
      <subscription>
        <pointOfContact>{Канал коммуникации Email/SMS/тд}</pointOfContact>
        <topic>{Тематика рассылок}</topic>
        <isSubscribed>{Статус подписки true/false}</isSubscribed>        
      </subscription>
    </subscriptions>
    <customFields>
      <Дополнительное поле>{Значение дополнительного поля}</Дополнительное поле>
    </customFields>
    <changeDateTimeUtc>{Дата регистрации/редактирования в формате YYYY-MM-DD hh:mm:ss.fff}</changeDateTimeUtc>
  </customer>
</result>
```

```json title="JSON"
{
    "status": "Success",
    "customer": {
        "processingStatus": "Found",
        "ids": {
            "mindboxId": "{ID клиента в БД mindbox}",
            "myWebSiteId": "{ID пользователя на сайте}"
        },
        "sex": "{пол - male/female}",
        "email": "{Емэйл клиента}",
        "isEmailInvalid": "{Емэйл клиента невалиден - true/false}",
        "isEmailConfirmed": "{Емэйл клиента подтвержден - true/false}",
        "pendingEmail": "{Емэйл, ожидающий подтверждения после смены}",
        "mobilePhone": "{Мобильный телефон}",
        "isMobilePhoneInvalid": "{Мобильный телефон невалиден - true/false}",
        "isMobilePhoneConfirmed": "{Мобильный телефон подтвержден - true/false}",
        "pendingMobilePhone": "{Мобильный телефон, ожидающий подтверждения после смены}",
        "lastName": "{Фамилия клиента}",
        "firstName": "{Имя клиента}",
        "birthDate": "{Дата рождения в формате YYYY-MM-DD}",
        "area": {
            "ids": {
                "externalId": "{Идентификатор географической зоны клиента}"
            },
            "name": "{Название географической зоны клиента}"
        },
        "subscriptions": [
            {
                "pointOfContact": "{Канал коммуникации Email/SMS/тд}",
                "topic": "{Тематика рассылок}",
                "isSubscribed": "{Статус подписки true/false}"
            }
        ],
        "customFields": {
            "Дополнительное поле": "{Значение дополнительного поля}"
        },
        "changeDateTimeUtc": "{Дата регистрации/редактирования в формате YYYY-MM-DD hh:mm:ss.fff}"
    }
}
```

</CodeTabs>

### Клиент не найден

<CodeTabs syncKey="language">

```xml title="XML"
<result>
  <status>Success</status>
  <customer>
    <processingStatus>NotFound</processingStatus>
  </customer>
</result>
```

```json title="JSON"
{
    "status": "Success",
    "customer": {
        "processingStatus": "NotFound"
    }
}
```

</CodeTabs>

Статус обработки/поиска клиента (`processingStatus`) может иметь различные значения для проверки наличия клиента:

* `Found` - клиент успешно найден
* `NotFound` - клиент не найден

## Мобильные приложения и устройства клиента

Узел `endpoints` возвращает список мобильных приложений клиента и зарегистрированных в них устройств. Используется для диагностики недоставки push-уведомлений.

:::info

Узел `endpoints` не возвращается, если у клиента нет зарегистрированных устройств. Максимум 5 устройств (`devices`) на приложение (`endpoint`).

:::

### Как обновляются данные о приложении

Данные устройства обновляются **только** в двух случаях:

* пользователь проявил активность в приложении;
* при попытке отправить push-уведомление выяснилось, что токен недействителен (например, приложение удалено).

**В фоновом режиме **Mindbox SDK не обновляет статус. Пока пользователь не откроет приложение, ни активность, ни статус токена не обновятся.

:::tip

Подробнее о недействительных токенах приложения и других ошибках при отправке push-уведомлений [в чек-листе](https://developers.mindbox.ru/docs/sdk-integration-checklist).

:::

### Контракт ответа

<CodeTabs syncKey="language">

```xml title="XML"
<result>
  <status>{Результат выполнения запроса}</status>
  <endpoints>
    <endpoint>
      <endpointName>{Имя точки интеграции приложения}</endpointName>
      <externalId>{Идентификатор точки интеграции приложения}</externalId>
      <devices>
        <device>
          <uuid>{Идентификатор мобильного устройства}</uuid>
          <isPushTarget>{Является ли устройство целевым для следующего push-уведомления}</isPushTarget>
          <model>{Модель устройства}</model>
          <operatingSystem>
            <family>{Семейство ОС}</family>
            <version>{Версия ОС}</version>
          </operatingSystem>
          <mobileAppInstallation>
            <version>{Версия мобильного приложения}</version>
            <lastUpdateDateTimeUtc>{Дата последней пользовательской активности в приложении или push-уведомления, выявившего неактивность токена}</lastUpdateDateTimeUtc>
            <status>{Статус токена}</status>
            <arePushNotificationsAllowed>{Статус разрешения получения push-уведомлений}</arePushNotificationsAllowed>
          </mobileAppInstallation>
        </device>
      </devices>
    </endpoint>
  </endpoints>
</result>
```

```json title="JSON"
"endpoints": [
  {
    "endpointName": "{Имя точки интеграции приложения}",
    "externalId": "{Идентификатор точки интеграции приложения}",
    "devices": [
      {
        "uuid": "{Идентификатор мобильного устройства}",
        "isPushTarget": "{Является ли устройство целевым для следующего push-уведомления}",
        "model": "{Модель устройства}",
        "operatingSystem": {
          "family": "{Семейство ОС}",
          "version": "{Версия ОС}"
        },
        "mobileAppInstallation": {
          "version": "{Версия мобильного приложения}",
          "lastUpdateDateTimeUtc": "{Дата последней пользовательской активности в приложении или push-уведомления, выявившего неактивность токена}",
          "status": "{Статус токена}",
          "arePushNotificationsAllowed": "{Статус разрешения получения push-уведомлений}"
        }
      }
    ]
  }
]
```

</CodeTabs>

#### Описание полей

| Поле | Описание |
|---|---|
| `endpointName` | Имя точки интеграции мобильного приложения |
| `externalId` | Внешний идентификатор точки интеграции.|
| `devices[].uuid` | Уникальный идентификатор устройства |
| `devices[].isPushTarget` | `true` — устройство, на которое будет отправлено push-уведомление. Уникально в пределах одного `endpoint` |
| `devices[].model` | Модель устройства |
| `operatingSystem.family` / `version` | Семейство и версия ОС |
| `mobileAppInstallation.version` | Версия (сборка) приложения |
| `mobileAppInstallation.lastUpdateDateTimeUtc` | Дата последней пользовательской активности либо момент, когда при отправке push-уведомления выявлена неактивность токена. Формат: `yyyy-MM-dd HH:mm:ss.fff` (UTC) |
| `mobileAppInstallation.status` | Статус токена: `Active`, `Inactive` |
| `mobileAppInstallation.arePushNotificationsAllowed` | Разрешение на получение push-уведомлений на устройстве |

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

**У пользователя одно устройство:**

<CodeTabs syncKey="language">

```xml title="XML"
<result>
  <status>Success</status>
  <endpoints>
    <endpoint>
      <endpointName>Test: мобильное приложение Android</endpointName>
      <externalId>2020TestMobileAndroid</externalId>
      <devices>
        <device>
          <uuid>229626a6-b7c1-4c68-84c0-66114b23701e</uuid>
          <isPushTarget>true</isPushTarget>
          <model>Generic Tablet</model>
          <operatingSystem>
            <family>Other</family>
            <version>null</version>
          </operatingSystem>
          <mobileAppInstallation>
            <version>2.47.1 (22050)</version>
            <lastUpdateDateTimeUtc>2026-06-16 16:05:00.000</lastUpdateDateTimeUtc>
            <status>Active</status>
            <arePushNotificationsAllowed>true</arePushNotificationsAllowed>
          </mobileAppInstallation>
        </device>
      </devices>
    </endpoint>
  </endpoints>
</result>
```

```json title="JSON"
{
  "status": "Success",
  "endpoints": [
    {
      "endpointName": "Test: мобильное приложение Android",
      "externalId": "2020TestMobileAndroid",
      "devices": [
        {
          "uuid": "229626a6-b7c1-4c68-84c0-66114b23701e",
          "isPushTarget": true,
          "model": "Generic Tablet",
          "operatingSystem": {
            "family": "Other",
            "version": null
          },
          "mobileAppInstallation": {
            "version": "2.47.1",
            "lastUpdateDateTimeUtc": "2026-06-16 16:05:00.000",
            "status": "Active",
            "arePushNotificationsAllowed": true
          }
        }
      ]
    }
  ]
}
```
</CodeTabs>

**У пользователя несколько устройств в разных приложениях:**

<CodeTabs syncKey="language">

```xml title="XML"
<result>
  <status>Success</status>
  <endpoints>
    <endpoint>
      <endpointName>Test: мобильное приложение Android</endpointName>
      <externalId>2020TestMobileiOS</externalId>
      <devices>
        <device>
          <uuid>229626a6-b7c1-4c68-84c0-66114b23701e</uuid>
          <isPushTarget>true</isPushTarget>
          <model>Apple iPhone 15</model>
          <operatingSystem>
            <family>iOS</family>
            <version>26.3.1</version>
          </operatingSystem>
          <mobileAppInstallation>
            <version>2.47.1</version>
            <lastUpdateDateTimeUtc>2026-06-14 17:13:00.000</lastUpdateDateTimeUtc>
            <status>Active</status>
            <arePushNotificationsAllowed>true</arePushNotificationsAllowed>
          </mobileAppInstallation>
        </device>
      </devices>
    </endpoint>
    <endpoints>
    <endpoint>
      <endpointName>Mindbox: мобильное приложение Android</endpointName>
      <externalId>Mindbox-Mobile-Android</externalId>
      <devices>
        <device>
          <uuid>b12c7b3b-f99c-40c0-b600-ee58d89bc58d</uuid>
          <isPushTarget>true</isPushTarget>
          <model>Generic Smartphone</model>
          <operatingSystem>
            <family>Android</family>
            <version>15</version>
          </operatingSystem>
          <mobileAppInstallation>
            <version>2.30.2 (20804)</version>
            <lastUpdateDateTimeUtc>2026-06-13 17:22:00.000</lastUpdateDateTimeUtc>
            <status>Active</status>
            <arePushNotificationsAllowed>true</arePushNotificationsAllowed>
          </mobileAppInstallation>
        </device>
      </devices>
    </endpoint>
  </endpoints>
</result>
```

```json
{
  "status": "Success",
  "endpoints": [
    {
      "endpointName": "Test: мобильное приложение iOS",
      "externalId": "2020TestMobileiOS",
      "devices": [
        {
          "uuid": "27f0da00-20da-4da7-ad87-6a0056dad931",
          "isPushTarget": true,
          "model": "Apple iPhone 15",
          "operatingSystem": { 
            "family": "iOS", 
            "version": "26.3.1" 
            },
          "mobileAppInstallation": {
            "version": "2.47.1",
            "lastUpdateDateTimeUtc": "2026-06-14 17:13:00.000",
            "status": "Active",
            "arePushNotificationsAllowed": true
          }
        }
      ]
    },
    {
      "endpointName": "Mindbox: мобильное приложение Android",
      "externalId": "Mindbox-Mobile-Android",
      "devices": [
        {
          "uuid": "b12c7b3b-f99c-40c0-b600-ee58d89bc58d",
          "isPushTarget": true,
          "model": "Generic Smartphone",
          "operatingSystem": { 
            "family": "Android", 
            "version": "15" 
            },
          "mobileAppInstallation": {
            "version": "2.30.2 (20804)",
            "lastUpdateDateTimeUtc": "2026-06-13 17:22:00.000",
            "status": "Active",
            "arePushNotificationsAllowed": true
          }
        }
      ]
    }
  ]
}
```
</CodeTabs>

### Диагностика недоставки уведомлений

Признаки типовых причин можно определить по комбинации полей:

* **Пользователь отключил разрешение на устройстве**. `lastUpdateDateTimeUtc` недавняя дата, а `arePushNotificationsAllowed` равно `false`.
* **Приложение может быть удалено**. `lastUpdateDateTimeUtc` старая дата — давно не было активности из приложения. При `arePushNotificationsAllowed:false` невозможно отправить уведомление для проверки статуса токена.
* **Неактивное устройство стало целевым для push-уведомлений**. У клиента два активных устройства на одном приложении. Удаление приложения и запрет на получение уведомлений также считается активностью, из-за чего неактивное приложение может получить `PushTarget:true`. Обращайте внимание на поля `mobileAppInstallation.status` и `mobileAppInstallation.arePushNotificationsAllowed`.