GOVIGO APIはAPIキー認証を使用します。すべてのリクエストに X-API-Key ヘッダーを含めてください。

GET /api/golf-clubs/plans.php?golf_club_id=1 HTTP/1.1
Host: govigolf.com
X-API-Key: YOUR_API_KEY

利用可能なスコープ:

すべてのAPIレスポンスは以下の共通形式で返却されます。

{
  "success": true,
  "data": { ... },
  "message": "",
  "http_code": 200
}

予約は2つのキーで参照できます。

APIキーの有効性・所有者・付与スコープ・レート上限を確認します。連携の初期疎通テストに使用してください（スコープ不問）。

{
  "success": true,
  "data": {
    "authenticated": true,
    "owner": { "type": "partner", "id": 3, "name": "Partner A" },
    "key_prefix": "a1b2c3d4",
    "scopes": ["golf_clubs:read", "tee_times:read", "reservations:read", "reservations:write"],
    "rate_limit": 120,
    "expires_at": null,
    "server_time": "2026-06-01T10:00:00+07:00"
  },
  "message": "pong",
  "http_code": 200
}

ゴルフ場の詳細情報を取得します。id を省略すると一覧として返却されます。

{
  "success": true,
  "data": {
    "lang": "en",
    "count": 1,
    "golf_clubs": [
      {
        "id": 1,
        "name": "Sample Golf Club",
        "area": "Central (Da Nang / Hue)",
        "area_code": 3,
        "country": 0,
        "address": "Xa Loc Vinh, Phu Loc, Hue, Viet Nam",
        "google_map": "https://maps.google.com/...",
        "latitude": 16.3312358,
        "longitude": 107.9558334,
        "phone": "+842343695880",
        "opening_hours": "05:30-18:00",
        "description": "Located about an hour's drive from Da Nang ...",
        "access": null,
        "courses": [
          { "name": "Lagoon Course", "holes": 18, "par": 71, "length_yards": 7101, "designer": "Sir Nick Faldo" }
        ],
        "course_info": "18 holes, Par 71 / 7,101 yards",
        "remark": "Located about an hour's drive from Da Nang ...",
        "opened_on": "2013-03-01",
        "dress_code": "Collared shirts required ...",
        "cancel_policy": "Free cancellation up to 9 days before tee time ...",
        "main_image": {
          "url": "https://govigolf.com/images/golf_club_top_picture/xxx.jpg",
          "thumbnail_url": "https://govigolf.com/images/golf_club_picture/thumb/xxx.jpg"
        },
        "images": [
          { "url": "https://govigolf.com/images/golf_club_picture/yyy.jpg",
            "thumbnail_url": "https://govigolf.com/api/golf-clubs/thumbnail.php?src=..." }
        ],
        "facilities": {
          "driving_range": { "available": true,  "note": null },
          "pro_shop":      { "available": true,  "note": null },
          "restaurant":    { "available": true,  "note": null },
          "lesson":        { "available": false, "note": null },
          "night_golf":    { "available": false },
          "note": null
        },
        "updated_at": "2026-08-18T09:30:40Z",
        "rental": {
          "club_available": true,
          "club_fee": 300000,
          "shoes_available": false,
          "shoes_fee": null
        },
        "options": {
          "rental_cart":      { "available": true,  "included": true,  "fee": null },
          "rental_umbrella":  { "available": false, "included": false, "fee": null },
          "caddy":            { "available": true,  "included": true,  "fee": null },
          "caddy_designate":  { "available": true,  "included": false, "fee": 200000 },
          "caddybag_storage": { "available": false, "included": false, "fee": null },
          "sent_caddybag":    { "available": false, "included": false, "fee": null },
          "accompany":        { "available": false, "included": false, "fee": null },
          "pickup":           { "available": false, "description": null }
        }
      }
    ]
  },
  "message": "Golf club information retrieved.",
  "http_code": 200
}

ゴルフ場のプラン一覧を取得します。ここで得られる id が予約時の golf_plan_id（必須）です。

{
  "success": true,
  "data": {
    "golf_club_id": 1,
    "lang": "ja",
    "count": 1,
    "plans": [
      {
        "id": 10,
        "source": "golf_plan",
        "name": "平日プラン",
        "day_type": "weekday",
        "price_local": 1500000,
        "price_inbound": 2000000,
        "partner_price_local": 1450000,
        "partner_price_inbound": 1850000,
        "apply_period": { "from": "2026-01-01", "to": "2026-12-31" },
        "time_ranges": [{ "from": "06:00", "to": "10:00" }],
        "minimum_players": 1,
        "summary": "平日限定のお得なプラン",
        "cancel_policy": "3日前まで無料キャンセル可能",
        "rental_club_fee": 300000,
        "rental_shoes_fee": 100000
      }
    ]
  },
  "message": "",
  "http_code": 200
}

指定日の空きティータイムスロットを取得します。ティータイムスロットを使う場合は、予約時に tee_time_slot_id を渡せます（任意）。

{
  "success": true,
  "data": {
    "golf_club_id": 1,
    "date": "2026-03-15",
    "lang": "en",
    "is_closed": false,
    "count": 1,
    "slots": [
      {
        "slot_id": 101,
        "course_id": 3,
        "course_name": "Lake Course",
        "tee_date": "2026-03-15",
        "tee_time": "07:00",
        "total_slots": 4,
        "available_slots": 2,
        "allow_join": true,
        "plan": { "id": 10, "name": "平日プラン", "price": 1500000 }
      }
    ]
  },
  "message": "",
  "http_code": 200
}

指定月の日別最低料金を取得します（カレンダー表示用）。

{
  "success": true,
  "data": {
    "golf_club_id": 1,
    "year": 2026,
    "month": 3,
    "prices": {
      "2026-03-01": 1500000,
      "2026-03-02": 1800000
    }
  },
  "message": "",
  "http_code": 200
}

予約作成前に確定金額を取得します。予約作成API（create）は同じ計算ロジックで金額を再計算するため、本見積と一致します。返却額はパートナー価格（通常価格 − パートナー割引）です。

{
  "success": true,
  "data": {
    "plan_id": 10,
    "plan_name": "平日プラン",
    "time_ranges": [{ "from": "06:00", "to": "10:00" }],
    "players": {
      "local":   { "count": 2, "regular_unit_price": 1500000, "discount_per_player": 50000, "unit_price": 1450000, "amount": 2900000 },
      "inbound": { "count": 2, "regular_unit_price": 2000000, "discount_per_player": 150000, "unit_price": 1850000, "amount": 3700000 }
    },
    "player_count": 4,
    "minimum_players": 1,
    "base_amount": 6600000,
    "rental": {
      "club_count": 2, "club_fee": 600000,
      "shoes_count": 0, "shoes_fee": 0,
      "subtotal": 600000
    },
    "currency": "VND",
    "total_amount": 7200000,
    "golf_club_id": 1
  },
  "message": "Quote calculated.",
  "http_code": 200
}

新しい予約を作成します。リクエストボディはJSON形式です。金額（total_amount）はサーバ側で golf_plan_id から再計算されるため、リクエストでは指定不要です。

POST /api/reservations/create.php HTTP/1.1
Host: govigolf.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "golf_club_id": 1,
  "golf_plan_id": 10,
  "tee_date": "2026-03-15",
  "customer_name": "田中太郎",
  "customer_email": "tanaka@example.com",
  "customer_phone": "090-1234-5678",
  "players": { "local": 2, "inbound": 2 },
  "options": { "rental_club": 2 },
  "external_ref": "EXT-2026-00500"
}

{
  "success": true,
  "data": {
    "reservation_id": 500,
    "status": 1,
    "golf_club_id": 1,
    "tee_date": "2026-03-15",
    "tee_time": "08:00",
    "player_count": 4,
    "players": { "local": 2, "inbound": 2 },
    "total_amount": 7200000,
    "source": "api_partner"
  },
  "message": "Reservation created successfully.",
  "http_code": 201
}

予約一覧を取得します（自分が作成した予約のみ）。ページネーション対応。

{
  "success": true,
  "data": {
    "reservations": [
      {
        "id": 500,
        "golf_club_id": 1,
        "golf_club_name": "Sample Golf Club",
        "customer_name": "田中太郎",
        "tee_date": "2026-03-15",
        "tee_time": "08:00",
        "player_count": 4,
        "players": { "local": 2, "inbound": 2 },
        "total_amount": 7200000,
        "status": "1.予約依頼",
        "status_code": 1,
        "source": "api_partner",
        "external_ref": "EXT-2026-00500",
        "created_at": "2026-03-01 10:00:00"
      }
    ],
    "pagination": {
      "page": 1, "per_page": 20, "total_count": 1,
      "total_pages": 1, "has_next": false, "has_prev": false
    }
  },
  "message": "",
  "http_code": 200
}

予約の詳細情報を取得します。id または external_ref のいずれかを指定します。

{
  "success": true,
  "data": {
    "reservation": {
      "id": 500,
      "golf_club_id": 1,
      "golf_club_name": "Sample Golf Club",
      "plan_id": 10,
      "plan_name": "平日プラン",
      "customer_name": "田中太郎",
      "customer_email": "tanaka@example.com",
      "customer_phone": "090-1234-5678",
      "tee_date": "2026-03-15",
      "tee_time": "08:00",
      "player_count": 4,
      "players": { "local": 2, "inbound": 2 },
      "total_amount": 7200000,
      "remark": null,
      "options": { "rental_club": 2, "rental_shoes": 0 },
      "status": "1.予約依頼",
      "status_code": 1,
      "source": "api_partner",
      "external_ref": "EXT-2026-00500",
      "created_at": "2026-03-01 10:00:00",
      "updated_at": "2026-03-01 10:00:00",
      "attendees": [
        { "name": "佐藤花子", "email": null, "phone": null }
      ]
    }
  },
  "message": "",
  "http_code": 200
}

予約内容を変更します。指定した項目のみ更新されます。players / options を変更した場合、total_amount はサーバ側で再計算されます。players は予約作成時と同じ解釈で、省略したタイプは0名として扱われます（必ず全タイプの人数を指定してください）。リアルタイム予約で合計人数が変わるとゴルフ場側の在庫も増減します。キャンセル系(status=6〜8)・完了(status=9,10)の予約は変更できません。

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

{
  "external_ref": "EXT-2026-00500",
  "players": { "local": 2, "inbound": 1 },
  "remark": "1名キャンセル"
}

{
  "success": true,
  "data": {
    "reservation_id": 500,
    "golf_club_id": 1,
    "plan_id": 10,
    "player_count": 3,
    "players": { "local": 2, "inbound": 1 },
    "total_amount": 5350000,
    "status": "1.予約依頼",
    "status_code": 1,
    "external_ref": "EXT-2026-00500",
    "updated_at": "2026-03-02 09:00:00"
  },
  "message": "Reservation updated.",
  "http_code": 200
}

予約をキャンセルします。reservation_id または external_ref を指定します。会員予約と同様にキャンセル依頼(status=6)として受け付け、担当者が確定します。リアルタイム枠の在庫は確定キャンセル時に復元されます（依頼時点では戻しません）。既にキャンセル系(status=6〜8)・完了(status=9,10)の予約はキャンセルできません。

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

{
  "external_ref": "EXT-2026-00500",
  "reason": "予定変更のため"
}

{
  "success": true,
  "data": {
    "reservation_id": 500,
    "status": "cancel_requested",
    "status_code": 6,
    "cancelled_at": "2026-03-02T10:00:00+07:00"
  },
  "message": "Reservation cancelled successfully.",
  "http_code": 200
}

Webhookの受信URLを登録します。配信範囲は自動的に「自分が作成した予約」に限定されます。

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

{
  "url": "https://your-system.com/webhook/govigo",
  "events": ["reservation.created", "reservation.status_changed", "reservation.cancelled"]
}

{
  "success": true,
  "data": {
    "subscription_id": 10,
    "url": "https://your-system.com/webhook/govigo",
    "events": ["reservation.created", "reservation.status_changed", "reservation.cancelled"],
    "secret": "a1b2c3d4e5f6..."
  },
  "message": "",
  "http_code": 201
}

登録済みのWebhook一覧を取得します（パラメータ不要）。

{
  "success": true,
  "data": {
    "count": 1,
    "subscriptions": [
      {
        "id": 10,
        "url": "https://your-system.com/webhook/govigo",
        "events": ["reservation.created", "reservation.status_changed"],
        "is_active": true,
        "created_at": "2026-03-01 10:00:00",
        "updated_at": "2026-03-01 10:00:00"
      }
    ]
  },
  "message": "",
  "http_code": 200
}

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

POST /api/webhooks/unsubscribe.php HTTP/1.1
Host: govigolf.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{ "subscription_id": 10 }

登録済みWebhookにテスト通知を送信し、受信URLの疎通と署名検証を確認します。

POST /api/webhooks/test.php HTTP/1.1
Host: govigolf.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{ "subscription_id": 10 }