开发者

面向俱乐部和认证合作伙伴的公开 REST API：范围明确的读取、通过 API 预订，以及 HMAC 签名的 Webhook。

身份验证

每个密钥都在俱乐部管理面板的“设置 → 开发者”中生成，以 Bearer 请求头的形式传递。

curl -H "Authorization: Bearer mp_…" \
  https://api.meetandplay.mx/api/v1/clubs/{clubId}/bookings

完整密钥只会显示一次，请妥善保存。

接口

每个密钥都声明了创建时被授予的权限；缺少所需权限的请求会被拒绝。

GET/clubs/{clubId}/courts
俱乐部的球场目录。
GET/clubs/{clubId}/availability
每个场地的占用时段，最多 14 天。
GET/clubs/{clubId}/bookings
俱乐部的预订，最新的排在前面。
GET/clubs/{clubId}/customers
俱乐部的客户名录 — 个人数据，需要单独的权限。
POST/clubs/{clubId}/bookings
创建预订，与俱乐部前台操作相同。
POST/clubs/{clubId}/bookings/{bookingId}/cancel
取消预订；按俱乐部政策退款或作废该笔支付。

Webhook 事件

在你自己的地址上接收 HMAC-SHA256 签名的事件：预订创建、确认或取消，支付成功，比赛满员。每次投递失败后都会按退避策略重试；多次失败后进入失效队列，可在俱乐部管理面板中重新投递。

Webhook 认证

除 HMAC 签名（x-map-signature）外，每个 webhook 还可以发送 Authorization 请求头，Basic（用户名和密码）或 Bearer（令牌）均可。在俱乐部管理面板的管理 → API 和 Webhook 中，为每个 webhook 的认证进行配置。凭据加密存储，之后不再显示。

POST https://…/webhooks
x-map-signature: t=1767225600,v1=…
x-map-delivery: 0199…
Authorization: Bearer …

每次投递都会发送该请求头，包括重试以及从失效队列重新投递，使用的是发送时有效的凭据：如果你更改或删除凭据，已在队列中的投递也会随之生效。如果服务器无法解密凭据，投递绝不会在缺少它的情况下发出，而是进入失效队列。如果你更改 URL 或删除该 Webhook，排队发往旧 URL 的投递会被取消或移入失效队列：凭据绝不会发送到你已不再登记的 URL。
我们仍建议你验证 HMAC 签名：Authorization 请求头说明调用方是谁，但只有签名能证明请求体未被篡改，其时间戳（t=）还能让你拒绝重放的投递。
我们不跟随重定向：3xx 响应视为投递失败并会重试，因此凭据绝不会被发送到其他 URL。请登记接收端的最终 URL。

速率限制

每个密钥每分钟的请求次数都有上限。收到 429 响应表示已达到上限，请放慢速度后重试。

认证合作伙伴

认证合作伙伴可在俱乐部管理面板中一键连接 — 无需手动复制粘贴密钥。

准备好接入你的俱乐部了吗？

登录俱乐部管理面板，在“设置 → 开发者”中生成你的第一个密钥。

前往俱乐部管理面板 OpenAPI 规范