Импорт дисконтных карт и анкет клиентов из ERP в SetRetail10

Для чтения визуальной составляющей схемы XSD, а также типами обязательных данных, ознакомьтесь с правилами использования.

Методы веб-сервиса для импорта дисконтных карт и анкет клиентов

Без обратной связи

МетодgetCardsCatalog
URLhttp://IP-адрес_сервера:8090/SET-ERPIntegration/SET/WSCardsCatalogImport
WSDLhttp://IP-адрес_сервера:8090/SET-ERPIntegration/SET/WSCardsCatalogImport?wsdl

Поле

Тип данных

Описание

Обязательное

Принимаемые параметры




cardsCatalogXML

base64Binary

Справочник карт и анкет клиентов в формате XML, кодированный с помощью base64Binary

Да

Возвращаемые параметры

return

boolean

True в случае успешной обработки пакета


Описание формата данных карт


C обратной связью

МетодgetCardsCatalogWithTi
URLhttp://IP-адрес_сервера:8090/SET-ERPIntegration/SET/WSCardsCatalogImport
WSDLhttp://IP-адрес_сервера:8090/SET-ERPIntegration/SET/WSCardsCatalogImport?wsdl

Поле

Тип данных

Описание

Обязательное

Принимаемые параметры

cardsCatalogXML

base64Binary

Справочник карт в формате XML кодированный с помощью base64Binary

Да

ti

String

Transaction Id - Номер передаваемого пакета данных, по которому можно будет получить обратную связь.

Нет

Возвращаемые параметры

return

boolean

True в случае успешной обработки пакета


Описание формата данных карт

Важно

Идентификатор пакета ti Transaction Id – является уникальным идентификатором этого пакета в SetRetail10, что накладывает определённые ограничения на повторный импорт пакета и загрузку разных типов данных с одним идентификатором.

Начисление бонусных баллов через веб-сервис

Для начисления бонусных баллов из ERP системы используйте веб-сервис и методы из статьи SetRetail10 ◾️ Ручное начисление бонусов.

Импорт карт <cards-catalog>

cards-catalog

Поле

Тип данных

Описание

Обязательное

internal-card-type

Комплексный

Список типов внутренних карт

Нет

internal-card

Комплексный

Список внутренних карт

Нет

bonus-account

Комплексный

Список обновлений бонусных счетов

Нет

Категории внутренних карт <internal-card-type>

cards-catalog/internal-card-type

Поле

Тип данных

Описание

Обязательное

guid

Long

Уникальный идентификатор категории внутренних карт. Ключевое поле.

Да

name

String

Название категории внутренних карт

Да

color

String

Цвет категории карты из списка:

  • BLUE
  • BRONZE
  • COPPER
  • GOLD
  • GREEN
  • GREY
  • IRON
  • ORANGE
  • PLATINUM
  • RED
  • SILVER
  • WHITE
  • YELLOW
Нет

personalized

Boolean

Признак персональной категории карт, для карт персонализированной категории система будет требовать заполнение анкеты

Нет

percentage-discount

Double

Процент скидки категории карт

Если не размер процента скидки отсутствует, тогда задается значение = 0

Да

work-period-start

Date

Дата начала действия категории, по умолчанию устанавливается время импорта

Нет

work-period-end

Date

Дата окончания действия категории, по умолчанию время срока действия категории карт не ограничен

Нет
show-card-from-range-notificationBoolean

Информировать кассира о добавлении карты из диапазона

Допустимые значения:

  • true
  • false
Нет

deleted

Boolean

Передается true для удаления категории

Допустимые значения:

  • true
  • false
Нет

card-range

Комплексный

Список диапазонов карт

Нет

Диапазон внутренних карт <card-range>

cards-catalog/internal-card-type/card-range

Поле

Тип данных

Описание

Обязательное

guid

Long

Уникальный идентификатор диапазона внутренних карт.

Ключевое поле

Да

startField

String

Номер первой карты диапазона

Да

countField

nonNegativeInteger

Количество карт в диапазоне

Да

deleted

Boolean

Передается true для удаления диапазона

Да

Экземпляры внутренних карт <internal-card>

cards-catalog/internal-card

Поле

Тип данныхОписаниеОбязательное

number

StringНомер картыДа

amount

DoubleСумма накоплений на картеНет

expiration-date

DateДата окончания срока действия, более приоритетный срок действия, чем общий срок действия категории картНет

status

Комплексный

Статус карты из списка

  • ACTIVE
  • BLOCKED
  • CREATE
  • INACTIVE
  • PRE_ACTIVE
  • PRE_DEACTIVE
  • PRE_USED
  • USED
Да

deleted

BooleanПередается true для удаления картыДа

card-type-guid

LongСсылка на идентификатор категории картНет

percentage-discount

DoubleПроцент скидки по карте. Заполняется, если не указан Card-type-guid. Карта будет привязана к категории с данным процентом картыНет

attached-to-counterparty

Boolean

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

Допустимые значения:

  • true
  • false
Нет

client

КомплексныйПривязка карты к клиентуНет

counterparty

КомплексныйПривязка карты к контрагенту (юридическому лицу)Нет

purchase-accumulation

КомплексныйНакопления по картеНет

Клиенты внутренних карт <client>

cards-catalog/internal-card/client

Поле

РазмерТип данныхОписаниеОбязательное

guid


LongИдентификатор клиентаДа

last-name

128StringФамилия клиентаНет

first-name

128StringИмя клиентаНет

middle-name

128StringОтчество клиентаНет

сlient-type


typeClient

Тип клиента:

  • PRIVATE – Физическое лицо
  • JURISTIC_PERSON – Юридическое лицо
Нет

birth-date


DateДата рождения клиентаНет

sex


sexType

Пол клиента. По умолчанию не указан.

  • MALE
  • FEMALE
Нет

marital


Boolean

Семейное положение: Замужем/Женат

Допустимые значения:

  • true
  • false
Нет

auto


Boolean

Наличие автомобиля

Допустимые значения:

  • true
  • false
Нет
pass-number12StringНомер паспортаНет
pass-serie12StringСерия паспортаНет
phone12StringТелефонНет
email128StringЭлектронная почта клиентаНет

city

128StringНазвание городаНет
region128StringРегион/Область

district

128StringРайонНет

district-area

128StringРайон городаНет

zip

6StringИндексНет

street

128StringУлицаНет

house

6StringНомер домаНет

building

6StringКорпус (строение)Нет

apartment

6StringКвартираНет
mobile-phone128StringМобильный телефонНет
smartphone-type
smartphoneType

Тип мобильного телефона

  • Android
  • iOS
  • Samsung
Нет
mobile-operator64StringОператор мобильной связи или выдавший картуНет
children-age12StringВозраст детей.Нет
delivery128StringКем выдан?Нет
delivery-date
DateКогда выдан?Нет
send-catalog
Boolean

Согласие на отправку каталога

Допустимые значения:

  • true
  • false
Нет
send-by-sms
Boolean

Согласие на отправку смс

Допустимые значения:

  • true
  • false
Нет

send-by-email


Boolean

Согласие на отправку по электронной почте

Допустимые значения:

  • true
  • false
Нет
shop-number5IntegerНомер магазина, в котором выдали картуНет
other255StringАдрес, прочая информацияНет
receipt-feedback
receipt-feedbackType

Способ оповещения этого держателя карты о совершенной покупке, а также для отправки электронных чеков ОФД.

  • BY_EMAIL - По электронной почте
  • BY_PHONE - СМС
Нет
wants-e-card
Booleand

Признак того, что клиент хочет получить электронную карту (отправлять на телефон или e-mail прислали png-изображение с штрих-кодом его номера карты).

По умолчанию: false

Допустимые значения:

  • true
  • false
Нет

deleted


Boolean

Признак удаления клиента

Допустимые значения:

  • true
  • false
Да

isCompleted


boolean

Признак заполненности анкеты клиента (по умолчанию false)

Допустимые значения:

  • true
  • false
Нет

Контрагенты внутренних карт (юридические лица) <counterparty>

Данная привязка означает, что дисконтная карта будет использоваться юридическим лицом.

cards-catalog/internal-card/counterparty

Поле

Тип данныхОписаниеОбязательное

inn

Integer

ИНН контрагента. Ключевое обязательное поле.

Да

kpp

Integer

КПП, не обязательное поле так как может отсутствовать у ИП

Да

name

String

Наименование Контрагента (короткое)

Да

full-name

String

Полное наименование контрагента.

Нет

address

String

Юридический адрес контрагента

Да

physical-address

String

Фактический адрес контрагента

Да

debitor-number

String

Идентификатор контрагента (дебитора) во внешней системе.

Да
debitor-typeString

Тип контрагента (дебитора) во внешней системе

  • mercury (вне зависимости от регистра) - контрагент зарегистрирован в системе "Меркурий"
  • Не mercury или отсутствие атрибута - контрагент не зарегистрирован в системе "Меркурий"
Да
Пример импорта юридического лица с привязкой к карте
<cards-catalog>
 
    <internal-card card-type-guid="12621262" number="12620001" expiration-date="2049-12-31T00:00:00" status="ACTIVE" attached-to-counterparty="true">
        <counterparty inn="1212121212" kpp="123456789" name="Тестовое юрлицо" full-name="" address="Тестовый адрес" debitor-number="1245648725"/>
		<client guid = "198116" last-name = "Юридический" first-name = "Роман" middle-name = "Аркадьевич" sex = "MALE" birth-date = "1976-05-01"
                email="roman@crystals.ru" send-by-email="true" receipt-feedback="BY_EMAIL"/>
    </internal-card>

  
</cards-catalog>

Привязка дисконтной карты Set10 к контрагенту используется в системе для возможности осуществления продажи юридическим лицам с соблюдением требований законодательства и автоматическим формированием и выдачей соответствующих сопроводительных документов.

Для возможности загрузки данных о контрагенте используется тег counterparty, в котором передаётся информация о самом юридическом лице, его наименовании и адресах – физическом и юридическом.

Привязка контрагента к карте осуществляется за счёт того, что тег <counterparty> вложен внутрь тега <Internal-card>.

Также осуществляется дополнительная проверка на то, что если у самой карты установлен атрибут attached-to-counterparty, то наличие корректного вложенного тега <counterparty> является обязательным условием импорта данной карты.

Пример возможной связки клиентов, карт и контрагентов:

Накопления по карте <purchase-accumulation>

cards-catalog/internal-card/purchase-accumulation

Поле

Тип данныхОписаниеОбязательное

operation-type

Boolean

Тип операции:

  • true – начисление
  • false – списание по возврату
Да

shop-number

Integer

Номер магазина

Да

cash-number

Integer

Номер кассы

Да

shift-number

Integer

Номер смены

Да

purchase-number

Integer

Номер чека

Да

purchase-date

DateTime

Дата чека

Да

purchase-sum

Integer

Сумма чека

Да

Бонусный баланс <bonus-account>

cards-catalog/bonus-account

Поле

Тип данныхОписаниеОбязательное

guid

Long

Идентификатор клиента

Да

bonus-update

String

Остаток бонусного счёта

Да

Особенности импорта данных карт

Обработка данных

Обработка пакета данных в модуле карт подразумевает следующие этапы:

  • Сохранение данных категорий карт, их экземпляров карт и клиентов в базе данных сервера SetRetail10 или SetCentrum.
  • Отправка данных на кассы (для SetRetail) и подчиненные магазины (для SetCentrum) через уже реализованные механизмы.

Оба этапа выполняются в одной транзакции для избежания потери данных в случае сбоев в работе.

Обработка категорий карт

  • В данных категории карт устанавливается свойства, которые наследуются всеми подчиненными ей картами. Наиболее важным из них является процент скидки по карте.
  • Важно понимать, что категории карт ввиду своей немногочисленности могут быть заведены непосредственно в SetRetail10. (Рекомендуется создавать категории карт в SetRetail10).
  • В процессе импорта из ERP, при получении данных категорий карт в секции internal-card-type данные в SetRetail10 перезаписываются безусловно. Идентификатором для перезаписи категории является поле guid.
  • При импорте недостающие, но необязательные к загрузке поля заполняются значением по умолчанию.
  • В случае отсутствия данных в поле work-period-end при импорте новой категории категория карт, их экземпляры становятся бессрочными.
  • В случае отсутствия необходимых данных для импорта категорий, категория карт будет отклонена системой.

Обработка диапазонов карт

  • Каждый диапазон карт привязан к одной категории карт.
  • Диапазоны карт используются в случае, когда нет причин вести карты поштучно (отсутствуют анкеты покупателей, не ведутся накопления и бонусные остатки).
  • Важно понимать, что диапазоны карт ввиду своей немногочисленности могут быть заведены непосредственно в SetRetail10.
  • В процессе импорта из ERP, при получении данных диапазонов карт в секции card-range, данные в SetRetail10 перезаписываются безусловно. Идентификатором для перезаписи диапазона карт является поле guid.
  • В случае отсутствия необходимых данных для импорта, диапазон карт будет отклонен системой.

Обработка экземпляров карт

  • Каждая карта привязана к одной категории карт и наследует свойства категории карты (процент скидки, необходимость заполнения анкеты, общий срок действия).
  • В процессе импорта из ERP, при получении данных экземпляров карт в секции internal-card, данные в SetRetail перезаписываются безусловно. Идентификатором для перезаписи является поле number.
  • При импорте, недостающие, но необязательные к загрузке поля, заполняются значением по умолчанию. Поле createDate заполняется при создании карты датой проведения импорта.
  • Привязка экземпляра карты к типу карт осуществляется через атрибут card-type-guid.
  • При загрузке из ERP, карты с cardTypeGuid, которых не соответствует ни одному guid из списка уже заведенных в SetRetail10 категорий карт, будут отклонены системой.

Альтернативная схема импорта карт:

  • В данной схеме в SetRetail10 должен быть загружен процент скидки по каждой карте, а атрибут card-type-guid должен отсутствовать,
  • Карта будет автоматически привязана механизмами SetRetail10, к уже имеющейся, в SetRetail10 категории с соответствующим значением percentage-discount. Такие категории карт, предварительно могут быть заведены в SetRetail10.
    • Если категории с таким discount-percent не существует, или одновременно не указан cardTypeGuid и percentage-discount, карта будет отклонена системой.

Обработка накоплений

  • Накопления не являются бонусными баллами.
  • В основном накопления предназначены для соблюдения условий по переходу из одной категорий карт в другую
  • Накопления в SetRetail10 ведутся в разрезе отдельных карт.
  • Накопления выгружаются только при первоначальном импорте карт для передачи данных об уже имеющихся накоплениях в SetRetail10 для дальнейшего ведения накопительного дисконта в SetRetail10. Данный функционал требуется для поддержки переноса ведения накопительного дисконта на SetRetail10 от других информационных систем. Данные накоплений загружаются из ERP в составе данных карт в поле amount.

Обработка данных клиентов

  • Данные клиентов не являются обязательными данными.
  • В случае, если данные не были отправлены, клиент не создается.
  • Каждый клиент может являться владельцем нескольких карт, или не иметь ни одной карты вообще.
  • При импорте к клиенту привязываются все присланные с ним карты.
  • Если с клиентом не отправлено ни одного экземпляра карт, создается клиент, к которому не привязано ни одной карты.
  • При получении данных клиентов в секции сlient данные перезаписываются безусловно. Идентификатором для перезаписи клиента является поле guid.
  • При импорте недостающие поля заполняются значением по умолчанию. В случае отсутствия необходимых данных для импорта клиентов, такие клиенты отклоняются системой.

В Set10 cуществуют две возможности разделения продажи на кассах для физических и юридических лиц.

  1. Привязка Дисконтной карты к контрагенту (к юрлицу). При этом у клиента могут быть как карты юридического лица, так и обычные дисконтные карты.
  2. Привязка Клиента – держателя карты к юридическому лицу. При этом все карты этого клиента считаются картами юридического лица.

Для изменения логики работы кассы при продаже товаров по таким картам, необходима дополнительная настройка в шаблонах касс.

Дисконтные карты юридических лиц

Привязка карт к контрагентам

  • Для осуществления привязки импортируемой дисконтной карты к контрагенту необходимо при импорте указать вложенную сущность counterparty с корректно заполненными атрибутами.
  • При этом необходимо дополнительно указать в карте, что она должна быть привязана к контрагенту (атрибут карты attached-to-counterparty).
  • При импорте произойдёт проверка наличия вложенного тега counterparty и проверка корректности заполнения требуемых полей по контрагенту, таких как ИНН, КПП и т.д.
  • Информация по контрагенту привящанному к такой карте, будет отображаться на вкладке Юридическое лицо в окне информации по карте в визуализации сервера SetRetail10.

Привязка клиентов к юридическим лицам

  • Для осуществления привязки импортируемого клиента карты к юридическому лицу необходимо при импорте клиента указать его тип в атрибуте сlient-type.
  • Возможные значения атрибута:
    • PRIVATE – физическое лицо.
    • JURISTIC_PERSON – юридическое лицо.
  • При такой привязке информация о самом юридическом лице указывается в анкетных данных клиента (либо не указывается вообще). 
  • Сам клиент становистся для системы юридическим лицом.