ゴルフ場API は用途の異なる2系統で構成されます。パートナー予約連携API（会員向け）とは別物です。

APIキー認証。すべてのリクエストに X-API-Key ヘッダーを付与します。キーは管理者が発行し、integration タイプのキーは 1キーにつき1ゴルフ場（owner_id）に紐づきます。対象ゴルフ場はキーから特定されるため、golf_club_id はリクエストに含めません（他ゴルフ場のデータには一切アクセスできません）。

POST /api/integration/tee-times/sync.php HTTP/1.1
Host: govigolf.comX-API-Key: YOUR_API_KEY
Content-Type: application/json

スコープ: 参照系は integration:read、更新系は integration:write。

APIキー認証（X-API-Key ヘッダー、owner_type='golf_club' のキー）。GolfClubAuthService が処理します。対象ゴルフ場はキー（owner_id）から特定されるため、golf_club_id をパラメータで渡す必要はありません。

GET /api/manage/reservations/list.php HTTP/1.1
Host: govigolf.comX-API-Key: YOUR_API_KEY

スコープ（リソース別）: reservations:read/write / tee_times:read/write / notifications:read/write / settings:read/write / reports:read。

CSVエクスポートを除き、すべて以下の JSON エンベロープで返ります。

{
  "status": "success",
  "message": "...",
  "data": { ... }
}

{
  "status": "error",
  "message": "エラー内容",
  "data": null
}

外部システムのティータイム枠を GOVIGO に同期（外部→GOVIGO）。最大 500 件／リクエスト。

POST /api/integration/tee-times/sync.php HTTP/1.1
Host: govigolf.comX-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "slots": [
    { "course_id": 10, "tee_time": "2026-07-01 07:30", "total_slots": 4, "available_slots": 4 }
  ]
}

GOVIGO 側のティータイムを取得（GOVIGO→外部）。

GET /api/integration/tee-times/pull.php?date_from=2026-07-01&date_to=2026-07-07 HTTP/1.1
Host: govigolf.comX-API-Key: YOUR_API_KEY

指定期間の全量スナップショットで GOVIGO ミラーをクラブ側の正に合わせます（webhook 取りこぼし等のドリフト修復用）。全枠を upsert し、スナップショットに無い枠を掃除します。未予約の枠は論理クローズ（status=closed・物理削除しない）、予約済みなのにスナップショットから消えた枠はクローズせず conflicts として返却（手動調整用）。クローズした枠は顧客の空き枠表示から除外され、クラブが再投入すれば自動的に open に戻ります。クラブが定期実行（例: 夜間）する想定。

POST /api/integration/tee-times/reconcile.php HTTP/1.1
Host: govigolf.comX-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "date_from": "2026-07-01",
  "date_to": "2026-07-01",
  "slots": [
    { "course_id": 10, "tee_time": "2026-07-01 07:30", "total_slots": 4, "available_slots": 4 }
  ]
}

外部システムで発生した予約を GOVIGO に取り込みます（外部→GOVIGO）。external_ref が冪等キーとなり、同じ値での二重送信は既存予約を返して終了します。

POST /api/integration/reservations/receive.php HTTP/1.1
Host: govigolf.comX-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "external_ref": "EXT-12345",
  "course_id": 10,
  "tee_date": "2026-07-01",
  "tee_time": "07:30",
  "customer_name": "山田 太郎",
  "customer_email": "taro@example.com",
  "customer_phone": "090-0000-0000",
  "player_count": 2,
  "total_amount": 3600000
}

外部システム側で変更された予約を GOVIGO ミラーへ反映します（外部→GOVIGO）。指定した項目だけ更新。人数を変更すると在庫を差分調整します（増員で空き不足は 409）。キャンセルは cancel.php を使用。スロット紐づき予約の日時変更は不可（キャンセル→再作成）。

POST /api/integration/reservations/update.php HTTP/1.1
Host: govigolf.comX-API-Key: YOUR_API_KEY
Content-Type: application/json

{ "external_ref": "EXT-12345", "player_count": 3, "tee_time": "08:00" }

外部システム側でキャンセルされた予約を GOVIGO ミラーへ反映します（外部→GOVIGO）。ステータスをキャンセルにし、枠があれば在庫を人数分復元します。冪等（既にキャンセル済みでも成功を返す）。

POST /api/integration/reservations/cancel.php HTTP/1.1
Host: govigolf.comX-API-Key: YOUR_API_KEY
Content-Type: application/json

{ "external_ref": "EXT-12345" }

GOVIGO 側の予約データを取得します（GOVIGO→外部）。既定では当日〜30日後が対象。

予約・在庫などのイベント通知先 URL を登録します。

POST /api/integration/webhooks/subscribe.php HTTP/1.1
Host: govigolf.comX-API-Key: YOUR_API_KEY
Content-Type: application/json

{ "url": "https://example.com/hook", "events": ["reservation.created", "reservation.cancelled"] }

登録済み Webhook の一覧を取得します（パラメータなし。対象ゴルフ場はキーから特定）。

登録済み Webhook を解除します。

指定サブスクリプションにテストイベントを送信します。

自ゴルフ場の予約一覧を取得します。既定: 20件／ページ（最大100件）。

GET /api/manage/reservations/list.php?date_from=2026-07-01&date_to=2026-07-31&page=1 HTTP/1.1
Host: govigolf.comX-API-Key: YOUR_API_KEY

予約の詳細を取得します。同伴者情報を含みます。

予約ステータスを変更します。status=9 はキャンセル扱いとなり、在庫を復元します。キャンセル済み予約を別ステータスへ戻すことはできません（409）。

POST /api/manage/reservations/update-status.php HTTP/1.1
Host: govigolf.comX-API-Key: YOUR_API_KEY
Content-Type: application/json

{ "reservation_id": 123, "status": 2, "memo": "確認済み" }

指定日の予約枠一覧を取得します。

予約枠を1件更新します。更新後の available_slots が 0〜total_slots の範囲を外れる場合は 400 を返します。

複数の予約枠をまとめて更新します（最大 200 件）。1件でもバリデーションエラーがあった場合はその件をスキップして続行し、errors に詳細を返します。

POST /api/manage/tee-times/bulk-update.php HTTP/1.1
Host: govigolf.comX-API-Key: YOUR_API_KEY
Content-Type: application/json

{ "slots": [ { "slot_id": 501, "available_slots": 0, "status": "closed" }, { "slot_id": 502, "available_slots": 2 } ] }

通知一覧を取得します。作成日時の降順。

通知を既読にします。notification_ids と all のいずれかが必須。

未読通知数を取得します。パラメータなし。

ゴルフ場設定を取得します。key 省略時は全件を { key: value } 形式で返します。

ゴルフ場設定を更新します（UPSERT）。複数キーを一括更新可能。

POST /api/manage/settings/update.php HTTP/1.1
Host: govigolf.comX-API-Key: YOUR_API_KEY
Content-Type: application/json

{ "settings": { "auto_confirm": "1", "cancel_deadline_days": "3" } }

予約実績の集計を取得します。既定期間は当月。

予約データを CSV でエクスポートします。レスポンスは text/csv（JSON エンベロープではなく、UTF-8 BOM 付き CSV ファイル）。

GET /api/manage/reports/export.php?date_from=2026-07-01&date_to=2026-07-31 HTTP/1.1
Host: govigolf.comX-API-Key: YOUR_API_KEY