Перейти к содержаниюСправка

Различия

Показаны различия между двумя версиями страницы.

Ссылка на это сравнение

public:api:customer [25.09.2026 18:17] – создано - внешнее изменениеpublic:api:customer [27.09.2026 01:46] (текущий) – удалено - внешнее изменение (Дата неизвестна)
Строка 1: Строка 1:
-====== Customer. Клиенты ====== 
- 
-В системе реализован программный интерфейс для получения, добавления и изменения данных о Клиентах (покупателях). Данные выгружаются по http протоколу. Формат на выбор - xml или json. 
- 
- 
-===== Пример запроса на получение данных ===== 
- 
-Пример запроса на получение данных о клиентах: 
- 
- https://[company].myvirtualpos.ru/api/customer?apikey=MySecret&format=xml 
- 
-Пример запроса на получение данных о клиентах постранично: 
- 
- https://[company].myvirtualpos.ru/api/customer?apikey=MySecret&format=xml&page=1&page_size=200 
-==== Параметры запроса ==== 
- 
-  * **apikey** (get или post) - Секретный ключ для доступа к данным. Обязательный параметр. 
- 
-  * **format** (get only) - формат, в котором сервер отдаст данные. Может принимать значения "xml" или "json". Необязательный параметр. 
- 
-  * **id** (get only) - код клиента, для которого нужно вернуть данные. Если не указан, то возвращаются данные обо всех Клиентах. 
-  * **external_id** (get only) - код Клиента во внешней системе, для которого нужно вернуть данные. Если не указан, то возвращаются данные обо всех Клиентах. 
-  * **phone** - телефон клиента в свободной форме. 
-  * **email** - адрес электронной почты клиента. 
-  * **with_phone** - true: получить клиентов, у которых указан телефон; false: получить клиентов без телефона. 
-  * **with_email** - true: получить клиентов, у которых указан адрес электронной почты; false: получить клиентов без адреса электронной почты. 
-  * **page** - номер страницы (для постраничного запроса). 
-  * **page_size** - размер страницы (для постраничного запроса). 
-  * **cards** - true: в ответ будут добавлены данные о картах лояльности клиента. false - получить данные без карт (по умолчанию) 
-  * **bonuses** - true: в ответ будут добавлены данные о бонусных накоплениях клиента. false - получить данные без бонусов (по умолчанию) 
- 
-==== Ответ сервера ==== 
- 
-В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info. 
- 
- 
- 
-==== Пример ответа сервера ==== 
- 
-Ниже приведен пример ответа сервера в формате XML 
- 
-<file xml> 
-<?xml version="1.0" encoding="UTF-8"?> 
-<root> 
- <success>1</success> 
- <type>customer</type> 
- <count>2</count> 
- <customers> 
- <customer> 
- <id>1</id> 
- <fname>Сергей</fname> 
- <lname>Иванов</lname> 
- <mname>Степанович</mname> 
- <age>24</age> 
- <email/> 
- <phone/> 
- <gender>F</gender> 
- <custom_information>очень требовательный</custom_information> 
- <birth_day>24</birth_day> 
- <birth_month>10</birth_month> 
- <birth_year>1992</birth_year> 
- <register_date>2016-07-18 13:54:37</register_date> 
- <accumulated_sales>15200</accumulated_sales> 
- <send_push>1</send_push> 
- <send_email>1</send_email> 
- <send_sms>1</send_sms> 
- <group_id/> 
- <group_name/> 
- <created_date>2016-07-18 13:54:37</created_date> 
- <created_by>2</created_by> 
- <last_update_date>2016-07-18 13:54:37</last_update_date> 
- <last_update_by>2</last_update_by> 
- </customer> 
- </customers> 
-</root> 
-</file> 
- 
-При постраничном запросе ответ содержит дополнительные поля: 
- 
-<file xml> 
-<?xml version="1.0" encoding="UTF-8"?> 
-<root> 
- <success>1</success> 
- <type>customer</type> 
- <count>200</count> 
- <customers> 
- <customer> 
- <id>1</id> 
- <fname>Сергей</fname> 
- <lname>Иванов</lname> 
- <mname>Степанович</mname> 
- <age>24</age> 
- <email/> 
- <phone/> 
- <gender>F</gender> 
- <custom_information>очень требовательный</custom_information> 
- <birth_day>24</birth_day> 
- <birth_month>10</birth_month> 
- <birth_year>1992</birth_year> 
- <register_date>2016-07-18 13:54:37</register_date> 
- <accumulated_sales>15200</accumulated_sales> 
- <send_push>1</send_push> 
- <send_email>1</send_email> 
- <send_sms>1</send_sms> 
- <group_id/> 
- <group_name/> 
- <created_date>2016-07-18 13:54:37</created_date> 
- <created_by>2</created_by> 
- <last_update_date>2016-07-18 13:54:37</last_update_date> 
- <last_update_by>2</last_update_by> 
- </customer> 
- </customers> 
-        <page>1</page> 
-        <page_size>200</page_size> 
-        <total_count>3000</total_count> 
-</root> 
-</file> 
-===== Пример запроса на добавление/изменение данных ===== 
- 
-Пример запроса на получение данных о клиенте: 
- 
- https://[company].myvirtualpos.ru/api/customer/update?apikey=MySecret&create_if_not_exist=0 
- 
-==== Параметры запроса ==== 
- 
-  * **apikey** (get или post) - Секретный ключ для доступа к данным. Обязательный параметр. 
- 
-  * **format** (get only) - формат, в котором сервер отдаст данные. Может принимать значения "xml" или "json". Необязательный параметр. 
- 
-  * **id** (get only) - код клиента, данные которого надо обновить 
- 
-  * **create_if_not_exist** (get only) - Если истина, то при неудачном поиске клиент будет добавлен в систему. 
-  
-  * **group_name** (get или post)- Название клиентской группы. Если значение указано, то происходит проверка, есть ли группа с таким именем в справочнике. Если нет, то она будет добавлена. Параметр игнорируется, если указан group_id 
- 
-  * Также в качестве параметров могут быть переданы все поля для Клиента (fname, lname, email и т.д.). Поле age(возраст) передавать нельзя - оно рассчитывается автоматически на основе данных о дате рождения клиента. Дополнительные параметры передаются как post-параметры. 
- 
-==== Ответ сервера ==== 
- 
-В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info. 
- 
-Также возвращается id записи, которая была обновлена или добавлена. Флаг isnew равен "1", если запись была создана, и "0" если обновлена. 
- 
- 
-==== Пример ответа сервера ==== 
-<file xml> 
-<?xml version="1.0" encoding="UTF-8"?> 
-<root> 
- <success>1</success> 
- <id>11</id> 
- <isnew>1</isnew> 
-</root> 
-</file> 
- 
-===== updateCard - изменение/добавление дисконтной карты ===== 
-Изменяет существующую (или добавляет новую) дисконтную карту. 
- 
-Параметры запроса: 
-  * **card_id** (get only) - внутренний ID дисконтной карты. Если передан, то карта с указанным ID будет обновлена 
-  * **external_id** (get only) - ID дисконтной карты во внешней системе (например, в 1С) 
-  * **uid** (get only) - уникальный номер карты 
-  * **card_barcode** (get only) - штрих-код карты (цифры для EAN-128). Используется только для поиска карты. Для обновления используйте поле barcode 
-  * **create_if_not_exist** (get only) - если "1", то будет создана новая карта в том случае, если не удалось найти карту с указанными параметрами. Поиск карты осуществляется по следующему алгоритму. Сначала система ищет карту по внутреннему идентификатору card_id. Если запись не найдена, то происходит поиск по уникальному номеру карты uid. Если запись снова не найден, то по external_id. И, в итоге, по штрихкоду card_barcode. 
-  * **uid_ean13** (get или post) - представление уникального номера uid в виде штрих-кода (нули перед uid, контрольная цифра в после uid). Не рекомендуется использовать этот параметр. Если параметр не передан, он штрих-код будет сгенерирован автоматически. 
-  * **barcode** (get или post) - штрих-код карты. Не рекомендуется использовать этот параметр. Если параметр не передан, он штрих-код будет сгенерирован автоматически. 
-  * **medium** (get или post) - носитель карты. Варианты: "PLASTIC" - пластиковая карта; "MAGNET" - карта с магнитной полосой; "APP" - виртуальная карта в мобильном приложении 
-  * **status** (get или post) - статус карты. Возможные значения: NEW - новая неактивированная карта; ACTIVE - действующая карта; BLOCKED - заблокированная карта 
-  * **block_date** (get или post) - дата блокировки карты 
-  * **activate_date** (get или post) - дата выдачи карты 
-  * **type_id** (get или post) - ID типа карты. Возможные типы карт настраиваются в административной панели системы 
-  * **type_name** (get или post) - Название типа карты. Используется только в том случае, если не передан параметр type_id. Если типа карты с указанным названием еще нет в системе, то он будет создан автоматически 
-  * **customer_id** (get или post) - ID клиента, которому принадлежит эта карта 
-  * **customer_external_id** (get или post) - ID клиента во внешней системе, которому принадлежит эта карта. Используется только в случае, если не передан параметр customer_id 
- 
-===== deleteCard - удаление дисконтной карты ===== 
-Удаление одной дисконтной карты. Для удаления карты необходимо передать один из следующих параметров (параметры обязательно передаются как get): 
-  * **card_id** - внутренний ID дисконтной карты. Если передан, то карта с указанным ID будет обновлена 
-  * **external_id** - ID дисконтной карты во внешней системе (например, в 1С) 
-  * **uid** - уникальный номер карты 
-  * **card_barcode** - штрих-код карты (цифры для EAN-128). Используется только для поиска карты. Для обновления используйте поле barcode 
- 
- 
- 
-===== insertCard - добавление дисконтной карты ===== 
-Добавление новой дисконтной карты. Параметры запроса аналогичны updateCard  
- 
- 
-===== updateBonus - изменение бонусных накоплений клиента ===== 
-Начисляет\списывает бонусные баллы с клиента. 
- 
-Параметры запроса: 
-  * (int) **customer_id** - код клиента, для которого нужно вернуть данные. Если не указан customer_external_id, то параметр обязательный. 
-  * (string) **customer_external_id** - код Клиента во внешней системе, для которого нужно вернуть данные. Если не указан customer_id, то параметр обязательный. 
-  * (int) **bonus_id** - идентификатор бонусной программы. Обязательный параметр. 
-  * (float) **amount** -  сумма начисления (если отрицательная, то списания). Обязательный параметр 
-  * (bool) **overwrite** - если true, то заменяет текущие бонусные накопления клиента на сумму amount. Иначе добавляет amount к имеющимся накоплениям. По умолчанию false