Различия

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

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

Предыдущая версия справа и слева Предыдущая версия
Следующая версия
Предыдущая версия
doc:dev:api:customer [01.09.2017 13:00]
mzubkov [Параметры запроса]
doc:dev:api:customer [27.09.2021 11:44] (текущий)
amalchenko [Пример запроса на добавление/изменение данных]
Строка 6: Строка 6:
 ===== Пример запроса на получение данных ===== ===== Пример запроса на получение данных =====
  
-Пример запроса на получение данных об остатках товаров:+Пример запроса на получение данных о клиентах:
  
  ​http://​mycompany.virtpos.ru/​api/​customer?​apikey=MySecret&​format=xml  ​http://​mycompany.virtpos.ru/​api/​customer?​apikey=MySecret&​format=xml
  
 +Пример запроса на получение данных о клиентах постранично:​
 +
 + ​http://​mycompany.virtpos.ru/​api/​customer?​apikey=MySecret&​format=xml&​page=1&​page_size=200
 ==== Параметры запроса ==== ==== Параметры запроса ====
  
Строка 16: Строка 19:
   * **format** (get only) - формат,​ в котором сервер отдаст данные. Может принимать значения "​xml"​ или "​json"​. Необязательный параметр.   * **format** (get only) - формат,​ в котором сервер отдаст данные. Может принимать значения "​xml"​ или "​json"​. Необязательный параметр.
  
-  * **id** (get only) - код ​Клиента,​ для которого надо вернуть данные. Если не указан,​ то возвращаются данные обо всех Клиентах. +  * **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 или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info.
  
  
Строка 65: Строка 76:
 </​file>​ </​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>​
 ===== Пример запроса на добавление/​изменение данных ===== ===== Пример запроса на добавление/​изменение данных =====
  
-Пример запроса на получение данных о точке продаж:+Пример запроса на получение данных о клиенте:
  
  ​http://​mycompany.virtpos.ru/​api/​customer/​update?​apikey=MySecret&​create_if_not_exist=0  ​http://​mycompany.virtpos.ru/​api/​customer/​update?​apikey=MySecret&​create_if_not_exist=0
Строка 78: Строка 128:
   * **format** (get only) - формат,​ в котором сервер отдаст данные. Может принимать значения "​xml"​ или "​json"​. Необязательный параметр.   * **format** (get only) - формат,​ в котором сервер отдаст данные. Может принимать значения "​xml"​ или "​json"​. Необязательный параметр.
  
-  * **id** (get only) - код ​магазина, данные которого надо обновить+  * **id** (get only) - код ​клиента, данные которого надо обновить
  
-  * **create_if_not_exist** (get only) - Если истина,​ то при неудачном поиске ​магазин будет добавлен в систему.+  * **create_if_not_exist** (get only) - Если истина,​ то при неудачном поиске ​клиент будет добавлен в систему.
    
   * **group_name** (get или post)- Название клиентской группы. Если значение указано,​ то происходит проверка,​ есть ли группа с таким именем в справочнике. Если нет, то она будет добавлена. Параметр игнорируется,​ если указан group_id   * **group_name** (get или post)- Название клиентской группы. Если значение указано,​ то происходит проверка,​ есть ли группа с таким именем в справочнике. Если нет, то она будет добавлена. Параметр игнорируется,​ если указан group_id
Строка 107: Строка 157:
  
 Параметры запроса:​ Параметры запроса:​
-  * **card_id** - внутренний ID дисконтной карты. Если передан,​ то карта с указанным ID будет обновлена +  * **card_id** ​(get only) - внутренний ID дисконтной карты. Если передан,​ то карта с указанным ID будет обновлена 
-  * **external_id** - ID дисконтной карты во внешней системе (например,​ в 1С) +  * **external_id** ​(get only) - ID дисконтной карты во внешней системе (например,​ в 1С) 
-  * **uid** - уникальный номер карты +  * **uid** ​(get only) - уникальный номер карты 
-  * **card_barcode** - штрих-код карты (цифры для EAN-128). Используется только для поиска карты. Для обновления используйте поле barcode +  * **card_barcode** ​(get only) - штрих-код карты (цифры для EAN-128). Используется только для поиска карты. Для обновления используйте поле barcode 
-  * **create_if_not_exist** - если "​1",​ то будет создана новая карта в том случае,​ если не удалось найти карту с указанными параметрами. Поиск карты осуществляется по следующему алгоритму. Сначала система ищет карту по внутреннему идентификатору card_id. Если запись не найдена,​ то происходит поиск по уникальному номеру карты uid. Если запись снова не найден,​ то по external_id. И, в итоге, по штрихкоду card_barcode. +  * **create_if_not_exist** ​(get only) - если "​1",​ то будет создана новая карта в том случае,​ если не удалось найти карту с указанными параметрами. Поиск карты осуществляется по следующему алгоритму. Сначала система ищет карту по внутреннему идентификатору card_id. Если запись не найдена,​ то происходит поиск по уникальному номеру карты uid. Если запись снова не найден,​ то по external_id. И, в итоге, по штрихкоду card_barcode. 
-  * **uid_ean13** - представление уникального номера uid в виде штрих-кода (нули перед uid, контрольная цифра в после uid). Не рекомендуется использовать этот параметр. Если параметр не передан,​ он штрих-код будет сгенерирован автоматически. +  * **uid_ean13** ​(get или post) - представление уникального номера uid в виде штрих-кода (нули перед uid, контрольная цифра в после uid). Не рекомендуется использовать этот параметр. Если параметр не передан,​ он штрих-код будет сгенерирован автоматически. 
-  * **barcode** - штрих-код карты. Не рекомендуется использовать этот параметр. Если параметр не передан,​ он штрих-код будет сгенерирован автоматически. +  * **barcode** ​(get или post) - штрих-код карты. Не рекомендуется использовать этот параметр. Если параметр не передан,​ он штрих-код будет сгенерирован автоматически. 
-  * **medium** - носитель карты. Варианты:​ "​PLASTIC"​ - пластиковая карта; "​MAGNET"​ - карта с магнитной полосой;​ "​APP"​ - виртуальная карта в мобильном приложении +  * **medium** ​(get или post) - носитель карты. Варианты:​ "​PLASTIC"​ - пластиковая карта; "​MAGNET"​ - карта с магнитной полосой;​ "​APP"​ - виртуальная карта в мобильном приложении 
-  * **status** - статус карты. Возможные значения:​ NEW - новая неактивированная карта; ACTIVE - действующая карта; BLOCKED - заблокированная карта +  * **status** ​(get или post) - статус карты. Возможные значения:​ NEW - новая неактивированная карта; ACTIVE - действующая карта; BLOCKED - заблокированная карта 
-  * **block_date** - дата блокировки карты +  * **block_date** ​(get или post) - дата блокировки карты 
-  * **activate_date** - дата выдачи карты +  * **activate_date** ​(get или post) - дата выдачи карты 
-  * **type_id** - ID типа карты. Возможные типы карт настраиваются в административной панели системы +  * **type_id** ​(get или post) - ID типа карты. Возможные типы карт настраиваются в административной панели системы 
-  * **type_name** - Название типа карты. Используется только в том случае,​ если не передан параметр type_id. Если типа карты с указанным названием еще нет в системе,​ то он будет создан автоматически +  * **type_name** ​(get или post) - Название типа карты. Используется только в том случае,​ если не передан параметр type_id. Если типа карты с указанным названием еще нет в системе,​ то он будет создан автоматически 
-  * **customer_id** - ID клиента,​ которому принадлежит эта карта +  * **customer_id** ​(get или post) - ID клиента,​ которому принадлежит эта карта 
-  * **customer_external_id** - ID клиента во внешней системе,​ которому принадлежит эта карта. Используется только в случае,​ если не передан параметр customer_id+  * **customer_external_id** ​(get или post) - ID клиента во внешней системе,​ которому принадлежит эта карта. Используется только в случае,​ если не передан параметр customer_id
  
 ===== deleteCard - удаление дисконтной карты ===== ===== deleteCard - удаление дисконтной карты =====
-Удаление одной дисконтной карты. Для удаления карты необходимо передать один из следующих параметров:​+Удаление одной дисконтной карты. Для удаления карты необходимо передать один из следующих параметров ​(параметры обязательно передаются как get):
   * **card_id** - внутренний ID дисконтной карты. Если передан,​ то карта с указанным ID будет обновлена   * **card_id** - внутренний ID дисконтной карты. Если передан,​ то карта с указанным ID будет обновлена
   * **external_id** - ID дисконтной карты во внешней системе (например,​ в 1С)   * **external_id** - ID дисконтной карты во внешней системе (например,​ в 1С)
Строка 134: Строка 184:
 ===== insertCard - добавление дисконтной карты ===== ===== insertCard - добавление дисконтной карты =====
 Добавление новой дисконтной карты. Параметры запроса аналогичны updateCard ​ Добавление новой дисконтной карты. Параметры запроса аналогичны 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