andrey-tech/yclients-api-php

Обертка для работы с API YCLIENTS v2.0 c троттлингом запросов и логированием в файл

1.8.0 2024-05-09 05:36 UTC

This package is auto-updated.

Last update: 2024-11-09 06:41:23 UTC


README

YCLIENTS logo

Обертка на PHP7+ для работы с REST API YCLIENTS v2.0 c троттлингом запросов к API и логированием в файл.

Данная библиотека является форком Yclients API wrapper со следующими изменениями:

  • добавлен регулируемый троттлинг запросов к API;
  • добавлена отключаемая проверка SSL/TLS-сертификата сервера YCLIENTS;
  • добавлена проверка наличия сообщений об ошибках в ответе API;
  • добавлено логирование запросов и ответов сервера в файл или STDOUT;
  • изменен и дополнен тест сообщений об ошибках;
  • добавлены методы getSchedule(), getGroups();
  • изменен метод postHooks() в связи с изменениями в API;
  • добавлен метод getAll() для выгрузки всех сущностей одного типа с использованием генератора при обработке больших объемов данных.

Содержание

Требования

  • PHP >= 7.0.
  • Произвольный автозагрузчик классов, реализующий стандарт PSR-4.

Установка

Установка через composer:

$ composer require andrey-tech/yclients-api-php

или добавить

"andrey-tech/yclients-api-php": "^1.7"

в секцию require файла composer.json.

Класс YclientsApi

Для работы с REST API YCLIENTS используется методы класса \Yclients\YclientsApi.
При возникновении ошибок выбрасывается исключение с объектом класса \Yclients\YclientsException.

Список методов класса

  • __construct(string $tokenPartner = null) Конструктор класса.

Авторизация

  • setTokenPartner(string $tokenPartner) :void Устанавливает токен партнера.
  • getTokenPartner() :string Возвращает токен партнера.
  • getAuth(string $login, string $password) :array Выполняет авторизацию и возвращает токен пользователя.

Онлайн-запись

  • getBookform($id) :array Возвращает настройки формы бронирования.
  • getI18n($locale = 'ru-RU') :array Возвращает параметры интернационализации.
  • getBookServices($companyId, $staffId = null, \DateTime $datetime = null, array $serviceIds = null, array $eventIds = null) :array Возвращает список услуг, доступных для бронирования.
  • getBookStaff($companyId, $staffId = null, \DateTime $datetime = null, array $serviceIds = null, array $eventIds = null, $withoutSeances = false) :array Возвращает список сотрудников, доступных для бронирования.
  • getBookDates($companyId, $staffId = null, array $serviceIds = null, \DateTime $date = null, array $eventIds = null) :array Возвращает список дат, доступных для бронирования.
  • getBookTimes($companyId, $staffId, \DateTime $date, array $serviceIds = null, array $eventIds = null) : array Возвращает список сеансов, доступных для бронирования.
  • postBookCode($companyId, $phone, $fullname = null) :array Отправляет СМС код подтверждения номера телефона.
  • postBookCheck($companyId, array $appointments): array Проверяет параметры записи.
  • postBookRecord($companyId, array $person, array $appointments, $code = null, array $notify = null, $comment = null, $apiId = null) :array Создает запись на сеанс.

Записи пользователя

  • postUserAuth($phone, $code) :array Выполняет авторизовацию пользователя по номеру телефона и SMS-коду.
  • getUserRecords($recordId, $recordHash = null, $userToken = null): array Возвращает записи пользователя.
  • deleteUserRecords($recordId, $recordHash = null, $userToken = null): array Удаляет записи пользователя.

Сети салонов

  • getGroups($userToken): array Возвращает список доступных сетей салонов

Компании

  • getCompanies($groupId = null, $active = null, $moderated = null, $forBooking = null, $my = null, $userToken = null) :array Возвращает список компаний.
  • postCompany(array $fields, $userToken) :array Создает компанию.
  • getCompany($id) :array Возвращает компанию.
  • putCompany($id, array $fields, $userToken) :array Изменяет компанию.
  • deleteCompany($id) :array Удаляет компанию.
  • getCompanyAnalytics($companyId, $dateFrom, $dateTo, $userToken) Возвращает основные показатели компании.

Категория услуг

  • getServiceCategories($companyId, $categoryId = null, $staffId = null) :array Возвращает список категорий услуг.
  • postServiceCategories($companyId, $categoryId, $fields, $userToken) :array Создает категорию услуг.
  • getServiceCategory($companyId, $categoryId) :array Возвращает категорию услуг.
  • putServiceCategory($companyId, $categoryId, $fields, $userToken) :array Изменяет категорию услуг.
  • deleteServiceCategory($companyId, $categoryId, $userToken) :array Удаляет категорию услуг.

Услуги

  • getServices($companyId, $serviceId = null, $staffId = null, $categoryId = null) :array Возвращает список услуг или конкретную услугу.
  • postServices($companyId, $serviceId, $categoryId, $title, $userToken, array $fields = null) :array Создает новую услугу.
  • putServices($companyId, $serviceId, $categoryId, $title, $userToken, array $fields = null) :array Изменяет услугу.
  • deleteServices($companyId, $serviceId, $userToken) :array Удаляет услугу.

Сотрудники

  • getStaff($companyId, $staffId = null) :array Возвращает список сотрудников или конкретного сотрудника.
  • postStaff($companyId, $staffId, $name, $userToken, array $fields = null) :array Добавляет нового сотрудника.
  • putStaff($companyId, $staffId, array $fields, $userToken) :array Изменяет сотрудника.
  • deleteStaff($companyId, $staffId, $userToken) :array Удаляет сотрудника.

Клиенты

  • getClients($companyId, $userToken, $fullname = null, $phone = null, $email = null, $page = null, $count = null) :array Возвращает список клиентов.
  • postClients($companyId, $name, $phone, $userToken, array $fields = []) :array Добавляет клиента.
  • getClient($companyId, $id, $userToken) :array Возвращает клиента.
  • putClient($companyId, $id, $userToken, array $fields) :array Изменяет клиента.
  • deleteClient($companyId, $id, $userToken) :array Удаляет клиента.

Записи

  • getRecords($companyId, $userToken, $page = null, $count = null, $staffId = null, $clientId = null, \DateTime $startDate = null, \DateTime $endDate = null, \DateTime $cStartDate = null, \DateTime $cEndDate = null, \DateTime $changedAfter = null, \DateTime $changedBefore = null) :array Возвращает список записей.
  • postRecords($companyId, $userToken, $staffId, $services, $client, \DateTime $datetime, $seanceLength, $saveIfBusy, $sendSms, $comment = null, $smsRemainHours = null, $emailRemainHours = null, $apiId = null, $attendance = null) :array Создает новую запись.
  • getRecord($companyId, $recordId, $userToken) :array Возвращает запись.
  • putRecord($companyId, $recordId, $userToken, array $fields) :array Изменяет запись.
  • deleteRecord($companyId, $recordId, $userToken) :array Удаляет запись.

Расписание работы сотрудников

  • getSchedule($companyId, $staffId, $startDate, $endDate, $userToken) :array Возвращает расписание работы сотрудника.
  • putSchedule($companyId, $staffId, $userToken, $fields) :array Изменяет расписание работы сотрудника.

Даты для журнала

  • getTimetableDates($companyId, \DateTime $date, $staffId, $userToken) :array Возвращает список дат для журнала.
  • getTimetableSeances($companyId, \DateTime $date, $staffId, $userToken) :array Возвращает список сеансов для журнала.

Комментарии

  • getComments($companyId, $userToken, \DateTime $startDate = null, \DateTime $endDate = null, $staffId = null, $rating = null) :array Возвращает комментарии.

Пользователи компании

  • getCompanyUsers($companyId, $userToken) :array Возвращает пользователей компании.

Кассы

  • getAccounts($companyId, $userToken) :array Возвращает кассы компании.

SMS рассылка

  • sendSMS($companyId, $userToken, $clientIds, $text) :array Отправляет SMS.

Склады

  • getStorages($companyId, $userToken) :array Возвращает склады компании.

Уведомления о событиях webhooks

  • getHooks($companyId, $userToken) :array Возвращает настройки уведомлений о событиях.
  • postHooks($companyId, $fields, $userToken) :array Изменяет настройки уведомлений о событиях.

Вспомогательные методы

  • getAll($callback) :\Generator Загружает все сущности одного типа.
    • $callback - анонимная функция function(int $page, int $count) { ... }, реализующая постраничную загрузку сущностей с помощью методов getClients() или getRecords():
      • $page - номер загружаемой страницы;
      • $count - максимальное количество сущностей, загружаемых на странице.

Дополнительные параметры

Дополнительные параметры работы устанавливаются через публичные свойства объекта класса YclientsApi.

Примеры

use Yclients\YclientsApi;

try {

    $login = 'user@example.com';
    $password = '37*%4Hd.Uda)532';
    $tokenPartner = 'erd8jrpo4mk7lsk8krs';

    $yc = new YclientsApi($tokenPartner);

    // Включаем отладочный режим с логированием в файл
    $yc->debug = true;

    // Устанавливаем лог файл отладочного режима
    $ys->debugLogFile = 'logs/debug_yclients_api.log';

    // Устанавливает максимальное число запросов к API YCLIENTS в секунду (значение 0 отключает троттлинг запросов к API)
    $yc->throttle = 1;

    // Выполняем авторизацию и получаем токен пользователя
    $response = $yc->getAuth($login, $password);
    $userToken = $response['user_token'];

    /*
     * Получаем список активных, прошедших модерацию компаний YCLINETS,
     * на управление которыми пользователь имеет права
     */
    $companies = $yc->getCompanies(
        $groupId = null,
        $active = true,
        $moderated = true,
        $forBooking = null,
        $my = 1,
        $userToken
    );

    // Получаем ID первой компании
    $companyId = $companies[0]['id'];

    // Получаем всех пользователей первой компании
    $users = $yc->getCompanyUsers($companyId, $userToken);
    print_r($users);

    // Получаем всех сотрудников компании
    $staff = $yc->getStaff($companyId);
    print_r($staff);

    // Получаем ID первого сотрудника
    $workerId = $staff[0]['id'];

    // Загружаем расписание работы первого сотрудника на 1 месяц
    $schedule = $yc->getSchedule(
        $companyId,
        $workerId,
        $startDate = '2020-01-01',
        $endDate = '2020-01-31'
        $userToken
    );
    print_r($schedule);

    /**
     * Выгружаем всех клиентов заданной компании с использованием генератора 
     * при обработке больших объемов данных
     */
    $generator = $yc->getAll(
        function (int $page, int $count) use ($yc, $companyId, $userToken) {
            return $yc->getClients(
                $companyId,
                $userToken,
                $fullname = null,
                $phone = null,
                $email = null,
                $page,
                $count
            );
        }
    );
    foreach ($generator as $response) {
        $clients = $response['data'];
        foreach ($clients as $client) {
            print_r($client);
        }
    }

    /**
     * Выгружаем все записи сотрудника заданной компании с использованием генератора 
     * при обработке больших объемов данных
     */
    $generator = $yc->getAll(
        function (int $page, int $count) use ($yc, $companyId, $userToken, $workerId) {
            return $yc->getRecords(
                $companyId,
                $userToken,
                $page,
                $count,
                $workerId
            );
        }
    );
    foreach ($generator as $response) {
        $records = $response['data'];
        foreach ($records as $record) {
            print_r($record);
        }
    }

} catch (\Yclients\YclientsException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

Авторы

© 2018 slowprog
© 2019-2024 andrey-tech

Лицензия

Данная библиотека распространяется на условиях лицензии MIT.