# Tài liệu tham chiếu

Phần tham chiếu mô tả mọi endpoint, sự kiện và khung dữ liệu đúng như máy chủ đang chạy. Nội dung được sinh từ mã nguồn và các bản OpenAPI công khai, nên thay đổi theo API. Nếu cần hướng dẫn từng bước, hãy bắt đầu từ phần [Hướng dẫn](https://hatang.dev/vi/docs/guides/getting-started/introduction.md).

| Tham chiếu | Nội dung | Base URL |
|---|---|---|
| [REST API](https://hatang.dev/vi/docs/reference/api.md) | Email, Hỗ trợ (chat), Thanh toán, API key và webhook: mọi endpoint kèm tham số, schema yêu cầu và phản hồi, code mẫu và bảng "Try it" để gọi thử | `https://api.hatang.dev` |
| [Chat gateway API](https://hatang.dev/vi/docs/reference/chat-gateway.md) | Những gì widget website, SDK di động và ứng dụng cho nhân viên gọi: bootstrap, hội thoại, tải tệp, thiết bị, API nhân viên | `https://chat.hatang.dev` |
| [Sự kiện webhook](https://hatang.dev/vi/docs/reference/webhooks.md) | Mọi sự kiện kèm payload | endpoint của bạn |
| [Giao thức realtime](https://hatang.dev/vi/docs/reference/realtime-protocol.md) | Websocket của khách: mọi khung, trường và giới hạn | `wss://chat.hatang.dev/ws` |
| [Mã lỗi](https://hatang.dev/vi/docs/reference/errors.md) | Mọi mã lỗi của API, giao thức realtime và SMTP relay | |
| [Giới hạn](https://hatang.dev/vi/docs/reference/limits.md) | Giới hạn tốc độ và kích thước | |

Phần tham chiếu sinh tự động được viết bằng tiếng Anh, giống tên trường và mã lỗi trong API.

## Tham chiếu SDK

Sinh từ chú thích trong mã nguồn của từng SDK, mỗi SDK một trang (chỉ có tiếng Anh):

| SDK | Tham chiếu |
|---|---|
| Node (`@hatang/sdk`) | [TypeDoc](https://hatang.dev/docs/reference/js/index.html) |
| Flutter (`hatang_chat`) | [dartdoc](https://hatang.dev/docs/reference/flutter/index.html) |
| iOS (`HatangChat`, `HatangChatCore`) | [DocC](https://hatang.dev/docs/reference/ios/documentation) |
| Android (`dev.hatang:chat`, `dev.hatang:chat-core`) | [Dokka](https://hatang.dev/docs/reference/android/index.html) |

## Quy ước chung

- **Xác thực.** Lệnh gọi REST gửi `Authorization: Bearer ht_...`. Xem [Xác thực](https://hatang.dev/vi/docs/guides/getting-started/authentication.md) để biết về scope và key thử nghiệm.
- **Định dạng.** JSON cả chiều gửi và nhận, UTF-8. Thời gian theo ISO 8601, múi giờ UTC; số tiền (đồng) là số nguyên.
- **Lỗi.** Mọi lỗi có dạng `{ "statusCode", "name", "message" }`; xử lý theo `name`.
- **Phân trang.** Endpoint dạng danh sách nhận `limit` và `after`, trả về `has_more` và `next_cursor`. Xem [Phân trang](https://hatang.dev/vi/docs/guides/getting-started/pagination.md).
- **Idempotency.** `POST /emails`, `POST /payments` và gửi tin nhắn chat nhận header `Idempotency-Key`. Xem [Idempotency](https://hatang.dev/vi/docs/guides/getting-started/idempotency.md).

## Bản đặc tả cho máy đọc

- REST API: [`openapi.json`](https://api.hatang.dev/openapi.json) (OpenAPI 3.1, có cả phần `webhooks`)
- Chat gateway: [`openapi.json`](https://chat.hatang.dev/openapi.json)
- Giao thức realtime: JSON Schema cho [khung của khách](https://hatang.dev/docs/schema/chat-protocol-v1/visitor-frames.json), [khung của server](https://hatang.dev/docs/schema/chat-protocol-v1/server-frames.json), [HTTP](https://hatang.dev/docs/schema/chat-protocol-v1/http.json) và [hằng số giao thức](https://hatang.dev/docs/schema/chat-protocol-v1/protocol.json)

- Toàn bộ tài liệu cho AI agent và công cụ LLM: [`llms.txt`](https://hatang.dev/docs/llms.txt) (mục lục), [`llms-full.txt`](https://hatang.dev/docs/llms-full.txt) (mọi trang trong một file), và bản Markdown của từng trang ở chính địa chỉ của trang thêm `.md`, ví dụ [`/vi/docs/reference/overview.md`](https://hatang.dev/docs/reference/overview.md)

Dùng được với mọi công cụ OpenAPI (Postman, Insomnia, trình sinh code) hoặc nhập vào bộ kiểm thử của bạn.

Source: https://hatang.dev/vi/docs/reference/overview