README

Laravel 应用程序的 Beem 包

此包使 Laravel 开发者能够将他们的网站/API与所有 Beem API 服务集成。

安装
配置
使用
调试技巧
许可证
贡献

安装

安装前要求

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

然后继续安装

composer require bryceandy/laravel-beem

配置

要访问 Beem 的 API，您需要向此包提供您的 Beem API 密钥和密钥。

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

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

在您创建 Beem 开发者账户并在仪表板上获得密钥后，将它们添加到 .env 变量中

BEEM_KEY=yourApiKey
BEEM_SECRET=yourSecretKey

使用

1. 短信

要发送短信，请使用 Beem 门面并传递消息和接收者作为参数

use Bryceandy\Beem\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'。

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

对于计划发送的短信，您可以使用 datetime 值或 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（请记得在开发者仪表板上更新此回调）。
一个事件 Bryceandy\Beem\Events\SmsDeliveryReportReceived，当数据发送到回调时收集 Beem 的数据。

收集投递数据

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

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

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

<?php

namespace App\Listeners;

use Bryceandy\Beem\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。
一个事件 Bryceandy\Beem\Events\TwoWaySmsCallbackReceived，当数据发送到回调时收集 Beem 的数据。

收集外发短信数据

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

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

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

<?php

namespace App\Listeners;

use Bryceandy\Beem\Events\TwoWaySmsCallbackReceived;
use Bryceandy\Beem\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 Bryceandy\Beem\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。
一个事件 Bryceandy\Beem\Events\UssdCallbackReceived，可用于处理 Beem 的数据

收集 USSD 回调数据

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

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

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

<?php

namespace App\Listeners;

use Bryceandy\Beem\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 Bryceandy\Beem\Facades\Beem;

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

4. 充值

在您有足够的资金在充值仪表板上时开始发送充值

use Bryceandy\Beem\Facades\Beem;

$referenceId = 123456;

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

话费回调成功

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

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

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

收集充值回调数据

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

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

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

<?php

namespace App\Listeners;

use Bryceandy\Beem\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 Bryceandy\Beem\Facades\Beem;

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

5. 收款

此软件包还提供了用于收款的其他回调实现。您可以使用以下功能：

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

收集收款回调数据

使用上述事件，创建一个监听器并将其分配到 App\Providers\EventServiceProvider

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

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

<?php

namespace App\Listeners;

use Bryceandy\Beem\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 Bryceandy\Beem\Facades\Beem;

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

6. 结账

此软件包提供了一个优雅的功能来通过重定向处理 Beem 的支付结账。

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

use Bryceandy\Beem\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

支付结账回调

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

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

收集支付结账回调数据

使用上述事件，创建一个监听器并将其分配到 App\Providers\EventServiceProvider

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

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

<?php

namespace App\Listeners;

use Bryceandy\Beem\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 Bryceandy\Beem\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）

要请求一个密码，你需要用户的号码以及你在OTP仪表板上创建的应用程序ID。

use Bryceandy\Beem\Facades\Beem;

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

为了验证用户发送了正确的PIN，你将从请求的响应中发送一个pinID，以及用户发送的PIN。

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

调试技巧

调试 Bryceandy\Beem\Facades\Beem 界面

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

许可证

MIT许可证

贡献

如果您发现任何错误或想添加功能，请随意发送包含工作测试的详细PR以提高项目质量

bryceandy / laravel-beem

维护者

详细信息