合作伙伴 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 面向已签署合作伙伴协议的旅行社。没有自助注册:每个代理机构和密钥均由我们的团队设置。

  1. 请联系我们的合作伙伴团队,并提供公司名称、国家/地区、网站、技术联系人和预计月交易量。
  2. 我们确认贵社的佣金比例、取消政策和付款条件,然后创建代理机构记录。
  3. 我们签发测试密钥。它读取真实的产品目录和可用性数据,但写入的预订为测试记录,不会占用库存,也不会计入对账单。
  4. 贵社使用测试密钥构建并测试集成。
  5. 准备就绪后,请将系统调用所用的固定 IP 地址发送给我们。我们会将其加入允许列表并签发正式密钥。
  6. 切换令牌,执行下方的上线检查,然后开始预订。
申请合作伙伴访问

密钥与身份验证

在每次已认证调用中以 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": {}
  }
}
状态 代码 何时
401invalid_credentials密钥缺失、格式错误、未知、已撤销或已过期。
403agency_suspended密钥有效,但其代理机构被暂停。
403insufficient_scope密钥缺少路由所需的权限范围。
403ip_not_allowed调用方不在密钥的地址列表中。
404not_found资源不存在,或属于其他代理机构。
409unavailable所选内容存在但无法出售:已过期、关闭、已满或未定价。请重新读取可用性并重新报价。
409idempotency_conflict该 Idempotency-Key 已用于不同的请求体。
422validation_failed请求未通过验证;details 包含字段错误。
429rate_limited请求过多。请等待 Retry-After 请求头指定的时间。
500server_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 下。版本内可能出现新增字段。破坏性变更会发布新版本,绝不会在当前版本内更改。

仍然遇到问题?

请发送请求 id、端点、时间戳和错误代码。切勿发送完整密钥。

联系合作伙伴团队
需要帮助?

需要帮助?

给我们留言,我们会通过电子邮件回复您。