nabarabane/zadarma

Простая PHP-обертка для работы с API Zadarma

zadarma

Простая PHP-обертка для работы с API Zadarma, _(*1)

Что умеет

• Запросы к API
• Отображение текущих лимитов
• Обработка входящих уведомлений и ответ на них-

Требования

• PHP >= 5.3.0

Установка

Composer

Добавьте в блок "require" в composer.json вашего проекта:, _(*2)

"nabarabane/zadarma": "~1.0"

или:, _(*3)

composer require nabarabane/zadarma:~1.0

Или

Скачайте архив с библиотекой и распакуйте его в удобное для вас место.
Подключите нужные файлы:, _(*4)

<?php

/* Если планируете совершать запросы к API */
require('Handler.php');

/* Если планируете принимать входящие уведомления */
require('Webhook.php');

Подготовка

Создайте папку "config" в корне библиотеки, если пользуетесь composer.
Если вы подключайте фалйы без использования composer, папка config должна лежать на директорию выше подключаемых файлов.
Туда положите два файла: - key.key - secret.key, _(*5)

Файлы должны содержать API-ключи, которые вы можете получить на странице своего личного кабинета - https://ss.zadarma.com/api/, _(*6)

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

Ознакомьтесь с официальной документацией, чтобы получить подробную информацию о списке досутпных методов и параметрах, передаваемых в них., _(*7)

Запросы к API

Простой запрос без параметров, _(*8)

<?php

use \Zadarma\Handler;

/* Не забудьте заинклюдить файлы библиотеки или автолоадер композера */

/* Обрачиваем в try{} catch() {}, чтбы отлавливать исключения */

try {
    $handler = new Handler();
    /* Вызывается метод "request", который выполняет запрос к API */
    /* Первый параметр - тип запроса (GET, PUT или POST)
        GET - Handler::TYPE_GET
        PUT - Handler::TYPE_PUT
        POST - Handler::TYPE_POST
    Тип запроса конкретного метода подписан рядом с названием метода в документации
    Метод "request" возвращает объект \Zadarma\Handler() с публичным свойством "result",
    которое содержит в себе массив ответа, полученный в результате запроса */
    $result = $handler->request(Handler::TYPE_GET, '/v1/info/balance/')->result;
} catch (\Exception $e) {
    /* Любая ошибка в ответе API выбрасывает исключение */
    echo 'Error: '.$e->getMessage();
}

Пример запроса на callback, _(*9)

<?php

use \Zadarma\Handler;

/* Не забудьте заинклюдить файлы библиотеки или автолоадер композера */

try {
    $handler = new Handler();
    /* Если запрос принимает параметры, они передаются третьим параметром в виде именованного массива */
    $result = $handler->request(Handler::TYPE_GET, '/v1/request/callback/', array(
        'from' => '71111111111',
        'to' => '72222222222'
    ))->result;
} catch (\Exception $e) {
    // Любая ошибка в ответе API выбрасывает исключение
    echo 'Error: '.$e->getMessage();
}

В случае успешного запроса, возвращается именованный массив ответа, в случае ошибки всегда выбрасывается исключение.
Пример ответа на запрос о балансе, _(*10)

array(
    'status' => 'success',
    'balance' => 0.849,
    'currency' => 'USD'
);

Также есть возможность добавить к ответу информацию о ваших текущих лимитах на запросы к API.
Для этого нужно вызвать конструктор с параметром "$limits = true", _(*11)

$handler = new Handler(true);

Тогда информация о лимитах будет добавлена к общему массиву ответа:, _(*12)

array(
    'status' => 'success',
    'balance' => 0.849,
    'currency' => 'USD',
    'limits' => array(
        'RateLimit-Reset' => 1437508962,
        'RateLimit-Limit' => 100,
        'RateLimit-Remaining' => 99
    )
);

Уведомления о звонках

Zadarma может отсылать на ваш сервер информацию о каждом входящем звонке.
Используйте следующий код на странице, которая будет принимать запросы от Zadarma, и укажите ее адрес в личном кабинете.
Не нужно добавлять поверочный код, чтобы система приняла ссылку, все проверки уже включены в обработчик., _(*13)

<?php

use \Zadarma\Webhook;

/* Не забудьте заинклюдить файлы библиотеки или автолоадер композера */

$listener = new Webhook();

/* Метод принимает единственным параметром callback-функцию,
которая будет вызвана, когда к вам поступит запрос от Zadarma о входящем звонке.
В функцию передается четыре параметра:
    $phone_from - номер, с которого был совершен звонок;
    $phone_to - номер, на который поступил звонок;
    $time - время начала звонка в формате UNIX Timestamp;
    $zadarma - объект слушателя \Zadarma\Webhook(). */
$listener->onCall(function($phone_from, $phone_to, $time, $zadarma) {
    /* Тут ваш код */

    /* Если хотите отправить обратно информацию о переадресации или смене имени звонящего
    Вы можете передать как оба параметра сразу, так и только один из них */
    $zadarma->respond(array(
        'redirect' => 123, // ID сценария редиректа или внутренний номер АТС
        'caller_name' => 'CallerName' // Имя звонящего
    ));
});

/* Включаем слушателя */
$listener->listen();