身份验证

访问权限通过 HMS 设立的合作伙伴账户授予。合作伙伴账户会获得一对 apiKey 和 apiSecret，并由 HMS 授权其可访问哪些酒店。登录端点用这对凭据换取绑定酒店的 token。

请求

POST /external/public/login HTTP/1.1
Host: test.hms.gen.tr
Content-Type: application/x-www-form-urlencoded

apiKey=5y94tLmALIKDyUVdEPlAAjg5xWGQNgQtnALlV4%2BAm7Q%3D&apiSecret=a143d640…&hotelCode=1000

响应 · 200

{
    "success": true,
    "hotelCode": "1000",
    "token": "eyJlbmREYXRlIjp7ImRhdGUiOiIyMDI2LTA5LTE1IDEwOjI0OjMxLjAwMDAwMCIs…",
    "hotelSeoUrl": "demo-otel"
}

字段	说明
`apiKey`	合作伙伴密钥。其中包含 base64 字符，因此在表单请求体中必须进行 URL 编码（`+` → `%2B`，`=` → `%3D`）。HTTP 库会自动处理。
`apiSecret`	机密密钥。只能保存在服务端，切勿放入浏览器或移动应用中。
`hotelCode`	酒店在 HMS 中的 ID。如果合作伙伴未获得该酒店的授权，将返回 `hotel_permission_is_not_found`。
`hotelSeoUrl`	酒店的 SEO 别名。仅 HMS 自有的预订引擎用它代替 `hotelCode`；第三方集成请发送 `hotelCode`。

Bearer 请求头#

除登录外，所有端点都要求在 Authorization 请求头中携带 token：

请求

GET /external/currencies HTTP/1.1
Host: test.hms.gen.tr
Authorization: Bearer eyJlbmREYXRlIjp7ImRhdGUiOiIyMDI2LTA5LTE1IDEwOjI0OjMxLjAwMDAwMCIs…

如果缺少该请求头、格式错误（没有 Bearer 前缀）或 token 无法识别，API 将返回 401：

401 Unauthorized

{
    "success": false,
    "error": "Authentication required"
}

token 有效期与续期#

token 有效期为 7 天。请在过期前重新登录以续期；登录开销很小，可以对同一酒店重复执行。
不要解析 token。虽然它是 base64 编码的结构，但其格式不作保证；请将其作为不透明字符串保存和传递。
收到 401 时，重新登录一次并重试请求；如果再次收到 401，说明密钥对或酒店授权已发生变化。

酒店上下文#

一个 token 只绑定一家酒店。各端点的 hotelID 参数必须与该酒店一致；请求其他酒店会得到授权错误或空结果。对接多家酒店时，请为每家酒店分别获取 token 并按酒店缓存。

message	含义
`partner_is_not_found`	`apiKey` / `apiSecret` 不匹配。请检查密钥及其 URL 编码。
`hotel_is_not_found`	找不到与 `hotelSeoUrl` 对应的酒店。
`hotel_permission_is_not_found`	合作伙伴未获得该酒店的授权，或授权已停用。请联系 HMS 技术支持。

这些错误以 HTTP 200 返回，并附带 success: false 和 token: null。

最后更新: 2026年9月21日发现错误？请告诉我们

身份验证

登录与 token#

Bearer 请求头#

token 有效期与续期#

酒店上下文#

登录错误#