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

Описание

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

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

URLhttp://IP-адрес_сервера:8090/SET-Cards/SET/Cards/ExternalSystemCardsProcessing
WSDLhttp://IP-адрес_сервера:8090/SET-Cards/SET/Cards/ExternalSystemCardsProcessing?wsdl

Методы

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

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

МетодgetActiveBonusAccounts

Поле

Тип данных

Описание

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

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

cardNumber

String

Номер карты. 

Допустимые значения: буквы или цифры.

Без специальных символов.

Да

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

return

Комплексный

Коллекция элементов с данными по бонусному счёту.

Да

balanceStringБаланс бонусных баллов.Да
bonusAccountIdLongИдентификатор бонусного счета в БД сервера SetRetail/SetCentrum.Да
enabledBoolean

Статус бонусного счёта:

  • True - активный;
  • False - неактивный.
Да
bonusAccountsTypeVOКомплексныйКоллекция элементов бонусного счетаДа

accountsTypetns:bonusAccountsType

Тип бонусного счёта:

  • NONE - отсутствует;
  • MONEY - денежный (бонусный);
  • GOODS - товарный;
  • TOKENS - электронные фишки.
Да
bonusAccountTypeCodeLong

Код типа бонусного счёта - уникальная сущность в рамках всей сети.

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

Да
bonusAccountTypeIdLongУникальный идентификатор типа счета.Да
bonusAccountsTypeNameStringНаименование типа счета.Да
bonusCourseLongКурс бонусов к валюте.Нет
bonusListtns:bonusAccountVOСписок бонусных счетов, привязанных к этому типу.Нет
currencyCourseLongКурс валюты счета.Нет
entirePurchaseBoolean

Оплата бонусами чека:

  • True - полностью;
  • False - частично.
Нет
maxPaymentPercentLongМаксимальный процент оплаты от суммы чекаНет
writeOffAllAmountAtOnceBoolean

Списывать всю сумму бонусов за одно применение карты.

  • 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

Комплексный

Коллекция элементов с данными по бонусному счёту.

Да

ammountStringБаланс бонусных баллов.Да
balanceTypetns:balanceType

Статус бонусных баллов:

  • ACTIVE - действующие;
  • BLOCKED - заблокированные;
  • WRITE_OFF - списанные;
  • NOT_ACTIVE - неактивированные;
  • REVOKED - отмененные (отозванные).
Да
bonusAccountIdLong

Идентификатор бонусного счета в БД сервера 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

Комплексный

Коллекция элементов с данными по бонусному счёту.

Да

errorCodeLong

Код ошибки при вызове метода.

Базовый список кодов ошибок для всех методов:

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

activeBonusesLongДействующие бонусные баллы.Нет
bonusAccountTypeIdLong

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

Нет
nextActivationDateDateTimeСледующая дата активации бонусных баллов.Нет
nextActivationSumLongСледующая сумма активации бонусных баллов.Нет
nextCancelingDateDateTimeСледующая дата сгорания бонусных баллов.Нет
nextCancelingSumLongСледующая сумма сгорания бонусных баллов.Нет
nonActiveBonusesLongНеактивированные бонусные баллы.Нет
Пример 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

Комплексный

Коллекция элементов с данными по бонусному счёту и информацией по клиенту.

Да

bonusAccountIdLongИдентификатор бонусного счета в БД сервера SetRetail/SetCentrum.Да
bonusValueLongРазмер бонусного баланса на счете.Да
cardNumberStringНомер карты.Да
clientFIOStringФИО клиента.Нет
clientIdLongУникальный идентификатор анкеты клиенты.Да
compositionIdLongИдентификатор детальной информации по балансу бонусного счёта клиента с датами сгорания бонусов.Да
emailStringАдрес электронной почты клиенты.Нет
expiredDateDateTimeДата окончания действия бонусных баллов.Нет
phoneStringМобильный телефон.Нет
Пример 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

Комплексный

Коллекция элементов с данными по бонусному счёту и информацией по клиенту.

Да

bonusBoolean

Бонусный счет:

  • True - бонусный;
  • False - нет.
Нет
bonusAccountsКомплексныйКоллекция бонусных счетов клиента.Нет

balanceLongБаланс бонусного счета.Нет
bonusAccountIdLongУникальный идентификатор бонусного счета.Нет
bonusAccountsTypeVOКомплексныйКоллекция элементов бонусного счета.Нет

accountsTypetns:bonusAccountsType

Тип бонусного счёта:

  • NONE - отсутствует;
  • MONEY - денежный (бонусный);
  • GOODS - товарный;
  • TOKENS - электронные фишки.
Нет
bonusAccountTypeCodeLong

Код типа бонусного счёта - уникальная сущность в рамках всей сети.

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

Нет
bonusAccountTypeIdLongИдентификатор типа бонусного счета.Нет
bonusAccountsTypeNameStringНименование типа счета.Нет
bonusCourseLongКурс бонусов к валюте.Нет
currencyCourseLongКурс валюты счета.Нет
entirePurchaseBoolean

Оплата бонусами чека:

  • True - полностью;
  • False - частично.
Нет
writeOffAllAmountAtOnceBoolean

Списывать всю сумму бонусов за одно применение карты.

  • True - списывать всё;
  • False - списывать частично.
Нет
enabledBoolean

Статус бонусного счёта:

  • True - активный;
  • False - неактивный.
Нет
cardNumberStringНомер карты.Да

cardTypeVO

КомплексныйКоллекция элементов категории карты.Да

idLongИдентификатор категории карты.Да
classTypeStringТип внутреннего класса карты.Да
colortns:displayColorКоллекция элементов для цветовой маркировки карты в формате RGB.Да

blueIntegerСинийДа
greenIntegerЗеленыйДа
redIntegerКрасныйДа
deletedBoolean

Статус категории:

  • True - удалена;
  • False - действующая.
Да
guidLongУникальный GUID категории карт. Да
nameStringНаименование категории карт.Да
personalizedBoolean

Персонифицированная (к картам в этой категории можно заполнить анкету клиенты):

  • True - удалена;
  • False - действующая.
Да
accumulativeBoolean

Накопительная (для перехода из категории в категории. Не бонусные баллы!):

  • True - накопительная;
  • False - без накоплений.
Да
bonusBoolean

Бонусная:

  • True - бонусная;
  • False - без учета бонусных баллов.
Да
domesticCreditBoolean

Внутренний кредит:

  • True - включен;
  • False - отключен.
Да
finishDateTimeОкончание срока действия.Да
percentageDiscountLongРазмер скидки в процентах.Да
showCardFromRangeNotificationBoolean

Наличие правил перехода из одной категории в другую:

  • True - есть;
  • False - нет.
Нет
startDateTimeНачало срока действия.Да
withoutFinishDateBoolean

Без срока окончания срока действия.

  • True - есть срок действия;
  • False - нет срока действия.
Нет
cardVOКомплексныйКоллекция элементов данных по экземпляру привязанной карты к счету.Да

idLongИдентификатор экземпляра привязаной карты.Да
activationDateDateTimeДата активации карты.Да
amountLongКоличество накоплений для перехода из одной категории в другую.Да
balanceLongОбщий баланс накоплений (не бонусных).Да
blockDateDateTimeДата блокировки.Нет
blockedBoolean

Статус блокировки:

  • True - карта заблокирована;
  • False - действующая.
Да
cardTypeVOКомплексный

Коллекция элементов категории карты.

См. выше.

Нет
clientVOКомплексныйКоллекция элементов анкеты клиента.Нет

idLongУникальный идентификатор анекты клиента.Да
autoBoolean

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

  • True - есть;
  • False - нет.
Нет
birthDateDateTimeДата рождения.Нет
bonusBalanceLongКоличество бонусных баллов на счете.Нет
childrenAgeStringДети.Нет
clientAddressКомплексныйКоллекция элементов адреса анкеты клиента.Нет

appartmentStringКвартира.Нет
buildingStringКорпус.Нет
cityStringГород.Нет
districtStringРайон (НЕ ИСПОЛЬЗУЕТСЯ).Нет
districtAreaStringРайон.Нет
houseStringДом.Нет
otherStringДругое.Нет
regionStringОбласть (регион).Нет
streetStringУлицаНет
zipStringИндексНет
clientTypetns:clientType

Тип клиента:

  • PRIVATE - физическое лицо;
  • JURISTIC_PERSON - юридическое лицо.
Да
creationDateDateTimeДата создания анкеты.Да
deletedBoolean

Статус анкеты:

  • True - удалена;
  • False - действующая.
Да
emailStringАдрес элетронной почты.Нет
firstNameStringИмя.Да
guidLongУникальный GUID анекты клиента.Да
isCompletedBooelan

Статус анкеты:

  • True - заполнена;
  • False - не заполнена.
Да
lastChangeDateDateTimeДата последних изменений в анкете.Да
lastNameStringФамилия.Да
maritalBoolean

Женат/замужем:

  • True - да;
  • False - нет.
Нет
middleNameStringОтчество.Нет
mobileOperatorStringОператор мобильной связи.Нет
mobilePhoneStringМобильный телефон.Нет
passportКомплексныйКоллекция элементов паспортных данных.Нет

deliveryStringКем выдан.Нет
deliveryDateStringДата выдачи.Нет
passNumberStringНомер.Нет
passSerieStringСерия.Нет
phoneStringДомашний телефонНет
receiptFeedbackTypeString

Уведомление обладателя карты о совершенной покупке для отправки чека:

  • 0 - не отправлять.
  • 1 - отправлять чек на email;
  • 2 - по SMS.
Да
sendByКомплексныйКомплекс элементов определяющих согласие на методы рассылки рекламного каталога.Нет

byEMailBoolean

Отправлять по электронной почте.

  • True - да;
  • False - нет.
Нет
byMailBoolean

Отправлять по обычной почте.

  • True - да;
  • False - нет.
Нет
byPhoneBoolean

Оповещение по телефону.

  • True - да;
  • False - нет.
Нет
bySMSBoolean

Отправлять SMS.

  • True - да;
  • False - нет.
Нет
sendCatalogBoolean

Отправять рекламный каталог.

  • True - да;
  • False - нет.
Нет
sextns:sex

Пол:

  • Male - мужской;
  • Female - женский;
  • Not_Specified - не указан.
Нет
shopNumberIntegerНомер магазина.Нет
smartphoneTypeString

Тип смартфона:

  • IOS
  • ANDROID
  • SAMSUNG
Нет
wantsECardBoolean

Признак хочет ли клиент получить элетронную карту.

  • True - да;
  • False - нет.
Нет
counterpartyIdString

Идентификатор привязки к юридическому лицу:

ИНН;КПП

Нет
createDateDateTimeДата создания клиента.Да
deletedBoolean

Статус клиента.

  • True - заблокирован;
  • False - действующий.
Да
guidLongУникальный GUID клиента.Да
numberLongНомер картыДа
signChangeOfCategoryCardBoolean

Признак смены категории карты.

  • True - возможна смена категории;
  • False - нет.
Нет
signExtensionCardBoolean

Признак продления карты.

  • True - возможно проделнение срока действия;
  • False - нет.
Нет
statusString

Статус карты:

  • Create - карта создана;
  • Active - карта активирована;
  • Blocked - карта неактивна/заблокирована;
  • Inactive - карта просрочена или устарела;
Да
domesticCreditBoolean

Внутренний кредит:

  • True - включен;
  • False - отключен.
Да
personalizedBoolean

Персонифициарованная карта:

  • 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

Комплексный

Коллекция элементов с информацией по статусу карты.

Да

cardNumberStringНомер картыДа
cardStatusString

Статус карты:

  • Create - карта создана;
  • Active - карта активирована;
  • Blocked - карта неактивна/заблокирована;
  • Inactive - карта просрочена или устарела;
Да
cardTypesString

Тип карты:

  • 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

Комплексный

Коллекция элементов с информацией из анкеты клиента.

Да

idLongУникальный идентификатор анекты клиента.Да
autoBoolean

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

  • True - есть;
  • False - нет.
Нет
birthDateDateTimeДата рождения.Нет
bonusBalanceLongКоличество бонусных баллов на счете.Нет
childrenAgeStringДети.Нет
clientAddressКомплексныйКоллекция элементов адреса анкеты клиента.Нет

appartmentStringКвартира.Нет
buildingStringКорпус.Нет
cityStringГород.Нет
districtStringРайон (НЕ ИСПОЛЬЗУЕТСЯ).Нет
districtAreaStringРайон.Нет
houseStringДом.Нет
otherStringДругое.Нет
regionStringОбласть (регион).Нет
streetStringУлицаНет
zipStringИндексНет
clientTypetns:clientType

Тип клиента:

  • PRIVATE - физическое лицо;
  • JURISTIC_PERSON - юридическое лицо.
Да
creationDateDateTimeДата создания анкеты.Да
deletedBoolean

Статус анкеты:

  • True - удалена;
  • False - действующая.
Да
emailStringАдрес элетронной почты.Нет
firstNameStringИмя.Нет
guidLongУникальный GUID анекты клиента.Нет
isCompletedBoolean

Статус анкеты:

  • True - заполнена;
  • False - не заполнена.
Да
lastChangeDateDateTimeДата последних изменений в анкете.Да
lastNameStringФамилия.Да
maritalBoolean

Женат/замужем:

  • True - да;
  • False - нет.
Нет
middleNameStringОтчество.Нет
mobileOperatorStringОператор мобильной связи.Нет
mobilePhoneStringМобильный телефон.Нет
passportКомплексныйКоллекция элементов паспортных данных.Нет

deliveryStringКем выдан.Нет
deliveryDateStringДата выдачи.Нет
passNumberStringНомер.Нет
passSerieStringСерия.Нет
phoneStringДомашний телефонНет
receiptFeedbackTypeString

Уведомление обладателя карты о совершенной покупке для отправки чека:

  • 0 - не отправлять.
  • 1 - отправлять чек на email;
  • 2 - по SMS.
Да
sendByКомплексныйКомплекс элементов определяющих согласие на методы рассылки рекламного каталога.Нет

byEMailBoolean

Отправлять по электронной почте.

  • True - да;
  • False - нет.
Нет
byMailBoolean

Отправлять по обычной почте.

  • True - да;
  • False - нет.
Нет
byPhoneBoolean

Оповещение по телефону.

  • True - да;
  • False - нет.
Нет
bySMSBoolean

Отправлять SMS.

  • True - да;
  • False - нет.
Нет
sendCatalogBoolean

Отправять рекламный каталог.

  • True - да;
  • False - нет.
Нет
sextns:sex

Пол:

  • Male - мужской;
  • Female - женский;
  • Not_Specified - не указан.
Нет
shopNumberIntegerНомер магазина.Нет
smartphoneTypeString

Тип смартфона:

  • IOS
  • ANDROID
  • SAMSUNG
Нет
wantsECardBoolean

Признак хочет ли клиент получить элетронную карту.

  • 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

Номер карты. 

Допустимые значения: буквы или цифры.

Без специальных символов.

Да
bonusAccountTypeLong

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

  • Варианта просмотра идентификатора:
    • База данных set → таблицаcards_bonusaccountstype → поле bonusaccounttypecode.
    • Или через один из методов получения информации по карте, где есть bonusAccountType
Нет
shopNumLongНомер магазина.Да
cashNumLongНомер кассы.Да
shiftNumLongНомер смены.Да
checkNumLongНомер чека.Да
chargeSumLong

Сумма начисления в копейках:

Например: нужно начислисть 200.22 бонусных балла, тогда значение = 20022

Да
activatingDateDateTimeДата активации бонусных баллов.Да
expirationDateDateTimeДата сгорания бонусных балловНет

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

return

Комплексный

Коллекция элементов обратной связи при вызове метода.

Да

errorCodeLong

Код ошибки при вызове метода.

Базовый список кодов ошибок для всех методов:

  • 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 - некорректный код из внешней системы (для этого кода нет ни одной операции).
Да
errorTextStringТекст ошибки.Нет
transactionIdLongИдентификатор тразнакции/операции по бонусному счетуДа

Пример 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

Номер карты. 

Допустимые значения: буквы или цифры.

Без специальных символов.

Да
bonusAccountTypeLong

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

  • Варианта просмотра идентификатора:
    • База данных set → таблицаcards_bonusaccountstype → поле bonusaccounttypecode.
    • Или через один из методов получения информации по карте, где есть bonusAccountType
Нет
shopNumLongНомер магазина.Нет
cashNumLongНомер кассы.Нет
shiftNumLongНомер смены.Нет
checkNumLongНомер чека.Нет
cancelSumLong

Сумма отмены в копейках:

Например: нужно отменить 200.22 бонусных балла, тогда значение = 20022

Нет

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

return

Комплексный

Коллекция элементов обратной связи при вызове метода.

Да

errorCodeLong

Код ошибки при вызове метода.

Базовый список кодов ошибок для всех методов:

  • 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 - некорректный код из внешней системы (для этого кода нет ни одной операции).
Нет
errorTextStringТекст ошибки.Нет
cancelActiveSumLongКоличество отмененных активных бонусных баллов.Нет
cancelNonActiveSumLongКоличество отмененных неактивных баллов.Нет
Пример 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

Поле

Тип данных

Описание

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

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

accountTypeCodeLong

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

  • Варианта просмотра идентификатора:
    • База данных set → таблицаcards_bonusaccountstype → поле bonusaccounttypecode.
    • Или через один из методов получения информации по карте, где есть bonusAccountType
Да
cardNumberString

Номер карты. 

Допустимые значения: буквы или цифры.

Без специальных символов.

Нет
writeOffSumDouble

Сумма отмены в копейках c разделителем в виде точки:

Например: нужно отменить 200.22 бонусных балла, тогда значение = 200.22

Если сумма указана без точки, тогда будет начислено целое число.

Да
purchaseUidКомплексныйКоллекция элементов с информацией по чеку.Нет

cashNumLongНомер кассы.Нет
checkNumLongНомер чека.Нет
createDateLongДата чека.Нет
shiftNumLongНомер смены.Нет
shopNumLongНомер магазина.Нет

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

returnBoolean

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

  • 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

Поле

Тип данных

Описание

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

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

accountTypeCodeLong

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

  • Варианта просмотра идентификатора:
    • База данных set → таблицаcards_bonusaccountstype → поле bonusaccounttypecode.
    • Или через один из методов получения информации по карте, где есть bonusAccountType
Да
cardNumberString

Номер карты. 

Допустимые значения: буквы или цифры.

Без специальных символов.

Нет
chargeSumDouble

Сумма возврата бонусных баллов в копейках c разделителем в виде точки:

Например: нужно вернуть 200.22 бонусных балла, тогда значение = 200.22

Если сумма указана без точки, тогда будет начислено целое число.

Да
purchaseUidКомплексныйКоллекция элементов с информацией по чеку.Нет

cashNumLongНомер кассы.Нет
checkNumLongНомер чека.Нет
createDateLongДата чека.Нет
shiftNumLongНомер смены.Нет
shopNumLongНомер магазина.Нет

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

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КомплексныйКоллекция элементов по операциям с бонусными счетамиДа

activatingDateDateTimeДата активации бонусных баллов.Да
bonusAccountTypeLong

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

  • Варианта просмотра идентификатора:
    • База данных set → таблицаcards_bonusaccountstype → поле bonusaccounttypecode.
    • Или через один из методов получения информации по карте, где есть bonusAccountType
Да
cardNumberString

Номер карты. 

Допустимые значения: буквы или цифры.

Без специальных символов.

Да
cashNumLongНомер кассы.Да
chargeSumLong

Сумма начисления в копейках:

Например: нужно начислисть 200.22 бонусных балла, тогда значение = 20022

Да
checkNumLongНомер чека.Да
expirationDateDateTimeДата сгорания бонусных баллов.Да
requestIdLongИндентификатор операции внутри запросаДа
createDateLongДата чека.Да
shiftNumLongНомер смены.Да
shopNumLongНомер магазина.Да
externalIdLongУникальный номер пакета для отслеживания операции.Да

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

returnBoolean

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

  • 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

Комплексный


Да

errorCodeLong

Код ошибки при вызове метода.

Базовый список кодов ошибок для всех методов:

  • 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 - некорректный код из внешней системы (для этого кода нет ни одной операции).
Да
errorTextStringТекст ошибки.Да
externalIdLongУникальный номер пакета для отслеживания операции.Да
Пример 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
Да
cardNumberString

Номер карты. 

Допустимые значения: буквы или цифры.

Без специальных символов.

Нет
writeOffSumDouble

Сумма отмены в копейках 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
Да
cardNumberString

Номер карты. 

Допустимые значения: буквы или цифры.

Без специальных символов.

Нет
writeOffSumDouble

Сумма отмены в копейках 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
Да
cardNumberString

Номер карты. 

Допустимые значения: буквы или цифры.

Без специальных символов.

Нет
writeOffSumDouble

Сумма отмены в копейках c разделителем в виде точки:

Например: нужно отменить 200.22 бонусных балла, тогда значение = 200.22

Если сумма указана без точки, тогда будет начислено целое число.

Да
purchaseUidКомплексныйНомер кассы.Нет

cashNumLongНомер чека.Нет
checkNumLongДата чека.Нет
createDateLongДата чека.Нет
shiftNumLongНомер смены.Нет
shopNumLongНомер магазина.Нет

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

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. Проверьте начисление бонусных баллов на счете клиента в истории бонусных счетов.