合作伙伴 API · v1
将您的系统连接到 PALAU EXPLORER
面向旅行社的机器对机器 REST API。使用贵社的净价读取我们的行程、越野和水上摩托班次,查询实时可用性,创建和取消预订,并对账您的账户。
仅限服务器对服务器调用。切勿将密钥放入浏览器、移动应用或公开代码库。
基础 URL
https://palauexplorer.com/api/v1
身份验证
Bearer API 密钥,按代理机构签发
速率限制
每个密钥每分钟 120 次请求
格式
HTTPS 上的 JSON,UTF-8
货币与日期
美元金额为保留两位小数的字符串。日期格式为 YYYY-MM-DD,时间戳为 RFC 3339。
概览
合作伙伴 API 是面向旅行社的机器对机器通道。它提供行程、越野班次和水上摩托班次。酒店无法通过此 API 预订。
读取
已发布的产品、介绍、图片和贵社净价。
预订
实时可用性、幂等写入的预订以及取消。
对账
旅行期间内的发票、付款和余额。
每次调用都受权限范围、速率限制和日志记录约束。密钥始终属于一个代理机构,只能读取或更改该机构的数据。
获取访问权限
本 API 面向已签署合作伙伴协议的旅行社。没有自助注册:每个代理机构和密钥均由我们的团队设置。
- 请联系我们的合作伙伴团队,并提供公司名称、国家/地区、网站、技术联系人和预计月交易量。
- 我们确认贵社的佣金比例、取消政策和付款条件,然后创建代理机构记录。
- 我们签发测试密钥。它读取真实的产品目录和可用性数据,但写入的预订为测试记录,不会占用库存,也不会计入对账单。
- 贵社使用测试密钥构建并测试集成。
- 准备就绪后,请将系统调用所用的固定 IP 地址发送给我们。我们会将其加入允许列表并签发正式密钥。
- 切换令牌,执行下方的上线检查,然后开始预订。
密钥与身份验证
在每次已认证调用中以 Bearer 令牌发送密钥:
Authorization: Bearer pk_live_01J4Z9K8YQ7V6N5M4P3R2S1T0H.7fK2pQ9wLm4Rx8Tn6Vb1Yc3Ds5Gh0Jk2Mn4Po6Qr8St0Uv
| 密钥 | 作用 |
|---|---|
pk_test_ |
读取真实数据。写入测试预订,不会占用库存、计入收入或出现在对账单中。 |
pk_live_ |
读写真实数据。预订会立即占用库存。 |
密钥规则
- 密钥仅在签发时显示一次,之后只存储哈希。如遗失,请轮换密钥,无法找回。
- 密钥可限制为 IPv4 或 IPv6 地址及 CIDR 网段。来自其他地址的调用会返回 403 ip_not_allowed。
- 轮换会签发替代密钥并同时撤销旧密钥。请立即部署新令牌,或安排短暂的维护窗口。
- 撤销立即生效。被暂停的代理机构每次调用都会收到 403 agency_suspended。
- 令牌中的模式必须与密钥匹配。测试令牌不能用于正式密钥,反之亦然。
- 将密钥保存在服务器的密钥管理器中。切勿将其嵌入浏览器、移动应用或公开代码库。
首次调用
在编写任何业务逻辑之前先执行这三个调用。它们按顺序验证可达性、凭据和商业条款。
1. 可达性
此调用无需密钥。它返回服务器时钟,并证明 DNS、TLS 和出站防火墙均已开放。
curl https://palauexplorer.com/api/v1/ping
2. 我是谁
此调用需要有效密钥,但不需要权限范围。它返回贵社的代理机构、密钥模式、持有的权限范围和速率限制。
curl https://palauexplorer.com/api/v1/me \ -H "Authorization: Bearer $PALAU_API_KEY"
{
"data": {
"agency": { "id": 7, "name": "Blue Lagoon Travel" },
"key": { "name": "Production integration", "mode": "live" },
"scopes": ["catalog.read", "inventory.read", "bookings.read", "bookings.write"],
"rate_limit": { "per_minute": 120 },
"status": "active"
}
}
3. 商业条款
此调用返回贵社的佣金、取消政策和付款条件。在向客户报价前,请与已签署的合同核对。
curl https://palauexplorer.com/api/v1/terms \ -H "Authorization: Bearer $PALAU_API_KEY"
接入检查清单
- GET /ping 返回 200,status 为 ok。
- GET /me 返回预期的代理机构和密钥模式。
- GET /me 列出贵社申请的所有权限范围。
- GET /terms 与已签署的佣金和取消政策一致。
- 401 表示密钥缺失、格式错误、未知、已撤销或已过期。
- 403 表示密钥有效,但代理机构被暂停、缺少权限范围,或地址未加入允许列表。
权限范围
密钥拥有一组权限范围。调用所需权限范围不在密钥中时返回 403 insufficient_scope。请只申请集成所需的最小集合。
| 权限范围 | 允许 |
|---|---|
catalog.read |
读取产品目录 行程和越野班次:介绍、图片和扣除佣金后的价格。 |
inventory.read |
读取实时库存 行程的每日可用性和越野班次的每时段座位可用性。 |
bookings.read |
读取自身预订 该代理机构已创建的预订及其状态。 |
bookings.write |
创建和取消预订 代表该代理机构创建和取消预订。 |
产品目录和库存是刻意分开的授权:合作伙伴可以在没有实时库存的情况下购买内容,反之亦然。写入权限也独立,因此对账任务可以读取预订,但不能创建或取消预订。
此版本在 /v1 下有 15 个路由。完整列表见下方端点表和 OpenAPI 契约。
产品目录
产品目录为只读。它返回已发布产品及贵社在参考日期的净价。可传入 locale=en、zh-Hans 或 ja;缺少翻译时回退到英文。
行程
GET /tours列出已发布且带标题的行程。使用 page 和 per_page 分页,每页最多 200 条。GET /tours/{slug}打开单个行程,包含完整介绍、行程安排、包含项目、不包含项目、亮点、图库和州许可证。- 每张卡片包含 id、slug、标题、文案、时长、容量、星期、图片和价格。预订时将 id 作为 product.id。将 slug 保留为稳定的外部引用。
- 州许可证需在当地购买,无法通过 API 预订。请单独报价,否则价格会少算这笔费用。
curl "https://palauexplorer.com/api/v1/tours?locale=en&date=2026-11-20&per_page=50" \ -H "Authorization: Bearer $PALAU_API_KEY"
越野与水上摩托
每个产品有一个端点和两个班次(上午和下午)。该响应中的班次 id 就是预订所需的 product.id。
curl "https://palauexplorer.com/api/v1/off-road?date=2026-11-20" \ -H "Authorization: Bearer $PALAU_API_KEY" curl "https://palauexplorer.com/api/v1/jet-ski?date=2026-11-20" \ -H "Authorization: Bearer $PALAU_API_KEY"
价格含义
public是面向公众网站的价格。net是贵社扣除佣金后支付的价格。rate是贵社的佣金百分比。child_public和child_net仅在产品设有儿童价时出现。
产品目录价格是参考日期的报价。创建预订时会再次检查可用性和价格。
可用性
可用性是实时的。座位可能在读取和写入之间被占用,因此始终以预订结果为准。
行程
GET /tours/{slug}/availability 返回窗口内的每一天,包括关闭日期。每天包含 state、remaining 和 price。
state为 bookable(可预订)、full(已满)或 closed(关闭)。remaining是剩余座位数。产品不限人数时为 null。price在当天关闭或没有价格时为 null。已满的日期仍有价格。- 窗口默认为从今天起 90 天,最长 366 天。过去的 from 日期会移动到今天。to 早于 from 会返回 422 validation_failed。
curl "https://palauexplorer.com/api/v1/tours/rock-islands-tour/availability?from=2026-11-20&to=2026-12-20" \ -H "Authorization: Bearer $PALAU_API_KEY"
越野与水上摩托
GET /off-road/availability 和 GET /jet-ski/availability 返回每个班次和日期的 seats_remaining。只显示可售日期,0 表示已满。
水上摩托响应还会为每个日期提供 skis 列表。每艘艇包含 assignment、seats_remaining 和 guide。将所需的 assignment 放入 party.skis。
- 客户艇出售两个座位。每位乘客按座位价格计算。
- 向导艇是唯一接受 party.pillion 的艇。其后座仅在该日其他所有座位售罄后开放,因此在此之前其 seats_remaining 保持为 0。
- 同一艘艇不能在一次预订中重复指定,pillion 必须是向导艇。
curl "https://palauexplorer.com/api/v1/jet-ski/availability?from=2026-11-20&to=2026-11-27" \ -H "Authorization: Bearer $PALAU_API_KEY"
创建预订
POST /bookings 创建预订并立即占用库存。需要 bookings.write 权限范围和 Idempotency-Key 请求头。
| 请求头 | 数值 |
|---|---|
Authorization |
Bearer pk_live_... |
Content-Type |
application/json |
Idempotency-Key |
此逻辑预订的唯一键,最多 191 个字符。每次预订生成一个,而不是每次重试生成。 |
行程请求体
curl -X POST "https://palauexplorer.com/api/v1/bookings" \
-H "Authorization: Bearer $PALAU_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6b0f0f7e-2f4a-4b31-9a8e-2d3c4b5a6f70" \
-d '{
"product": { "type": "tour", "id": 3 },
"date": "2026-11-20",
"party": { "adults": 2, "children": 1 },
"guest": { "name": "Ana Reyes", "email": "ana@example.com", "phone": "+680 555 0100" },
"partner_reference": "INV-2041",
"hold_ttl_minutes": 60
}'
越野和水上摩托请求体
越野预订指定座位数。水上摩托预订指定整艘艇及每艇乘客数。
{
"product": { "type": "off_road", "id": 1 },
"date": "2026-11-20",
"party": { "seats": 2 },
"guest": { "name": "Ana Reyes", "email": "ana@example.com" }
}
{
"product": { "type": "jet_ski", "id": 1 },
"date": "2026-11-20",
"party": {
"skis": [
{ "assignment": 13, "riders": 2 },
{ "assignment": 14, "riders": 1 }
],
"pillion": 12
},
"guest": { "name": "Ana Reyes", "email": "ana@example.com" }
}
字段
product.type为 tour、off_road 或 jet_ski。product.id是 /tours 返回的行程 id,或 /off-road、/jet-ski 返回的班次 id。date是旅行日期,格式为 YYYY-MM-DD。end_date为可选字段,仅对多日行程有意义。party行程使用 adults 和 children,越野使用 seats,水上摩托使用 skis。guest.email必须是有效地址;旅客确认信将发送到此处。partner_reference会原样返回,是放置贵社预订编号的最佳位置。hold_ttl_minutes为可选字段,范围 5 到 10080。开放预订时请省略。
幂等性
使用相同 Idempotency-Key 和相同请求体重复调用会重放第一次响应,而不会创建第二个预订。相同键但不同请求体会返回 409 idempotency_conflict。键会保留 24 小时。
这就是超时安全的原因:再次发送相同的键和请求体,您会得知原始结果,而不会冒重复预订的风险。
响应
{
"data": {
"reference": "PE-01J4Z9K8YQ7V6N5M4P3R2S1T0H",
"status": "unpaid",
"test": false,
"product": { "type": "tour", "id": 3, "name": "Rock Islands Kayak" },
"date": "2026-11-20",
"end_date": null,
"party": { "adults": 2, "children": 1, "seats": null },
"guest": { "name": "Ana Reyes", "email": "ana@example.com", "phone": "+680 555 0100" },
"partner_reference": "INV-2041",
"price": { "public": "300.00", "rate": "15.00", "commission": "45.00", "net": "255.00" },
"invoice": { "number": "BLT-000042", "amount": "255.00", "status": "outstanding" },
"hold_expires_at": "2026-11-20T12:00:00+00:00",
"cancel_reason": null,
"cancel_penalty": null,
"created_at": "2026-11-20T11:00:00+00:00"
}
}
使用测试密钥的预订返回 test: true。请保留 reference,它是后续读取、取消和对账的依据。
管理预订
密钥只能看到所属代理机构的预订。其他机构的 reference 会返回普通 404。
GET /bookings列出贵社的预订,最新在前。可按状态(unpaid、confirmed、cancelled)、from 和 to 旅行日期、page 和 per_page 筛选。GET /bookings/{reference}返回单个预订。POST /bookings/{reference}/cancel取消预订,释放库存,并记录贵社取消政策对应的罚金。
curl "https://palauexplorer.com/api/v1/bookings?status=unpaid&from=2026-11-01&to=2026-11-30" \ -H "Authorization: Bearer $PALAU_API_KEY" curl -X POST "https://palauexplorer.com/api/v1/bookings/PE-01J4Z9K8YQ7V6N5M4P3R2S1T0H/cancel" \ -H "Authorization: Bearer $PALAU_API_KEY"
取消本身是幂等的:取消已取消的预订会原样返回,因此重试是安全的。因保留到期而失效的预订携带 cancel_reason hold_expired;由贵社取消的携带 partner。
对账
GET /statement 返回旅行期间内的发票、付款和余额。预订归属于其开始日期所在的期间,付款归属于其所结算预订的期间,无论款项何时到账。
- 窗口默认为当前月份。to 早于 from 会返回 422 validation_failed。
- 发票状态为 outstanding(未付)、paid(已付)或 void(作废)。取消预订会作废其发票。
- 数据来自管理端对账单使用的同一服务,因此两者不会不一致。
curl "https://palauexplorer.com/api/v1/statement?from=2026-11-01&to=2026-11-30" \ -H "Authorization: Bearer $PALAU_API_KEY"
没有合作伙伴 Webhook。请轮询 GET /bookings 获取状态变化,轮询 GET /statement 获取资金信息。通常 5 到 15 分钟的间隔就足够;不要在每个页面浏览时轮询。
端点、错误与速率限制
以下每个路径都相对于基础 URL。显示调用所需的权限范围。“Any valid key”表示不检查权限范围。
| 方法 | 路径 | 权限范围 |
|---|---|---|
| GET | /bookings |
bookings.read
|
| POST | /bookings |
bookings.write
|
| GET | /bookings/{reference} |
bookings.read
|
| POST | /bookings/{reference}/cancel |
bookings.write
|
| GET | /jet-ski |
catalog.read
|
| GET | /jet-ski/availability |
inventory.read
|
| GET | /me |
任意有效密钥 |
| GET | /off-road |
catalog.read
|
| GET | /off-road/availability |
inventory.read
|
| GET | /ping |
无(公开) |
| GET | /statement |
bookings.read
|
| GET | /terms |
任意有效密钥 |
| GET | /tours |
catalog.read
|
| GET | /tours/{tour} |
catalog.read
|
| GET | /tours/{tour}/availability |
inventory.read
|
错误响应结构
所有失败响应的结构相同,无论由什么产生。请根据 code 分支,不要根据 message。
{
"error": {
"code": "insufficient_scope",
"message": "This key may not do that.",
"details": {}
}
}
| 状态 | 代码 | 何时 |
|---|---|---|
| 401 | invalid_credentials | 密钥缺失、格式错误、未知、已撤销或已过期。 |
| 403 | agency_suspended | 密钥有效,但其代理机构被暂停。 |
| 403 | insufficient_scope | 密钥缺少路由所需的权限范围。 |
| 403 | ip_not_allowed | 调用方不在密钥的地址列表中。 |
| 404 | not_found | 资源不存在,或属于其他代理机构。 |
| 409 | unavailable | 所选内容存在但无法出售:已过期、关闭、已满或未定价。请重新读取可用性并重新报价。 |
| 409 | idempotency_conflict | 该 Idempotency-Key 已用于不同的请求体。 |
| 422 | validation_failed | 请求未通过验证;details 包含字段错误。 |
| 429 | rate_limited | 请求过多。请等待 Retry-After 请求头指定的时间。 |
| 500 | server_error | 我们的问题。不会泄露内部信息。请退避后重试。 |
速率限制
- 已认证密钥每分钟可发起 120 次请求。
- 未认证调用方每个地址每分钟限制为 30 次请求。
- 429 响应携带以秒为单位的 Retry-After。请使用指数退避并加入抖动;不要紧密循环重试。
重试策略
- 对 429 和 5xx 的 GET 请求使用指数退避重试。
- 仅使用相同的 Idempotency-Key 和相同的请求体重试 POST /bookings。
- 不要重试 401、403、404 或 422。这些需要修正配置或请求体。
- 遇到 409 unavailable 时,请重新读取可用性并重新报价,再决定是否尝试其他日期或班次。
代码示例
以下示例创建与上方相同的行程预订。请替换基础 URL、密钥和 id。
PHP
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;
$response = Http::withToken(config('services.palau.key'))
->withHeaders(['Idempotency-Key' => (string) Str::uuid()])
->post(config('services.palau.base_url').'/bookings', [
'product' => ['type' => 'tour', 'id' => 3],
'date' => '2026-11-20',
'party' => ['adults' => 2, 'children' => 1],
'guest' => [
'name' => 'Ana Reyes',
'email' => 'ana@example.com',
'phone' => '+680 555 0100',
],
'partner_reference' => 'INV-2041',
]);
if ($response->failed()) {
$error = $response->json('error');
// Branch on $error['code'], never on the message.
}
$booking = $response->json('data');
Node.js
const baseUrl = process.env.PALAU_API_BASE_URL;
const key = process.env.PALAU_API_KEY;
const response = await fetch(`${baseUrl}/bookings`, {
method: 'POST',
headers: {
Authorization: `Bearer ${key}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
product: { type: 'tour', id: 3 },
date: '2026-11-20',
party: { adults: 2, children: 1 },
guest: {
name: 'Ana Reyes',
email: 'ana@example.com',
phone: '+680 555 0100',
},
partner_reference: 'INV-2041',
}),
});
const payload = await response.json();
if (!response.ok) {
throw new Error(`Booking failed: ${payload.error.code}`);
}
const booking = payload.data;
使用 UUID 或其他唯一值作为 Idempotency-Key。将其与预订尝试一起保存,以便超时后使用相同值重试。
上线检查清单
- 正式密钥已签发,并限制为贵社的生产出口地址。
- 生产配置或日志中不存在测试密钥。
- 密钥存储在密钥管理器中,绝不在代码或公开代码库中。
- HTTP 客户端连接超时约为 10 秒,读取超时约为 30 秒。
- 每次预订尝试(包括重试)都持久化 Idempotency-Key。
- 您的任务按计划轮询 /bookings 和 /statement,并在 401、403、429 和 5xx 时告警。
- 您已完成一次端到端测试预订:创建、读取、取消和对账。
- 您清楚由谁轮换密钥,以及新令牌如何到达生产环境。
- 在宣布集成上线前,您已使用真实客户完成一次正式预订。
常见问题
可以通过此 API 预订酒店吗?
不可以。合作伙伴 API 覆盖行程、越野班次和水上摩托班次。酒店住宿不属于 v1。
有独立的沙箱 URL 吗?
没有。请使用相同的基础 URL 和 pk_test_ 密钥。测试读取返回真实数据;测试写入创建测试预订,不占用库存,也不计入对账单。
可以从浏览器或移动应用调用 API 吗?
不可以。密钥是服务器机密。请从自己的后端调用,以便安全存储和轮换密钥。
你们发送 Webhook 吗?
v1 没有合作伙伴 Webhook。请轮询 /bookings 获取状态变化,轮询 /statement 获取资金信息。
为什么我刚创建的预订返回 404?
预订仅对创建它的代理机构可见。请确认使用相同的密钥,并且 reference 完整。
产品目录价格是最终价格吗?
它们是参考日期的报价。预订时会重新检查可用性和价格,并返回最终净额。州许可证需额外购买,且无法预订。
在哪里找到行程或水上摩托的 id?
行程 id 是每个 /tours 卡片上的 id 字段。水上摩托的 assignment id 是 /jet-ski/availability 的 skis 列表中的 assignment 值。
可以提高速率限制吗?
请联系您的合作伙伴经理。限制按密钥合同设定,不是全局上限。
API 如何版本化?
所有内容都在 /v1 下。版本内可能出现新增字段。破坏性变更会发布新版本,绝不会在当前版本内更改。