README

Класс для работы с API SMS Club.

Подключение сервиса

Для установки сервиса, необходимо добавить атозагрузщик классов в начало файла:

require_once 'smsclub_api/autoload.php';

Затем объявить класс:

$api = new \SmsclubApi\Services\ApiService([
    'token' => 'your_token',      // Токен пользователя
    'login' => 'your_login',      // Логин пользователя
    'password' => 'your_password' // Пароль пользвоателя
]);

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

Акканут

Просмотр баланса

Для просмотра баланса необходимо вызвать метод $api->getBalance();. В ответ вернется объект интерфейса BalanceInterface или false в случае ошибки.

Пример:

$balance = $api->getBalance();

if ($balance) {
    // Получить остаток на балансе
    var_dump($balance->getMoney());    
    
    // Получить валюту аккаунта
    var_dump($balance->getCurrency()); 
}

Получение списака Альфа-имен для отправки СМС

Для получения спсиска Альфа-имен необходимо вызвать метод $api->getSmsOriginators();. В ответ вернется массив объектов интерфейса OriginatorInterface или false в случае ошибки.

Пример:

$originators = $api->getSmsOriginators();

if ($originators) {
    foreach($originators as $originator) {
        // Получить ID отправителя
        var_dump($originator->getId());   
        
        // Получить имя отправителя
        var_dump($originator->getName());  
    }
}

Отправка сообщений

Отправка СМС

Для отправки СМС сообщения необходимо создать объект реализующий SmsInterface и передать его в метод sendSms($sms) API сервиса. Вызов метода sendSms($sms) вернет массив объектов интерфеса SendResponseInterface или false в случае ошибки.

Сервис содержит готовый объект интерфейса SmsInterface - Sms.

Пример:

$sms = new \SmsclubApi\Classes\Sms();
$sms
    // Устанавливаем отправителя
    ->setOriginator(new \SmsclubApi\Classes\Originator('InetShop'))
    // Устанавливаем номера получателей
    // Если получатель один, следует указывать один елемент массива
    ->setPhones(['380123456789', '380123456780'])
     // Устанавливаем текст сообщения
    ->setMessage('Message text')

$result = $api->sendSms($sms);

if ($result) {
    foreach($result as $item) {
        // Получить ID сообщения от SMS Club
        var_dump($item->getId());
        
        // Получить номер на которой отправлено СМС
        var_dump($item->getNumber());
    }
}

Отправка Viber сообщений

Для отправки Viber сообщения необходимо создать объект реализующий ViberMessageInterface и передать его в метод sendViber($viberMessage) API сервиса. Вызов метода sendViber($viberMessage) вернет массив объектов интерфеса SendResponseInterface или false в случае ошибки.

Сервис содержит готовый объект интерфейса ViberMessageInterface - Sms.

Пример:

$viberMessage = new \SmsclubApi\Classes\ViberMessage();
$viberMessage
    // Устанавливаем отправителя
    ->setOriginator(new \SmsclubApi\Classes\Originator('InetShop'))
    // Устанавливаем номера получателей
    // Если получатель один, следует указывать один елемент массива
    ->setPhones(['380123456789', '380123456780'])
     // Устанавливаем текст сообщения
    ->setMessage('Message text');

$result = $api->sendViber($viberMessage);

if ($result) {
    foreach($result as $item) {
        // Получить ID сообщения от SMS Club
        var_dump($item->getId());
        
        // Получить номер на которой отправлено СМС
        var_dump($item->getNumber());
    }
}

Получение списака Альфа-имен для отправки Viber сообщений

Для получения спсиска Альфа-имен необходимо вызвать метод $api->getViberOriginators();. В ответ вернется массив объектов интерфейса OriginatorInterface или false в случае ошибки.

Пример:

$originators = $api->getViberOriginators();

if ($originators) {
    foreach($originators as $originator) {
        // Получить ID отправителя
        var_dump($originator->getId());   
        
        // Получить имя отправителя
        var_dump($originator->getName());  
    }
}

Получение статусов

Константы статусов и их описание

Для сверки статусов рекомендуется использовать константы класса StatusHandler:

SMS_ENROUTE_STATUS - сообщение отправлено;
SMS_DELIVRD_STATUS - сообщение доставлено;
SMS_REJECTED_STATUS - сообщение отклонено системой (черный список или же другие фильтры);
SMS_EXPIRED_STATUS - истек срок жизни, сообщение не доставлено;
SMS_UNDELIV_STATUS - невозможно доставить сообщение.

Получение СМС стутсов

Для получения стасов СМС необходимо вызвать метод getSmsStatuses([...]) и передать в него массив с ID смс в системе SMS Club. Вызов метода вернет массив объектов интрефейса SmsStatusInterface или false в случае ошибки.

Пример:

$result = $api->getSmsStatuses(['111222333', '444555666']);

if ($result) {
    foreach($result as $item) {
        // Получить ID СМС в системе SMS Club
        var_dump($result->getId());

        // Получить статус сообщения
        var_dump($result->getStatus());
    }
}

Список возможных статусов:

StatusHandler::SMS_ENROUTE_STATUS (Message enroute.) – сообщение отправлено;
StatusHandler::SMS_DELIVRD_STATUS (Message delivered.) – сообщение доставлено;
StatusHandler::SMS_EXPIRED_STATUS (Message expired.) – истек срок жизни, сообщение не доставлено;
StatusHandler::SMS_UNDELIV_STATUS (Message undelivered.) – невозможно доставить сообщение;
StatusHandler::SMS_REJECTED_STATUS (Message rejected.) – сообщение отклонено системой (черный список или же другие фильтры).

Примечание: Для корретной проверки статусов следует использовать константы класса StatusHandler, а не текстовые значения.

Получение Viber статусов

Для получения стасов Viber сообщений необходимо вызвать метод getViberStatuses([...]) и передать в него массив с ID Viber сообщений в системе SMS Club. Вызов метода вернет массив объектов интрефейса ViberStatusInterface или false в случае ошибки.

Пример:

$result = $api->getViberStatuses(['111222333', '444555666']);

if ($result) {
    foreach($result as $item) {
        // Получить ID Viber сообщения в системе SMS Club
        var_dump($result->getId());

        // Получить статус Viber сообщения
        var_dump($result->getStatus());
        
        // Получить дополнительный статус
        var_dump($result->getAdditionalStatus());
    }
}

Список возможных статусов:

StatusHandler::SMS_ENROUTE_STATUS (Message enroute.) - сообщение отправлено;
StatusHandler::SMS_DELIVRD_STATUS (Message delivered.) – сообщение доставлено;
StatusHandler::SMS_EXPIRED_STATUS (Message expired.) – истек срок жизни, сообщение не доставлено;
StatusHandler::SMS_UNDELIV_STATUS (Message undelivered.) – невозможно доставить сообщение;
StatusHandler::SMS_REJECTED_STATUS (Message rejected.) – сообщение отклонено системой (черный список или же другие фильтры).

Список возсожных дополнительных статусов:

Прочитано – абонент прочитал сообщение;
Заблокировано получателем – абонент заблокировал сообщение от заданного альфа-имени.
Не зарегистрирован – на мобильном устройстве абонента не установлено актуальное Viber-приложение.
Не поддерживаются рассылки – для мобильного устройства абонента не предусмотрены Viber-рассылки (как правило это планшеты).
Черный список — телефон в черном списке, рассылка на него запрещена.
Спам — отправка сообщения заблокирована по подозрению на спам.
Цензура — в сообщении обнаружена нецензурная лексика или стоп-слова.
Некорректный номер получателя — указан некорректный номер абонента.
Запрещенный оператор — запрещена отправка сообщений на номера данного оператора.

Важно! Дополнительные статусы несут исключительно информативный характер и могут быть изменены на стороне сервиса SMS Club. Не стоит использовать дополнительные статусы для программной логики (например сравнений, выборок и т.д.).

Обработка ошибок

При вызове методов отвечающих за запросы к сервису SMS Club, возвращаемое значение может быть false, это указывает на наличие ошибки. Для получения списка ошибок стоит использовать метод getErrors().

Для проверки наличия ошибок следует использовать метод hasErrors().

Метод getErrors() возвращает массив объектов интерфеса ErrorInterface.

Методы интерфейса ErrorInterface:

getCode() - получить код ошибки;
getMessage() - получить сообщение ошибки;

Пример:

$balance = $api->getBalance();

if (!$balance) {
    foreach($api->getErrors() as $error) {
        // Получить код ошибки
        var_dump($error->getCode());
        
        // Получить сообщение ошибки
        var_dump($error->getMessage());
    }
}

// Или:

if ($api->hasErrors()) {
    foreach($api->getErrors() as $error) {
        // Получить сообщение ошибки
        var_dump($error->getCode());
        
        // Получить сообщение ошибки
        var_dump($error->getCode());
    }
}

Достпуные коды ошибок (описание в работе)

ErrorHandler::SMS_PHONE_EMPTY (101) - не заполнен номер получателя;
ErrorHandler::SMS_MESSAGE_EMPTY (102) - не заполнен текст сообщения;
ErrorHandler::SMS_SRC_ADDR_EMPTY (103) - не заполнен отправитель сообщения;
ErrorHandler::SMS_INVALID_PHONE (104) - некорректный номер получателя;
ErrorHandler::SMS_INVALID_ID_SMS (105) - некорректный ID сообщения;
ErrorHandler::SMS_UNAUTHORIZED (106) - некорректные данные авторизации;
ErrorHandler::SMS_VALIDATION (107) - ошибка валидации данных;
ErrorHandler::SMS_TOO_MANY_QUERIES (108) - превышен лимит запросов;
ErrorHandler::SMS_SERVICE_UNAVAILABLE (109) - сервис недоступен;
ErrorHandler::VIBER_ACCOUNT (110) - осуществление Viber рассылок с данного аккаунта недоступно;
ErrorHandler::VIBER_SYSTEM_ERROR (111) - системная ошибка;
ErrorHandler::VIBER_NO_MONEY (112) - недостаточно средств;
ErrorHandler::VIBER_ANY_CORRECT_PHONES (113) - некоррекнтые номера получателей;
ErrorHandler::VIBER_TEXT (114) - некорректный текст сообщения;
ErrorHandler::VIBER_UPLOAD_IMG (115) - ошибка при загрузке изображения;
ErrorHandler::VIBER_SENDER (116) - некорректный отправитель;
ErrorHandler::VIBER_SMS (117) - некорректное СМС сообщения (каскадная отправка);
ErrorHandler::VIBER_INCORRECT_PHONES (118) - некоррекнтые номера получателей;

smsclub / php-new

Maintainers

Details

README

Подключение сервиса

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

Акканут

Просмотр баланса

Получение списака Альфа-имен для отправки СМС

Отправка сообщений

Отправка СМС

Отправка Viber сообщений

Получение списака Альфа-имен для отправки Viber сообщений

Получение статусов

Константы статусов и их описание

Получение СМС стутсов

Получение Viber статусов

Обработка ошибок