README

SMS Connexion API PHP库提供了从PHP语言编写的应用程序中对SMS.CX SMS API的方便访问。

使用此库，您可以

发送短信（交易性、促销性）- 单条或批量短信
接收短信
租赁电话号码
验证电话号码
查找电话号码（HLR）
发送OTP短信（双因素认证）
创建联系人组
导入联系人
创建短链接
等等

更多信息，请访问https://sms.cx

内容

安装
认证
使用
处理错误
速率限制
文档
可用方法

安装

要求

PHP 7.4及以后版本（与PHP 8.0兼容）。

Composer

为了安装库，建议您使用Composer

$ composer require smscx/smscx-api-php-library

上述命令将安装库及其所有依赖项。

要使用库，请使用Composer的自动加载

require_once('vendor/autoload.php');

依赖项

库需要以下扩展才能正常运行

ext-curl
ext-json
ext-mbstring
Guzzle（PHP HTTP客户端，便于发送HTTP请求）
GuzzleHttp\Psr7（请求、响应和流的PSR-7接口）

如果您使用Composer，这些依赖项应该会自动处理。如果您手动安装，请确保这些扩展可用。

认证

要使用库，您必须进行认证。SMS.CX PHP库支持SMS Connexion API支持的认证方法

API密钥
Oauth2访问令牌

1. API密钥

要创建新的API密钥，请访问SMS.CX账户 > HTTP API > API密钥并点击新建API密钥。

复制API密钥并在库中使用它。

2. Oauth2访问令牌

访问令牌由应用程序用于发出API请求。

要创建新应用程序，请访问SMS.CX账户 > HTTP API > 应用程序并点击新建应用程序。

当您有应用程序ID和应用密钥时，您可以使用它们请求一个访问令牌，该令牌可用于发出API调用。

复制APPLICATION_ID和APPLICATION_SECRET并使用它们请求访问令牌

<?php

require_once(__DIR__ . '/vendor/autoload.php');

$config = Smscx\Configuration::getDefaultConfiguration()
              ->setApplicationId('YOUR_APPLICATION_ID')
              ->setApplicationSecret('YOUR_APPLICATION_SECRET');

$smscx = new Smscx\Api\OauthApi(
    new GuzzleHttp\Client(),
    $config
);
// A list of space-delimited, case-sensitive strings. If left empty or ommited,
// the issued access token will be granted with all scopes (full privileges)
$scopes = ''; 

try {
    $result = $smscx->getAccessToken($scopes);
    $accessToken = $result->getAccessToken();
    $expiresIn = $result->getExpiresIn();
    print_r($result);
} catch (Smscx\Client\Exception\InvalidRequestException $e) {
    //Code for Invalid request
} catch (Smscx\Client\Exception\InvalidCredentialsException $e) {
    //Code for Invalid credentials
} catch (Smscx\Client\Exception\InvalidScopeException $e) {
    //Code for Invalid scope
} catch (Smscx\Client\Exception\ApiException $e) {
    echo 'Exception when calling OauthApi->getAccessToken: ', $e->getMessage(), PHP_EOL;
}

与使用API密钥相比，访问令牌提供了三个主要的安全优势

可撤销的访问。可以撤销访问令牌，移除仅对该令牌的访问权限，而无需在所有地方更改API密钥。
有限的访问。访问令牌具有访问范围，这允许对API资源进行更细粒度的访问。例如，您可以仅授予发送短信的访问权限，而不授予获取联系人组的访问权限。
短暂的生命周期。访问令牌有过期时间（1天、1周），这降低了令牌被泄露的风险。

使用

库需要配置您的账户的应用程序ID & 密钥或API密钥，这些在您的SMS.CX仪表板中可用。

以下示例将向单个手机号码发送短信

<?php

require_once(__DIR__ . '/vendor/autoload.php');

// Use authentication via API Key
$config = Smscx\Configuration::getDefaultConfiguration()->setApiKey('YOUR_API_KEY');

// OR

// Use authentication via Access Token
// $config = Smscx\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');

$smscx = new Smscx\Api\SmsApi(
    new GuzzleHttp\Client(),
    $config
);

$send_sms_message_request = [
    'to' => '+31612469xxx',
    'from' => 'InfoText',
    'text' => 'Your confirmation code is 15997',
];

try {
    $result = $smscx->sendSms($send_sms_message_request);
    print_r($result);
    //$result->getInfo()->getTotalCost();
} catch (InvalidArgumentException $e) {
    //Code for Invalid argument provided
} catch (Smscx\Client\Exception\NoCoverageException $e) {
    //Code for No coverage
} catch (Smscx\Client\Exception\InvalidRequestException $e) {
    //Code for Invalid request    
} catch (Smscx\Client\Exception\InvalidPhoneNumberException $e) {
    //Code for Invalid phone number    
} catch (Smscx\Client\Exception\InsufficientBalanceException $e) {
    //Code for Insufficient balance
} catch (Smscx\Client\Exception\ApiException $e) {
    echo 'Exception when calling SmsApi->sendSms: ', $e->getMessage(), PHP_EOL;
    // $http_code = $e->getCode();  # For HTTP response code: 400, 401, 403, 429, 500, etc
    // $error_type = $e->getResponseObject()->getError()->getType();  # For type of error: invalid_param, insufficient_credit, rate_limit, etc
    // $error_message = $e->getResponseObject()->getError()->getMessage();  # Short description of the error
    // $error_code = $e->getResponseObject()->getError()->getCode();  # API internal error code: 1208, 1101, 1221, etc    
}

批量发送短信示例（最多25,000个目标手机号码）

<?php

require_once(__DIR__ . '/vendor/autoload.php');

// Use authentication via API Key
$config = Smscx\Configuration::getDefaultConfiguration()->setApiKey('YOUR_API_KEY');

// OR

// Use authentication via Access Token
// $config = Smscx\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');

$smscx = new Smscx\Api\SmsApi(
    new GuzzleHttp\Client(),
    $config
);

$send_sms_message_request = [
    //Max 25.000 phone numbers
    'to' => [
        '+31612469xxx', 
        '+4474005085xx', 
        '+49151238353xx', 
        '+417811126xx', 
        '+3519123350xx', 
        '+4206016090xx',
        '+359483059xx',
        '+336127904xx',
        '+436645595xx',
        '+3519121385xx',
        '+3069125917xx',
    ],
    'from' => 'InfoText',
    'text' => 'Redeem this voucher and you will get 30% discount off all Summer Fashion {{optoutLink}}',
    'allowInvalid' => true,
    'transliteration' => [
        'alphabet' => 'NON_GSM',
        'removeEmojis' => true,
    ],
    'idempotencyId' => '854cd53f-d77d-4aa8-9bd9-fbf720f3332d',
];

try {
    $result = $smscx->sendSms($send_sms_message_request);
    print_r($result);
    //$result->getInfo()->getTotalCost();
    //$result->getInfo()->getInvalid();
} catch (InvalidArgumentException $e) {
    //Code for Invalid argument provided
} catch (Smscx\Client\Exception\NoCoverageException $e) {
    //Code for No coverage
} catch (Smscx\Client\Exception\InvalidRequestException $e) {
    //Code for Invalid request    
} catch (Smscx\Client\Exception\InvalidPhoneNumberException $e) {
    //Code for Invalid phone number    
} catch (Smscx\Client\Exception\InsufficientBalanceException $e) {
    //Code for Insufficient balance
} catch (Smscx\Client\Exception\ApiException $e) {
    echo 'Exception when calling SmsApi->sendSms: ', $e->getMessage(), PHP_EOL;
    // $http_code = $e->getCode();  # For HTTP response code: 400, 401, 403, 429, 500, etc
    // $error_type = $e->getResponseObject()->getError()->getType();  # For type of error: invalid_param, insufficient_credit, rate_limit, etc
    // $error_message = $e->getResponseObject()->getError()->getMessage();  # Short description of the error
    // $error_code = $e->getResponseObject()->getError()->getCode();  # API internal error code: 1208, 1101, 1221, etc    
}

处理错误

使用此客户端库，您无需检查非200 HTTP响应。库将它们转换为异常。

在某些特定且罕见的情况下，您可能需要分析type和code属性的错误对象。

要处理错误，请使用以下两种技术

捕获异常
分析并处理响应体中提供的错误对象

1. 捕获异常

SMS.CX PHP库会对每种错误类型抛出异常。建议捕获并处理异常。

要捕获异常，请使用PHP的try/catch语法。SMS Connexion提供了许多您可以捕获的异常类。每个类代表不同类型的错误。当您捕获一个异常时，可以使用其类来选择一个响应。

一般异常

DuplicateIdException - 具有相同ID的资源已存在
DuplicateValueException - 您正在尝试创建/更新必须唯一的资源（例如，发件人、群组名称、短链接、模板名称）
InsufficientScopeException - 您的应用程序没有访问资源的权限
InvalidCredentialsException - 根据提供的信息无法验证您
InvalidRequestException - 提供的参数无效
InvalidScopeException - 请求的范围不存在
RateLimitExcedeedException - 您在短时间内进行了过多的API调用。
ResourceNotFoundException - 请求的资源ID未找到（例如，群组、活动、OTP、短链接、模板等）
ApiMethodNotAllowedException - 目标资源不支持此HTTP方法
AccessDeniedException - 您没有执行操作（例如，编辑被锁定模板、在客户回复24小时后回复WhatsApp等）的权限
ServerErrorException - SMS Connexion内部出现错误。
ApiException - SMS Connexion内部出现错误

验证数字或产生成本的方法的异常（发送短信、将电话号码添加到群组、验证数字等）

InsufficientBalanceException - 您的请求产生的费用超过现有余额。
InvalidPhoneNumberException - 提供的电话号码无效

需要网络覆盖的方法的异常（发送短信、Viber、WhatsApp）

NoCoverageException - 目标请求没有覆盖（这些很少见）

OTP的异常

InvalidPinException - 提供的PIN与我们记录不匹配
OtpAlreadyVerifiedException - OTP已被验证
OtpCancelledException - 您不能验证已取消的OTP
OtpActionNotAllowedException - 您不能取消具有非挂起状态（例如，已被验证、取消或过期）的OTP
OtpExpiredException - 您不能验证过期的OTP
OtpFailedException - OTP验证失败，因为达到最大尝试次数

Viber/WhatsApp的异常

ChannelNotActiveException - 通道未激活。您需要通过联系我们注册Viber和WhatsApp
TemplateNotApprovedException - 发送Viber或WhatsApp的模板未获批准

2. 分析错误对象

错误对象（ \Smscx\Client\Model\Error ），存在于所有异常中，存储有关失败的信息。

如果您不想依赖于我们现有的异常，您可能需要分析错误对象的详细信息。

您可以检索错误对象并检查它以了解更多关于失败的信息。根据错误类型选择适当的响应。检查提供的示例以了解如何获取HTTP代码和错误对象。

API 返回多种不同类型的错误，与它们的 HTTP 状态码相关联

对于错误类型 invalid_param 和 insufficient_credit，返回 HTTP 400 错误请求
对于 invalid_api_key 和 invalid_client，返回 HTTP 401 未授权
对于错误类型 not_found，返回 HTTP 404 未找到
对于错误类型 rate_limit，返回 HTTP 429 请求过多

请参阅 API 规范中的完整错误类型和代码列表：错误类型和代码

错误处理示例

try {
    // Method
} catch (Smscx\Client\Exception\InvalidRequestException $e) {
    // Code for this situation
} catch (Smscx\Client\Exception\RateLimitExcedeedException $e) {
    // Wait some time and retry the request
    $retryAfter = $e->getHeader('X-Rate-Limit-Reset'); //Unix timestamp eg. 1664103086
} catch (Smscx\Client\Exception\ServerErrorException $e) {
    // Code for this situation
} catch (Smscx\Client\Exception\ApiException $e) {
    // If you want to analyze the Error object
    $httpCode = $e->getCode();
    $errorType = $e->getResponseObject()->getError()->getType();
    $errorMessage = $e->getResponseObject()->getError()->getMessage();
    $errorCode = $e->getResponseObject()->getError()->getCode();
}

在特殊情况下，当使用批量验证电话号码的方法或在现有组中添加电话号码时，Error 对象将包含一个 无效电话号码列表（如果未将参数 allowInvalid 设置为 true 或没有检测到任何有效的号码）。

$invalidPhoneNumbers = $e->getResponseObject()->getError()->getInvalid();
/*
Returns array of invalid numbers:
[
  "+336123",
  "+336123",
  "+44158994578",
  "+39677814354",
  "+336259987345",
]
*/

速率限制

要检测 API 速率限制错误，可以捕获异常 RateLimitExcedeedException 或检查错误对象的错误类型是否为 rate_limit 或检查 HTTP 状态码是否为 429

try {
    // Method
} catch (Smscx\Client\Exception\RateLimitExcedeedException $e) {
    //Rate limited
    $retryAfter = $e->getHeader('X-Rate-Limit-Reset'); //Unix timestamp eg. 1664103086
}

文档

在 docs 文件夹中提供了使用此库的详细指南（方法、模型、示例）。

在 examples 文件夹中为每个方法提供了一个示例。

API 的完整文档可在此处获取。

可用方法

阅读每个方法的文档，以获取更多示例、完整的参数列表、预期响应和错误代码列表。

类 AccountApi

类 ApplicationsApi

类 AttachmentsApi

类 ConversationsApi

类 GroupsApi

类 MultichannelApi

类 NumbersApi

类 OauthApi

类 OptoutsApi

类 OriginatorsApi

类 OtpApi

类 ReportsApi

类 ShortlinksApi

类 SmsApi

类 TemplatesApi

类 ViberApi

类 WhatsappApi

授权

ApiKeyAuth

类型：API密钥
API密钥参数名：X-API-KEY
位置：HTTP头

BasicAuth

类型：HTTP基本身份验证

BearerAuth

类型：Bearer身份验证

测试

要运行测试，请使用

composer install
vendor/bin/phpunit

作者

dev@sms.cx

关于此包

客户端库版本：0.1.1
API版本：1.0.2

smscx / smscx-api-php-library

维护者

详细信息