elefymove
文档

与 ElefyMove 一起构建

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

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

API 能做什么

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

房源 API

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

空档同步

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

临时锁定

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

Webhook

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

iCal 同步

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

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

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

可以

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

不可以

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

获取访问权限

创建开发者账户并验证邮箱后，即可直接在控制台签发自己的测试 API 密钥。正式密钥由房东在 ElefyMove 后台创建。

创建您的 API 密钥

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

可用权限范围

listings:readlistings:writeavailability:readavailability:writeholds:writewebhooks:managecommunity:readcommunity:writemarketplace:readmarketplace:write

默认速率限制:每个密钥每分钟 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"
}

完整 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将你的房源下架。
POST/api/public/v1/listings/{externalId}/photoslistings:write为房源添加一张照片，无需完整更新。图片会由 ElefyMove 抓取并重新托管——你的 URL 不会被直接存储。
DELETE/api/public/v1/listings/{externalId}/photos/{photoId}listings:write从房源中移除一张照片。如果会使已发布房源的照片数低于最低要求，将返回 400 拒绝。

参考数据

方法端点权限范围用途
GET/api/public/v1/locations任意有效密钥读取省 → 区/县 → 片区的规范地理位置树。
GET/api/public/v1/locations/search任意有效密钥在规范地理位置层级中进行输入联想搜索。
GET/api/public/v1/reference/property-types任意有效密钥房源可接受的全部房产类型取值。
GET/api/public/v1/reference/amenities任意有效密钥设施字段必须遵守的长度与数量限制——设施是自由文本，并非固定目录。
GET/api/public/v1/reference/locales任意有效密钥房源翻译内容可接受的全部语言代码。
GET/api/public/v1/reference/currencies任意有效密钥房源价格使用的货币。ElefyMove 仅服务泰国，因此始终为泰铢（THB）。

可订日期与封锁

方法端点权限范围用途
GET/api/public/v1/listings/{id}/availabilityavailability:read按日期区间读取房源的统一日历——可订、占位、已订或已封锁。
GET/api/public/v1/availabilityavailability:read一次调用读取最多 50 个房源的可订情况。你不拥有或不存在的 ID 会列入 notFound，而不会使整个请求失败。
GET/api/public/v1/listings/{id}/blocksavailability:read读取你自己在某房源上仍生效的外部渠道封锁，可选按日期区间缩小范围。
POST/api/public/v1/listings/{id}/blocksavailability:write创建或更新一条外部渠道封锁，用你自己的引用编号标识。
POST/api/public/v1/listings/{id}/blocks/batchavailability:write一次调用为同一房源创建或更新最多 100 条外部渠道封锁，每条都有各自的成功/失败结果。
DELETE/api/public/v1/listings/{id}/blocks/batchavailability:write一次调用为同一房源删除最多 100 条外部渠道封锁，每条都有各自的成功/失败结果。
DELETE/api/public/v1/listings/{id}/blocks/{externalRef}availability:write删除你此前写入的外部渠道封锁。

临时占位

方法端点权限范围用途
GET/api/public/v1/holdsholds:write按最新排列列出你自己的占位。默认只显示 active 状态，可用 ?status=all 扩大范围。
GET/api/public/v1/holds/{id}holds:write按 ID 读取你的某个占位。
POST/api/public/v1/listings/{id}/holdsholds:write在客人于你这边完成结账期间占住日期区间。竞争失败的请求会收到带 SLOT_TAKEN 的 409。
POST/api/public/v1/holds/{id}/extendholds:write从当前时间起延长占位的到期时间。占位的总时长自创建起最多 30 分钟——超出该上限的延长请求会被 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

方法端点权限范围用途
PUT/api/public/v1/webhookswebhooks:manage设置你的 webhook 端点 URL，并可选择替换事件订阅列表。
GET/api/public/v1/webhookswebhooks:manage读取你当前的 webhook 配置。永远不会返回签名密钥。
DELETE/api/public/v1/webhookswebhooks:manage清除你的 webhook URL 并停止投递。
POST/api/public/v1/webhooks/testwebhooks:manage无论当前订阅了哪些事件，都向已配置的端点发送一次已签名的测试事件。
GET/api/public/v1/webhook-deliverieswebhooks:manage列出你自己的 webhook 投递尝试记录，包括状态、时间戳和重试历史。
POST/api/public/v1/webhook-deliveries/{id}/redeliverwebhooks:manage手动重试一次失败或已进入死信状态的投递。

社区帖子

方法端点权限范围用途
POST/api/public/v1/community/postscommunity:write提交一篇社区帖子。合作伙伴创建的帖子都会先进入审核，不会立即发布。
GET/api/public/v1/community/postscommunity:read列出你自己的社区帖子及其审核状态。
GET/api/public/v1/community/posts/{externalId}community:read按你指定的外部 ID 读取你的某篇社区帖子。
PATCH/api/public/v1/community/posts/{externalId}community:write更新你的社区帖子；未提交的字段保持不变。
DELETE/api/public/v1/community/posts/{externalId}community:write下架你的社区帖子。

市场预订

方法端点权限范围用途
GET/api/public/v1/marketplace/bookingsmarketplace:read分页并按条件列出你自己的市场预订。返回内容仅包含日期和引用编号。
GET/api/public/v1/marketplace/bookings/{id}marketplace:read按 ID 读取你的某个市场预订。
POST/api/public/v1/marketplace/bookings/{id}/declinemarketplace:write拒绝一个仍在等待付款的预订。没有确认接口——预订只在付款成功后才会确认，而不是经服务方批准。

通用

方法端点权限范围用途
GET/api/public/v1/ping任意有效密钥检查密钥是否可用，并读回绑定的客户端名称与权限范围。
GET/api/public/v1/me任意有效密钥读取你 API 客户端自身的身份信息——名称、环境，以及密钥绑定的权限范围。

数据与合理使用

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

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