度假物业管理系统 — TIDY

通过TIDY API管理度假租赁物业、客人预订和清洁清单。专为短租房东、度假物业经理以及Airbnb/VRBO运营商打造。

身份验证

所有请求都需要Bearer令牌。通过登录或注册获取。

bash

注册

curl -X POST https://public-api.tidy.com/api/v2/auth/signup \
-H Content-Type: application/json \
-d {firstname:Jane,lastname:Doe,email:jane@example.com,password:secret123}

登录

curl -X POST https://public-api.tidy.com/api/v2/auth/login \ -H Content-Type: application/json \ -d {email:jane@example.com,password:secret123}

两者均返回 { token: abc123... }。令牌永不过期。

bash
export TIDYAPITOKEN=abc123...

在所有后续请求中包含 Authorization: Bearer $TIDYAPITOKEN。

---

地址（物业）

API中将物业称为地址。每个地址代表您管理的一个实体物业。

列出所有地址

bash
curl -s https://public-api.tidy.com/api/v2/addresses \
-H Authorization: Bearer $TIDYAPITOKEN

获取单个地址

bash
curl -s https://public-api.tidy.com/api/v2/addresses/123 \
-H Authorization: Bearer $TIDYAPITOKEN

响应字段：id、address、unit、city、postalcode、countrycode、addressname、notes（access、closing）、parking（paidparking、parkingspot、parkingpaywith、maxparkingcost、parkingnotes）、created_at。

创建地址

bash
curl -X POST https://public-api.tidy.com/api/v2/addresses \
-H Authorization: Bearer $TIDYAPITOKEN \
-H Content-Type: application/json \
-d {
address: 123 Beach Rd,
city: Miami,
postal_code: 33139,
country_code: US,
address_name: Beach House,
notes: {
access: 侧门密码锁盒代码4521,
closing: 将钥匙留在厨房台面上
},
parking: {
paid_parking: false,
parking_spot: myspot,
parkingpaywith: card,
maxparkingcost: 0,
parking_notes: 停在车道2号车位
}
}

必填项： address、city、postalcode、parking（包含paidparking、parkingspot、parkingnotes）。

可选项： unit、countrycode（默认US）、addressname、notes（包含access、closing）。

parking_spot取值： myspot、meter、street、guest、paidlot。

parkingpaywith取值： card、cash（默认card）。

更新地址

bash
curl -X PUT https://public-api.tidy.com/api/v2/addresses/123 \
-H Authorization: Bearer $TIDYAPITOKEN \
-H Content-Type: application/json \
-d {
address_name: Oceanfront Beach House,
notes: { access: 已更新：使用智能锁代码9876 }
}

仅更改提供的字段。

删除地址

bash
curl -X DELETE https://public-api.tidy.com/api/v2/addresses/123 \
-H Authorization: Bearer $TIDYAPITOKEN

---

客人预订

跟踪每个物业的客人入住和退房日期。预订可自动触发换房清洁。

列出所有预订

bash
curl -s https://public-api.tidy.com/api/v2/guest-reservations \
-H Authorization: Bearer $TIDYAPITOKEN

按地址筛选

curl -s https://public-api.tidy.com/api/v2/guest-reservations?address_id=123 \ -H Authorization: Bearer $TIDYAPITOKEN

获取单个预订

bash
curl -s https://public-api.tidy.com/api/v2/guest-reservations/456 \
-H Authorization: Bearer $TIDYAPITOKEN

响应字段：id、addressid、jobid、checkin（date、time）、checkout（date、time）、created_at。

创建预订

bash
curl -X POST https://public-api.tidy.com/api/v2/guest-reservations \
-H Authorization: Bearer $TIDYAPITOKEN \
-H Content-Type: application/json \
-d {
address_id: 123,
check_in: { date: 2026-04-10, time: 15:00 },
check_out: { date: 2026-04-14, time: 11:00 }
}

必填项： addressid、checkin.date、check_out.date。

可选项： checkin.time、checkout.time。

日期格式：YYYY-MM-DD。时间格式：HH:MM（24小时制）。

删除预订

bash
curl -X DELETE https://public-api.tidy.com/api/v2/guest-reservations/456 \
-H Authorization: Bearer $TIDYAPITOKEN

---

待办清单（清洁清单）

待办清单是可以附加到工单上的清洁清单。它们告知服务提供商在物业中需要执行哪些具体任务。

bash
curl -s https://public-api.tidy.com/api/v2/to-do-lists \
-H Authorization: Bearer $TIDYAPITOKEN

按地址筛选

curl -s https://public-api.tidy.com/api/v2/to-do-lists?address_id=123 \ -H Authorization: Bearer $TIDYAPITOKEN

---

自然语言（message-tidy）

对于复杂的多步骤操作，可以发送自然语言请求，而无需调用单个端点。

bash
curl -X POST https://public-api.tidy.com/api/v2/message-tidy \
-H Authorization: Bearer $TIDYAPITOKEN \
-H Content-Type: application/json \
-d {
message: 在德克萨斯州奥斯汀市橡树巷456号添加一处新物业，大门密码1234,
context: { address_id: 123 }
}

此为异步操作。每3-5秒轮询 GET /api/v2/message-tidy/{id}，直到status变为completed或failed。

示例请求

• - 在亚利桑那州斯科茨代尔市棕榈大道789号添加一处新的度假租赁物业
• 在我的海滨别墅创建一个4月10日至14日的客人预订
• 显示地址123的所有即将到来的预订
• 更新我市中心公寓的访问备注，改为使用智能锁代码5678

---

CLI替代方案

安装：brew install tidyapp/tap/tidy-request 或 npm i -g @tidydotcom/cli。

bash
tidy-request login
tidy-request 在海滨别墅创建一个4月10日至14日的客人预订
tidy-request 列出我所有的物业
tidy-request 更新地址123的访问备注 --address-id 123
tidy-request 将预订延长2天 --reservation-id 456

---

错误处理

HTTP状态码	错误类型	发生情况
400	invalidrequesterror	缺少或无效参数
401

authentication_error | 凭据错误或缺少令牌 |
| 404 | notfounderror | 资源不存在 |
| 500 | internal_error | 服务器错误 |