API Sân golf gồm hai hệ thống với mục đích khác nhau. Tách biệt hoàn toàn với API Đặt chỗ Đối tác (dành cho hội viên).

Xác thực bằng API key. Thêm header X-API-Key vào mỗi request. Key do quản trị viên cấp; key loại integration được gắn với một sân golf theo từng key (owner_id). Sân golf đích được xác định từ key — không cần truyền golf_club_id trong request (không thể truy cập dữ liệu sân golf khác).

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

Phạm vi: integration:read cho thao tác đọc, integration:write cho thao tác ghi.

Xác thực bằng API key (header X-API-Key, key loại owner_type='golf_club'). Xử lý bởi GolfClubAuthService. Sân golf đích xác định từ key (owner_id) — không cần truyền golf_club_id làm tham số.

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

Phạm vi (theo từng tài nguyên): reservations:read/write / tee_times:read/write / notifications:read/write / settings:read/write / reports:read.

Tất cả phản hồi (ngoại trừ xuất CSV) đều được trả về theo cấu trúc JSON sau.

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

{
  "status": "error",
  "message": "Mô tả lỗi",
  "data": null
}

Đồng bộ khung giờ tee từ hệ thống bên ngoài vào GOVIGO (ngoài → GOVIGO). Tối đa 500 khung giờ mỗi request.

POST /api/integration/tee-times/sync.php HTTP/1.1
Host: vn.govigolf.com
X-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 }
  ]
}

Lấy khung giờ tee từ GOVIGO (GOVIGO → ngoài).

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

Đối chiếu bản sao GOVIGO với toàn bộ snapshot khung giờ trong khoảng thời gian từ phía sân golf (để khắc phục lệch lạc do bỏ sót webhook, v.v.). Tất cả khung giờ được upsert; các khung giờ vắng mặt trong snapshot sẽ được xử lý. Khung giờ chưa có đặt chỗ sẽ bị đóng logic (status=closed — không xóa vật lý); khung giờ đã có đặt chỗ nhưng vắng mặt trong snapshot sẽ được trả về dưới dạng conflicts (cần giải quyết thủ công) thay vì bị đóng. Khung giờ đã đóng sẽ ẩn khỏi chế độ xem tình trạng chỗ trống của khách hàng và tự động chuyển lại open khi sân golf gửi lại. Nên chạy định kỳ (ví dụ: hằng đêm).

POST /api/integration/tee-times/reconcile.php HTTP/1.1
Host: vn.govigolf.com
X-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 }
  ]
}

Nhập đặt chỗ từ hệ thống bên ngoài vào GOVIGO (ngoài → GOVIGO). external_ref là khóa idempotency; gửi trùng với cùng giá trị sẽ trả về đặt chỗ đã tồn tại và kết thúc.

POST /api/integration/reservations/receive.php HTTP/1.1
Host: vn.govigolf.com
X-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": "Nguyen Van A",
  "customer_email": "nguyenvana@example.com",
  "customer_phone": "+84-90-0000-0000",
  "player_count": 2,
  "total_amount": 3600000
}

Phản ánh thay đổi từ hệ thống ngoài vào bản sao GOVIGO (ngoài → GOVIGO). Chỉ cập nhật các trường được chỉ định. Thay đổi số người chơi sẽ điều chỉnh kho theo chênh lệch (409 nếu tăng mà không đủ chỗ). Dùng cancel.php để hủy. Thay đổi ngày/giờ không được phép với đặt chỗ liên kết khung giờ (hãy hủy và tạo lại).

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

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

Phản ánh hủy từ hệ thống ngoài vào bản sao GOVIGO (ngoài → GOVIGO). Đặt trạng thái thành đã hủy và hoàn trả kho khung giờ theo số người chơi nếu có liên kết. Idempotent (trả về thành công ngay cả khi đã hủy rồi).

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

{ "external_ref": "EXT-12345" }

Lấy dữ liệu đặt chỗ từ GOVIGO (GOVIGO → ngoài). Khoảng mặc định: hôm nay đến 30 ngày tới.

Đăng ký URL nhận thông báo sự kiện về đặt chỗ, kho, v.v.

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

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

Trả về danh sách Webhook đã đăng ký (không tham số; sân golf đích xác định từ key).

Hủy đăng ký Webhook đã đăng ký.

Gửi sự kiện kiểm thử đến đăng ký chỉ định.

Trả về danh sách đặt chỗ của sân golf. Mặc định 20 mục/trang (tối đa 100).

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

Trả về chi tiết đặt chỗ bao gồm thông tin đồng hành.

Cập nhật trạng thái đặt chỗ. status=9 được xử lý như hủy và hoàn trả kho khung giờ. Đặt chỗ đã hủy không thể chuyển sang trạng thái khác (409).

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

{ "reservation_id": 123, "status": 1, "memo": "Đã xác nhận" }

Trả về danh sách khung giờ tee cho ngày chỉ định.

Cập nhật một khung giờ tee. Trả về 400 nếu available_slots sau cập nhật nằm ngoài khoảng 0–total_slots.

Cập nhật nhiều khung giờ tee trong một request (tối đa 200). Nếu khung giờ nào không qua được xác thực thì bỏ qua và trả về chi tiết trong errors; các khung giờ khác vẫn được cập nhật.

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

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

Trả về danh sách thông báo theo thứ tự ngày tạo giảm dần.

Đánh dấu thông báo là đã đọc. Cần cung cấp notification_ids hoặc all.

Trả về số lượng thông báo chưa đọc (không tham số).

Lấy cài đặt sân golf. Nếu bỏ qua key, trả về tất cả cài đặt dưới dạng { key: value }.

Cập nhật cài đặt sân golf (UPSERT). Có thể cập nhật nhiều key cùng lúc.

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

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

Trả về tổng hợp thống kê đặt chỗ. Khoảng mặc định: tháng hiện tại.

Xuất dữ liệu đặt chỗ dưới dạng CSV. Phản hồi là text/csv (không phải JSON; file CSV UTF-8 BOM).

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