Bỏ qua để đến nội dung

OpenAPI

Xem markdown

API phiên bản 2 có đặc tả OpenAPI 3.1, sinh từ cùng schema zod mà máy chủ dùng để kiểm tra dữ liệu. Tải về: openapi.json.

  • Mọi đường dẫn tính từ gốc /api trên host API của môi trường bạn dùng; đặc tả khai báo máy chủ là /api.
  • Dữ liệu trả về là JSON trần, không bọc { success, data } như phiên bản 1.
  • Số tiền là số nguyên, đơn vị đồng. Thời gian theo ISO 8601.
  • Trạng thái lịch hẹn là chữ thường: held, pending, confirmed, in_progress, completed, cancelled, no_show, expired.

Gọi API bằng Authorization: Bearer <JWT>. JWT do dịch vụ xác thực cấp, sống năm phút, mang đúng sáu claim và không chứa thông tin người dùng. Các đường dẫn /v2/salon/* xác định salon từ claim tổ chức.

Lỗi trả về application/problem+json theo RFC 9457:

{
"type": "about:blank",
"title": "Giờ này đã có người đặt",
"status": 409,
"code": "BOOKING_SLOT_TAKEN"
}

Xử lý theo code, không theo chữ trong title. Ví dụ mã: BOOKING_SLOT_TAKEN, BOOKING_HOLD_EXPIRED, BOOKING_INVALID_TRANSITION, BOOKING_CANCEL_REASON_REQUIRED.

Tạo lịch (POST /v2/bookings) nhận header Idempotency-Key. Gửi lại cùng khoá trả lại đúng kết quả cũ, kể cả mã thanh toán cọc, nên an toàn khi mạng chập chờn.

API phiên bản 1 vẫn chạy cho ứng dụng di động đã phát hành. Dự án mới nên dùng phiên bản 2.