1 Описание
2 Адрес веб-сервиса для управления бонусными счетами
3 Методы
4 Управление бонусными баллами на примере SOAP UI
- 4.1 Ручное начисление бонусов
  - 4.1.1 Пример SOAP-запроса:

Описание

Модуль процессинга 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

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

Описание

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

Методы

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

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

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

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

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

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

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

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

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

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

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

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

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

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