README

使用SuperSaaS调度平台在PHP中进行在线预订/预约/日历 - https://supersaas.com

SuperSaaS API提供的服务可用于将在线预订和调度功能添加到现有网站或CRM软件。

先决条件

注册（免费）SuperSaaS账户，并且
在账户信息页面获取您的账户名称和API密钥。

依赖项

PHP 8.3或更高版本。

无外部库。仅使用标准调用json_encode/json_decode和stream_context_create。

安装

1: Composer

SuperSaaS PHP API客户端可在Packagist上获取，并且可以通过Composer将其包含到您的项目中。注意，supersaas-api-client可能会进行重大版本更新，引入破坏性更改，因此建议在表达包依赖时使用主要版本。例如：

$ composer require "supersaas/api-client:2.0.*"

在composer.json中

{
    "require": {
        "supersaas/supersaas-api-client": "^2"
    }
}

2: 手动

从github下载或检出项目，并手动包含src/SuperSaaS文件夹。

配置

可以使用Client通过以下方式之一（1）通过单例辅助方法Instance，例如：

SuperSaaS\Client::Instance(); //=> Client

并使用configure方法配置授权凭据

SuperSaaS\Client::configure('accountname', 'apikey');

或者（2）简单创建一个新的客户端实例并手动设置属性，例如：

$client = new Supersaas\Client();
$client->account_name = 'accountname';
$client->api_key = 'apikey';

注意，确保在Instance之前调用configure，否则客户端将使用默认配置初始化。

如果客户端未明确配置，它将使用默认的ENV变量（账户名称和API密钥）。

在调用客户端之前设置这些ENV变量。

putenv("SSS_API_ACCOUNT_NAME=your-env-supersaas-account-name");
putenv("SSS_API_KEY=your-env-supersaas-account-api-key"); 
SuperSaaS\Client::Instance()->account_name; //=> 'your-env-supersaas-account-name'
SuperSaaS\Client::Instance()->api_key; //=> 'your-env-supersaas-account-api-key'

所有配置选项都可以在客户端中单独设置。

SuperSaaS\Client::Instance()->api_key = 'xxxxxxxxxxxxxxxxxxxxxx'; 
SuperSaaS\Client::Instance()->verbose = TRUE;
...

API方法

数据结构、参数和值的详细信息可以在开发文档网站上找到

https://www.supersaas.com/info/dev

列出计划

获取所有账户计划

SuperSaaS\Client::Instance()->schedules->getList(); //=> array(Schedule, ...)

列出资源

通过schedule_id获取所有服务/资源

SuperSaaS\Client::Instance()->schedules->resources(12345); //=> array(Resource, ...)

注意：不适用于容量类型计划。

列出计划的字段

通过schedule_id获取所有可用的计划字段

SuperSaaS\Client::Instance()->schedules->fieldList(12345); //=> array(FieldList, ...)

创建用户

使用用户属性参数创建用户 create($attributes, $user_id = null, $webhook = null, $duplicate = null)。如果存在 webhook=true，则将触发与帐户连接的所有webhooks。为了避免将“创建”操作自动解释为“更新”，可以添加参数 duplicate=raise，然后错误 422 Unprocessable Entity 将被引发。如果您的数据库中用户的ID为 1234，则可以在 $user_id（可选）中提供格式为 1234fk 的外键，以识别用户：如果任何字段验证失败，则错误 422 Unprocessable Entity 将被引发，并将任何附加信息打印到您的日志中。您可以提供的数据字段可以在这里找到。

SuperSaaS\Client::Instance()->users->create(array('name' => 'name@name.com', 'full_name' => 'Example Name', 'email' => 'example@example.com')); //=> https://www.supersaas.com/api/users/1234.json

更新用户

使用用户属性参数 update($user_id, $attributes, $webhook=null, $notFound=null) 更新具有 $user_id 的用户。如果存在 webhook=true，则将触发与帐户连接的所有webhooks。为了避免自动创建新记录，可以添加参数 notfound=error 或 notfound=ignore 以返回404 Not Found或200 OK。如果 $user_id 不存在，将引发404错误。您只需指定要更新的属性

SuperSaaS\Client::Instance()->users->update(12345, array('full_name' => 'New Name')); //=> array()

删除用户

通过 user_id 删除单个用户

SuperSaaS\Client::Instance()->users->delete(12345); //=> array()

获取用户

通过 $user_id 获取单个用户，如果用户不存在，将引发404错误

SuperSaaS\Client::Instance()->users->get(12345); //=> User

列出用户

通过可选的 $form 和 $limit/$offset 分页参数获取所有用户，getList($form=null, $limit=null, $offset=null)。用户可以附加表单，设置 form=true 将显示数据

SuperSaaS\Client::Instance()->users->getList(true, 25, 0); //=> array(User, ...)

获取用户对象的字段列表

获取用户对象可用的所有字段

SuperSaaS\Client::Instance()->users->fieldList() //=> array(FieldList, ...)

创建预约/预订

使用 schedule_id、user_id（可选）（请参阅有关创建新的API文档）的预约/预订属性和可选的 form 和 webhook 参数创建预约，create($schedule_id, $attributes, $user_id, $form=null, $webhook=null)

SuperSaaS\Client::Instance()->appointments->create(12345, 67890, array('full_name' => 'Example Name', 'email' => 'example@example.com', 'slot_id' => 12345), TRUE, TRUE); //=> www.supersaas.com/api/bookings/34554.json

更新预约/预订

通过 schedule_id 和 appointment_id 更新预约，使用预约属性，请参阅上述链接，update($schedule_id, $appointment_id, $attributes, $form=null, $webhook=null)

SuperSaaS\Client::Instance()->appointments->update(12345, 67890, array('full_name' => 'New Name')); //=> array()

删除预约/预订

通过 schedule_id 和 appointment_id 删除单个预约

SuperSaaS\Client::Instance()->appointments->delete(12345, 67890); //=> array()

获取预约/预订

通过 schedule_id 和 appointment_id 获取单个预约

SuperSaaS\Client::Instance()->appointments->get(12345, 67890); //=> Appointment

列出预约/预订

通过 schedule_id 列出预约，带有 form 和 start_time 以及 limit 视图参数，getList($schedule_id, $form=null, $start_time=null, $limit=null)

SuperSaaS\Client::Instance()->appointments->getList(12345, 67890, TRUE, TRUE); //=> array(Appointment, ...)

获取日程表

通过 schedule_id 和 user_id 获取日程（即将到来的）预约，带有 from_time 视图参数（请参阅详情，agenda($schedule_id, $user_id, $from_time = null, $slot=false)

SuperSaaS\Client::Instance()->appointments->agenda(schedule_id=12345, user_id=67890, form=TRUE, slot=FALSE); //=> array(Appointment, ...)

SuperSaaS\Client::Instance()->appointments->agenda(schedule_id=12345, user_id=67890, form=TRUE, slot=TRUE); //=> array(Slot, ...)

获取可用的预约/预订

通过 schedule_id、from 时间和 length_minutes 以及 resource 参数获取可用的预约（请参阅详情，available($schedule_id, $from_time = null, $length_minutes = null, $resource = null, $full = null, $limit = null)

SuperSaaS\Client::Instance()->appointments->available(schedule_id=12345, from='2018-01-31 00:00:00', length_minutes=15, resource='My Class'); //=> array(Appointment, ...)

获取最近更改

通过 schedule_id 获取最近更改的预约，带有 from 时间、to 时间、user 用户、slot 视图参数（请参阅文档），changes($schedule_id, $from_time = null, $to=null, $slot=false, $user=null, $limit=null, $offset=null)

SuperSaaS\Client::Instance()->appointments->changes(schedule_id=12345, from_time='2018-01-31 00:00:00', slot=FALSE); //=> array(Appointment, ...)

SuperSaaS\Client::Instance()->appointments->changes(schedule_id=12345, from_time='2018-01-31 00:00:00', slot=TRUE); //=> array(Slot, ...)

获取最近更改的插槽

通过 schedule_id 和 from_time 时间参数获取最近更改的插槽预约（请参阅文档），changesSlots($schedule_id, $from_time = null)

SuperSaaS\Client::Instance()->appointments->changesSlots(schedule_id=12345, from_time='2018-01-31 00:00:00'); //=> array(Slot, ...)

获取日程表插槽

通过schedule_id和user_id获取（即将到来）的日程安排槽位，使用from_time视图参数，agendaSlots($schedule_id, $user_id, $from_time = null)

SuperSaaS\Client::Instance()->appointments->agendaSlots(12345, 67890, '2018-01-31 00:00:00') //=> array(Slot, ...)

注意：仅适用于容量类型日程安排。

获取预约列表

通过schedule_id获取预约列表，使用today、from time、to时间和slot视图参数（见更新后的范围函数），listAppointments($schedule_id, $today = false, $from_time = null, $to = null, $slot = false)

SuperSaaS\Client::Instance()->appointments->listAppointments(schedule_id=12345, today=TRUE, from_time='2020-01-31 00:00:00',from_time='2020-02-01 00:00:00' slot=False) //=> array(Slot, ...)

获取预约范围

这是获取预约范围（见上面列表）的更新方法。通过schedule_id获取预约范围，使用today、from时间、to时间和slot视图参数（见文档），range($scheduleId, $today = false, $fromTime = null, $to = null, $slot = false, $user = null, $resourceId = null, $serviceId = null, $limit = null, $offset = null)

SuperSaaS\Client::Instance()->appointments->range(12345, false, '2018-01-31 00:00:00', '2019-01-31 00:00:00', true) //=> array(Appointment, ...)

模板表单列表

通过模板superform_id获取所有表单，使用from_time和user参数（见见）

SuperSaaS\Client::Instance()->forms->getList(12345, '2018-01-31 00:00:00'); //=> array(Form, ...)

获取表单

通过form_id获取单个表单，如果未找到则抛出404错误

SuperSaaS\Client::Instance()->forms->get(12345); //=> Form

获取SuperForms列表

获取表单模板（SuperForms）列表

SuperSaaS\Client::Instance()->forms->forms() //=> array(SuperForm, ...)

列出账户中的组

列出账户中的组（见见）

SuperSaaS\Client::Instance()->groups->list() //=> array(Group, ...)

列出促销活动

获取带有分页参数limit和offset的促销优惠券代码列表（见文档），list($limit = null, $offset = null)

SuperSaaS\Client::Instance()->promotions->list() //=> array(Promotion, ...)

获取单个优惠券代码

使用promotion_code检索单个优惠券代码的信息

SuperSaaS\Client::Instance()->promotions->promotion((12345) //=> array(Promotion, ...)

重复促销代码

通过提供（新）promotion_code和template_code来复制模板促销，顺序如下，duplicatePromotionCode($promotionCode, $templateCode)

Supersaas::Client.instance.promotions.duplicatePromotionCode(12345, 94832838)

示例

./examples文件夹包含几个可执行的PHP脚本，展示了如何使用API客户端进行常见请求。

这些示例将需要您的账户名称、API密钥，以及一些示例需要日程ID和/或用户ID和/或表单ID。这些可以设置为环境变量。例如。

$ export SSS_API_UID=myuserid SSS_API_SCHEDULE=myscheduleid SSS_API_ACCOUNT_NAME=myaccountname  SSS_API_KEY=myapikey && php -f ./examples/appointments.php
$ export SSS_API_FORM=myuserid SSS_API_ACCOUNT_NAME=myaccountname SSS_API_KEY=myapikey && php -f ./examples/forms.php
$ export SSS_API_ACCOUNT_NAME=myaccountname && export SSS_API_KEY=myapikey && php -f ./examples/users.php

测试

可以通过配置客户端的dry_run选项来模拟HTTP请求，例如。

SuperSaaS\Client::Instance()->dry_run = TRUE;

注意，模拟请求始终返回空数组。

Client还提供了一个last_request属性，包含最后一个执行的HTTP数组对象，例如。

SuperSaaS\Client::Instance()->last_request; //=> array('method' => ..., 'header' => ..., 'content' => ...)

可以检查最后一个请求的头部、正文等，以进行测试断言或故障排除失败的API请求。

为了额外的故障排除，可以通过verbose选项配置客户端，这将puts请求和响应中的任何JSON内容，例如。

SuperSaaS\Client::Instance()->verbose = TRUE;

运行内部单元测试（phpunit）

./vendor/bin/phpunit # Runs all
./vendor/bin/phpunit --filter AppointmentsUnitTest # Run selection

其他信息

联系：support@supersaas.com

版本

该软件包遵循语义版本控制，即MAJOR.MINOR.PATCH

许可

SuperSaaS PHP API客户端可在MIT许可证下使用。有关更多信息，请参阅LICENSE文件。

supersaas / api-client

维护者

详细信息