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.
Đọc đặc tả
Phần tiêu đề “Đọc đặc tả”- Mọi đường dẫn tính từ gốc
/apitrê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.
Xác thực
Phần tiêu đề “Xác thực”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.
Idempotency
Phần tiêu đề “Idempotency”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.
Phiên bản 1
Phần tiêu đề “Phiên bản 1”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.
dac de doc duong don dong dung dinh da