Сервис для выдачи виртуальных карт представляет собой сервис, который работает напрямую с кассовым и бонусным сервером. Предназначен для быстрой выдачи карты клиенту, а также создания виртуальных карт.
Установка сервиса производится командой:
apt-get install artixcs-issuance-card |
Настройка работы сервиса осуществляется в конфигурационном файле application.properties, который находится в директории /opt/artixcs-issuance-card/application.properties.
#Подключение к кассовому серверу
cashserver.host=localhost
cashserver.port=8080
cashserver.login=admin
cashserver.password=admin
#Подключение к бонусному серверу
bonus.server.rest.host=localhost
bonus.server.rest.port=8080
bonus.server.rest.contextpath=/ACC/
#Авторизация на бонусном сервере через terminalid
terminal.id=ISSUANCE_DEFAULT_TERMINAL
bonus.server.auth.terminalid=true
#Авторизация на бонусном сервере через логин и пароль
bonus.server.username=admin
bonus.server.password=admin
#Генерация справочников
cashserver.start.generate.dict=true
#Преобразование номеров телефона для поиска клиентов
#Маска номера телефона
#Для России можно использовать ^[+]?[78]?([0-9]{10})$
regexp.phone.mask=(.*)
#Преобразование телефона. Преобразованный номер будет сохранен в БД при создании клиента, а также будет участвовать в поиске
#Для России можно использовать 7\\1
regexp.phone.transform=\\1
#Порт, на котором будет запущен текущий сервис
server.port=8094
#Настройка группы виртуальных карт (При создании карты необходимо указать идентификатор группы карт).
virtual.card.groupid=1
#Время жизни пин-кода в секундах
pincode.lifetime=300
#Настройки специальных дат
#Номер специальной даты для регистрации клиента (варьируется от 1 до 3)
special.date.number=1
#Имя специальной даты
special.date.name=registration
#Настройки для генерации номера карты
#Длина номера карты варьируется от 4 до 200 символов включая длину префикса номера карты
cardnumber.length=16
#Префикс номера карты
cardnumber.prefix=
#Текст для смс клиенту при выдаче карты в формате SpEL
#Внимание! Текст нужно заключать в одиночные кавычки ''
#Пример: чтобы указать имя клиента в смс, запишем: 'Уважаемый(ая) ' + name + ', спасибо, что Вы с нами!'
#Если текст не указан, смс отправляться не будут
sms.text = |
Для отправки СМС о выдаче карты с собственного СМС шлюза в файле /opt/artixcs-issuance-card/application.properties необходимо добавить строку в формате: sms.gateway.key = <ключ СМС шлюза>. |
Предварительно необходимо настроить СМС шлюз, подробнее об этом в разделе "Настройки сервера" (подраздел "СМС").
Сервис выдачи карт выполняет следующие функции:
| Поиск клиента осуществляется по номеру телефона. |
Если в процессе назначения произошла ошибка, клиент буден удален.
Получение пин-кода для создания карты.
В случае отсутствия клиента или карты в системе на кассовый сервер будет направлен запрос на получение пин-кода для верификации клиента. Ответом на данный запрос будет пин-код.
В случае если клиент существует, но у него нет карты, на кассовый сервер также будет направлен соответствующий запрос на получение пин-кода. Ответом на данный запрос будет пин-код.
В случае если клиент существует, и у него есть привязанная карта (или карты, если их несколько), то будет направлено соответствующее сообщение в ответном запросе.
| Пин-код, полученный от кассового сервера, по-умолчанию хранится 300 секунд. |
Создание виртуальной карты с помощью пин-кода.
При создании виртуальной карты учитывается префикс и длина генерируемой карты. Длина генерируемой части номера карты должна быть в диапазоне от 4 до 200 символов.
В случае если пин-код истек или не был отправлен, процесс создания виртуальной карты будет прерван, и будет направлено соответствующее сообщение.
В случае отсутствия номера телефона клиента создается клиент по заданному номеру телефона, и с помощью настройки задается номер специальной даты и ее имя. В качестве специальной даты назначается текущая дата. Остальные параметры клиента будут сохранены, исходя из тех данных, которые были направлены в запросе. Далее происходит генерация уникального номера карты. В процессе генерации отправляются запросы на кассовый сервер, в рамках которых происходит проверка уникального номера карты.
В случае если карта с генерируемым номером уже существует на кассовом сервере, то будет произведена повторная генерация. Количество повторных генераций вычисляется по формуле 9 * 10 длина генерируемого префикса.
В случае если клиент существует, но у него отсутствует карта, будет произведена генерация уникального номера карты. После завершения генерации уникального номера карты происходит процедура создания карты на кассовом сервере, а в последствии и на бонусном сервере. Если в процессе создания карты возникла какая-либо ошибка, произойдет удаление ранее созданных карт на кассовом и бонусном серверах.
В случае если клиент существует, и у него есть привязанная карта (или карты, если их несколько), то будет направлено соответствующее сообщение в ответе на запрос.
Включив настройку cashserver.start.generate.dict, будет осуществлена генерация справочников после успешной привязки карты к клиенту. |
{"swagger":"2.0","info":{"description":"","version":"","title":"API Сервиса выдачи карт","termsOfService":"","contact":{},"license":{"name":" ","url":""}},"host":"","basePath":"","tags":[{"name":"Сервис artixcs-issuance-card для выдачи карт","description":" "}],"paths":{"/v1/issuancecard/cardnumber/{cardNumber}":{"post":{"tags":["Сервис artixcs-issuance-card для выдачи карт"],"summary":"Выдача карты клиенту","operationId":"issuanceCardUsingPOST","consumes":["application/json"],"produces":["*/*"],"parameters":[{"name":"cardNumber","in":"path","description":"Номер карты","required":false,"type":"string"},{"name":"cashId","in":"query","description":"Идентификатор кассы","required":false,"type":"string","allowEmptyValue":false},{"in":"body","name":"client","description":"Клиент","required":false,"schema":{"$ref":"#/definitions/Клиент"}},{"name":"clusterId","in":"query","description":"Идентификатор кластера","required":false,"type":"string","allowEmptyValue":false},{"name":"shopCode","in":"query","description":"Код магазина","required":false,"type":"string","allowEmptyValue":false}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Результат работы сервиса"}},"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}},"deprecated":false}},"/v1/issuancecard/create/card":{"post":{"tags":["Сервис artixcs-issuance-card для выдачи карт"],"summary":"Создание виртуальной карты с помощью пин-кода","operationId":"createClientAndVirtualCardByPinCodeUsingPOST","consumes":["application/json"],"produces":["*/*"],"parameters":[{"name":"cashId","in":"query","description":"Идентификатор кассы","required":false,"type":"string","allowEmptyValue":false},{"in":"body","name":"client","description":"Клиент","required":false,"schema":{"$ref":"#/definitions/Клиент"}},{"name":"clusterId","in":"query","description":"Идентификатор кластера","required":false,"type":"string","allowEmptyValue":false},{"name":"length","in":"query","description":"Длина генерируемой части","required":false,"type":"integer","format":"int32","allowEmptyValue":false},{"name":"pincode","in":"query","description":"Пин-код","required":false,"type":"string","allowEmptyValue":false},{"name":"prefix","in":"query","description":"Префикс номера карты","required":false,"type":"string","allowEmptyValue":false},{"name":"shopCode","in":"query","description":"Код магазина","required":false,"type":"string","allowEmptyValue":false}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Результат работы сервиса"}},"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}},"deprecated":false}},"/v1/issuancecard/verify/phonenumber":{"post":{"tags":["Сервис artixcs-issuance-card для выдачи карт"],"summary":"Получение пин-кода для создания клиента/карты","operationId":"getVerificationCodeForCreatingVirtualCardUsingPOST","consumes":["application/json"],"produces":["*/*"],"parameters":[{"name":"cashId","in":"query","description":"Идентификатор кассы","required":false,"type":"string","allowEmptyValue":false},{"in":"body","name":"client","description":"Клиент","required":false,"schema":{"$ref":"#/definitions/Клиент"}},{"name":"clusterId","in":"query","description":"Идентификатор кластера","required":false,"type":"string","allowEmptyValue":false},{"name":"shopCode","in":"query","description":"Код магазина","required":false,"type":"string","allowEmptyValue":false}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Результат работы сервиса"}},"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}},"deprecated":false}},"/version":{"get":{"tags":["Сервис artixcs-issuance-card для выдачи карт"],"summary":"Получить версию сервиса","operationId":"getVersionUsingGET","produces":["*/*"],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}},"deprecated":false}}},"definitions":{"Клиент":{"type":"object","properties":{"address":{"type":"string","description":"Адрес клиента"},"birthday":{"type":"string","format":"date-time","description":"День рождения"},"childrencount":{"type":"integer","format":"int32","description":"Количество детей клиента"},"codeword":{"type":"string","description":"Кодовое слово"},"document":{"type":"string","description":"Данные документа клиента (паспорт, водительское удостоверение и т.д.)"},"email":{"type":"string","description":"Электронный адрес (E-mail)"},"extendedoptions":{"type":"string","description":"Дополнительные параметры"},"idclient":{"type":"string","description":"Идентификационный номер клиента"},"inn":{"type":"string","description":"ИНН"},"name":{"type":"string","description":"ФИО клиента"},"occupation":{"type":"string","description":"Род занятий"},"okpd":{"type":"string","description":"ОКПД"},"okpo":{"type":"string","description":"ОКПО"},"options":{"type":"integer","format":"int32","example":"0 – нет установленных опций, 1 – отправлять чек на e-mail, 2 – e-mail подтвержден","description":"Дополнительные опции"},"organizationcode":{"type":"string","description":"Уникальный код организации"},"phonenumber":{"type":"string","description":"Телефонный номер клиента"},"sex":{"type":"integer","format":"int32","example":"0 - мужской, 1 - женский","description":"Пол клиента"},"specialdate1":{"type":"string","format":"date-time","description":"Первая особая дата клиента"},"specialdate1name":{"type":"string","description":"Название первой особой(специальной) даты"},"specialdate2":{"type":"string","format":"date-time","description":"Вторая особая дата клиента"},"specialdate2name":{"type":"string","description":"Название второй особой(специальной) даты"},"specialdate3":{"type":"string","format":"date-time","description":"Третья особая дата клиента"},"specialdate3name":{"type":"string","description":"Название третьей особой(специальной) даты"},"subscriptionadj":{"type":"integer","format":"int32","example":"0 или NULL – не согласен на рассылку, 1 – согласен на рассылку","description":"Согласие на рассылку"},"text":{"type":"string","description":"Дополнительная информация"},"userid":{"type":"string","description":"Идентификатор пользователя"},"webpage":{"type":"string","description":"Web-страница"},"zipcode":{"type":"string","description":"Почтовый индекс клиента"}},"title":"Клиент"},"Результат работы сервиса":{"type":"object","properties":{"message":{"type":"string","description":"Сообщение о результате работы"},"status":{"type":"integer","format":"int32","example":"0 - успешно, 1 - Не указан номер телефона пользователя, 2 - Клиент с указанным номером уже создан, 3 - Пользователь с указанным номером телефона создан и имеет карту, 4 - Карта с указанным номером не существует, 5 - Отсутствует идентификатор клиента, 6 - Карт с указанным номером больше одной, 7 - Карта уже привязана к клиенту, 8 - Клиент не должен быть пустым, 9 - Генерация справочника завершилась неуспешно, 10 - Карту не удалось привязать к пользователю, 11 - Ошибка при обработке телефонного номера, 12 - Ошибка при создании карты на КС, 13 - Ошибка пин-кода, либо не соответствует, тому, что хранится в кеше, либо истек, 14 - Пин-код не передан, либо пустой, 15 - Ошибка, при которой существует несколько клиентов с одним номером телефона, 16 - Ошибка при создании бонусной карты на бонусном сервере, 100 - Неизвестная ошибка","description":"Статус операции"},"success":{"type":"boolean","example":false,"description":"Флаг результата"}},"title":"Результат работы сервиса"}}} |