Различия
Здесь показаны различия между двумя версиями данной страницы.
Предыдущая версия справа и слева Предыдущая версия Следующая версия | Предыдущая версия | ||
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 | ||