groupsCustomer. Клиенты

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

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

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

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

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

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

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

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

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

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

{
  "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 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>

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

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

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

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

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

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, создаётся новая.

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

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

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

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

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

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

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

Ошибка авторизации и общие ошибки описаны в статье Общие сведения. Ошибки методов раздела приходят с кодом HTTP 200 и success равным 0:

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