Описание API:
https://api-online.class365.ru
Требования:
PHP 7.3 (и выше)
Установка:
В консоли с помощью Composer
Установите пакетный менеджер Composer в папке вашего проекта, если до этого момента он еще не был установлен.
В консоли выполните команду
composer require business-ru/business-online-sdk-php
Либо
- В файле composer.json своего проекта
Добавьте строку “business-ru/business-online-sdk-php”: “*” в список зависимостей вашего проекта в файле composer.json
"require": {
"business-ru/business-online-sdk-php": "*"
}
- Обновите зависимости проекта. В консоли перейдите в каталог, где лежит composer.json, и выполните команду:
composer update
Начало работы:
Создайте объект для работы с API:
$api = new \bru\api\Client($account, $app_id, $secret, $sleep, $cache, $http);
При создании обьекта ему передаются параметры:
- $account - Имя аккаунта. Например для работы с API https://a13344.business.ru/ это a13344. Данный параметр является обязательным.
- $app_id - ID интеграции. Представляет собой набор цифр, который выдается при создании интеграции. Данный параметр является обязательным.
- $secret - Секретный ключ. Представляет собой набор символов, который выдается при создании интеграции. Длина - 32 символа. Данный параметр является обязательным.
- $sleep - При превышении количества запросов включение данной функции даст возможность ожидать сброса лимита и продолжить выполнение запросов к API. true - Включить функцию false - Отключить функцию (По умолчанию) Данный параметр не является обязательным.
- $cache - Библиотека использует кеширование для хранения токенов. Если вы хотите чтобы использовался ваш кэш, в качестве параметра нужно передать объект, реализующий интерфейс CacheInterface (PSR-16). По умолчанию библиотека использует встроенный кэш. Данный параметр не является обязательным.
- $http - Если вы хотите использовать свой HTTP - клиент для запросов к API, в качестве параметра нужно передать объект, реализующий интерфейс ClientInterface (PSR-18). По умолчанию библиотека использует встроенный HTTP - клиент. Данный параметр не является обязательным.
Запросы к API реализуются путем вызова методов у данного обьекта.
Запросы:
Запрос к API может быть выполнен двумя способами:
- с помощью метода request
- c помощью метода requestAll
Request($method, $model, $params)
$method - Метод запроса
Поддерживаются 4 метода запроса:
- get - Запрос на получение записи
- post - Запрос на создание записи
- put - Запрос на изменение записи
- delete - Запрос на удаление записи
Не все модели поддерживают все методы.
Подробнее о методах запроса можно узнать на сайте документации.
$model - Модель
Модель - требуется для указания типа данных для работы Все поддерживаемые модели можно узнать на сайте документации.
$params - Параметры запроса
Параметры запроса нужны для указания конкретного документа, сортировки, условий выборки и т.д. Возможные параметры можно узнать на сайте документации.
RequestAll($model, $params)
В отличии от предыдущего метода, данный метод выполняет только get запросы, но в ответе можно получить неограниченное количество данных (ограничение запросов в 250 записей не действует). Время выполнения данного метода может занимать длительное время. Если при создании данного объекта был передан параметр $sleepy равный true, то даже при превышении лимита запросов метод будет продолжать работу до тех пор, пока не получит все записи.
$model - Модель
Модель - требуется для указания типа данных для работы Все поддерживаемые модели можно узнать на сайте документации.
$params - Параметры запроса
Параметры запроса нужны для указания конкретного документа, сортировки, условий выборки и т.д. Возможные параметры можно узнать на сайте документации.
Работа с веб-хуками
Для работы с веб - хуками у созданного обьекта есть специальный метод - checkNotification()
При сравбатываниии веб - хука вы можете вызвать этот метод для проверки подлинности уведомления.
Метод возвращает true если событие прошло проверку, в противном случае вернет false
В случае если вам нужен функционал только проверки подлинности хуков, возможно не создавать обьект, а вызвать статичный метод Client::check($app_id, $secret)
Параметры:
- $app_id - ID интеграции. Представляет собой набор цифр, который выдается при создании интеграции. Данный параметр является обязательным.
- $secret - Секретный ключ. Представляет собой набор символов, который выдается при создании интеграции. Длина - 32 символа. Данный параметр является обязательным.
Подробнее о веб - хуках можно узнать на сайте документации.
Уведомления
Для отправки уведомления пользователям используется метод sendNotification()
Метод принимает в качестве аргумента массив с параметрами уведомления, подробнее можно узнать на сайте документации.
Логирование
Библиотека использует стандарт PSR-3 для логгирования. Для включения логирования нужно у созданного ранее класса вызвать метод setLogger() и передать в качестве аргумента обьект, реализующий интерфейс
LoggerInterface пакета Psr\Log. Подробнее о PSR-3
Подготовленные запросы
Если вы хотите самостоятельно делать запросы - библиотека предоставляет возможность получать данные для этого. Для этого есть метод getPreparedUrl($method, $model, $params), где $method - метод запроса, $model - модель, $params - параметры запроса. Результатом работы метода является массив с ключом url - URL - адрес для выполенения запроса и data - данные, которые должны быть переданы в теле запроса.
Примеры
//Создаем обьект для работы с API сайта https://a13344.business.ru
$api = new Client('a13344', 2134124, 'CWZf963mlm0srCKXu8LPepSq69uEv6Hf', true);
//Устанавливаем свой логгер
$api->setLogger($myLogger);
//Удалить задачу с ID 224
$api->request('delete', 'tasks', ['id' => 224]);
//Создать задачу c описанием 'Задача создана с помощью API'
$api->request('post', 'tasks', ['task_type_id' => 2, 'description' => 'Задача создана с помощью API', 'author_employee_id' => 44224]);
//Вернет все задачи с типом 2
$api->requestAll('tasks', ['task_type_id' => 2]);
//Вернет все товары
$api->requestAll('goods');
//Отправить пользователя 12345 уведомление
$api->sendNotification(['employee_ids' => [12345], 'header' => 'Это заголовок уведомления', 'message' => 'Это текст сообщения']);
Ответ
В массиве ответа
- ключ status - статус запроса
- ключ result - ответ на запрос
Примечания
- Для работы библиотеки требуется права на чтение и запись в директории библиотеки.
- При выполнении запроса requestAll нужно понимать, что если например запросить все товары, а товаров бывает очень много, получение ответа может занять продолжительное время.
- При включении опции sleep библиотека будет ждать до 300 секунд, пока не получит разрешения продолжить запрос. Если в конфигурации интерпретатора php.ini параметр max_execution_time указано значение меньше 300, то время ожиидания будет снижено до этого значения.