Acuity调度开发平台：OAuth、Webhook 和报告

Acuity Scheduling 的开发人员解决方案

欢迎收看 Acuity 开发人员友好型日程安排和预订平台系列的第三集。在之前的剧集中，我们对其日历预约和预约服务 以及Acuity 的嵌入、开发者 api 和集成服务进行了一般性介绍 。

今天，我们将继续介绍 Acuity 的开发人员平台，继续介绍其独特的 oauth 支持、通知 webhook 和基于 API 的报告功能。

由于本教程专注于其开发人员平台，因此我鼓励您 在 Acuity 注册 并自行探索更多内容。

Acuity Scheduling 可能是对开发人员最友好的调度解决方案。但它也是一个非常有效的 Web 服务，可以满足您的所有日程安排、预订和日历约会的需求。 

如果您想了解更多信息，请观看 下面的日程安排视频 ：

在我开始之前，我想鼓励您提出有关 Acuity Scheduling 和我们的教程系列的任何问题。请在下面的评论中发布它们，或者随时在 Twitter 上与我联系@lookahead_io 。

现在，让我们回到第三集……

Acuity 调度oauth2集成

如果您正在扩展您的应用程序以使用多个 Acuity 帐户，例如为一家拥有许多 Acuity 团队成员帐户的大公司安排日程，您可以使用Acuity OAuth 集成，以便每个用户都可以快速轻松地使用和管理他们的日历和预订。

您可能通过使用 Facebook 或 Google 帐户登录应用程序来熟悉 OAuth。Acuity 为其帐户提供了相同的功能（请参见上面的特色图片）。

OAuth2 的工作原理

OAuth2是应用程序安全地授予 API 授权和交换凭据的标准。这是允许您的应用程序用户连接到 Acuity 的最佳选择。

用户单击客户端（您的应用程序）中的连接按钮并被重定向到 Acuity 以输入其凭据。授权您的应用程序后，用户将使用授权代码重定向回您的应用程序，您将使用该授权代码交换 API 访问令牌。

您需要 注册 Acuity OAuth2 客户帐户 才能开始：

回调URI 是 Acuity 将为请求用户提供 OAuth 授权代码的 URL 。然后，您需要使用该代码和您的 API 密钥来请求将永久令牌存储在您的数据库中。该令牌将允许您代表该用户进行调度和日历 API 调用。

这是一个示例回调 URI：

https://your-app.example.com/oauth2-callback.php

提交表单后，Acuity 将授予您一个Client IDOAuthClient Secret调用所需的权限：

与 Acuity OAuth2 集成

获得 客户帐户后，您就可以开始集成了。第一步是将用户重定向到我们的 authorization_url. 显示“连接到 Acuity”之类的按钮通常是个好主意。

例如，您可以使用您的客户端 ID 和重定向 URI 将用户从连接按钮链接到 URL，如下所示：

https://acuityscheduling.com/oauth2/authorize?    response_type=code&scope=api-v1&client_id=YOUR_CLIENT_ID

    &redirect_uri=YOUR_REDIRECT_URI

人们将被带到他们帐户的客户授权请求中：

您还可以依赖Acuity 的 PHP 和 javascript SDK 库，例如：

<?phprequire_once('vendor/autoload.php');
$acuity = new AcuitySchedulingOAuth(array(
  'clientId' => 'YOUR_CLIENT_ID',
  'clientSecret' => 'YOUR_CLIENT_SECRET',
  'redirectUri' => 'YOUR_REDIRECT_URI'
));
$acuity->authorizeRedirect(array('scope' => 'api-v1'));

Acuity 将验证您的 client_id、 redirect_uri 和 scope，然后向用户显示一个登录屏幕，允许他们授予您的应用程序访问其 Acuity 帐户的权限。连接用户后，Acuity 将 redirect_uri 使用 authorization_code. 像这样，example.org 是您的应用程序的 URL：

https://example.org/oauth2?code=AN_AUTHORIZATION_CODE

作为对 的响应AUTHORIZATION_CODE，您将执行类似这样的操作来请求access_token：

curl https://acuityscheduling.com/oauth2/token \

 -d grant_type=authorization_code \

 -d code=AN_AUTHORIZATION_CODE \

 -d redirect_uri= YOUR_REDIRECT_URI \

 -d client_id=YOUR_CLIENT_ID \

 -d client_secret=YOUR_CLIENT_SECRET

或者，在JavaScript中：

var Acuity = require('acuityscheduling');

var express = require('express');

var url = require('url');

var port = process.env.PORT || 8000;



var app = express();



app.get(url.parse('YOUR_REDIRECT_URI').path, function (req, res) {

  var acuity = Acuity.oauth({

    clientId: 'YOUR_CLIENT_ID',

    clientSecret: 'YOUR_CLIENT_SECRET',

    redirectUri: 'YOUR_REDIRECT_URI'

  });

  acuity.requestAccessToken(req.query.code, function (err, tokenResponse) {

    if (err) return res.send(err);

    res.send(tokenResponse);

  });

});



app.listen(port, function () {

  console.log('Listening on %s', port);

}).on('error', function () {

  if (e) return console.error(e);

});

如果一切顺利，您将通过 JSON 收到响应，其中包括 access_token：

{

  "access_token": "AN_ACCESS_TOKEN",

  "token_type": "Bearer"

}

然后，ACCESS_TOKEN为您的用户存储用于正在进行的 API 请求。

ACCESS_TOKEN以下是使用您获得的信息代表 Acuity 团队成员或帐户提出请求的示例：

<?php

require_once('vendor/autoload.php');



$acuity = new AcuitySchedulingOAuth(array(

  'accessToken' => 'AN_ACCESS_TOKEN'

));



$me = $acuity->request('me');

print_r($me);

对于深度集成的服务，Acuity 提供了对您的平台及其功能的近乎即时的扩展，以及一种将您的团队对 Acuity 的使用扩展到其他服务的简单方法。

正如我之前写的，如果你能想象到，Acuity 的开发者平台几乎已经提供了它。

敏锐度网络挂钩

Acuity API 还提供 webhook 以在安排、取消或重新安排约会时通知您的应用程序。在 Acuity 的 集成 菜单下，将 Webhook 与 URL 的集成设置为在约会更改时收到通知（如上所示）。URL 必须指向端口 443 或 80。

Webhook 请求是 application/x-www-form-urlencoded 具有以下变量的 post 请求：

• action：scheduled、  rescheduled、  或 canceled， changed取决于发起 webhook 调用的操作。

• id： 约会的ID，通过get约会API调用获取约会详情。

• calendarID： 约会的日历 ID。

• 约会类型ID： 约会类型的ID。

不同的动作：

• scheduled 在初次预约时调用一次。

• rescheduled 当约会被重新安排到一个新的时间时被调用。

• canceled 每当取消约会时都会调用。

• changed 当约会以任何方式改变时被调用。这包括最初安排、重新安排或取消的时间，以及电子邮件地址或入学表格等预约详细信息的更新时间。

Acuity 会像这样发布到您的 API，您可以翻译收到的数据以记录新约会和现有约会的更新：

POST https://example.com/webhook-callback action=changed&id=13

    &calendarID=1&appointmentTypeID=13

您还可以使用 curl 模拟 Acuity webhook 来协助开发：

curl -d "action=changed&id=1&calendarID=1

    &appointmentTypeID=1"

     "https://example.com/webhook-callback"

验证 Webhook 请求

Webhook 通知由 Acuity 使用您的 API 密钥签名，因此您可以验证通知是否来自 Acuity。API 文档中有专门针对此的丰富信息和示例。 

Created event和 Bookings 的动态 Webhook

如果您查看 Acuity 的 API，您会注意到您现在可以通过 webhook 动态创建订阅。此功能目前正在测试中，但您可以 在此处试用该功能。

使用 Acuity Developer API 进行报告

您将应用程序和服务与 Acuity 的日历和预订 API 集成得越多，跟踪正在发生的事情就越重要。这就是使用 API 进行报告非常有用的地方。

如何报告约会

一项明显的报告要求是显示来自客户和客户的各种团队成员进入系统的约会。API 使这变得简单。

这是一个从系统请求约会的 PHP SDK 示例：

<?php

require_once('vendor/autoload.php');



$acuity = new AcuityScheduling(array(

  'userId' => ACUITY_USER_ID,

  'apiKey' => 'ACUITY_API_KEY'

));



$appointments = $acuity->request('appointments');

print_r($appointments);

这是针对特定用户日历的类似 curl 请求：

curl -u ACUITY_USER_ID:ACUITY_API_KEY "https://acuityscheduling.com/api/v1/appointments?max=25

    &calendarID=27238"

这是一个示例响应：

[{

    "id": 54321,

	"firstName": "Bob",

	"lastName": "McTest",

	"phone": "",

	"email": "bob.mctest@example.com",

	"date": "June 17, 2013",

	"time": "10:15am",

	"endTime": "11:15am",

  "dateCreated": "July 2, 2013",

  "datetime": "2013-07-02T10:15:00-0700",

	"price": "10.00",

	"paid": "no",

  "amountPaid": "0.00",

	"type": "Regular Visit",

  "appointmentTypeID": 1,

  "classID": null,

	"duration": "60",

	"calendar": "My Calendar",

	"calendarID": 27238,

  "certificate": null,

	"confirmationPage": "https://acuityscheduling.com/schedule.php?owner=11145481&id[]=1220aa9f41091c50c0cc659385cfa1d0&action=appt",

	"formsText": "...",

	"notes": "Notes",

	"timezone": "America/New_York",

	"forms": [

		{

			"id": 1,

			"name": "Example Intake Form",

			"values": [

				{

					"value": "yes",

					"name": "Is this your first visit?",

					"fieldID": 1,

					"id": 21502993

				},

				{

					"value": "Ninja",

					"name": "What is your goal for this appointment?",

					"fieldID": 2,

					"id": 21502994

				}

			]

		}

	]

},

{

	"id": 2051308,

	"firstName": "Eve",

	"lastName": "Cooper",

	"phone": "1231231234",

	"email": "eve@example.com",

	"date": "June 24, 2013",

  "datetime": "2013-06-24T09:00:00-0700",

	"time": " 9:00am",

	"endTime": "10:00am",

	"price": "0.00",

	"paid": "no",

	"type": "Another Type",

  "appointmentTypeID": 2,

  "classID": 1,

	"duration": "60",

	"calendar": "My Calendar",

	"calendarID": 27238,

	"confirmationPage": "https://acuityscheduling.com/schedule.php?owner=11145481&id[]=3320aa9f41091c50c0cc659385cfa1d0&action=appt",

	"formsText": "...",

	"notes": "Notes",

	"timezone": "America/New_York",

	"forms": []

}]

这些是支持的参数appointments：

默认情况下，取消的约会不会被退回。要检索取消的约会，请使用查询 ?canceled=true。取消的约会响应包括一个 noShow 字段，如果管理员已将约会标记为未出现，则该字段为 true，如果该约会被简单地取消，则该字段为 false。

报告令

由于 Acuity 还允许您通过其预约服务列出和销售产品，因此 /orders 从在线商店中检索最新的订单列表。 

这是一个卷曲示例：

curl -u ACUITY_USER_ID:ACUITY_API_KEY
    “https://acuityscheduling.com/api/v1/orders”

虽然上面没有显示，但您可以请求状态为已交付、已付款或未付款，并使用标题变量请求产品名称，作为订购产品名称的分号分隔列表。

以下是结果示例：

[

  {

      "id":1234,

  	"total":"55",

  	"status": "paid",

  	"time": "2014-09-23 14:22",

  	"firstName": "Testy",

  	"lastName": "McTest",

  	"phone": "1234567890",

  	"email": "test@example.com",

  	"title": "Massage Gift Certificate, Relaxing Candle",

  	"notes": "Some notes from the client"

  }

]

非常简单……但 Acuity 在其平台上提供的所有内容都让我印象深刻，而且非常先进。

结束时

迄今为止，我们在本系列中了解了很多关于 Acuity Scheduling 的功能。回顾一下，今天我们了解到：

• OAuth2：允许 Acuity 用户通过 OAuth 使用您的应用程序或服务来管理他们的日历和约会。

• Webhook：在安排或更改约会时，使用 Webhook 将通知引导到您的服务或应用程序中。

• 报告： 枚举您的 Acuity 帐户网络中的约会和订单。

•