Это старая версия документа.
API :: Customer. Получение/изменение данных о Клиентах
В системе реализован программный интерфейс для получения, добавления и изменения данных о Клиентах (покупателях). Данные выгружаются по http протоколу. Формат на выбор - xml или json.
Пример запроса на получение данных
Пример запроса на получение данных об остатках товаров:
http://mycompany.virtpos.ru/api/customer?apikey=MySecret&format=xml
Параметры запроса
- apikey (get или post) - Секретный ключ для доступа к данным. Обязательный параметр.
- format (get only) - формат, в котором сервер отдаст данные. Может принимать значения «xml» или «json». Необязательный параметр.
- id (get only) - код клиента, для которого нужно вернуть данные. Если не указан, то возвращаются данные обо всех Клиентах.
- external_id (get only) - код Клиента во внешней системе, для которого нужно вернуть данные. Если не указан, то возвращаются данные обо всех Клиентах.
- phone - телефон клиента в свободной форме
- email - адрес электронной почты клиента
Ответ сервера
В ответ получаем XML или JSON. В ответе обязательно присутствует поле success. Если success=1, то операция выполнена успешно. Если success=0, то произошла ошибка. Дополнительная информация об ошибке содержится в поле info
Пример ответа сервера
Ниже приведен пример ответа сервера в формате 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>
Пример запроса на добавление/изменение данных
Пример запроса на получение данных о точке продаж:
http://mycompany.virtpos.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» если обновлена.
Пример ответа сервера
<?xml version="1.0" encoding="UTF-8"?> <root> <success>1</success> <id>11</id> <isnew>1</isnew> </root>
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