Описание

Модуль процессинга Set Retail 10 предоставляет набор методов для работы с бонусными счетами клиентов торговой сети из любых внешних систем. Примерами таких систем могут быть CRM-модуль, личный кабинет на сайте торговой сети, стороннее кассовое решение. Описанные ниже методы позволяют обеспечить полный цикл управления бонусными баллами заказчика: получать информацию о текущем состоянии счетов клиента, начислять и списывать бонусные баллы, возвращать в случае необходимости и даже блокировать на время, если такой сценарий подразумевается бизнес-сценариями обслуживания клиента.

Адрес веб-сервиса для управления бонусными счетами

URL	http://IP-адрес_сервера:8090/SET-Cards/SET/Cards/ExternalSystemCardsProcessing
WSDL	http://IP-адрес_сервера:8090/SET-Cards/SET/Cards/ExternalSystemCardsProcessing?wsdl

Методы

Информация о карте и бонусных счетах

Информация по номеру карты о балансе активных бонусных баллов
Метод			getActiveBonusAccounts
Поле			Тип данных	Описание	Обязательное
Принимаемые параметры
cardNumber			String	Номер карты. Допустимые значения: буквы или цифры. Без специальных символов.	Да
Возвращаемые параметры
return			Комплексный	Коллекция элементов с данными по бонусному счёту.	Да
	balance		String	Баланс бонусных баллов.	Да
	bonusAccountId		Long	Идентификатор бонусного счета в БД сервера SetRetail/SetCentrum.	Да
	enabled		Boolean	Статус бонусного счёта: True - активный; False - неактивный.	Да
	bonusAccountsTypeVO		Комплексный	Коллекция элементов бонусного счета	Да
		accountsType	tns:bonusAccountsType	Тип бонусного счёта: NONE - отсутствует; MONEY - денежный (бонусный); GOODS - товарный; TOKENS - электронные фишки.	Да
		bonusAccountTypeCode	Long	Код типа бонусного счёта - уникальная сущность в рамках всей сети. Данный код будет отдаваться при создании плагина результата.	Да
		bonusAccountTypeId	Long	Уникальный идентификатор типа счета.	Да
		bonusAccountsTypeName	String	Наименование типа счета.	Да
		bonusCourse	Long	Курс бонусов к валюте.	Нет
		bonusList	tns:bonusAccountVO	Список бонусных счетов, привязанных к этому типу.	Нет
		currencyCourse	Long	Курс валюты счета.	Нет
		entirePurchase	Boolean	Оплата бонусами чека: True - полностью; False - частично.	Нет
		maxPaymentPercent	Long	Максимальный процент оплаты от суммы чека	Нет
		writeOffAllAmountAtOnce	Boolean	Списывать всю сумму бонусов за одно применение карты. True - списывать всё; False - списывать частично.	Да

Пример SOAP-запроса:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/">
   <soapenv:Header/>
   <soapenv:Body>
      <proc:getActiveBonusAccounts>
         <cardNumber>987987</cardNumber>
      </proc:getActiveBonusAccounts>
   </soapenv:Body>
</soapenv:Envelope>

Пример SOAP-ответа:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getActiveBonusAccountsResponse xmlns:ns2="http://processing.cards.crystals.ru/">
         <return>
            <balance>5079.79</balance>
            <bonusAccountId>155464</bonusAccountId>
            <bonusAccountsTypeVO>
               <accountsType>MONEY</accountsType>
               <bonusAccountTypeCode>153225</bonusAccountTypeCode>
               <bonusAccountTypeId>153225</bonusAccountTypeId>
               <bonusAccountsTypeName>Клиентский</bonusAccountsTypeName>
               <bonusCourse>100</bonusCourse>
               <currencyCourse>100</currencyCourse>
               <entirePurchase>true</entirePurchase>
               <writeOffAllAmountAtOnce>false</writeOffAllAmountAtOnce>
            </bonusAccountsTypeVO>
            <enabled>true</enabled>
         </return>
      </ns2:getActiveBonusAccountsResponse>
   </soap:Body>
</soap:Envelope>

Информация по номеру карты о балансе бонусных баллов, в зависимости от их статуса
Информация по баллам: активные; заблокированные; активные; неактивные; списанные.
Метод		getBonusAccountBalances
Поле		Тип данных	Описание	Обязательное
Принимаемые параметры
cardNumber		String	Номер карты. Допустимые значения: буквы или цифры. Без специальных символов.	Да
Возвращаемые параметры
return		Комплексный	Коллекция элементов с данными по бонусному счёту.	Да
	ammount	String	Баланс бонусных баллов.	Да
	balanceType	tns:balanceType	Статус бонусных баллов: ACTIVE - действующие; BLOCKED - заблокированные; WRITE_OFF - списанные; NOT_ACTIVE - неактивированные; REVOKED - отмененные (отозванные).	Да
	bonusAccountId	Long	Идентификатор бонусного счета в БД сервера SetRetail/SetCentrum.	Да

Пример SOAP-запроса:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/">
   <soapenv:Header/>
   <soapenv:Body>
      <proc:getBonusAccountBalances>
         <cardNumber>22022202</cardNumber>
      </proc:getBonusAccountBalances>
   </soapenv:Body>
</soapenv:Envelope>

Пример SOAP-ответа:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getBonusAccountBalancesResponse xmlns:ns2="http://processing.cards.crystals.ru/">
         <return>
            <ammount>23232300</ammount>
            <balanceType>ACTIVE</balanceType>
            <bonusAccountId>11661</bonusAccountId>
         </return>
         <return>
            <ammount>0</ammount>
            <balanceType>BLOCKED</balanceType>
            <bonusAccountId>11661</bonusAccountId>
         </return>
         <return>
            <ammount>0</ammount>
            <balanceType>WRITE_OFF</balanceType>
            <bonusAccountId>11661</bonusAccountId>
         </return>
         <return>
            <ammount>0</ammount>
            <balanceType>NOT_ACTIVE</balanceType>
            <bonusAccountId>11661</bonusAccountId>
         </return>
         <return>
            <ammount>46464600</ammount>
            <balanceType>REVOKED</balanceType>
            <bonusAccountId>11661</bonusAccountId>
         </return>
      </ns2:getBonusAccountBalancesResponse>
   </soap:Body>
</soap:Envelope>

Информация по номеру карты размера и даты следующей активации бонусных баллов на счету
Также можно получить размер и дату следующего сгорания бонусных баллов.
Метод			getBonusAccountsInformation
Поле			Тип данных	Описание	Обязательное
Принимаемые параметры
cardNumber			String	Номер карты. Допустимые значения: буквы или цифры. Без специальных символов.	Да
Возвращаемые параметры
return			Комплексный	Коллекция элементов с данными по бонусному счёту.	Да
	errorCode		Long	Код ошибки при вызове метода. Базовый список кодов ошибок для всех методов: 0 - <НЕТ ОШИБКИ> - запрос выполнен успешно; 1 - CARD_NOT_FOUND_ERROR - карта не найдена (номер карты не принадлежит к рабочим диапазонам); 2 - INCORRECT_CARD_ARGUMENT_ERROR - неправильный номер карты; 3 - INCORRECT_CHECK_UID_ARGUMENTS_ERROR - неправильный идентификатор (номер) чека; 4 - INCORRECT_ACCRUAL_SUM_ARGUMENT_ERROR - неправильный формат суммы начилсения; 5 - INCORRECT_EXPIRATION_DATE_ARGUMENT_ERROR - неправильная дата окончания действия; 6 - NO_ACTIVE_ACCOUNTS_FOR_CARD_ERROR - нет активных бонусных счетов для этой карты; 7 - BONUS_CHARGE_ERROR - ошибка начисления бонусов; 8 - BONUS_CANCEL_CHARGE_ERROR - ошибка отмены начисления бонуснов; 9 - INCORRECT_CANCEL_SUM_ARGUMENT_ERROR - некорректный формат суммы начисления; 10 - IN_PROCESS - операция в работе; 11 - INCORRECT_EXTERNAL_CODE - некорректный код из внешней системы (для этого кода нет ни одной операции).	Да
	errorText		String	Текст ошибки.	Да
	accounts		tns:bonusAccountInformationVO	Коллекция элементов с информацией по бонусным счетам.	Нет
		activeBonuses	Long	Действующие бонусные баллы.	Нет
		bonusAccountTypeId	Long	Идентификатор типа бонусного счета.	Нет
		nextActivationDate	DateTime	Следующая дата активации бонусных баллов.	Нет
		nextActivationSum	Long	Следующая сумма активации бонусных баллов.	Нет
		nextCancelingDate	DateTime	Следующая дата сгорания бонусных баллов.	Нет
		nextCancelingSum	Long	Следующая сумма сгорания бонусных баллов.	Нет
		nonActiveBonuses	Long	Неактивированные бонусные баллы.	Нет

Пример SOAP-запроса:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/">
   <soapenv:Header/>
   <soapenv:Body>
      <proc:getBonusAccountsInformation>
         <cardNumber>22022202</cardNumber>
      </proc:getBonusAccountsInformation>
   </soapenv:Body>
</soapenv:Envelope>

Пример SOAP-ответа:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getBonusAccountsInformationResponse xmlns:ns2="http://processing.cards.crystals.ru/">
         <return>
            <errorCode>0</errorCode>
            <errorText/>
            <accounts>
               <activeBonuses>23232300</activeBonuses>
               <bonusAccountTypeId>11657</bonusAccountTypeId>
               <nextActivationSum>0</nextActivationSum>
               <nextCancelingDate>2021-03-23T00:00:00+03:00</nextCancelingDate>
               <nextCancelingSum>23232300</nextCancelingSum>
               <nonActiveBonuses>0</nonActiveBonuses>
            </accounts>
         </return>
      </ns2:getBonusAccountsInformationResponse>
   </soap:Body>
</soap:Envelope>

Информация о клиентских счетах с бонусными баллами, которые сгорят до введённой даты
Метод		getBonusesExpiredAfterDate
Поле		Тип данных	Описание	Обязательное
Принимаемые параметры
expiredDate		DateTime	Дата после которой сгорят бонусные баллы: Варианты ввода: YYYY-MM-DD YYYY-MM-DDTHH:MM:SS YYYY-MM-DDTHH:MM:SS+HH:MM +HH:MM (Часовой пояс), например: +03:00	Да
Возвращаемые параметры
return		Комплексный	Коллекция элементов с данными по бонусному счёту и информацией по клиенту.	Да
	bonusAccountId	Long	Идентификатор бонусного счета в БД сервера SetRetail/SetCentrum.	Да
	bonusValue	Long	Размер бонусного баланса на счете.	Да
	cardNumber	String	Номер карты.	Да
	clientFIO	String	ФИО клиента.	Нет
	clientId	Long	Уникальный идентификатор анкеты клиенты.	Да
	compositionId	Long	Идентификатор детальной информации по балансу бонусного счёта клиента с датами сгорания бонусов.	Да
	email	String	Адрес электронной почты клиенты.	Нет
	expiredDate	DateTime	Дата окончания действия бонусных баллов.	Нет
	phone	String	Мобильный телефон.	Нет

Пример SOAP-запроса:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/">
   <soapenv:Header/>
   <soapenv:Body>
      <proc:getBonusesExpiredAfterDate>
         <expiredDate>2021-03-23T00:00:00</expiredDate>
      </proc:getBonusesExpiredAfterDate>
   </soapenv:Body>
</soapenv:Envelope>

Пример SOAP-ответа:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getBonusesExpiredAfterDateResponse xmlns:ns2="http://processing.cards.crystals.ru/">
         <return>
            <bonusAccountId>11661</bonusAccountId>
            <bonusValue>23232200</bonusValue>
            <cardNumber>22022202</cardNumber>
            <clientFIO>Иванов Иван Иванович</clientFIO>
            <clientId>11658</clientId>
            <compositionId>17888</compositionId>
            <email>test@csi.ru</email>
            <expiredDate>2021-03-23T00:00:00+03:00</expiredDate>
            <phone>+7-922-33-33-33</phone>
         </return>
      </ns2:getBonusesExpiredAfterDateResponse>
   </soap:Body>
</soap:Envelope>

Получить по номеру карты подробную информацию (данные категории карты, анкета владельца)
Метод								getCardInformationByNumber
Поле								Тип данных	Описание	Обязательное
Принимаемые параметры
cardNumber								String	Номер карты. Допустимые значения: буквы или цифры. Без специальных символов.	Да
Возвращаемые параметры
return								Комплексный	Коллекция элементов с данными по бонусному счёту и информацией по клиенту.	Да
	bonus							Boolean	Бонусный счет: True - бонусный; False - нет.	Нет
	bonusAccounts							Комплексный	Коллекция бонусных счетов клиента.	Нет
		balance						Long	Баланс бонусного счета.	Нет
		bonusAccountId						Long	Уникальный идентификатор бонусного счета.	Нет
		bonusAccountsTypeVO						Комплексный	Коллекция элементов бонусного счета.	Нет
			accountsType					tns:bonusAccountsType	Тип бонусного счёта: NONE - отсутствует; MONEY - денежный (бонусный); GOODS - товарный; TOKENS - электронные фишки.	Нет
			bonusAccountTypeCode					Long	Код типа бонусного счёта - уникальная сущность в рамках всей сети. Данный код будет отдаваться при создании плагина результата.	Нет
			bonusAccountTypeId					Long	Идентификатор типа бонусного счета.	Нет
			bonusAccountsTypeName					String	Нименование типа счета.	Нет
			bonusCourse					Long	Курс бонусов к валюте.	Нет
			currencyCourse					Long	Курс валюты счета.	Нет
			entirePurchase					Boolean	Оплата бонусами чека: True - полностью; False - частично.	Нет
			writeOffAllAmountAtOnce					Boolean	Списывать всю сумму бонусов за одно применение карты. True - списывать всё; False - списывать частично.	Нет
		enabled						Boolean	Статус бонусного счёта: True - активный; False - неактивный.	Нет
	cardNumber							String	Номер карты.	Да
	cardTypeVO							Комплексный	Коллекция элементов категории карты.	Да
		id						Long	Идентификатор категории карты.	Да
		classType						String	Тип внутреннего класса карты.	Да
		color						tns:displayColor	Коллекция элементов для цветовой маркировки карты в формате RGB.	Да
			blue					Integer	Синий	Да
			green					Integer	Зеленый	Да
			red					Integer	Красный	Да
		deleted						Boolean	Статус категории: True - удалена; False - действующая.	Да
		guid						Long	Уникальный GUID категории карт.	Да
		name						String	Наименование категории карт.	Да
		personalized						Boolean	Персонифицированная (к картам в этой категории можно заполнить анкету клиенты): True - удалена; False - действующая.	Да
		accumulative						Boolean	Накопительная (для перехода из категории в категории. Не бонусные баллы!): True - накопительная; False - без накоплений.	Да
		bonus						Boolean	Бонусная: True - бонусная; False - без учета бонусных баллов.	Да
		domesticCredit						Boolean	Внутренний кредит: True - включен; False - отключен.	Да
		finish						DateTime	Окончание срока действия.	Да
		percentageDiscount						Long	Размер скидки в процентах.	Да
		showCardFromRangeNotification						Boolean	Наличие правил перехода из одной категории в другую: True - есть; False - нет.	Нет
		start						DateTime	Начало срока действия.	Да
		withoutFinishDate						Boolean	Без срока окончания срока действия. True - есть срок действия; False - нет срока действия.	Нет
	cardVO							Комплексный	Коллекция элементов данных по экземпляру привязанной карты к счету.	Да
		id						Long	Идентификатор экземпляра привязаной карты.	Да
		activationDate						DateTime	Дата активации карты.	Да
		amount						Long	Количество накоплений для перехода из одной категории в другую.	Да
		balance						Long	Общий баланс накоплений (не бонусных).	Да
		blockDate						DateTime	Дата блокировки.	Нет
		blocked						Boolean	Статус блокировки: True - карта заблокирована; False - действующая.	Да
		cardTypeVO						Комплексный	Коллекция элементов категории карты. См. выше.	Нет
		clientVO						Комплексный	Коллекция элементов анкеты клиента.	Нет
			id					Long	Уникальный идентификатор анекты клиента.	Да
			auto					Boolean	Наличие автомобиля: True - есть; False - нет.	Нет
			birthDate					DateTime	Дата рождения.	Нет
			bonusBalance					Long	Количество бонусных баллов на счете.	Нет
			childrenAge					String	Дети.	Нет
			clientAddress					Комплексный	Коллекция элементов адреса анкеты клиента.	Нет
				appartment				String	Квартира.	Нет
				building				String	Корпус.	Нет
				city				String	Город.	Нет
				district				String	Район (НЕ ИСПОЛЬЗУЕТСЯ).	Нет
				districtArea				String	Район.	Нет
				house				String	Дом.	Нет
				other				String	Другое.	Нет
				region				String	Область (регион).	Нет
				street				String	Улица	Нет
				zip				String	Индекс	Нет
			clientType					tns:clientType	Тип клиента: PRIVATE - физическое лицо; JURISTIC_PERSON - юридическое лицо.	Да
			creationDate					DateTime	Дата создания анкеты.	Да
			deleted					Boolean	Статус анкеты: True - удалена; False - действующая.	Да
			email					String	Адрес элетронной почты.	Нет
			firstName					String	Имя.	Да
guid					Long	Уникальный GUID анекты клиента.	Да
isCompleted					Booelan	Статус анкеты: True - заполнена; False - не заполнена.	Да
lastChangeDate					DateTime	Дата последних изменений в анкете.	Да
lastName					String	Фамилия.	Да
marital					Boolean	Женат/замужем: True - да; False - нет.	Нет
middleName					String	Отчество.	Нет
mobileOperator					String	Оператор мобильной связи.	Нет
mobilePhone					String	Мобильный телефон.	Нет
passport					Комплексный	Коллекция элементов паспортных данных.	Нет
			delivery				String	Кем выдан.	Нет
			deliveryDate				String	Дата выдачи.	Нет
			passNumber				String	Номер.	Нет
			passSerie				String	Серия.	Нет
phone					String	Домашний телефон	Нет
receiptFeedbackType					String	Уведомление обладателя карты о совершенной покупке для отправки чека: 0 - не отправлять. 1 - отправлять чек на email; 2 - по SMS.	Да
sendBy					Комплексный	Комплекс элементов определяющих согласие на методы рассылки рекламного каталога.	Нет
			byEMail				Boolean	Отправлять по электронной почте. True - да; False - нет.	Нет
			byMail				Boolean	Отправлять по обычной почте. True - да; False - нет.	Нет
			byPhone				Boolean	Оповещение по телефону. True - да; False - нет.	Нет
			bySMS				Boolean	Отправлять SMS. True - да; False - нет.	Нет
sendCatalog					Boolean	Отправять рекламный каталог. True - да; False - нет.	Нет
sex					tns:sex	Пол: Male - мужской; Female - женский; Not_Specified - не указан.	Нет
shopNumber					Integer	Номер магазина.	Нет
smartphoneType					String	Тип смартфона: IOS ANDROID SAMSUNG	Нет
wantsECard					Boolean	Признак хочет ли клиент получить элетронную карту. True - да; False - нет.	Нет
counterpartyId						String	Идентификатор привязки к юридическому лицу: ИНН;КПП	Нет
createDate						DateTime	Дата создания клиента.	Да
deleted						Boolean	Статус клиента. True - заблокирован; False - действующий.	Да
guid						Long	Уникальный GUID клиента.	Да
number						Long	Номер карты	Да
signChangeOfCategoryCard						Boolean	Признак смены категории карты. True - возможна смена категории; False - нет.	Нет
signExtensionCard						Boolean	Признак продления карты. True - возможно проделнение срока действия; False - нет.	Нет
status						String	Статус карты: Create - карта создана; Active - карта активирована; Blocked - карта неактивна/заблокирована; Inactive - карта просрочена или устарела;	Да
domesticCredit							Boolean	Внутренний кредит: True - включен; False - отключен.	Да
personalized							Boolean	Персонифициарованная карта: True - да; False - нет.	Да

Пример SOAP-запроса:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/">
   <soapenv:Header/>
   <soapenv:Body>
      <proc:getCardInformationByNumber>
         <cardNumber>22022202</cardNumber>
      </proc:getCardInformationByNumber>
   </soapenv:Body>
</soapenv:Envelope>

Пример SOAP-ответа:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getCardInformationByNumberResponse xmlns:ns2="http://processing.cards.crystals.ru/">
         <return>
            <bonus>false</bonus>
            <bonusAccounts>
               <balance>232323</balance>
               <bonusAccountId>11661</bonusAccountId>
               <bonusAccountsTypeVO>
                  <accountsType>MONEY</accountsType>
                  <bonusAccountTypeCode>11657</bonusAccountTypeCode>
                  <bonusAccountTypeId>11657</bonusAccountTypeId>
                  <bonusAccountsTypeName>JFT</bonusAccountsTypeName>
                  <bonusCourse>100</bonusCourse>
                  <currencyCourse>100</currencyCourse>
                  <entirePurchase>true</entirePurchase>
                  <writeOffAllAmountAtOnce>false</writeOffAllAmountAtOnce>
               </bonusAccountsTypeVO>
               <enabled>true</enabled>
            </bonusAccounts>
            <cardNumber>22022202</cardNumber>
            <cardTypeVO xsi:type="ns2:internalCardsVO" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
               <id>11628</id>
               <classType>InternalCardsVO</classType>
               <color>
                  <blue>47</blue>
                  <green>223</green>
                  <red>116</red>
               </color>
               <deleted>false</deleted>
               <guid>11628</guid>
               <name>JFT</name>
               <personalized>true</personalized>
               <accumulative>false</accumulative>
               <bonus>false</bonus>
               <domesticCredit>false</domesticCredit>
               <finish>2019-11-26</finish>
               <percentageDiscount>0</percentageDiscount>
               <showCardFromRangeNotification>false</showCardFromRangeNotification>
               <start>2019-11-26</start>
               <withoutFinishDate>true</withoutFinishDate>
            </cardTypeVO>
            <cardVO>
               <id>11659</id>
               <activationDate>2019-11-26T16:21:09.679+03:00</activationDate>
               <amount>0</amount>
               <balance>0</balance>
               <blockDate/>
               <blocked>false</blocked>
               <cardTypeVO xsi:type="ns2:internalCardsVO" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                  <id>11628</id>
                  <classType>InternalCardsVO</classType>
                  <color>
                     <blue>47</blue>
                     <green>223</green>
                     <red>116</red>
                  </color>
                  <deleted>false</deleted>
                  <guid>11628</guid>
                  <name>JFT</name>
                  <personalized>true</personalized>
                  <accumulative>false</accumulative>
                  <bonus>false</bonus>
                  <domesticCredit>false</domesticCredit>
                  <finish>2019-11-26</finish>
                  <percentageDiscount>0</percentageDiscount>
                  <showCardFromRangeNotification>false</showCardFromRangeNotification>
                  <start>2019-11-26</start>
                  <withoutFinishDate>true</withoutFinishDate>
               </cardTypeVO>
               <clientVO>
                  <id>11658</id>
                  <auto>false</auto>
                  <birthDate>1984-02-24</birthDate>
                  <bonusBalance>2333400</bonusBalance>
                  <childrenAge>Катя 13, Миша, 14</childrenAge>
                  <clientAddress>
                     <appartment>234</appartment>
                     <building>1</building>
                     <city>Великий Новгород</city>
                     <district/>
                     <districtArea>Центральный</districtArea>
                     <house>2</house>
                     <other>2 этаж</other>
                     <region>Новгородская</region>
                     <street>Царская</street>
                     <zip>198332</zip>
                  </clientAddress>
                  <clientType>PRIVATE</clientType>
                  <creationDate>2019-11-26T16:21:08.993+03:00</creationDate>
                  <deleted>false</deleted>
                  <email>test@csi.ru</email>
                  <firstName>Иван</firstName>
                  <guid>11658</guid>
                  <isCompleted>true</isCompleted>
                  <lastChangeDate>2021-01-16T01:16:34.116+03:00</lastChangeDate>
                  <lastName>Иванов</lastName>
                  <marital>false</marital>
                  <middleName>Иванович</middleName>
                  <mobileOperator/>
                  <mobilePhone>+7-922-33-33-33</mobilePhone>
                  <passport>
                     <delivery>32 отделом полиции</delivery>
                     <deliveryDate>2007-12-12</deliveryDate>
                     <passNumber>123123</passNumber>
                     <passSerie>4000</passSerie>
                  </passport>
                  <phone>+7-233-21-31-23</phone>
                  <receiptFeedbackType>BY_PHONE</receiptFeedbackType>
                  <sendBy>
                     <byEMail>true</byEMail>
                     <byMail>false</byMail>
                     <byPhone>false</byPhone>
                     <bySMS>true</bySMS>
                  </sendBy>
                  <sendCatalog>true</sendCatalog>
                  <sex>Male</sex>
                  <shopNumber/>
                  <smartphoneType>IOS</smartphoneType>
                  <wantsECard>true</wantsECard>
               </clientVO>
               <counterpartyId>123456789000;545464654</counterpartyId>
               <createDate>2019-11-26T16:21:09.133+03:00</createDate>
               <deleted>false</deleted>
               <guid>0</guid>
               <number>22022202</number>
               <signChangeOfCategoryCard>false</signChangeOfCategoryCard>
               <signExtensionCard>false</signExtensionCard>
               <status>Create</status>
            </cardVO>
            <domesticCredit>false</domesticCredit>
            <personalized>true</personalized>
         </return>
      </ns2:getCardInformationByNumberResponse>
   </soap:Body>
</soap:Envelope>

Информация по номеру карты о статусе (активна, заблокирована и т.п.)
Метод		getCardStatus
Поле		Тип данных	Описание	Обязательное
Принимаемые параметры
cardNumber		String	Номер карты. Допустимые значения: буквы или цифры. Без специальных символов.	Да
Возвращаемые параметры
return		Комплексный	Коллекция элементов с информацией по статусу карты.	Да
	cardNumber	String	Номер карты	Да
	cardStatus	String	Статус карты: Create - карта создана; Active - карта активирована; Blocked - карта неактивна/заблокирована; Inactive - карта просрочена или устарела;	Да
	cardTypes	String	Тип карты: CardNotFound - карта не найдена/Неопределённый тип карты; InternalCard - внутренняя карта; ExternalCard - внешняя карта; PresentCard - подарочная карта; BonusCard - бонусная карта; CardCoupon - обычный серийный купон, создаётся на сервере; ChequeCoupon - чековый купон без контроля повторного применения; ProcessingCoupon - чековый/возвратный купон с префиксом 2999, создаётся на кассе, скидка расчитывается; UniqueCoupon - несерийный купон; ExternalCoupon - купон внешней системы.	Да

Пример SOAP-запроса:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/">
   <soapenv:Header/>
   <soapenv:Body>
      <proc:getCardStatus>
         <cardNumber>987987</cardNumber>
      </proc:getCardStatus>
   </soapenv:Body>
</soapenv:Envelope>

Пример SOAP-ответа:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getCardStatusResponse xmlns:ns2="http://processing.cards.crystals.ru/">
         <return>
            <cardNumber>987987</cardNumber>
            <cardStatus>Active</cardStatus>
            <cardTypes>InternalCard</cardTypes>
         </return>
      </ns2:getCardStatusResponse>
   </soap:Body>
</soap:Envelope>

Информация по номеру карты об анкете клиента
Метод			getClientInfoByCardNumber
Поле			Тип данных	Описание	Обязательное
Принимаемые параметры
cardNumber			String	Номер карты. Допустимые значения: буквы или цифры. Без специальных символов.	Да
Возвращаемые параметры
return			Комплексный	Коллекция элементов с информацией из анкеты клиента.	Да
	id		Long	Уникальный идентификатор анекты клиента.	Да
	auto		Boolean	Наличие автомобиля: True - есть; False - нет.	Нет
	birthDate		DateTime	Дата рождения.	Нет
	bonusBalance		Long	Количество бонусных баллов на счете.	Нет
	childrenAge		String	Дети.	Нет
	clientAddress		Комплексный	Коллекция элементов адреса анкеты клиента.	Нет
		appartment	String	Квартира.	Нет
		building	String	Корпус.	Нет
		city	String	Город.	Нет
		district	String	Район (НЕ ИСПОЛЬЗУЕТСЯ).	Нет
		districtArea	String	Район.	Нет
		house	String	Дом.	Нет
		other	String	Другое.	Нет
		region	String	Область (регион).	Нет
		street	String	Улица	Нет
		zip	String	Индекс	Нет
	clientType		tns:clientType	Тип клиента: PRIVATE - физическое лицо; JURISTIC_PERSON - юридическое лицо.	Да
	creationDate		DateTime	Дата создания анкеты.	Да
	deleted		Boolean	Статус анкеты: True - удалена; False - действующая.	Да
	email		String	Адрес элетронной почты.	Нет
	firstName		String	Имя.	Нет
	guid		Long	Уникальный GUID анекты клиента.	Нет
	isCompleted		Boolean	Статус анкеты: True - заполнена; False - не заполнена.	Да
	lastChangeDate		DateTime	Дата последних изменений в анкете.	Да
	lastName		String	Фамилия.	Да
	marital		Boolean	Женат/замужем: True - да; False - нет.	Нет
	middleName		String	Отчество.	Нет
	mobileOperator		String	Оператор мобильной связи.	Нет
	mobilePhone		String	Мобильный телефон.	Нет
	passport		Комплексный	Коллекция элементов паспортных данных.	Нет
		delivery	String	Кем выдан.	Нет
		deliveryDate	String	Дата выдачи.	Нет
		passNumber	String	Номер.	Нет
		passSerie	String	Серия.	Нет
	phone		String	Домашний телефон	Нет
	receiptFeedbackType		String	Уведомление обладателя карты о совершенной покупке для отправки чека: 0 - не отправлять. 1 - отправлять чек на email; 2 - по SMS.	Да
	sendBy		Комплексный	Комплекс элементов определяющих согласие на методы рассылки рекламного каталога.	Нет
		byEMail	Boolean	Отправлять по электронной почте. True - да; False - нет.	Нет
		byMail	Boolean	Отправлять по обычной почте. True - да; False - нет.	Нет
		byPhone	Boolean	Оповещение по телефону. True - да; False - нет.	Нет
		bySMS	Boolean	Отправлять SMS. True - да; False - нет.	Нет
	sendCatalog		Boolean	Отправять рекламный каталог. True - да; False - нет.	Нет
	sex		tns:sex	Пол: Male - мужской; Female - женский; Not_Specified - не указан.	Нет
	shopNumber		Integer	Номер магазина.	Нет
	smartphoneType		String	Тип смартфона: IOS ANDROID SAMSUNG	Нет
	wantsECard		Boolean	Признак хочет ли клиент получить элетронную карту. True - да; False - нет.	Нет

Пример SOAP-запроса:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/">
   <soapenv:Header/>
   <soapenv:Body>
      <proc:getClientInfoByCardNumber>
         <cardNumber>22022202</cardNumber>
      </proc:getClientInfoByCardNumber>
   </soapenv:Body>
</soapenv:Envelope>

Пример SOAP-ответа:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getClientInfoByCardNumberResponse xmlns:ns2="http://processing.cards.crystals.ru/">
         <return>
            <id>11658</id>
            <auto>false</auto>
            <birthDate>1984-02-24</birthDate>
            <bonusBalance>2333400</bonusBalance>
            <childrenAge>Катя 13, Миша, 14</childrenAge>
            <clientAddress>
               <appartment>234</appartment>
               <building>1</building>
               <city>Великий Новгород</city>
               <district/>
               <districtArea>Центральный</districtArea>
               <house>2</house>
               <other>2 этаж</other>
               <region>Новгородская</region>
               <street>Царская</street>
               <zip>198332</zip>
            </clientAddress>
            <clientType>PRIVATE</clientType>
            <creationDate>2019-11-26T16:21:08.993+03:00</creationDate>
            <deleted>false</deleted>
            <email>test@csi.ru</email>
            <firstName>Иван</firstName>
            <guid>11658</guid>
            <isCompleted>true</isCompleted>
            <lastChangeDate>2021-01-16T01:16:34.116+03:00</lastChangeDate>
            <lastName>Иванов</lastName>
            <marital>false</marital>
            <middleName>Иванович</middleName>
            <mobileOperator/>
            <mobilePhone>+7-922-33-33-33</mobilePhone>
            <passport>
               <delivery>32 отделом полиции</delivery>
               <deliveryDate>2007-12-12</deliveryDate>
               <passNumber>123123</passNumber>
               <passSerie>4000</passSerie>
            </passport>
            <phone>+7-233-21-31-23</phone>
            <receiptFeedbackType>BY_PHONE</receiptFeedbackType>
            <sendBy>
               <byEMail>true</byEMail>
               <byMail>false</byMail>
               <byPhone>false</byPhone>
               <bySMS>true</bySMS>
            </sendBy>
            <sendCatalog>true</sendCatalog>
            <sex>Male</sex>
            <shopNumber/>
            <smartphoneType>IOS</smartphoneType>
            <wantsECard>true</wantsECard>
         </return>
      </ns2:getClientInfoByCardNumberResponse>
   </soap:Body>
</soap:Envelope>

Начисление и списание бонусных баллов

Начислить бонусные баллы на счет клиента
Метод		chargeOnBonusAccount
Поле		Тип данных	Описание	Обязательное
Принимаемые параметры
cardNumber		String	Номер карты. Допустимые значения: буквы или цифры. Без специальных символов.	Да
bonusAccountType		Long	Идентификатор типа бонусного счета. Варианта просмотра идентификатора: База данных set → таблицаcards_bonusaccountstype → поле bonusaccounttypecode. Или через один из методов получения информации по карте, где есть `bonusAccountType`.	Нет
shopNum		Long	Номер магазина.	Да
cashNum		Long	Номер кассы.	Да
shiftNum		Long	Номер смены.	Да
checkNum		Long	Номер чека.	Да
chargeSum		Long	Сумма начисления в копейках: Например: нужно начислисть 200.22 бонусных балла, тогда значение = 20022	Да
activatingDate		DateTime	Дата активации бонусных баллов.	Да
expirationDate		DateTime	Дата сгорания бонусных баллов	Нет
Возвращаемые параметры
return		Комплексный	Коллекция элементов обратной связи при вызове метода.	Да
	errorCode	Long	Код ошибки при вызове метода. Базовый список кодов ошибок для всех методов: 0 - <НЕТ ОШИБКИ> - запрос выполнен успешно; 1 - CARD_NOT_FOUND_ERROR - карта не найдена (номер карты не принадлежит к рабочим диапазонам); 2 - INCORRECT_CARD_ARGUMENT_ERROR - неправильный номер карты; 3 - INCORRECT_CHECK_UID_ARGUMENTS_ERROR - неправильный идентификатор (номер) чека; 4 - INCORRECT_ACCRUAL_SUM_ARGUMENT_ERROR - неправильный формат суммы начилсения; 5 - INCORRECT_EXPIRATION_DATE_ARGUMENT_ERROR - неправильная дата окончания действия; 6 - NO_ACTIVE_ACCOUNTS_FOR_CARD_ERROR - нет активных бонусных счетов для этой карты; 7 - BONUS_CHARGE_ERROR - ошибка начисления бонусов; 8 - BONUS_CANCEL_CHARGE_ERROR - ошибка отмены начисления бонуснов; 9 - INCORRECT_CANCEL_SUM_ARGUMENT_ERROR - некорректный формат суммы начисления; 10 - IN_PROCESS - операция в работе; 11 - INCORRECT_EXTERNAL_CODE - некорректный код из внешней системы (для этого кода нет ни одной операции).	Да
	errorText	String	Текст ошибки.	Нет
	transactionId	Long	Идентификатор тразнакции/операции по бонусному счету	Да

Пример SOAP-запроса:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/">
   <soapenv:Header/>
   <soapenv:Body>
      <proc:chargeOnBonusAccount>
         <!--Номер карты-->
         <cardNumber>22022202</cardNumber>
        <!--id бонусного счета
        Необязательно (БД SET -> таблица cards_bonusaccountstype -> столбец bonusaccounttypecode)
         <bonusAccountType>11657</bonusAccountType>-->
         <!--Номер магазина-->
         <shopNum>234</shopNum>
         <!--Номер кассы:-->
         <cashNum>2</cashNum>
         <!--Номер смены:-->
         <shiftNum>1</shiftNum>
         <!--Номер чека:-->
         <checkNum>200</checkNum>
         <!--Сумма начисления в копейках:
         Например: Нужно начислисть 200.22
         Значение 20022
         -->
         <chargeSum>20022</chargeSum>
         <!--Дата активации бонусных баллов-->
         <activatingDate>2021-01-01</activatingDate>
         <!--Дата сгорания бонусных баллов-->
         <expirationDate>2027-01-31</expirationDate>
      </proc:chargeOnBonusAccount>
   </soapenv:Body>
</soapenv:Envelope>

Пример SOAP-ответа:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:chargeOnBonusAccountResponse xmlns:ns2="http://processing.cards.crystals.ru/">
         <return>
            <errorCode>0</errorCode>
            <errorText/>
            <transactionId>31746</transactionId>
         </return>
      </ns2:chargeOnBonusAccountResponse>
   </soap:Body>
</soap:Envelope>

Результат операции в SetRetail:

Отмена начисления бонусных баллов на счет клиента (отмена по возврату)
Метод		cancelChargeOnBonusAccount
Поле		Тип данных	Описание	Обязательное
Принимаемые параметры
cardNumber		String	Номер карты. Допустимые значения: буквы или цифры. Без специальных символов.	Да
bonusAccountType		Long	Идентификатор типа бонусного счета. Варианта просмотра идентификатора: База данных set → таблицаcards_bonusaccountstype → поле bonusaccounttypecode. Или через один из методов получения информации по карте, где есть `bonusAccountType`.	Нет
shopNum		Long	Номер магазина.	Нет
cashNum		Long	Номер кассы.	Нет
shiftNum		Long	Номер смены.	Нет
checkNum		Long	Номер чека.	Нет
cancelSum		Long	Сумма отмены в копейках: Например: нужно отменить 200.22 бонусных балла, тогда значение = 20022	Нет
Возвращаемые параметры
return		Комплексный	Коллекция элементов обратной связи при вызове метода.	Да
	errorCode	Long	Код ошибки при вызове метода. Базовый список кодов ошибок для всех методов: 0 - <НЕТ ОШИБКИ> - запрос выполнен успешно; 1 - CARD_NOT_FOUND_ERROR - карта не найдена (номер карты не принадлежит к рабочим диапазонам); 2 - INCORRECT_CARD_ARGUMENT_ERROR - неправильный номер карты; 3 - INCORRECT_CHECK_UID_ARGUMENTS_ERROR - неправильный идентификатор (номер) чека; 4 - INCORRECT_ACCRUAL_SUM_ARGUMENT_ERROR - неправильный формат суммы начилсения; 5 - INCORRECT_EXPIRATION_DATE_ARGUMENT_ERROR - неправильная дата окончания действия; 6 - NO_ACTIVE_ACCOUNTS_FOR_CARD_ERROR - нет активных бонусных счетов для этой карты; 7 - BONUS_CHARGE_ERROR - ошибка начисления бонусов; 8 - BONUS_CANCEL_CHARGE_ERROR - ошибка отмены начисления бонуснов; 9 - INCORRECT_CANCEL_SUM_ARGUMENT_ERROR - некорректный формат суммы начисления; 10 - IN_PROCESS - операция в работе; 11 - INCORRECT_EXTERNAL_CODE - некорректный код из внешней системы (для этого кода нет ни одной операции).	Нет
	errorText	String	Текст ошибки.	Нет
	cancelActiveSum	Long	Количество отмененных активных бонусных баллов.	Нет
	cancelNonActiveSum	Long	Количество отмененных неактивных баллов.	Нет

Пример SOAP-запроса:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/">
   <soapenv:Header/>
   <soapenv:Body>
      <proc:cancelChargeOnBonusAccount>
         <cardNumber>22022202</cardNumber>
         <bonusAccountType>11657</bonusAccountType>
         <shopNum>234</shopNum>
         <cashNum>2</cashNum>
         <shiftNum>2</shiftNum>
         <checkNum>2</checkNum>
         <cancelSum>1822</cancelSum>
      </proc:cancelChargeOnBonusAccount>
   </soapenv:Body>
</soapenv:Envelope>

Пример SOAP-ответа:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:cancelChargeOnBonusAccountResponse xmlns:ns2="http://processing.cards.crystals.ru/">
         <return>
            <errorCode>0</errorCode>
            <errorText/>
            <cancelActiveSum>1822</cancelActiveSum>
            <cancelNonActiveSum>0</cancelNonActiveSum>
         </return>
      </ns2:cancelChargeOnBonusAccountResponse>
   </soap:Body>
</soap:Envelope>

Результат операции в SetRetail:

Списание активных бонусных баллов со счета клиента
Метод		writeOffFromBonusAccount
Поле		Тип данных	Описание	Обязательное
Принимаемые параметры
accountTypeCode		Long	Идентификатор бонусного счета. Варианта просмотра идентификатора: База данных set → таблицаcards_bonusaccountstype → поле bonusaccounttypecode. Или через один из методов получения информации по карте, где есть `bonusAccountType`.	Да
cardNumber		String	Номер карты. Допустимые значения: буквы или цифры. Без специальных символов.	Нет
writeOffSum		Double	Сумма отмены в копейках c разделителем в виде точки: Например: нужно отменить 200.22 бонусных балла, тогда значение = 200.22 Если сумма указана без точки, тогда будет начислено целое число.	Да
purchaseUid		Комплексный	Коллекция элементов с информацией по чеку.	Нет
	cashNum	Long	Номер кассы.	Нет
	checkNum	Long	Номер чека.	Нет
	createDate	Long	Дата чека.	Нет
	shiftNum	Long	Номер смены.	Нет
	shopNum	Long	Номер магазина.	Нет
Возвращаемые параметры
return		Boolean	Результат операции: True - успешено; False - операция не удалась.	Да

Пример SOAP-запроса:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/">
   <soapenv:Header/>
   <soapenv:Body>
      <proc:writeOffFromBonusAccount>
         <accountTypeCode>11657</accountTypeCode>
         <cardNumber>22022202</cardNumber>
         <writeOffSum>2099</writeOffSum>
         <purchaseUid>
            <cashNum>2</cashNum>
            <checkNum>1</checkNum>
            <createDate>2021-01-16</createDate>
            <shiftNum>3</shiftNum>
            <shopNum>234</shopNum>
         </purchaseUid>
      </proc:writeOffFromBonusAccount>
   </soapenv:Body>
</soapenv:Envelope>

Пример SOAP-ответа:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:writeOffFromBonusAccountResponse xmlns:ns2="http://processing.cards.crystals.ru/">
         <return>true</return>
      </ns2:writeOffFromBonusAccountResponse>
   </soap:Body>
</soap:Envelope>

Результат операции в SetRetail:

Возврат бонусных баллов на счет клиента
Метод		returnPaymentToBonusAccount
Поле		Тип данных	Описание	Обязательное
Принимаемые параметры
accountTypeCode		Long	Идентификатор бонусного счета. Варианта просмотра идентификатора: База данных set → таблицаcards_bonusaccountstype → поле bonusaccounttypecode. Или через один из методов получения информации по карте, где есть `bonusAccountType`.	Да
cardNumber		String	Номер карты. Допустимые значения: буквы или цифры. Без специальных символов.	Нет
chargeSum		Double	Сумма возврата бонусных баллов в копейках c разделителем в виде точки: Например: нужно вернуть 200.22 бонусных балла, тогда значение = 200.22 Если сумма указана без точки, тогда будет начислено целое число.	Да
purchaseUid		Комплексный	Коллекция элементов с информацией по чеку.	Нет
	cashNum	Long	Номер кассы.	Нет
	checkNum	Long	Номер чека.	Нет
	createDate	Long	Дата чека.	Нет
	shiftNum	Long	Номер смены.	Нет
	shopNum	Long	Номер магазина.	Нет
Возвращаемые параметры
ns2:returnPaymentToBonusAccountResponse			Результат операции. Успешная операция без текста ответа.	Да

Пример SOAP-запроса:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/">
   <soapenv:Header/>
   <soapenv:Body>
      <proc:returnPaymentToBonusAccount>
         <accountTypeCode>11657</accountTypeCode>
         <cardNumber>22022202</cardNumber>
         <chargeSum>2099</chargeSum>
         <purchaseUid>
            <cashNum>1</cashNum>
            <checkNum>3</checkNum>
            <createDate>2021-01-16</createDate>
            <shiftNum>23</shiftNum>
            <shopNum>234</shopNum>
         </purchaseUid>
      </proc:returnPaymentToBonusAccount>
   </soapenv:Body>
</soapenv:Envelope>

Пример SOAP-ответа:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:returnPaymentToBonusAccountResponse xmlns:ns2="http://processing.cards.crystals.ru/"/>
   </soap:Body>
</soap:Envelope>

Результат операции в SetRetail:

Пакетное начисление бонусных баллов (для большого количества карт)

Для того, чтобы пакетная обработка бонусных начислений происходила эффективно и задания не оставались в базе данных set → таблицы external_operation_bonus_charge_on установите параметр в базе данных set → таблицы sales_management_properties → строки external.bonus.operation.processing.interval.in.seconds (период обработки бонусных операций пришедших из внешних систем (по умолчанию 0 - не обрабатывать).

Настройка времени обработки пакетов начислений

Для того, чтобы установить периоды обработки пакетов начисления бонусных баллов, например для более ускоренного отображения их после начисления, измените настройки в БД set таблице sales_management_properties, модуль SET_CARDS_COMMON

Название	Описание	По умолчанию
external.bonus.operation.processing.interval.in.seconds	Период обработки бонусных операций пришедших из внешних систем (по умолчанию 0 - не обрабатывать) в секундах. Для начала работы с операцией пакетного начисления нужно выставить желаемую частоту обработки в секундах (60 - 1 раз за 60 секунд).	0
external.bonus.operation.processing.count	Количество операций которое будем пытаться обработать за одно срабатывание таймера	50

Пакетное начисление бонусных баллов на счета клиентов
Предназначен для начисления бонусов определенному сегменту клиентов. При этом каждому пакету назначается уникальный номер `externalId`, по которому можно отследить статус выполнения операции по начислению.
Метод		packageChargeOnBonusAccounts
Поле		Тип данных	Описание	Обязательное
Принимаемые параметры
operations		Комплексный	Коллекция элементов по операциям с бонусными счетами	Да
	activatingDate	DateTime	Дата активации бонусных баллов.	Да
	bonusAccountType	Long	Идентификатор бонусного счета. Варианта просмотра идентификатора: База данных set → таблицаcards_bonusaccountstype → поле bonusaccounttypecode. Или через один из методов получения информации по карте, где есть `bonusAccountType`.	Да
	cardNumber	String	Номер карты. Допустимые значения: буквы или цифры. Без специальных символов.	Да
	cashNum	Long	Номер кассы.	Да
	chargeSum	Long	Сумма начисления в копейках: Например: нужно начислисть 200.22 бонусных балла, тогда значение = 20022	Да
	checkNum	Long	Номер чека.	Да
	expirationDate	DateTime	Дата сгорания бонусных баллов.	Да
	requestId	Long	Индентификатор операции внутри запроса	Да
	createDate	Long	Дата чека.	Да
	shiftNum	Long	Номер смены.	Да
	shopNum	Long	Номер магазина.	Да
externalId		Long	Уникальный номер пакета для отслеживания операции.	Да
Возвращаемые параметры
return		Boolean	Результат операции: True - успешено; False - операция не удалась.	Да

Пример SOAP-запроса:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/">
   <soapenv:Header/>
   <soapenv:Body>
      <proc:packageChargeOnBonusAccounts>
         <!--Zero or more repetitions:-->
         <operations>
            <activatingDate>2021-01-16</activatingDate>
            <bonusAccountType>11657</bonusAccountType>
            <cardNumber>22022202</cardNumber>
            <cashNum>1</cashNum>
            <chargeSum>99999</chargeSum>
            <checkNum>1</checkNum>
            <expirationDate>2025-01-01</expirationDate>
            <requestId>879</requestId>
            <shiftNum>1</shiftNum>
            <shopNum>234</shopNum>
         </operations>
         <externalId>2134</externalId>
      </proc:packageChargeOnBonusAccounts>
   </soapenv:Body>
</soapenv:Envelope>

Пример SOAP-ответа:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:packageChargeOnBonusAccountsResponse xmlns:ns2="http://processing.cards.crystals.ru/">
         <return>true</return>
      </ns2:packageChargeOnBonusAccountsResponse>
   </soap:Body>
</soap:Envelope>

Запрос статуса пакета с начислением бонусов выполненных пакетным сценарием
Метод		getResultOfPackageChargeOnBonusAccounts
Поле		Тип данных	Описание	Обязательное
Принимаемые параметры
externalId		Long	Уникальный номер пакета для отслеживания операции.	Да
Возвращаемые параметры
return		Комплексный		Да
	errorCode	Long	Код ошибки при вызове метода. Базовый список кодов ошибок для всех методов: 0 - <НЕТ ОШИБКИ> - запрос выполнен успешно; 1 - CARD_NOT_FOUND_ERROR - карта не найдена (номер карты не принадлежит к рабочим диапазонам); 2 - INCORRECT_CARD_ARGUMENT_ERROR - неправильный номер карты; 3 - INCORRECT_CHECK_UID_ARGUMENTS_ERROR - неправильный идентификатор (номер) чека; 4 - INCORRECT_ACCRUAL_SUM_ARGUMENT_ERROR - неправильный формат суммы начилсения; 5 - INCORRECT_EXPIRATION_DATE_ARGUMENT_ERROR - неправильная дата окончания действия; 6 - NO_ACTIVE_ACCOUNTS_FOR_CARD_ERROR - нет активных бонусных счетов для этой карты; 7 - BONUS_CHARGE_ERROR - ошибка начисления бонусов; 8 - BONUS_CANCEL_CHARGE_ERROR - ошибка отмены начисления бонуснов; 9 - INCORRECT_CANCEL_SUM_ARGUMENT_ERROR - некорректный формат суммы начисления; 10 - IN_PROCESS - операция в работе; 11 - INCORRECT_EXTERNAL_CODE - некорректный код из внешней системы (для этого кода нет ни одной операции).	Да
	errorText	String	Текст ошибки.	Да
	externalId	Long	Уникальный номер пакета для отслеживания операции.	Да

Пример SOAP-запроса:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/">
   <soapenv:Header/>
   <soapenv:Body>
      <proc:getResultOfPackageChargeOnBonusAccounts>
         <externalId>21341</externalId>
      </proc:getResultOfPackageChargeOnBonusAccounts>
   </soapenv:Body>
</soapenv:Envelope>

Пример SOAP-ответа:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getResultOfPackageChargeOnBonusAccountsResponse xmlns:ns2="http://processing.cards.crystals.ru/">
         <return>
            <errorCode>10</errorCode>
            <errorText>IN_PROCESS</errorText>
            <externalId>21341</externalId>
         </return>
      </ns2:getResultOfPackageChargeOnBonusAccountsResponse>
   </soap:Body>
</soap:Envelope>

Блокировка бонусных баллов

Блокировка бонусных баллов на счете клиента
Метод	blockingAmountFromBonusAccount
Поле	Тип данных	Описание	Обязательное
Принимаемые параметры
accountTypeCode	Long	Идентификатор бонусного счета. Варианта просмотра идентификатора: База данных set → таблицаcards_bonusaccountstype → поле bonusaccounttypecode. Или через один из методов получения информации по карте, где есть `bonusAccountType`.	Да
cardNumber	String	Номер карты. Допустимые значения: буквы или цифры. Без специальных символов.	Нет
writeOffSum	Double	Сумма отмены в копейках c разделителем в виде точки: Например: нужно отменить 200.22 бонусных балла, тогда значение = 200.22 Если сумма указана без точки, тогда будет начислено целое число.	Да
Возвращаемые параметры
return	Boolean	Результат операции: True - успешено; False - операция не удалась.	Да

Пример SOAP-запроса:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/">
   <soapenv:Header/>
   <soapenv:Body>
      <proc:blockingAmountFromBonusAccount>
         <accountTypeCode>11657</accountTypeCode>
         <cardNumber>22022202</cardNumber>
         <writeOffSum>1099</writeOffSum>
      </proc:blockingAmountFromBonusAccount>
   </soapenv:Body>
</soapenv:Envelope>

Пример SOAP-ответа:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:blockingAmountFromBonusAccountResponse xmlns:ns2="http://processing.cards.crystals.ru/">
         <return>true</return>
      </ns2:blockingAmountFromBonusAccountResponse>
   </soap:Body>
</soap:Envelope>

Результат в SetRetail:

d

Разблокировать бонусные баллы на счете клиента
Метод	unlockingAmountFromBonusAccount
Поле	Тип данных	Описание	Обязательное
Принимаемые параметры
accountTypeCode	Long	Идентификатор бонусного счета. Варианта просмотра идентификатора: База данных set → таблицаcards_bonusaccountstype → поле bonusaccounttypecode. Или через один из методов получения информации по карте, где есть `bonusAccountType`.	Да
cardNumber	String	Номер карты. Допустимые значения: буквы или цифры. Без специальных символов.	Нет
writeOffSum	Double	Сумма отмены в копейках c разделителем в виде точки: Например: нужно отменить 200.22 бонусных балла, тогда значение = 200.22 Если сумма указана без точки, тогда будет начислено целое число.	Да
Возвращаемые параметры
return	Boolean	Результат операции: True - успешено; False - операция не удалась.	Да

Пример SOAP-запроса:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/">
   <soapenv:Header/>
   <soapenv:Body>
      <proc:unlockingAmountFromBonusAccount>
         <accountTypeCode>11657</accountTypeCode>
         <cardNumber>22022202</cardNumber>
         <writeOffSum>1099</writeOffSum>
      </proc:unlockingAmountFromBonusAccount>
   </soapenv:Body>
</soapenv:Envelope>

Пример SOAP-ответа:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:unlockingAmountFromBonusAccountResponse xmlns:ns2="http://processing.cards.crystals.ru/">
         <return>true</return>
      </ns2:unlockingAmountFromBonusAccountResponse>
   </soap:Body>
</soap:Envelope>

Результат в SetRetail:

Списать заблокированные бонусные баллы со счета клиента
Метод		writeOffBlockedFromBonusAccount
Поле		Тип данных		Описание	Обязательное
Принимаемые параметры
accountTypeCode		Long		Идентификатор бонусного счета. Варианта просмотра идентификатора: База данных set → таблицаcards_bonusaccountstype → поле bonusaccounttypecode. Или через один из методов получения информации по карте, где есть `bonusAccountType`.	Да
cardNumber		String		Номер карты. Допустимые значения: буквы или цифры. Без специальных символов.	Нет
writeOffSum		Double		Сумма отмены в копейках c разделителем в виде точки: Например: нужно отменить 200.22 бонусных балла, тогда значение = 200.22 Если сумма указана без точки, тогда будет начислено целое число.	Да
purchaseUid		Комплексный		Номер кассы.	Нет
	cashNum	Long		Номер чека.	Нет
	checkNum	Long		Дата чека.	Нет
	createDate	Long		Дата чека.	Нет
	shiftNum	Long		Номер смены.	Нет
	shopNum	Long		Номер магазина.	Нет
Возвращаемые параметры
return			Boolean	Результат операции: True - успешено; False - операция не удалась.	Да

Пример SOAP-запроса:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/">
   <soapenv:Header/>
   <soapenv:Body>
      <proc:writeOffBlockedFromBonusAccount>
         <accountTypeCode>11657</accountTypeCode>
         <cardNumber>22022202</cardNumber>
         <writeOffSum>1099</writeOffSum>
         <purchaseUid>
            <cashNum>13</cashNum>
            <checkNum>13</checkNum>
            <createDate>2021-01-16</createDate>
            <shiftNum>13</shiftNum>
            <shopNum>234</shopNum>
         </purchaseUid>
      </proc:writeOffBlockedFromBonusAccount>
   </soapenv:Body>
</soapenv:Envelope>

Пример SOAP-ответа:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:writeOffBlockedFromBonusAccountResponse xmlns:ns2="http://processing.cards.crystals.ru/">
         <return>true</return>
      </ns2:writeOffBlockedFromBonusAccountResponse>
   </soap:Body>
</soap:Envelope>

Результат в SetRetail:

Управление бонусными баллами на примере SOAP UI

Ручное начисление бонусов

Подробная инструкция по работе SOAP UI.

1. Откройте SOAP → нажмите SOAP.

2. Введите настройки для подключения веб-сервиса управления бонусными счетами, который описан в интеграционной документации:

[Project Name] - введите любое наименование проекта.
Initalial WSDL - введите адрес веб-сервиса управления бонусными баллами на стороне сервера SetRetail10.
Нажмите OK.

3. Разверните добавленный проект → разверните метод chargeOnBonusAccount → откройте двумя кликами мыши Request 1.

4. Создайте SOAP-запрос на основе примера и описания полей с данными из метода chargeOnBonusAccount вставьте его в окно запроса.

Пример SOAP-запроса:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/">
   <soapenv:Header/>
   <soapenv:Body>
      <proc:chargeOnBonusAccount>
         <!--Номер карты-->
         <cardNumber>22022202</cardNumber>
        <!--id бонусного счета
        Необязательно (БД SET -> таблица cards_bonusaccountstype -> столбец bonusaccounttypecode)-->
         <bonusAccountType>11657</bonusAccountType>
         <!--Номер магазина-->
         <shopNum>234</shopNum>
         <!--Номер кассы:-->
         <cashNum>2</cashNum>
         <!--Номер смены:-->
         <shiftNum>1</shiftNum>
         <!--Номер чека:-->
         <checkNum>200</checkNum>
         <!--Сумма начисления в копейках:
         Например: Нужно начислисть 200.22
         Значение 20022
         -->
         <chargeSum>300099</chargeSum>
         <!--Дата активации бонусных баллов-->
         <activatingDate>2021-01-01</activatingDate>
         <!--Дата сгорания бонусных баллов-->
         <expirationDate>2027-01-31</expirationDate>
      </proc:chargeOnBonusAccount>
   </soapenv:Body>
</soapenv:Envelope>

5. Нажмите для выполнения запроса.

6. По результату выполнения запроса, отобразится ответное сообщение:

7. Проверьте начисление бонусных баллов на счете клиента в истории бонусных счетов.

Интеграция

Веб-сервис управления бонусными счетами и начислениями из внешних систем

Описание

Адрес веб-сервиса для управления бонусными счетами

Методы

Информация о карте и бонусных счетах

Информация по номеру карты о балансе активных бонусных баллов

Информация по номеру карты о балансе бонусных баллов, в зависимости от их статуса

Информация по номеру карты размера и даты следующей активации бонусных баллов на счету

Информация о клиентских счетах с бонусными баллами, которые сгорят до введённой даты

Получить по номеру карты подробную информацию (данные категории карты, анкета владельца)

Информация по номеру карты о статусе (активна, заблокирована и т.п.)

Информация по номеру карты об анкете клиента

Начисление и списание бонусных баллов

Начислить бонусные баллы на счет клиента

Отмена начисления бонусных баллов на счет клиента (отмена по возврату)

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

Возврат бонусных баллов на счет клиента

Пакетное начисление бонусных баллов (для большого количества карт)

Пакетное начисление бонусных баллов на счета клиентов

Запрос статуса пакета с начислением бонусов выполненных пакетным сценарием

Блокировка бонусных баллов

Блокировка бонусных баллов на счете клиента

Разблокировать бонусные баллы на счете клиента

Списать заблокированные бонусные баллы со счета клиента

Управление бонусными баллами на примере SOAP UI

Ручное начисление бонусов