# Customer. Клиенты

> Источник: https://wiki.virtualpos.ru/hc/api/customer  
> Обновлено: 2026-10-01  
> Где в программе: CRM и лояльность → Клиенты

Методы для работы с клиентами (покупателями): получение списка клиентов вместе с их картами и бонусными счетами, создание и изменение клиентов, управление картами, начисление и списание бонусов.

> **Примечание:**
> Как получить ключ, как формируются запросы и какие бывают ответы и ошибки — в статье [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview). Здесь описаны только особенности методов раздела `customer`.

## Методы

| Метод | Адрес | Что делает |
| --- | --- | --- |
| Получить клиентов | `/api/customer` | Возвращает одного клиента или список клиентов |
| Создать или изменить клиента | `/api/customer/update` | Обновляет клиента или создаёт нового |
| Создать или изменить карту | `/api/customer/updateCard` | Обновляет карту, при необходимости создаёт |
| Добавить карту | `/api/customer/insertCard` | Всегда создаёт новую карту |
| Удалить карту | `/api/customer/deleteCard` | Удаляет карту |
| Изменить бонусы | `/api/customer/updateBonus` | Начисляет, списывает или устанавливает бонусный баланс |

> **Важно:**
> **Где передавать параметры.** Ключ `apikey` и формат `format` принимаются и в адресной строке, и в теле POST-запроса. Параметры, по которым ищется запись — `id` и `external_id` в методе получения, `card_id`, `external_id`, `uid`, `card_barcode` в методах карт — читаются **только из адресной строки (GET)**. Остальные параметры можно передавать и в адресной строке, и в теле POST. Удобнее всего: параметры поиска и ключ — в адресе, данные клиента или карты — в теле POST.
>
> Значения с пробелами, кириллицей и знаком `+` кодируйте (`%2B` вместо `+`). Иначе в телефоне `+7…` знак плюса превратится в пробел.

## Получение клиентов

```
GET https://[компания].myvirtualpos.ru/api/customer?apikey=MySecret&page=1&page_size=500
```

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

- **id** — Число. Внутренний ид клиента. Если указан, вернётся один клиент, остальные фильтры не действуют
- **external_id** — Строка. Код клиента во внешней системе. Действует так же, как `id`, если `id` не указан
- **phone** — Строка. Фильтр по телефону
- **email** — Строка. Фильтр по адресу электронной почты
- **with_phone** — `1` — только клиенты с указанным телефоном, `0` — только без телефона
- **with_email** — `1` — только клиенты с указанным адресом почты, `0` — только без него
- **cards** — `1` — добавить к каждому клиенту список его карт. По умолчанию не добавляется
- **bonuses** — `1` — добавить к каждому клиенту бонусные балансы. По умолчанию не добавляются
- **page** — Число. Номер страницы, начиная с **1**. Включает постраничную выдачу
- **page_size** — Число от 10 до 10000. Размер страницы, по умолчанию 100. Включает постраничную выдачу
- **format** — `json` (по умолчанию) или `xml`

Фильтры `phone`, `email`, `with_phone`, `with_email` можно сочетать, но они действуют только если не указан `id` или `external_id`.

> **Важно:**
> **Используйте постраничную выдачу.** Если ни `page`, ни `page_size` не указаны, метод собирает в один ответ всю клиентскую базу. При большой базе это занимает много времени и памяти, и сервер может вернуть ошибку. Загружайте клиентов порциями: увеличивайте `page`, пока не получите всех, — общее число указано в `total_count`. Записи сортируются по `id`.

### Структура ответа

- **success** — `1` — данные получены
- **type** — Тип данных, всегда `customer`
- **count** — Количество клиентов в ответе
- **show_cards** — `1`, если в ответ включены карты (параметр `cards`)
- **show_bonuses** — `1`, если в ответ включены бонусы (параметр `bonuses`)
- **page**, **page_size**, **total_count** — Только при постраничной выдаче: номер страницы, её размер и общее число клиентов, подходящих под фильтр
- **customers** — Список клиентов. Каждый клиент обёрнут в объект `customer`

### Поля клиента

Пустые значения в JSON приходят как `null`, в XML — как пустой элемент.

**Идентификация**

- **id** — Число. Внутренний ид клиента
- **external_id** — Строка. Код клиента во внешней системе
- **group_id** — Число. Ид группы клиентов
- **group_name** — Строка. Название группы клиентов

**Личные данные**

- **fname** — Строка. Имя
- **lname** — Строка. Фамилия
- **mname** — Строка. Отчество
- **gender** — Строка. Пол: `M` — мужской, `F` — женский
- **age** — Строка. Возраст в годах, рассчитывается по дате рождения
- **birth_day**, **birth_month**, **birth_year** — Число. День, месяц и год рождения
- **email** — Строка. Адрес электронной почты
- **phone** — Строка. Телефон в том виде, в котором он сохранён в системе
- **custom_information** — Строка. Произвольная информация о клиенте

**Учёт и рассылки**

- **register_date** — Дата регистрации клиента, если задана
- **accumulated_sales** — Строка. Накопленная сумма покупок, например `1500.50`
- **send_push**, **send_email**, **send_sms** — Число. Согласие на push-уведомления, письма и SMS: `1` — согласен, `0` — нет
- **card_count** — Число. Количество карт клиента
- **created_date**, **last_update_date** — Строка. Дата и время создания и последнего изменения, формат `гггг-мм-дд чч:мм:сс`
- **created_by**, **last_update_by** — Ид пользователя, создавшего и изменившего запись. Для записей, созданных через API, пусто

**Карты** (при `cards=1`: список `cards`, каждая карта в объекте `card`)

- **id** — Число. Ид карты
- **external_id** — Строка. Код карты во внешней системе
- **uid** — Строка. Номер (UID) карты
- **barcode** — Строка. Штрихкод карты
- **medium** — Строка. Носитель: `PLASTIC` — карта без магнитной полосы, `MAGNET` — с магнитной полосой, `APP` — виртуальная карта
- **status** — Строка. Статус: `NEW` — новая, `ACTIVE` — активная, `BLOCKED` — заблокирована
- **block_date**, **activate_date** — Дата блокировки и активации карты
- **type_id**, **type_name** — Ид и название типа карты
- **emission_id** — Ид эмиссии, в которой выпущена карта
- **activate_user_id**, **activate_terminal_id**, **activate_warehouse_id** — Кто, на какой кассе и в какой точке продаж активировал карту

**Бонусы** (при `bonuses=1`: список `bonuses`, каждый баланс в объекте `bonus`)

- **bonus_id** — Число. Ид бонусной программы
- **amount** — Строка. Текущий баланс, например `100.00`. Может быть отрицательным

Гибкие поля клиента в ответ не включаются.

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

```json
{
  "success": 1,
  "type": "customer",
  "count": 1,
  "show_cards": 1,
  "show_bonuses": 1,
  "customers": [
    {
      "customer": {
        "id": 40824,
        "external_id": "CRM-1001",
        "fname": "Пётр",
        "lname": "Иванов",
        "mname": "Петрович",
        "age": "36",
        "email": "ivanov@example.com",
        "phone": "+7 900 000-00-02",
        "gender": "M",
        "custom_information": "VIP",
        "birth_day": 12,
        "birth_month": 5,
        "birth_year": 1990,
        "register_date": null,
        "accumulated_sales": "1500.50",
        "send_push": 1,
        "send_email": 1,
        "send_sms": 0,
        "group_id": 2,
        "group_name": "Постоянные",
        "created_date": "2026-09-26 09:23:01",
        "created_by": null,
        "last_update_date": "2026-09-26 09:23:44",
        "last_update_by": null,
        "card_count": 1,
        "cards": [
          {
            "card": {
              "id": 8287,
              "external_id": "CARD-1",
              "uid": "990001",
              "barcode": "DK-0001009900018",
              "medium": "PLASTIC",
              "status": "ACTIVE",
              "block_date": null,
              "activate_date": null,
              "emission_id": null,
              "type_id": 5,
              "type_name": "Золотая",
              "activate_user_id": null,
              "activate_terminal_id": null,
              "activate_warehouse_id": null
            }
          }
        ],
        "bonuses": [
          { "bonus": { "bonus_id": 1, "amount": "100.00" } }
        ]
      }
    }
  ]
}
```

Тот же ответ при `format=xml` (сокращённо):

```xml
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <success>1</success>
  <type>customer</type>
  <count>1</count>
  <show_cards>1</show_cards>
  <show_bonuses>1</show_bonuses>
  <customers>
    <customer>
      <id>40824</id>
      <external_id>CRM-1001</external_id>
      <fname>Пётр</fname>
      <lname>Иванов</lname>
      <!-- остальные поля клиента -->
      <cards>
        <card>
          <id>8287</id>
          <uid>990001</uid>
          <!-- остальные поля карты -->
        </card>
      </cards>
      <bonuses>
        <bonus><bonus_id>1</bonus_id><amount>100.00</amount></bonus>
      </bonuses>
    </customer>
  </customers>
</root>
```

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

| Задача | Запрос |
| --- | --- |
| Клиенты порциями по 500 | `/api/customer?apikey=MySecret&page=1&page_size=500` |
| Один клиент по коду из внешней системы, с картами | `/api/customer?apikey=MySecret&external_id=CRM-1001&cards=1` |
| Клиент по ид, с картами и бонусами | `/api/customer?apikey=MySecret&id=40824&cards=1&bonuses=1` |
| Поиск по телефону | `/api/customer?apikey=MySecret&phone=9000000002&page=1` |
| Клиенты без указанной почты | `/api/customer?apikey=MySecret&with_email=0&page=1` |

## Создание и изменение клиента

```
POST https://[компания].myvirtualpos.ru/api/customer/update?apikey=MySecret&external_id=CRM-1001&create_if_not_exist=1
fname=Пётр&lname=Иванов&phone=%2B7%20900%20000-00-02
```

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

- **id** — Число. Ид клиента, которого нужно изменить. Читается только из адресной строки
- **external_id** — Строка. Код клиента во внешней системе. Если `id` не указан, по нему ищется клиент. Одновременно это поле клиента: при создании код сохраняется
- **create_if_not_exist** — `1` — если клиент не найден, создать нового. Без этого параметра при отсутствии клиента будет ошибка. Если указан, `id` и `external_id` можно не передавать
- **fname**, **lname**, **mname** — Строка. Имя, фамилия, отчество
- **email**, **phone** — Строка. Почта и телефон
- **gender** — `M` или `F`
- **custom_information** — Строка. Произвольная информация
- **birth_day**, **birth_month**, **birth_year** — Число. Дата рождения
- **register_date** — Дата регистрации
- **accumulated_sales** — Число. Накопленная сумма покупок
- **send_push**, **send_email**, **send_sms** — `1` или `0`. Согласие на уведомления
- **group_id** — Число. Ид группы клиентов
- **group_name** — Строка. Название группы: используется, только если `group_id` не указан. Если группы с таким названием нет, она будет создана
- **[гибкое поле]** — Значение гибкого поля клиента. Имя — название поля из настроек («Размер») или системное `attribute1`…`attribute15`. Пустое значение очищает поле. Подробнее — в статье [FlexField. Гибкие поля](https://wiki.virtualpos.ru/hc/api/flexfield)

Изменяются только переданные поля, остальные остаются прежними. Если данные не проходят проверку, метод вернёт ошибку с перечнем полей и причин.

### Ответ

```json
{"success":1,"id":"40824","isnew":"1"}
```

- **success** — `1` — клиент сохранён
- **id** — Ид клиента. При создании приходит строкой, при изменении — числом
- **isnew** — `"1"` — клиент создан, `"0"` — изменён существующий

## Карты

Карты создаются, изменяются и удаляются тремя методами. Поля карты одинаковы для `updateCard` и `insertCard`:

- **customer_id** — Число. Ид клиента-владельца карты
- **customer_external_id** — Строка. Код клиента во внешней системе; используется в `updateCard`, если `customer_id` не указан
- **external_id** — Строка. Код карты во внешней системе
- **uid** — Строка. Номер (UID) карты
- **uid_ean13** — Строка. Номер карты в формате EAN-13
- **barcode** — Строка. Штрихкод. Если не указан или не начинается с `EK` или `DK`, система задаёт `DK-` + `uid_ean13`
- **medium** — `PLASTIC` (по умолчанию), `MAGNET` или `APP`
- **status** — `NEW` (по умолчанию), `ACTIVE` или `BLOCKED`
- **type_id** — Число. Ид типа карты
- **type_name** — Строка. Название типа карты, используется, если `type_id` не указан. Тип с таким названием создаётся, если его нет
- **block_date**, **activate_date** — Дата блокировки и активации

Тип карты обязателен: без `type_id` или `type_name` придёт ошибка проверки данных.

### updateCard. Изменить или создать карту

```
POST /api/customer/updateCard?apikey=MySecret&uid=990001
status=BLOCKED&customer_id=40824
```

Карта ищется по параметрам, которые читаются только из адресной строки, в таком порядке: `card_id`, `uid`, `external_id`, `card_barcode`. Если карта не найдена и передан `create_if_not_exist=1`, создаётся новая.

- **card_id** — Число. Ид карты
- **uid** — Строка. Номер (UID) карты. Одновременно условие поиска и поле карты
- **external_id** — Строка. Код карты. Одновременно условие поиска и поле карты
- **card_barcode** — Строка. Штрихкод карты, условие поиска
- **create_if_not_exist** — `1` — создать карту, если она не найдена

Остальные поля карты — из таблицы выше. Ответ: `{"success":1,"id":8287,"isnew":"0"}`, где `isnew` равен `"1"` для созданной карты.

> **Важно:**
> **Привязка к клиенту сбрасывается.** Метод всегда записывает владельца карты: если в запросе нет ни `customer_id`, ни `customer_external_id` (или клиент с таким кодом не найден), карта **отвязывается** от клиента. Поэтому при изменении статуса и других полей всегда передавайте владельца. Остальные поля карты меняются, только если переданы.

### insertCard. Добавить карту

```
POST /api/customer/insertCard?apikey=MySecret
customer_id=40824&external_id=CARD-3&uid=990002&type_name=Золотая
```

Всегда создаёт новую карту. Принимает поля карты из таблицы выше. Ответ: `{"success":1,"id":"8288"}`.

> **Важно:**
> В этом методе владелец задаётся **только через `customer_id`**. Параметр `customer_external_id` игнорируется, карта создаётся без владельца. Для привязки по коду клиента используйте `updateCard` с `create_if_not_exist=1`.

### deleteCard. Удалить карту

```
GET /api/customer/deleteCard?apikey=MySecret&card_id=8288
```

- **card_id** — Число. Ид карты
- **external_id** — Строка. Код карты во внешней системе
- **card_uid** — Строка. Номер (UID) карты
- **card_barcode** — Строка. Штрихкод карты

Нужен хотя бы один параметр; если указано несколько, карта ищется по первому из списка выше. Ответ при удалении: `{"success":1}`.

> **Важно:**
> Если карты с такими данными нет, метод тоже отвечает **успехом**: `{"success":1,"info":"Record not found"}`. Это удобно для повторных запросов, но не подтверждает, что карта существовала.

## Бонусы

```
POST /api/customer/updateBonus?apikey=MySecret
customer_id=40824&bonus_id=1&amount=100
```

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

- **customer_id** — Число. Ид клиента
- **customer_external_id** — Строка. Код клиента во внешней системе; используется, если `customer_id` не указан. Один из двух параметров обязателен
- **bonus_id** — Число. Ид бонусной программы. Обязателен
- **amount** — Число. Сумма. Обязателен. Может быть отрицательной
- **overwrite** — `1` — установить баланс равным `amount`. Иначе `amount` добавляется к текущему балансу (отрицательное число списывает)

> **Важно:**
> Метод не проверяет, что баланс достаточен: при списании больше остатка баланс станет отрицательным.

### Ответ

```json
{"success":1,"customer_id":40824,"amount_before":100,"amount_change":-70,"amount_after":30}
```

- **customer_id** — Ид клиента
- **amount_before** — Баланс до операции
- **amount_change** — Фактическое изменение баланса. При `overwrite=1` — разница между новым и прежним балансом
- **amount_after** — Баланс после операции

## Ошибки

Ошибка авторизации и общие ошибки описаны в статье [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview). Ошибки методов раздела приходят с кодом HTTP 200 и `success` равным `0`:

| Сообщение | Метод | Причина | Что делать |
| --- | --- | --- | --- |
| You have to specify [id] or [external_id] to update record | update | Не указан ни `id`, ни `external_id`, нет `create_if_not_exist` | Передайте идентификатор клиента или `create_if_not_exist=1` |
| Record not found | update, updateCard | Запись не найдена, а `create_if_not_exist` не указан | Проверьте идентификатор или передайте `create_if_not_exist=1` |
| You have to specify [card_id], [uid] or [card_barcode] to update record | updateCard | Нет параметров для поиска карты | Передайте один из них или `create_if_not_exist=1` |
| You have to specify [card_id], [external_id], [card_uid] or [card_barcode] to delete record | deleteCard | Нет параметров для поиска карты | Передайте хотя бы один параметр |
| Data validation failed. … | update, updateCard, insertCard | Данные не прошли проверку; после текста идёт перечень полей и причин | Исправьте указанные поля: например, неверный `status` или не указан тип карты |
| Cannot save data. … | update, updateCard, insertCard | Ошибка при сохранении в базе данных | Проверьте данные; текст после точки поясняет причину |
| Required parameters are missing | updateBonus | Нет клиента, `bonus_id` или `amount` | Передайте все обязательные параметры |
| Customer not found | updateBonus | Клиент не найден | Проверьте `customer_id` или `customer_external_id` |
| Bonus program not found: bonus_id=N | updateBonus | Бонусной программы с таким ид нет | Проверьте `bonus_id` |
| Invalid [page] parameter. Pagination starts with 1. | получение | `page` не число или меньше 1 | Передайте `page` от 1 |
| Invalid [page_size] parameter. Valid values range: 10..10000 | получение | `page_size` вне диапазона | Передайте значение от 10 до 10000 |

Если по фильтрам ничего не найдено, метод получения возвращает успешный ответ с `count` равным `0` и пустым списком `customers`.

## Связанные разделы

- [Общие сведения](https://wiki.virtualpos.ru/hc/api/overview) — Ключ доступа, вызов методов, форматы ответов и ошибки
- [FlexField. Гибкие поля](https://wiki.virtualpos.ru/hc/api/flexfield) — Названия гибких полей клиента
- [Дисконтные карты](https://wiki.virtualpos.ru/hc/crm/cards) — Типы карт и работа с картами в интерфейсе
- [Бонусные программы](https://wiki.virtualpos.ru/hc/crm/bonus) — Бонусные программы, ид которых указывается в `bonus_id`
