API GOVIGO dùng xác thực bằng API key. Hãy thêm header X-API-Key vào mọi yêu cầu.

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

Các scope khả dụng:

Tất cả phản hồi API được trả về theo định dạng chung sau.

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

Có thể tham chiếu đặt chỗ bằng hai khóa.

Kiểm tra tính hợp lệ của API key, chủ sở hữu, scope được cấp và giới hạn tần suất. Dùng để kiểm tra kết nối ban đầu (không cần scope).

{
  "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
}

Lấy thông tin chi tiết sân golf. Bỏ qua id để trả về danh sách.

{
  "success": true,
  "data": {
    "count": 1,
    "golf_clubs": [
      {
        "id": 1,
        "name": "Sample Golf Club",
        "area": "Hanoi",
        "country": 0,
        "address": "123 Golf Street",
        "google_map": "https://maps.google.com/...",
        "course_info": "18 lỗ, par 72",
        "cancel_policy": "Miễn phí đến 3 ngày trước",
        "rental": {
          "club_available": true,
          "club_fee": 300000,
          "shoes_available": false,
          "shoes_fee": null
        },
        "options": {
          "rental_cart":      { "available": true,  "fee": 500000 },
          "rental_umbrella":  { "available": false, "fee": null },
          "caddy":            { "available": true,  "fee": 400000 },
          "caddy_designate":  { "available": false, "fee": null },
          "caddybag_storage": { "available": false, "fee": null },
          "sent_caddybag":    { "available": false, "fee": null },
          "accompany":        { "available": false, "fee": null },
          "pickup":           { "available": false, "fee": null }
        }
      }
    ]
  },
  "message": "",
  "http_code": 200
}

Lấy danh sách gói của sân golf. id lấy ở đây chính là golf_plan_id (bắt buộc) khi đặt chỗ.

{
  "success": true,
  "data": {
    "golf_club_id": 1,
    "count": 1,
    "plans": [
      {
        "id": 10,
        "source": "golf_plan",
        "name": "Gói ngày thường",
        "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_range": "06:00-10:00",
        "minimum_players": 1,
        "summary": "Gói ưu đãi chỉ ngày thường",
        "cancel_policy": "Hủy miễn phí đến 3 ngày trước",
        "rental_club_fee": 300000,
        "rental_shoes_fee": 100000
      }
    ]
  },
  "message": "",
  "http_code": 200
}

Lấy các khung giờ tee trống cho ngày chỉ định. Nếu dùng khung giờ tee, truyền tee_time_slot_id khi đặt (tùy chọn).

{
  "success": true,
  "data": {
    "golf_club_id": 1,
    "date": "2026-03-15",
    "is_closed": false,
    "count": 1,
    "slots": [
      {
        "slot_id": 101,
        "tee_date": "2026-03-15",
        "tee_time": "07:00",
        "total_slots": 4,
        "available_slots": 2,
        "allow_join": true,
        "plan": { "id": 10, "name": "Gói ngày thường", "price": 1500000 }
      }
    ]
  },
  "message": "",
  "http_code": 200
}

Lấy giá tối thiểu theo ngày trong tháng chỉ định (để hiển thị lịch).

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

Lấy số tiền cuối cùng trước khi tạo đặt chỗ. API create tính lại bằng cùng logic nên khớp với báo giá này. Số tiền trả về là giá đối tác (giá thường trừ chiết khấu đối tác).

{
  "success": true,
  "data": {
    "plan_id": 10,
    "plan_name": "Gói ngày thường",
    "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
}

Tạo đặt chỗ mới. Thân yêu cầu là JSON. Số tiền (total_amount) được tính lại ở máy chủ từ golf_plan_id, nên không cần chỉ định trong yêu cầu.

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

{
  "golf_club_id": 1,
  "golf_plan_id": 10,
  "tee_date": "2026-03-15",
  "customer_name": "Taro Tanaka",
  "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
}

Lấy danh sách đặt chỗ (chỉ đặt chỗ do bạn tạo). Hỗ trợ phân trang.

{
  "success": true,
  "data": {
    "reservations": [
      {
        "id": 500,
        "golf_club_id": 1,
        "golf_club_name": "Sample Golf Club",
        "customer_name": "Taro Tanaka",
        "tee_date": "2026-03-15",
        "tee_time": "08:00",
        "player_count": 4,
        "players": { "local": 2, "inbound": 2 },
        "total_amount": 7200000,
        "status": "1.đã yêu cầu",
        "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
}

Lấy chi tiết đặt chỗ. Chỉ định id hoặc external_ref.

{
  "success": true,
  "data": {
    "reservation": {
      "id": 500,
      "golf_club_id": 1,
      "golf_club_name": "Sample Golf Club",
      "plan_id": 10,
      "plan_name": "Gói ngày thường",
      "customer_name": "Taro Tanaka",
      "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.đã yêu cầu",
      "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": "Hanako Sato", "email": null, "phone": null }
      ]
    }
  },
  "message": "",
  "http_code": 200
}

Cập nhật đặt chỗ. Chỉ cập nhật các trường được chỉ định. Nếu players / options thay đổi, total_amount được tính lại ở máy chủ. players được hiểu giống như khi tạo đặt chỗ: các loại bị bỏ qua được coi là 0 người (luôn chỉ định số người cho tất cả các loại). Với đặt real-time, thay đổi tổng số người cũng điều chỉnh tồn kho phía sân golf. Đặt chỗ đã hủy (status=6-8) / hoàn tất (status=9,10) không thể sửa.

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

{
  "external_ref": "EXT-2026-00500",
  "players": { "local": 2, "inbound": 1 },
  "remark": "Hủy 1 người"
}

{
  "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.đã yêu cầu",
    "status_code": 1,
    "external_ref": "EXT-2026-00500",
    "updated_at": "2026-03-02 09:00:00"
  },
  "message": "Reservation updated.",
  "http_code": 200
}

Hủy đặt chỗ. Chỉ định reservation_id hoặc external_ref. Giống đặt chỗ hội viên, được tiếp nhận như yêu cầu hủy (status=6) và nhân viên xác nhận. Tồn kho khung real-time được khôi phục khi hủy được xác nhận (không khôi phục ở thời điểm yêu cầu). Đặt chỗ đang hủy (status=6-8) / hoàn tất (status=9,10) không thể hủy.

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

{
  "external_ref": "EXT-2026-00500",
  "reason": "Do thay đổi lịch"
}

{
  "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
}

Đăng ký URL nhận Webhook. Phạm vi gửi tự động giới hạn ở các đặt chỗ do bạn tạo.

POST /api/webhooks/subscribe.php HTTP/1.1
Host: vn.govigolf.comX-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
}

Lấy danh sách Webhook đã đăng ký (không cần tham số).

{
  "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
}

Hủy đăng ký một Webhook đã đăng ký.

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

{ "subscription_id": 10 }

Gửi thông báo thử đến Webhook đã đăng ký để kiểm tra kết nối URL và xác minh chữ ký.

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

{ "subscription_id": 10 }