Оглавление

Описание

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

...

Якорь

	wsbonus
	wsbonus

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

...

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

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

Метод

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

Идентификатор типа бонусного счета.

Якорь

	getBonusAccountsInformation
	getBonusAccountsInformation

Нет

nextActivationDate

DateTime

Следующая дата активации бонусных баллов.

Нет

nextActivationSum

Long

Следующая сумма активации бонусных баллов.

Нет

nextCancelingDate

DateTime

Следующая дата сгорания бонусных баллов.

Нет

nextCancelingSum

Long

Следующая сумма сгорания бонусных баллов.

Нет

nonActiveBonuses

Long

Неактивированные бонусные баллы.

Нет

...

Информация по номеру карты об анкете клиента
Метод			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 - нет.	Нет

...

НетНетНетНет

Начислить бонусные баллы на счет клиента
Метод		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	Идентификатор тразнакции/операции по бонусному счету	Да

Якорь

	chargeOnBonusAccount
	chargeOnBonusAccount

...

Отмена начисления бонусных баллов на счет клиента (отмена по возврату)
Метод		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	Количество отмененных неактивных баллов.	Нет

...

Списание активных бонусных баллов со счета клиента
Метод		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 - операция не удалась.	Да

...

Возврат бонусных баллов на счет клиента
Метод		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			Результат операции. Успешная операция без текста ответа.	Да

...

Пакетное начисление бонусных баллов на счета клиентов
Предназначен для начисления бонусов определенному сегменту клиентов. При этом каждому пакету назначается уникальный номер `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 - операция не удалась.	Да

...

Запрос статуса пакета с начислением бонусов выполненных пакетным сценарием
Метод		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	Уникальный номер пакета для отслеживания операции.	Да

...

Списать заблокированные бонусные баллы со счета клиента
Метод		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 UI.

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

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

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

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

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

Блок кода

language	xml
title	Пример 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. Нажмите для выполнения запроса.

Image Modified

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

Image Modified

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

...

Сравнение версий

Старая версия 31

Новая версия Текущий

Ключ

Описание

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

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

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

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

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

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

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

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

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

Сравнение страниц

Сравнение версий

Старая версия 31

Новая версия Текущий

Ключ

Описание

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

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

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

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

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

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

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

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

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