Описание API:

https://api-online.class365.ru

Требования:

PHP 7.3 (и выше)

Установка:

В консоли с помощью Composer

1. Установите пакетный менеджер Composer в папке вашего проекта, если до этого момента он еще не был установлен.

2. В консоли выполните команду

composer require business-ru/business-online-sdk-php

Либо

2. В файле composer.json своего проекта

Добавьте строку "business-ru/business-online-sdk-php": "*" в список зависимостей вашего проекта в файле composer.json

    "require": {
        "business-ru/business-online-sdk-php": "*"
	}

3. Обновите зависимости проекта. В консоли перейдите в каталог, где лежит 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, то время ожиидания будет снижено до этого значения.