loyalty php sdk

лояльность-php-sdk

loyalty php sdk — инструмент для работы с REST-API Программы лояльности приложений Битрикс24 и бонусными картами для Битрикс24 CRM

• Приложение лояльности добавляет бонусную карту для профиля клиента Битрикс24 в CRM
• Поддержка транзакций приложения лояльности для операций оплаты и начисления
• процент скидки магазина
• операции с карточками: создание, чтение, удаление, блокировка

Документация

• Документация REST-API

Установка

Через композитор

$ composer require b24io/loyalty-php-sdk

Версии

лояльность-php-sdk версия	статус поддержки	строить статус	REST-API версия	PHP версии
v4.x	? активный		2	8.2 , 8.3
v3.x	? только исправление ошибок		2	7.4
v2	? конец жизни ☠️		1	7.4
v1	? конец жизни ☠️		1	7.4

Требования

loyalty php sdk работает с PHP 8.2 или выше, требуется поддержка ext-json и ext-curl

Аутентификация с ролями администратора и пользователя

SDK может работать с двумя ролями:

• admin - может работать со всеми картами в своем аккаунте и экземпляре приложения лояльности
• user - может работать только со своей картой

Мы работаем со многими учетными записями, каждая учетная запись имеет CLIENT_API_KEY Если вы хотите работать в роли администратора, вы должны использовать ADMIN_API_KEY для подписи запросов. Если вы хотите работать с ролью клиента в JS, вы должны использовать CLIENT_API_KEY и CARD_UUID в качестве ключа API пользователя.

Сущности предметной области, доступные из REST-API

Легенда

• ✅ — доступно через rest-api и реализовано в PHP-SDK.
• ? — доступно через rest-api и не реализовано в PHP-SDK
• — не реализовано в rest-api

Карты

Работа с картой от имени admin

Метод	Статус	Описание
list	✅	получить список карточек с навигацией по страницам
getById	✅	получить карту по uuid
count	✅️	считать карты
delete		удалить карту по uuid
add	✅️	добавить новую карту
block	️	заблокировать карту по uuid
unblock	️	разблокировать карту по uuid
setLevel	️	установить уровень карты по uuid
setPercentage	️	установить процент карты по uuid

Работа с картой в роли user

Метод	Статус	Описание
getById	?	получить карту по uuid

Если вам нужно экспортировать все карточки, вы можете использовать CardsFetcher

Уровни карт

Работайте с уровнями карт в качестве admin .

Метод	Статус	Описание
list	?	получить список уровней карты
add	?	добавить новый уровень карты
delete	?	удалить уровень карты
update	️	обновить уровень карты

Транзакции

Работайте с транзакциями в роли admin .

Сервис транзакций содержит методы, метод списка работает с нумерацией страниц.

Метод	Описание
list	получить список транзакций для всех карт с нумерацией страниц
count	считать транзакции
getByCardNumber	получить список транзакций по текущему номеру карты
processAccrualTransactionByCardNumber	обработка транзакции начисления
processPaymentTransactionByCardNumber	обрабатывать платежную транзакцию

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

Метод	Описание
list	получить список транзакций по всем картам
listByCardNumber	список всех транзакций по текущей карте

Работа с транзакциями в роли user

Метод	Статус	Описание
getByCardId	?	получить список транзакций по текущей карте

Контакты

Работайте с контактами в роли admin

Метод	Статус	Описание
list	✅	получить список контактов
getById	✅	получить контакт по идентификатору
add	✅	добавить новый контакт
update	️	обновить контакт
delete	️	удалить контакт
count	✅	подсчитать контакты
startAuthByPhone	️	начать попытку авторизации по телефону
finishAuth	️	завершить попытку аутентификации

Работа с контактами в роли user

Метод	Статус	Описание
getById	?	получить контакт по идентификатору
startAuthByPhone	?	начать попытку авторизации по телефону
finishAuth	?	завершить попытку аутентификации

Если вам нужно экспортировать все контакты, вы можете использовать ContactsFetcher

Компания

Работа с компанией в роли admin

Метод	Статус	Описание
current		получить текущую компанию
add	️	добавить компанию
update	️	обновить компанию
delete	️	удалить компанию

Работа с компанией в роли user

Метод	Статус	Описание
current	?	получить текущую компанию

Журнал приложений

Работайте с журналом приложений в качестве admin .

Метод	Статус	Описание
list	?	получить список элементов журнала приложения с навигацией по страницам
getById	?	получить элемент журнала приложения по идентификатору

Точки касания

Работайте с точками взаимодействия в роли admin

Метод	Статус	Описание
list	?	получить список точек взаимодействия с навигацией по страницам
getById	?	получить элемент точки касания по идентификатору
add	?	добавить новую точку соприкосновения
update	️	обновить точку контакта
delete		удалить точку касания

Основное использование

Утилиты командной строки

Утилиты командной строки для работы через REST-API

php bin/console

• cards:export Экспортировать карты лояльности в файл csv.
• transactions:bulk-transaction Массовая транзакция на все активные карты: начисление или оплата
• transactions:load-from-file Обработка транзакций из файла csv
• transactions:export Экспорт транзакций в файл csv

Отправка ошибок и запросов на добавление функций

Ошибки и запросы на добавление функций отслеживаются на GitHub.

Разработка

Тестирование

Запустите инструмент статического анализа

make phpstan

Поддерживать

• приложение@b24.io

Безопасность

Если вы обнаружите какие-либо проблемы, связанные с безопасностью, свяжитесь с нами по адресу [email protected].

Лицензия

Лицензия MIT (MIT). Дополнительную информацию см. в файле лицензии.