b24io/loyalty-php-sdk

B24io.Loyalty: PHP-SDK for bonus cards and loyalty program for Bitrix24

2.0.1 2020-09-28 22:38 UTC

README

License Total Downloads Build Status

Loyalty PHP SDK is a tool for work with REST-API Bitrix24 Application Loyalty Program and bonus cards for Bitrix24 CRM

  • Loyalty app adds bonus card for Bitrix24 client profile in CRM
  • Loyalty app support transactions for payment and accrual operations
  • store percentage of discount
  • operations with cards: create, read, delete, block

Documentation

Who uses loyalty PHP SDK

  • B2C companies who works with customers and grow they LTV
  • HoReCa companies such us fast food or restaurants

How it works

Loyalty Program and bonus cards for Bitrix24 CRM

Domain entities

In loyalty-php-sdk available domain entities from application with DTO (data transfer objects).

Cards

Loyalty card object:

  • number - card number
  • barcode - card barcode
  • status - card status enumeration (active, blocked or deleted)
  • user - card owner user id
  • balance - card balance with php-money object
  • percentage - card percentage
  • created - card date create
  • modified - card date modified
  • uuid - card universally unique identifier

Transactions

Transactions - accrual or payment operation with card balance

Transaction object:

  • value - transaction amount with php-money object
  • operationId - internal operation id, read only
  • type - payment or accrual transaction
  • cardNumber - card number
  • created - transaction date create
  • reason - transaction reason with comment

Turnovers

Turnover object:

  • modified - last operation date
  • totalPurchasesSum - total purchases sum for card
  • totalPurchasesCount - total purchases count for card

OperationsJournal

Operations journal with card - it's read only log with card state history

Operation objects implements operation interface:

  • Uuid - operation uuid
  • OperationType - enumeration of operation types ()
  • CardUuid - card uuid
  • UserId - user id
  • Timestamp - operation timestamp
  • Reason - operation reason

Operation types

  • accrual_transaction - accrual transaction
  • payment_transaction - payment transaction
  • create_card - card create
  • block_card - block card
  • unblock_card - unblock card
  • delete_card - delete card
  • decrement_percent - decrement percent on card
  • increment_percent - increment percent on card
  • purchase - purchase registration
  • b24_deal_monetary_discount_payment_trx - Bitrix24 deal partial payment with monetary discount
  • b24_deal_percentage_discount_payment_trx - Bitrix24 deal partial payment with percentage discount

Metrics

Metrics describe operational parameters loyalty application

Metric object:

  • uuid - metric uuid
  • name - metric name
  • description - metric description
  • code - metric code
  • type - metric type enumeration: INTEGER, FLOAT, MONEY, PERCENTAGE
  • created - metric created date time

Bitrix24 Contacts

Bitrix24 Loyalty application do not store contacts, app fetch Bitrix24 contacts in realtime with each API-request.

Contact object:

  • contactId - Bitrix24 contact id
  • name - name
  • secondName - second name
  • lastName - last name
  • birthday - contact birthday
  • comments - comments about contact
  • created - contact date create
  • modified - contact date modified
  • mobilePhone - contact mobile phone
  • email - contact personal email
  • address - contact address
  • originId - origin identifier
  • originatorId - originator identifier
  • utm - utm labels for contact ads channel tracking
  • sourceDescription - source description

Installation

Via Composer

$ composer require b24io/loyalty-php-sdk

Requirements

Loyalty PHP SDK works with PHP 7.1 or above, need ext-json and ext-curl support

Authentication with admin and user roles

SDK can work with two roles:

  • admin - can work with all cards in his Bitrix24 account and loyalty application instance
  • user - can work only with his card

Bitrix24 Application Loyalty Program and bonus cards work with many Bitrix24 accounts, each account has a CLIENT_API_KEY If you want work in admin role you must use ADMIN_API_KEY to sign queries.

$token = new SDK\Auth\DTO\Token(
    SDK\Transport\DTO\Role::initializeByCode('admin'),
    Uuid::fromString('CLIENT_API_KEY'),
    Uuid::fromString('ADMIN_API_KEY')
);

If you want work with client role in JS you must use CLIENT_API_KEY and CARD_UUID as user API key.

Basic Usage

use \Monolog\Logger;
use \B24io\Loyalty\SDK;
use Ramsey\Uuid\Uuid;

use GuzzleHttp\HandlerStack;
use GuzzleHttp\Middleware;
use GuzzleHttp\MessageFormatter;

$log = new Logger('loyalty-php-sdk');
$log->pushHandler(new \Monolog\Handler\StreamHandler('loyalty-php-sdk-example.log', Logger::DEBUG));
$guzzleHandlerStack = HandlerStack::create();
$guzzleHandlerStack->push(
    Middleware::log(
        $log,
        new MessageFormatter(MessageFormatter::SHORT)
    )
);
$httpClient = new \GuzzleHttp\Client();

$log->info('loyalty.apiClient.start');
$token = new SDK\Auth\DTO\Token(
    SDK\Transport\DTO\Role::initializeByCode('admin'),
    Uuid::fromString('CLIENT_API_KEY'),
    Uuid::fromString('ADMIN_API_KEY')
);
$apiClient = new SDK\ApiClient($apiEndpoint, $token, $httpClient, $log);
$apiClient->setGuzzleHandlerStack($guzzleHandlerStack);

$cardsTransport = SDK\Cards\Transport\Admin\Fabric::getCardTransport($apiClient, $log);

$cardResponse = $cardsTransport->getCardByNumber(22222);

$decimalMoneyFormatter = new \Money\Formatter\DecimalMoneyFormatter(new \Money\Currencies\ISOCurrencies());
var_dump($cardResponse->getCard()->getNumber());
var_dump($cardResponse->getCard()->getStatus()->getCode());
var_dump($decimalMoneyFormatter->format($cardResponse->getCard()->getBalance()));
var_dump($cardResponse->getCard()->getPercentage()->format());

Documentation and examples

More complex examples and use cases you can see in folder examples

Submitting bugs and feature requests

Bugs and feature request are tracked on GitHub

Support

Security

If you discover any security related issues, please contact us at app@b24.io

License

The MIT License (MIT). Please see License File for more information.