Acuity Scheduling开发人员平台：OAuth，Webhooks和报告

最新推荐文章于 2024-10-05 12:07:50 发布

cunjie3951

最新推荐文章于 2024-10-05 12:07:50 发布

阅读量293

点赞数

文章标签： java python php http 大数据

Acuity Scheduling的开发人员解决方案

欢迎来到Acuity开发人员友好的日程安排和预订平台系列的第三集。在之前的几集中，我们对日历的预定和约会服务以及Acuity的嵌入，开发人员API和集成服务进行了概述。

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

由于本教程的重点是其开发人员平台，因此我建议您在Acuity注册并自己进行更多探索。

敏锐度计划可能是对开发人员最友好的计划解决方案。但是，它还是一种非常有效的Web服务，可满足您所有的日程安排，预订和日历约会需求。

如果您想了解更多信息，请观看下面的调度视频：

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

现在，让我们跳回第三集...

视力调度OAuth2集成

如果您要扩展应用程序以使其能够与多个Acuity帐户一起使用，例如，为具有许多Acuity团队成员帐户的大型公司进行计划，则可以使用Acuity OAuth集成，以便每个用户可以快速轻松地使用和管理其日历和预订。

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

OAuth2如何运作

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

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

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

Acuity Scheduling Developer API-OAuth2帐户注册

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

这是一个示例回调URI：

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

提交表单后，Acuity会授予您一个OID调用所需的Client ID和Client Secret ：

Acuity Scheduling Developer API-OAuth2注册完成

与Acuity OAuth2集成

获得客户帐户后，就可以开始集成了。第一步是将用户重定向到我们的authorization_url 。显示“ Connect to 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 Scheduling Developer API-OAuth2身份验证屏幕

您还可以依赖Acuity的SDK库来获取PHP和JavaScript ，例如：

<?php

require_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会使用authorization_code将其发送回您的redirect_uri 。像这样，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 Scheduling Developer API-注册您的应用程序Webhooks

当安排，取消或重新安排约会时，Acuity API还提供了Webhooks来通知您的应用程序。在Acuity的Integrations菜单下，设置Webhook与URL的集成，以在约会更改时得到通知（如上所示） 。 URL必须是端口443或80。

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

操作：已 scheduled ， rescheduled ， canceled或changed ，具体取决于启动Webhook调用的操作。
id：约会的ID，通过获取约会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 Webhooks，以协助开发：

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

    &appointmentTypeID=1"

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

验证Webhook请求

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

用于创建事件和预订的动态Webhooks

如果看一下Acuity的API，您会发现您现在可以通过webhooks动态创建订阅。此功能目前正在测试中，但是您可以在此处试用该功能。

使用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 -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 orders会从在线商店中检索最新的订单列表。

这是一个curl示例：

curl -u ACUITY_USER_ID:ACUITY_API_KEY 

    "https://acuityscheduling.com/api/v1/orders"

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

这是结果的示例：

[

  {

      "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在其平台上提供的所有功能都使我深刻而深刻地印象深刻。