andrey-tech/yclients-api-php

用于操作 YCLIENTS v2.0 API 的包装，支持请求节流和文件日志记录

维护者

详细信息

github.com/andrey-tech/yclients-api-php

主页

源代码

问题

安装量: 3,556

依赖者: 0

建议者: 0

安全性: 0

星标: 9

关注者: 2

分支: 21

开放问题: 0

1.8.0 2024-05-09 05:36 UTC

Requires

MIT bf96ae0b59f9d37576beb1aee3369f99799e2d7a

loggingapithrottlingapi-wrapperyclients

This package is auto-updated.

Last update: 2024-09-09 06:19:00 UTC

README

YCLIENTS logo

PHP7+ 的包装库，用于操作 REST API YCLIENTS v2.0，支持请求节流和文件日志记录。

该库是基于 Yclients API wrapper 的分支，以下是一些修改

  • 增加了可调节的 API 请求节流；
  • 增加了可选的 YCLIENTS 服务器 SSL/TLS 证书验证；
  • 增加了对 API 响应中错误消息的检查；
  • 增加了请求和服务器响应的日志记录，记录到文件或 STDOUT；
  • 修改并扩展了错误消息的测试；
  • 增加了 getSchedule() 和 getGroups() 方法；
  • 由于 API 的变化，修改了 postHooks() 方法；
  • 增加了 getAll() 方法，用于批量获取同一类型实体，处理大量数据时使用生成器。

内容

要求

  • PHP >= 7.0.
  • 实现 PSR-4 标准的任意自动加载类。

安装

使用 composer 安装

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

或

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

在 composer.json 文件的 require 部分添加

类 YclientsApi

使用 \Yclients\YclientsApi 类的方法来操作 YCLIENTS REST API。
在出现错误时，会抛出带有 \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 发送 SMS 验证码到手机号码。
  • 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 通过手机号和短信验证码执行用户认证。
  • 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 发送短信。

仓库

  • getStorages($companyId, $userToken) :array 返回公司仓库。

事件 webhook 通知

  • 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 许可证分发。