开放 API v1

与 ElefyMove 一起构建

将你的平台接入 ElefyMove:发布房源、实时同步空档,从此不再出现同一日期被重复预订。

登录 / 获取 API 密钥查看 API 参考文档

API 能做什么

一个统一的接入层,覆盖房源发布、空档同步与实时联动。

房源 API

将多语言房源信息推送到 ElefyMove。你可以提交我们支持的 9 种语言中的任意一种或多种内容,每条房源在正式发布前都会经过审核。

空档同步

ElefyMove 的主日历是平台上所有可预订资源的唯一真实数据源。每个日期区间都带有状态标记——空闲、临时锁定、已预订或已封锁——清洁/交接缓冲时间由系统统一执行,确保任何渠道都不会造成重复预订。

临时锁定

在客人于你的平台完成结账期间,可设置最长 10 分钟的临时锁定。冲突按服务器接收顺序先到先得处理,落败的请求会返回可供程序解析的 409 响应。

Webhook

订阅经 HMAC-SHA256 签名的事件——房源审核结果、空档变化、锁定生命周期以及订单状态——近乎实时送达。负载内容仅包含日期与引用编号,绝不包含客人的个人信息。

iCal 同步

每个房源都可导出经签名的 iCal 订阅链接,ElefyMove 也可以反向轮询你的订阅链接,让外部封锁在双方系统中保持一致,无需额外编写对接代码。

合作伙伴可以做什么——不可以做什么

第一原则:每一项操作都仅限于你自己的数据。任何方向上都不存在跨合作伙伴的访问。

可以

  • 创建、更新和下架你自己的房源,可使用我们支持的 9 种语言中的任意一种
  • 查看你自己的房源及其审核状态
  • 查看你自己房源的空档情况,并写入带引用编号的外部渠道封锁
  • 在结算期间创建并释放临时锁定,最长 10 分钟
  • 注册 webhook 并接收已签名的事件——仅包含日期和引用编号
  • 导出房源日历(iCal),并注册你自己的 iCal 订阅源
  • 查询公开的地理位置层级信息

不可以

  • 通过本 API 转移任何款项、退款或押金
  • 创建 ElefyMove 的预订或合同——外部预订只会以日历封锁的形式录入
  • 发送或接收房客的个人信息
  • 访问或修改其他合作伙伴的房源、锁定、封锁或配置
  • 向 ElefyMove 用户发送消息、联系或招揽
  • 读取或转载你不拥有的房源
  • 超出速率限制、共享密钥,或自动化创建账号
阅读完整的 API 使用条款

获取访问权限

创建开发者账户并验证邮箱后，即可直接在控制台签发自己的 API 密钥。要发布正式房源，还需由 ElefyMove 团队将您的密钥关联到已认证的房东账户。

创建您的 API 密钥

创建账户即表示您同意API 使用条款。

可用权限范围

listings:readlistings:writeavailability:readavailability:writeholds:writewebhooks:manage

默认速率限制:每个密钥每分钟 120 次请求。

快速上手

每个请求都需要通过 X-Api-Key 请求头携带你获得的密钥进行身份验证。

查询房源空档

curl "https://elefymove.com/api/public/v1/listings/{listingId}/availability?from=2026-09-01&to=2026-09-30" \
  -H "X-Api-Key: efy_live_xxxxxxxxxxxxxxxxxxxxxxxx"

# Response — 200 OK
[
  { "from": "2026-09-01", "to": "2026-09-14", "state": "AVAILABLE" },
  { "from": "2026-09-15", "to": "2026-09-20", "state": "BLOCKED", "source": "partner-site", "externalRef": "HMXYZ123" },
  { "from": "2026-09-21", "to": "2026-09-30", "state": "AVAILABLE" }
]

创建临时锁定

curl -X POST "https://elefymove.com/api/public/v1/listings/{listingId}/holds" \
  -H "X-Api-Key: efy_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"from": "2026-09-15", "to": "2026-09-20", "ttlSeconds": 300}'

# Response — 201 Created
{ "holdId": "hld_9f3a2c1b", "expiresAt": "2026-08-13T10:15:00Z" }

落败的请求会收到可供程序解析的 409 响应

# Same request, the dates were just taken by another channel
# Response — 409 Conflict
{
  "code": "SLOT_TAKEN",
  "conflictingState": "HELD",
  "wonBy": "external"
}
OpenAPI / Swagger

完整 API 参考文档

每个请求与响应的结构、错误格式和示例，都记录在交互式 OpenAPI 文档中——可以用你自己的密钥实时调用任意端点。

打开 API 文档浏览完整文档

全部端点一览

Open API v1 的完整接口。每个请求都需在 X-Api-Key 请求头中携带你的密钥，且所有路由只能访问你自己的数据。

基础 URL https://elefymove.com

房源

方法端点权限范围用途
POST/api/public/v1/listingslistings:write提交新房源进入审核，内容可使用我们支持的 9 种语言中的任意几种。
GET/api/public/v1/listingslistings:read列出该密钥拥有的全部房源及其当前审核状态。
GET/api/public/v1/listings/{externalId}listings:read按你指定的外部 ID 读取你的某个房源。
PATCH/api/public/v1/listings/{externalId}listings:write更新你的房源，未提交的字段保持不变。
DELETE/api/public/v1/listings/{externalId}listings:write将你的房源下架。

可订日期与封锁

方法端点权限范围用途
GET/api/public/v1/listings/{id}/availabilityavailability:read按日期区间读取房源的统一日历——可订、占位、已订或已封锁。
POST/api/public/v1/listings/{id}/blocksavailability:write创建或更新一条外部渠道封锁，用你自己的引用编号标识。
DELETE/api/public/v1/listings/{id}/blocks/{externalRef}availability:write删除你此前写入的外部渠道封锁。

临时占位

方法端点权限范围用途
POST/api/public/v1/listings/{id}/holdsholds:write在客人于你这边完成结账期间占住日期区间。竞争失败的请求会收到带 SLOT_TAKEN 的 409。
DELETE/api/public/v1/holds/{id}holds:write在到期前释放你的某个占位。

日历同步（iCal）

方法端点权限范围用途
GET/api/public/v1/listings/{id}/calendar.ics签名 URL，无需密钥以 iCal 订阅源下载房源日历。URL 中的签名令牌即为身份凭证，日历应用可直接订阅。
PUT/api/public/v1/listings/{id}/ical-sourcesavailability:write注册或替换 ElefyMove 为你的房源轮询的入站 iCal 源。
GET/api/public/v1/listings/{id}/ical-sourcesavailability:read读取房源已注册的源，及其轮询状态和最近一次错误。
DELETE/api/public/v1/listings/{id}/ical-sourcesavailability:write停止轮询并删除房源已注册的源。

Webhook

v1 中的 Webhook 没有供合作伙伴调用的端点。申请密钥时把你的接收地址发给我们，ElefyMove 团队会为你注册，并配置用于签名每次推送的 HMAC-SHA256 密钥。推送失败会按退避策略重试，负载中只包含日期和引用编号。

可接收的事件
listing.approvedlisting.rejectedavailability.changedhold.createdhold.releasedhold.expiredbooking.createdbooking.cancelledping

通用

方法端点权限范围用途
GET/api/public/v1/ping任意有效密钥检查密钥是否可用，并读回绑定的客户端名称与权限范围。

数据与合理使用

  • 客人的个人信息绝不会经由 API 传输——外部封锁仅包含日期和引用编号,符合泰国《个人数据保护法》(PDPA)的要求。
  • 通过 API 录入的房源都会链接回 elefymove.com 上的原始页面。
  • 所有密钥都有明确的权限范围,ElefyMove 团队可随时予以吊销。

Open API v1 —— 目前正在陆续接入合作伙伴。