# OpenAPI

> Đặc tả OpenAPI 3.1 của API phiên bản 2, cách đọc, xác thực và xử lý lỗi.

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](/openapi.json).

## Đọc đặc tả

- 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`.

## 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

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

```json
{
  "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

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

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.
