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

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

Описание методов по управлению бонусными счетами

Методы доступны через вэб сервис системы Лояльности (Описание в WSDL файле ExternalSystemCardsProcessing.wsdl)
 
URL: http://{host}:8090/SET-Cards/SET/Cards/ExternalSystemCardsProcessing
WSDL: http://{host}:8090/SET-Cards/SET/Cards/ExternalSystemCardsProcessing?wsdl

Метод Описание
Получение информации о карте и бонусных счетах
getActiveBonusAccounts Метод позволяет по номеру карты получить информацию о балансе активных бонусных баллов
getBonusAccountBalances Метод позволяет по номеру карты получить подробную информацию о балансе бонусных баллов, в зависимости от их статуса (активные, заблокированные, активные, не активные, списанные)
getBonusAccountsInformation Метод позволяет по номеру карты получить размер и дату следующей активации бонусных баллов на счету, а также размер и дату следующего сгорания бонусных баллов
getBonusesExpiredAfterDate Метод позволяет получить информацию о клиентских счетах с бонусными баллами, которые сгорят ранее введенной даты в запросе
getCardInformationByNumber Метод позволяет по номеру карты получить полный набор информации, включая данные категории карты, а также анкету владельца карты
getCardStatus Метод позволяет по номеру карты получить статус карты (активна, заблокирована)
getClientInfoByCardNumber Метод позволяет по номеру карты получить данные клиентской анкеты
Начисление и списание бонусных баллов
chargeOnBonusAccount Метод позволяет начислять бонусные баллы на счет клиента
cancelChargeOnBonusAccount Метод позволяет отменять начисление бонусных баллы на счет клиента
writeOffFromBonusAccount Метод позволяет списать активные бонусные баллы со счета клиента
returnPaymentToBonusAccount Метод позволяет вернуть бонусные баллы на счета клиента
Пакетное начисление бонусных баллов сразу на большое количество карт
packageChargeOnBonusAccounts Метод позволяет производить пакетоное начисление бонусных баллов на счета клиентов
getResultOfPackageChargeOnBonusAccounts Метод позволяет запросить статус пакета с начислением бонусов packageChargeOnBonusAccounts
Возможности по блокировке бонусных баллов
blockingAmountFromBonusAccount Метод позволяет заблокировать бонусные баллы на счете клиента
unlockingAmountFromBonusAccount Метод позволяет разблокировать бонусные баллы на счете клиента
writeOffBlockedFromBonusAccount Метод позволяет списать заблокированные бонусные баллы со счета клиента

Примеры использования методов

Для тестирования WS методов можно использовать программу SOAP UI  и инструкцию по работе с ней

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

Для блока методов, позволяющих получить информации о карте и бонусных счетах достаточно в запросе использовать номер бонусной карты.
Пример getActiveBonusAccounts
Входные параметры Результат запроса
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/">
<soapenv:Header/>
<soapenv:Body>
<proc:getActiveBonusAccounts>
<!--Optional:-->

<cardNumber>180000</cardNumber> <!--номер карты-->
</proc:getActiveBonusAccounts>
</soapenv:Body>
</soapenv:Envelope>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:getActiveBonusAccountsResponse xmlns:ns2="http://processing.cards.crystals.ru/">
<return>
<balance>557.03</balance>
<bonusAccountId>13307</bonusAccountId>
<bonusAccountsTypeVO>
<accountsType>Money</accountsType>
<bonusAccountTypeCode>1366</bonusAccountTypeCode>
<bonusAccountTypeId>1366</bonusAccountTypeId>
<bonusAccountsTypeName>Bonus 1b=1rub</bonusAccountsTypeName>
<bonusCourse>100</bonusCourse>
<currencyCourse>100</currencyCourse>
<entirePurchase>true</entirePurchase>
<writeOffAllAmountAtOnce>false</writeOffAllAmountAtOnce>
</bonusAccountsTypeVO>
<enabled>true</enabled>
</return>
</ns2:getActiveBonusAccountsResponse>
</soap:Body>
</soap:Envelope>

Начиная с верси 10.2.13.0 появился метод getBonusesExpiredAfterDate, который позволяет получить информацию о клиентах,у которых сгорят бонусы на введенную дату в запросе. 
Метод будет полезен для оповещения клиентов (СМС, e-mail) о сгоревших бонусах на дату.
Пример getBonusesExpiredAfterDate

Входные параметры Результат запроса
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/"> 
<soapenv:Header/> 
<soapenv:Body> 
<proc:getBonusesExpiredAfterDate> 
<expiredDate>2067-01-01</expiredDate> <!--дата сгорания бонусов-->
</proc:getBonusesExpiredAfterDate> 
</soapenv:Body> 
</soapenv:Envelope>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
<soap:Body> 
<ns2:getBonusesExpiredAfterDateResponse xmlns:ns2="http://processing.cards.crystals.ru/"> 
<return> 
<bonusAccountId>1536</bonusAccountId> 
<bonusValue>900</bonusValue> 
<cardNumber>597111</cardNumber> 
<clientFIO>Иванов Иван</clientFIO> 
<clientId>1533</clientId> 
<compositionId>14012</compositionId> 
<email/> 
<expiredDate>2016-01-29T00:00:00+03:00</expiredDate> 
<phone/> 
</return> 
<return> 
<bonusAccountId>13307</bonusAccountId> 
<bonusValue>10000</bonusValue> 
<cardNumber>180000</cardNumber> 
<clientFIO>Петрова Елена Владимировна</clientFIO> 
<clientId>13304</clientId> 
<compositionId>1379790</compositionId> 
<email>epetrova@mail.com</email> 
<expiredDate>2055-03-02T00:00:00+03:00</expiredDate> 
<phone>+79213312251</phone> 
</return> 
</ns2:getBonusesExpiredAfterDateResponse> 
</soap:Body> 
</soap:Envelope>

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

Метод chargeOnBonusAccount по начислению на одну карту клиента описан в статье Ручное начисление бонусов
Пример chargeOnBonusAccount 
Входные параметры Результат запроса
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/">
<soapenv:Header/>
<soapenv:Body>
<proc:chargeOnBonusAccount>
<cardNumber>780014086178</cardNumber> <!--номер карты-->
<bonusAccountType>1203</bonusAccountType> <!--id бонусного счета (см.в таблице SET.cards_bonusaccountstype.bonusaccounttypecode) Опционально,указывается в случае нескольких бонусных счетов-->
<shopNum>99</shopNum> <!--номер магазина-->
<cashNum>99</cashNum> <!--номер кассы-->
<shiftNum>1</shiftNum> <!--номер смены-->
<checkNum>2</checkNum> <!--номер чека-->
<chargeSum>10000</chargeSum> <!--сумма к начислению в копейках-->
<activatingDate>2015-03-26</activatingDate> <!--дата активации бонусов-->
<expirationDate>2055-03-02</expirationDate> <!--дата сгорания бонусов-->
</proc:chargeOnBonusAccount>
</soapenv:Body>
</soapenv:Envelope>
<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>1379789</transactionId>
</return>
</ns2:chargeOnBonusAccountResponse>
</soap:Body>
</soap:Envelope>

Для списания бонусов используется метод writeOffFromBonusAccount
Входные параметрыРезультат запроса
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/">
<soapenv:Header/>
<soapenv:Body>
<proc:writeOffFromBonusAccount>
<accountTypeCode>1366</accountTypeCode> <!--id бонусного счета (см.в таблице SET.cards_bonusaccountstype.bonusaccounttypecode) Опционально,указывается в случае нескольких бонусных счетов-->
<cardNumber>180000</cardNumber><!--номер карты-->
<writeOffSum>10</writeOffSum><!--сумма к начислению в рублях-->
<purchaseUid>
<shopNum>99</shopNum> <!--номер магазина-->
<cashNum>99</cashNum> <!--номер кассы-->
<shiftNum>1</shiftNum> <!--номер смены-->
<checkNum>2</checkNum> <!--номер чека-->
<createDate>2015-10-21T00:00:00.000+04:00</createDate><!--дата списания бонусов-->
</purchaseUid>
</proc:writeOffFromBonusAccount>
</soapenv:Body>
</soapenv:Envelope>
<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>


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

Начиная с версии 10.2.8.0 существует возможность использовать пакетное начисление бонусов на несколько карт. Например, для начисления бонусов определенному сегменту клиентов. При этом каждому пакету назначается уникальный номер, по которому можно отследить статус выполнения операции по начислению. Для этого используется метод packageChargeOnBonusAccounts
Входные параметры Результат запроса
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/">
<soapenv:Header/>
<soapenv:Body>
<proc:packageChargeOnBonusAccounts>
<externalId>123456</externalId> <!--номер пакета -->
<operations>
    <requestId>1</requestId> <!--номер запроса внутри пакета-->
    <activatingDate>2015-10-20</activatingDate> <!--дата активации бонусов-->
    <expirationDate>2016-10-20</expirationDate> <!--дата сгорания бонусов-->
    <bonusAccountType>1366</bonusAccountType> <!--id бонусного счета (см.в таблице SET.cards_bonusaccountstype.bonusaccounttypecode) Опционально,указывается в случае нескольких бонусных счетов-->
    <cardNumber>180000</cardNumber> <!--номер карты-->
    <shopNum>7</shopNum> <!--номер магазина-->
    <cashNum>7</cashNum> <!--номер кассы-->
    <shiftNum>7</shiftNum> <!--номер смены-->
    <checkNum>7</checkNum> <!--номер чека-->
    <chargeSum>999</chargeSum> <!--сумма к начислению в копейках-->
</operations>
<operations> 
    <requestId>2</requestId> <!--номер запроса внутри пакета-->
    <activatingDate>2015-10-20</activatingDate> <!--дата активации бонусов-->
    <expirationDate>2016-10-20</expirationDate> <!--дата сгорания бонусов-->
    <bonusAccountType>1366</bonusAccountType> <!--id бонусного счета (см.в таблице SET.cards_bonusaccountstype.bonusaccounttypecode)-->
    <cardNumber>170000</cardNumber> <!--номер карты-->
    <shopNum>7</shopNum> <!--номер магазина-->
    <cashNum>8</cashNum> <!--номер кассы-->
    <shiftNum>7</shiftNum> <!--номер смены-->
    <checkNum>8</checkNum> <!--номер чека-->
    <chargeSum>50</chargeSum> <!--сумма к начислению в копейках-->
</operations> 
</proc:packageChargeOnBonusAccounts>
</soapenv:Body>
</soapenv:Envelope>
<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
Входные параметры Результат запроса
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/">
<soapenv:Header/>
<soapenv:Body>
<proc:getResultOfPackageChargeOnBonusAccounts>
<externalId>123456</externalId> <!--номер пакета -->
</proc:getResultOfPackageChargeOnBonusAccounts>
</soapenv:Body>
</soapenv:Envelope>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getResultOfPackageChargeOnBonusAccountsResponse xmlns:ns2="http://processing.cards.crystals.ru/">
         <return>
            <errorCode>0</errorCode>
            <errorText/>
            <externalId>123456</externalId>
            <operationsResult>
               <errorCode>0</errorCode>
               <errorText/>
               <requestId>1</requestId>
               <transactionId>41180796</transactionId>
            </operationsResult>
            <operationsResult>
               <errorCode>0</errorCode>
               <errorText/>
               <requestId>2</requestId>
               <transactionId>41180798</transactionId>
            </operationsResult>
            <operationsResult>
               <errorCode>0</errorCode>
               <errorText/>
               <requestId>3</requestId>
               <transactionId>41180800</transactionId>
            </operationsResult>
         </return>
      </ns2:getResultOfPackageChargeOnBonusAccountsResponse>
   </soap:Body>
</soap:Envelope>

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

Метод blockingAmountFromBonusAccount позволяет заблокировать бонусные баллы
Входные параметрыРезультат запроса
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/"> 
<soapenv:Header/> 
<soapenv:Body> 
<proc:blockingAmountFromBonusAccount> 
<accountTypeCode>1366</accountTypeCode><!--id бонусного счета (см.в таблице SET.cards_bonusaccountstype.bonusaccounttypecode) Опционально,указывается в случае нескольких бонусных счетов--> 
<cardNumber>180000</cardNumber> <!--номер карты-->
<writeOffSum>10</writeOffSum> <!--сумма заблокированных баллов в рублях-->
</proc:blockingAmountFromBonusAccount> 
</soapenv:Body> 
</soapenv:Envelope>
<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>


Метод unlockingAmountFromBonusAccount соответственно разблокирует бонусные баллы
Входные параметрыРезультат запроса
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proc="http://processing.cards.crystals.ru/"> 
<soapenv:Header/> 
<soapenv:Body> 
<proc:unlockingAmountFromBonusAccount> 
<accountTypeCode>1366</accountTypeCode> <!--id бонусного счета (см.в таблице SET.cards_bonusaccountstype.bonusaccounttypecode) Опционально,указывается в случае нескольких бонусных счетов--> 
<cardNumber>180000</cardNumber> <!--номер карты-->
<writeOffSum>10</writeOffSum> <!--сумма разблокированных баллов в рублях-->
</proc:unlockingAmountFromBonusAccount> 
</soapenv:Body> 
</soapenv:Envelope>
<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>


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

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