README

此包允许Laravel开发者将他们的网站/API与所有Beem API服务集成

Laravel Beem

安装

预安装要求

支持从版本8.*开始的Laravel项目
最低PHP版本为7.4
您的服务器必须已安装cURL PHP扩展（ext-curl）

然后继续安装

composer require beem/laravel-beem

配置

要访问Beem的API，您需要提供包以访问您的Beem API密钥和密钥

为此，我们需要使用以下内容发布包的配置文件

php artisan vendor:publish --tag=beem-config

在您创建Beem供应商账户并在仪表板上获取密钥后，将它们的值添加到.env变量中

BEEM_KEY=yourApiKey
BEEM_SECRET=yourSecretKey

用法

1. 短信

要发送短信，请使用Beem外观，并传递消息和收件人作为参数

use Beem\Laravel\Facades\Beem;

$recipients = [
    [
        'recipient_id' => (string) 1,
        'dest_addr' => (string) 255784000000,
    ],
    [
        'recipient_id' => (string) 2,
        'dest_addr' => (string) 255754000000,
    ],
];
    
Beem::sms('This is the message', $recipients);

如果您的请求已在供应商仪表板上被接受，则可选地包含您的自定义发送者名称。

默认发送者名称为'INFO'。您可以通过传递sender_name参数来更改它。在使用默认发送者名称时，Beem可以在发送消息时使用另一个发送者，例如'ONSMS'。

Beem::sms('Another message', $recipients, 'SENDER-NAME');

对于计划中的短信，您可以使用日期时间值或Carbon\Carbon实例，但请确保时区为GMT+0

$time = now()->addHours(10);

Beem::smsWithSchedule('Reminder message', $recipients, $time, 'SENDER-NAME');

您还可以使用以下内容检查剩余短信余额

Beem::smsBalance()->json();

短信投递报告

如果您在账户资料中指定了回调URL，则可以使用该路由的任何方式。

可选地，此包包含

可定制的回调路由/beem/sms-delivery-report。前缀可以使用.env值中的BEEM_PATH进行更改。一旦更改，路由变为/{env-value}/sms-delivery-report（请记住在供应商仪表板上更新此回调）。
一个事件Beem\Laravel\Events\SmsDeliveryReportReceived，用于收集Beem发送到回调的数据。

收集投递数据

要使用上述事件，请在App\Providers\EventServiceProvider中分配一个监听器

class EventServiceProvider extends ServiceProvider
{
    protected $listen = [
        \Beem\Laravel\Events\SmsDeliveryReportReceived::class => [
            \App\Listeners\ProcessDeliveryReport::class,
        ],
    ];
}

创建监听器类后，您可以使用Beem的投递报告

<?php

namespace App\Listeners;

use Beem\Laravel\Events\SmsDeliveryReportReceived;

class ProcessDeliveryReport
{
    /**
     * Handle the event.
     *
     * @param  SmsDeliveryReportReceived $event
     * @return \Illuminate\Http\JsonResponse
     */
    public function handle(SmsDeliveryReportReceived $event)
    {
        $requestId = $event->request['request_id'];
        $recipientId = $event->request['recipient_id'];
        $mobileNumber = $event->request['dest_addr'];
        $status = $event->request['status'];
        //...
        
        // After processing this report, send back an OK response to Beem
        return response()->json([]);
    }
}

在您的供应商账户中获取短信发送者名称

Beem::smsSenderNames()->json();

新发送者名称也可以通过API请求。遵循Beem关于发送者名称格式的指南

$name = 'BRYCEANDY';
$sampleMessage = 'A sample message';

Beem::requestSmsSenderName($name, $sampleMessage);

短信模板

以下内容可用于查看供应商的所有短信模板

Beem::smsTemplates()->json();

也可以添加新的短信模板

$message = 'Have a nice day!';
$smsTitle = 'Greetings';

Beem::addSmsTemplate($message, $smsTitle);

如果您有它们的template_id，则可以编辑或删除短信模板

// Template IDs can be obtained from the call above - Beem::smsTemplates()->json()

Beem::editSmsTemplate($templateId, $message, $smsTitle);

Beem::deleteSmsTemplate($templateId);

双向短信

在短信仪表板上请求一个号码后，您将必须编辑它以分配回调URL。

您可以使用提供的路由的任何方式，但此包包含

可自定义的回调路由 /beem/outbound-sms。可以使用.env文件中的BEEM_PATH值来更改前缀。更改后，路由变为/{env-value}/outbound-sms。
一个事件 Beem\Laravel\Events\TwoWaySmsCallbackReceived，用于收集在发送到回调后Beem的数据。

收集出站短信数据

在EventServiceProvider中为上述事件分配一个事件监听器

class EventServiceProvider extends ServiceProvider
{
    protected $listen = [
        \Beem\Laravel\Events\TwoWaySmsCallbackReceived::class => [
            \App\Listeners\ProcessOutboundSms::class,
        ],
    ];
}

创建监听器后，您可以收集短信数据并发送回复

<?php

namespace App\Listeners;

use Beem\Laravel\Events\TwoWaySmsCallbackReceived;
use Beem\Laravel\Facades\Beem;

class ProcessOutboundSms
{
    /**
     * Handle the event.
     *
     * @param  TwoWaySmsCallbackReceived $event
     * @return void
     */
    public function handle(TwoWaySmsCallbackReceived $event)
    {
        $from = $event->request['from'];
        $to = $event->request['to'];
        $text = $event->request['message']['text'];
        //...
        
        // After processing the received text, send a reply in your preferred way
        $recipients = [
            [
                'recipient_id' => (string) 1,
                'dest_addr' => $from
            ],
        ];

        Beem::sms('Your order is being processed!', $recipients, $to);
    }
}

2. 联系人

列出所有地址簿

use Beem\Laravel\Facades\Beem;

Beem::addressBooks()->json();
Beem::addressBooks($name)->json(); // Search by address book name

使用以下方法添加新的地址簿

Beem::addAddressBook($name, $description);

如果您有它们的addressbook_id，可以编辑或删除地址簿

// Obtain the address book IDs from - Beem::addressBooks();

Beem::editAddressBook($addressBookId, $name, $description);

Beem::deleteAddressBook($addressBookId);

列出特定地址簿的联系人。可选地按姓氏、名或手机号码筛选

// $q values are either 'fname', 'lname', or 'mob_no'
Beem::contacts($addressBookId, $q)->json();

将新联系人添加到地址簿需要手机号码和地址簿ID数组。其他字段是可选的；

$addressBookIds = ['abcd123', '456efg'];
$mobileNumber = '255784123456';

Beem::addContact($addressBookIds, $mobileNumber);
Beem::addContact($addressBookIds, $mobileNumber, $firstName, $lastName, $title, $gender, $mobileNumber2, $email, $country, $city, $area, $birthDate);

// $title can be Mr./Mrs./Ms.
// $gender can be male, female
// $birthDate can be a datetime value or Carbon instance

可以通过contact_id编辑联系人。其他必需字段是地址簿ID和手机号码。

// Contact IDs can be obtained from the previous method - Beem::contacts()

Beem::editContact($contactId, $addressBookIds, $mobileNumber, $firstName);
Beem::editContact($contactId, $addressBookIds, $mobileNumber, $firstName, $lastName, $title, $gender, $mobileNumber2, $email, $country, $city, $area, $birthDate);

最后，可以通过指定contact_id和addressbook_id来删除联系人

$contactId = ['4sgb9ddfgb'];
$addressBookIds = ['abcdefg', '123456'];

Beem::deleteContact($addressBookIds, $contactId);

3. USSD

在USSD应用中，Beem将数据发送到您在USSD仪表板中指定的回调URL。

此包附带一个可选实现，提供以下功能：

一个可自定义的路由/beem/ussd-callback，用于定义回调URL。如果您在.env文件中添加了BEEM_PATH的值，路径现在将是/{env-value}/ussd-callback。
一个事件Beem\Laravel\Events\UssdCallbackReceived，可以用于处理Beem的数据。

收集USSD回调数据

在EventServiceProvider中为上述事件分配一个事件监听器

class EventServiceProvider extends ServiceProvider
{
    protected $listen = [
        \Beem\Laravel\Events\UssdCallbackReceived::class => [
            \App\Listeners\ProcessUssdCallback::class,
        ],
    ];
}

然后在ProcessUssdCallback监听器类中，您可以收集处理所需的数据

<?php

namespace App\Listeners;

use Beem\Laravel\Events\UssdCallbackReceived;

class ProcessUssdCallback
{
    /**
     * Handle the event.
     *
     * @param  UssdCallbackReceived $event
     * @return \Illuminate\Http\JsonResponse
     */
    public function handle(UssdCallbackReceived $event)
    {
        $command = $event->request['command'];
        $msisdn = $event->request['msisdn'];
        $session_id = $event->request['session_id'];
        $operator = $event->request['operator'];
        $payload = $event->request['payload'];
        
        // After processing this data, send your custom response to Beem
        
        $sampleResponse = [
            'msisdn' => '2556730893370',
            'operator' => 'vodacom',
            'session_id' => '14545',
            'command' => 'initiate',
            'payload' => [
                'request_id' => 0,
                'request' => 'enter phone number',
            ],
        ];
        
        return response()->json($sampleResponse);
    }
}

检查USSD余额

use Beem\Laravel\Facades\Beem;

Beem::ussdBalance()->json();

4. 充值

当您在话费仪表板中有足够的余额时，开始发送话费

use Beem\Laravel\Facades\Beem;

$referenceId = 123456;

Beem::airtimeRecharge('255789123456', '1000.00', $referenceId);

充值回调成功

如果您在话费仪表板配置文件中定义了回调URL，交易完成后Beem将发送数据。

可选地，您可以使用此包的回调实现，该实现提供以下功能：

一个回调路由/beem/airtime-callback，可以通过在env文件中添加BEEM_PATH值来自定义。一旦设置此变量，您的回调路由将变为/{env-value}/airtime-callback（请记住在配置文件中更改此设置）。
一个事件Beem\Laravel\Events\AirtimeCallbackReceived，可以用于监听所有回调。

收集充值回调数据

使用上述事件并在App\Providers\EventServiceProvider中分配一个新的监听器

class EventServiceProvider extends ServiceProvider
{
    protected $listen = [
        \Beem\Laravel\Events\AirtimeCallbackReceived::class => [
            \App\Listeners\ProcessAirtimeCallback::class,
        ],
    ];
}

然后在创建App\Listeners\ProcessAirtimeCallback类后，获取回调数据

<?php

namespace App\Listeners;

use Beem\Laravel\Events\AirtimeCallbackReceived;

class ProcessAirtimeCallback
{
    /**
     * Handle the event.
     *
     * @param  AirtimeCallbackReceived $event
     * @return \Illuminate\Http\JsonResponse
     */
    public function handle(AirtimeCallbackReceived $event)
    {
        $code = $event->request['code'];
        $message = $event->request['message'];
        //...
        
        // After processing this data, send an OK response to Beem
        return response()->json([]);
    }
}

查询充值交易状态

检查充值请求的状态。使用从请求的->json()响应中获得的transaction_id。

//$request = Beem::airtimeRecharge('255789123456', '1000.00', $referenceId)->json();

Beem::airtimeTransaction($request['transaction_id'])->json()

检查充值余额

use Beem\Laravel\Facades\Beem;

Beem::airtimeBalance()->json();

5. 收款

此包还提供另一个支付收集回调的实现。以下可供您使用：

支付收集事件Beem\Laravel\Events\PaymentCollectionReceived，允许您即时处理Bpay支付。
一个可自定义的回调路由/beem/payment-collection。如果您决定使用此回调实现，请记住在产品仪表板上更新回调URL。

收集收款回调数据

使用上述事件创建一个监听器来处理回调，并在App\Providers\EventServiceProvider中分配它们

class EventServiceProvider extends ServiceProvider
{
    protected $listen = [
        \Beem\Laravel\Events\PaymentCollectionReceived::class => [
            \App\Listeners\ProcessPaymentCollection::class,
        ],
    ];
}

然后在创建App\Listeners\ProcessPaymentCollection监听器类后，获取所需的数据

<?php

namespace App\Listeners;

use Beem\Laravel\Events\PaymentCollectionReceived;

class ProcessPaymentCollection
{
    /**
     * Handle the event.
     *
     * @param  PaymentCollectionReceived $event
     * @return \Illuminate\Http\JsonResponse
     */
    public function handle(PaymentCollectionReceived $event)
    {
        $transactionId = $event->request['transaction_id'];
        $amount = $event->request['amount_collected'];
        $subscriber = $event->request['subscriber_msisdn'];
        $network = $event->request['network_name'];
        $referenceNumber = $event->request['reference_number'];
        //...
        
        // After processing this data, send a response to Bpay 
        return response()->json([
            'transaction_id' => $transactionId,
            'successful' => true,
        ]);
    }
}

检查收款余额

use Beem\Laravel\Facades\Beem;

Beem::paymentCollectionBalance()->json();

6. 结账

此包提供了一种eloquent功能来处理Beem的支付结账通过重定向。

收集所需数据，并在您的控制器或类中的任何位置使用重定向门面；

use Beem\Laravel\Facades\BeemRedirect;

$amount = '2000';
$transactionId = '96f9cc09-afa0-40cf-928a-d7e2b27b2408';
$referenceNumber = 'SAMPLE-12345';

return BeemRedirect::checkout($amount, $transactionId, $referenceNumber);
// Or include the mobile number
// BeemRedirect::checkout($amount, $transactionId,$referenceNumber, '255798333444');
// Tip: always use a return statement, in order to send the user to the payment page

结账回调

此包还提供另一个支付结账回调的实现。以下可供您使用：

支付结账事件Beem\Laravel\Events\PaymentCheckoutCallbackReceived，在支付结账回调击中您的回调URL时触发。
一个可自定义的回调路由/beem/payment-checkout。如果您决定使用此回调实现，请记住在产品仪表板上更新回调URL。

收集结账回调数据

使用上述事件创建一个监听器，并在App\Providers\EventServiceProvider中分配它

class EventServiceProvider extends ServiceProvider
{
    protected $listen = [
        \Beem\Laravel\Events\PaymentCheckoutCallbackReceived::class => [
            \App\Listeners\ProcessPaymentCheckout::class,
        ],
    ];
}

创建监听器类 App\Listeners\ProcessPaymentCheckout 后，获取所需的数据

<?php

namespace App\Listeners;

use Beem\Laravel\Events\PaymentCheckoutCallbackReceived;

class ProcessPaymentCheckout
{
    /**
     * Handle the event.
     *
     * @param  PaymentCheckoutCallbackReceived $event
     * @return \Illuminate\Http\JsonResponse
     */
    public function handle(PaymentCheckoutCallbackReceived $event)
    {
        $transactionId = $event->request['transactionId'];
        $amount = $event->request['amount'];
        $referenceNumber = $event->request['referenceNumber'];
        $status = $event->request['status'];
        //...
        
        // After processing this data, send a response to Bpay as follows
        $statusMessage = 'This payment has been completed';

        return response()->json(
            compact('amount', 'status', 'referenceNumber', 'statusMessage', 'transactionId')
        );
    }
}

7. 支付

要通过分摊发送付款，请使用具有适当参数的外观

use Beem\Laravel\Facades\Beem;

Beem::disburse($amount, $clientReferenceId, $accountNumber, $walletNumber, $walletCode);

// Optionally, specify the currency, the default is TZS
Beem::disburse($amount, $clientReferenceId, $accountNumber, $walletNumber, $walletCode, $currency);

8. OTP

要请求PIN，您需要用户的电话号码和您在OTP仪表板中创建的应用ID。

use Beem\Laravel\Facades\Beem;

Beem::requestOtp($appId, $phoneNumber)->json();

为了验证用户发送了正确的PIN，您将发送请求响应中的pinID和用户发送的PIN。

Beem::verifyOtp($pinId, $pin)->json();

调试技巧

要调试 Beem\Laravel\Facades\Beem 外观

使用 ->json() 方法获取响应数据。
使用布尔方法 ->successful() 查看请求是否成功

测试

composer test

变更日志

请参阅变更日志了解最近更改的信息。

贡献

请参阅贡献指南了解详细信息。

安全漏洞

请参阅我们的安全策略了解如何报告安全漏洞。

鸣谢

Bryce Andy 进行初始实现。
Alpha Olomi
所有贡献者

许可

MIT许可（MIT）。请参阅许可文件了解更多信息。

beem / laravel-beem

维护者

详细信息