パートナーAPI · v1
PALAU EXPLORER にシステムを接続する
旅行会社向けのマシン・ツー・マシン REST API。御社のネット料金でツアー、オフロード、ジェットスキーの便を取得し、リアルタイムの空き状況を確認し、予約の作成・キャンセルとアカウント照合を行えます。
サーバー間通信専用です。キーをブラウザ、モバイルアプリ、公開リポジトリに置かないでください。
ベース URL
https://palauexplorer.com/api/v1
認証
代理店ごとに発行される Bearer APIキー
レート制限
キーごとに毎分 120 リクエスト
形式
HTTPS 上の JSON、UTF-8
通貨と日付
米ドル金額は小数2桁の文字列です。日付は YYYY-MM-DD、タイムスタンプは RFC 3339 です。
概要
パートナーAPI は旅行会社向けのマシン・ツー・マシン窓口です。ツアー、オフロード便、ジェットスキー便を提供します。ホテルはこの API では予約できません。
読み取り
公開中の商品、説明、画像、御社のネット料金。
予約
リアルタイムの空き状況、冪等な書き込みによる予約、キャンセル。
照合
旅行期間の請求書、支払い、残高。
すべての呼び出しはスコープ、レート制限、ログの対象です。キーは常に1つの代理店に属し、その代理店のデータのみを読み取り・変更できます。
アクセスの取得
本 API はパートナー契約を結んだ旅行会社向けです。セルフサインアップはありません。代理店とキーはすべて当社チームが設定します。
- パートナーチームに、会社名、国・地域、ウェブサイト、技術担当者、月間予定取引量をお知らせください。
- 手数料率、キャンセル規定、支払条件を合意し、代理店レコードを作成します。
- テストキーを発行します。実際のカタログと空き状況を読み取りますが、書き込まれる予約はテスト記録であり、在庫を確保せず、明細にも計上されません。
- テストキーで連携を構築・テストします。
- 準備ができたら、システムが使用する固定 IP アドレスをお知らせください。許可リストに追加し、本番キーを発行します。
- トークンを切り替え、以下の本番チェックを実行して予約を開始します。
キーと認証
認証が必要なすべての呼び出しで、キーを Bearer トークンとして送信します:
Authorization: Bearer pk_live_01J4Z9K8YQ7V6N5M4P3R2S1T0H.7fK2pQ9wLm4Rx8Tn6Vb1Yc3Ds5Gh0Jk2Mn4Po6Qr8St0Uv
| キー | 用途 |
|---|---|
pk_test_ |
実データを読み取ります。書き込むテスト予約は在庫を確保せず、売上や明細に計上されません。 |
pk_live_ |
実データを読み書きします。予約は即座に在庫を確保します。 |
キーのルール
- シークレットは発行時に一度だけ表示され、ハッシュのみ保存されます。紛失した場合はキーをローテーションしてください。復元はできません。
- キーは IPv4/IPv6 アドレスや CIDR ブロックに制限できます。それ以外の場所からの呼び出しは 403 ip_not_allowed を返します。
- ローテーションは代替キーを発行し、旧シークレットを同時に失効させます。新しいトークンをすぐに配備するか、短いメンテナンス時間を設けてください。
- 失効は即時です。停止中の代理店はすべての呼び出しで 403 agency_suspended を受け取ります。
- トークンのモードはキーと一致する必要があります。テストトークンを本番キーに、またはその逆に使用することはできません。
- キーはサーバーのシークレットマネージャーに保管してください。ブラウザ、モバイルアプリ、公開リポジトリに埋め込まないでください。
最初の呼び出し
業務ロジックを書く前に、この3つの呼び出しを実行してください。到達性、認証情報、商業条件を順に確認できます。
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 でページングし、1ページ最大200件です。GET /tours/{slug}1つのツアーを、詳細説明、旅程、含まれるもの、含まれないもの、ハイライト、ギャラリー、州の許可証とともに開きます。- 各カードには 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"
オフロードとジェットスキー
各商品には1つのエンドポイントと午前・午後の2便があります。そのレスポンスの便 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 が含まれます。
statebookable(予約可)、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 に渡します。
- 顧客用の艇は2席を販売します。各乗員は1席分の料金です。
- ガイド艇は party.pillion を受け付ける唯一の艇です。後部座席はその日の他の全席が埋まってから開放されるため、それまでは seats_remaining は 0 のままです。
- 同じ艇を1つの予約で2回指定することはできず、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.typetour、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 と同じ本文で繰り返すと、2件目を作成せず最初のレスポンスを再生します。同じキーで本文が異なる場合は 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予約を新しい順に一覧します。status(unpaid、confirmed、cancelled)、from、to の旅行日、page、per_page で絞り込めます。GET /bookings/{reference}1件の予約を返します。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
|
エラーの共通形式
どの失敗も同じ形式です。message ではなく code で分岐してください。
{
"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 を返します。指数バックオフとジッターを使い、tight loop で再試行しないでください。
再試行ポリシー
- 429 と 5xx の GET は指数バックオフで再試行します。
- POST /bookings の再試行は、同じ Idempotency-Key と同じ本文の場合のみ行います。
- 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;
Idempotency-Key には UUID などの一意な値を使用します。タイムアウト時に同じ値で再試行できるよう、予約試行と一緒に保存してください。
本番稼働チェックリスト
- 本番キーが発行され、本番の送信元アドレスに制限されています。
- 本番設定やログにテストキーが含まれていません。
- キーはシークレットマネージャーに保存され、コードや公開リポジトリにはありません。
- HTTP クライアントの接続タイムアウトは約10秒、読み取りタイムアウトは約30秒です。
- すべての予約試行(再試行を含む)で Idempotency-Key を永続化しています。
- ジョブが定期的に /bookings と /statement をポーリングし、401、403、429、5xx でアラートを出します。
- テスト予約をエンドツーエンドで実行済みです(作成、読み取り、キャンセル、照合)。
- 誰がキーをローテーションし、新しいトークンが本番にどのように届くかを把握しています。
- 連携の告知前に、実顧客で本番予約を1件完了しています。
よくある質問
この 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 配下です。バージョン内でフィールドが追加されることがあります。破壊的変更は新しいバージョンで行い、現行バージョン内では変更しません。