# Shop · Hướng dẫn cộng tác viên và API mua hàng

- Trang hỗ trợ / bảng giá: https://your-shop.example/ctv
- Tài liệu trên web: https://your-shop.example/shop-api
- Đặc tả OpenAPI 3.0: https://your-shop.example/shop-api/openapi.json
- Base URL: `https://your-shop.example/api/shop/v1`
- Bot: https://t.me/your_shop_bot
- Support: https://t.me/your_support_username

Đây là API mua sản phẩm tại Shop, không phải endpoint gọi model AI. Dùng ID sản phẩm trong danh mục hiện tại, không hardcode ID từ ví dụ. API hiện dùng V1, đặc tả 1.5.0. Những endpoint chưa có: webhook giao hàng cho shop đại lý, hủy/hoàn đơn tự động. Đơn cần hỗ trợ/hoàn tiền do shop đối soát.

## 1. Tài khoản, giá và ví

Mở bot, gửi `/api` và tạo key. `scu_live_…` dành cho khách thường, `scd_live_…` dành cho đại lý được shop cấp quyền. Liên hệ support để nâng quyền; không tự sửa tiền tố key. Mỗi tài khoản có một key đang hoạt động. Tạo lại key sẽ thu hồi key cũ nhưng không xóa ví hay lịch sử đơn.

Gửi key trong `Authorization: Bearer YOUR_SHOP_SHOP_KEY` hoặc `X-API-Key`. Không dùng cả hai với giá trị khác nhau. Không để key trong URL, log, source công khai, ứng dụng khách hàng hoặc gửi cho khách của bạn. Trang /ctv chính thức có thể kết nối key để xem giá: key chỉ ở bộ nhớ tab, mất khi ngắt kết nối/đóng trang, không lưu localStorage/sessionStorage/cookie. Không tự tạo bản clone lưu key người dùng.

Giá chuẩn để mua là `price_vnd` API trả cho chính tài khoản, không phải tự lấy giá lẻ trừ phần trăm. `retail_price_vnd` là giá bán lẻ hiện tại tại Shop để tham khảo. Nếu có mức giảm riêng, hệ thống chọn giá có lợi hơn giữa mức chung và mức riêng nhưng vẫn xét sàn vốn/lãi và làm tròn hiện có; không cộng dồn hai phần trăm. Khi sale hoặc giá dưới sàn, SKU có thể tạm chưa nhận đơn đại lý. Đổi giá không tính lại đơn đã tạo. Mọi số tiền là số nguyên VND.

Ví dùng chung bot và API. Nạp qua `/nap` hoặc `/napapi 100000` trong bot, hoặc tạo QR bằng API. QR không đồng nghĩa đã cộng tiền: chuyển đúng tiền/nội dung trước `expires_at`, chờ ngân hàng xác nhận, kiểm tra `/me`. Không chuyển tiếp vào QR đã hết hạn. Nạp API tối thiểu 10.000đ, tối đa 1 tỷ/lượt, tối đa 5 yêu cầu còn hạn.

Response nạp ví có `payment_ref` là mã đối soát và `transfer_content` là nội dung chuyển khoản đầy đủ (lời chúc không dấu + mã, tối đa 48 ký tự). Hiển thị/sao chép `transfer_content` hoặc dùng `qr_url`; không tự nối thêm chữ khiến nội dung vượt giới hạn. Cùng yêu cầu nạp giữ nguyên nội dung khi thử lại. QR cũ chỉ có mã vẫn được đối soát.

## 2. Toàn bộ endpoint

Các path bên dưới nằm sau base URL. Tất cả yêu cầu key.

| Method | Path | Công dụng |
|---|---|---|
| GET | /me | Telegram ID, quyền, số dư, mức giảm riêng nếu có |
| GET | /products | Danh mục được bán qua API, giá theo tài khoản |
| GET | /products/{id} | Giá/tồn và đầu vào của một SKU; kiểm tra snapshot nguồn khi cần |
| GET | /catalog/stock | Giá/tồn gọn toàn danh mục; có ETag |
| POST | /orders | Tạo đơn, trừ ví một lần; cần Idempotency-Key |
| GET | /orders | Danh sách đơn của tài khoản; không chứa tài khoản/mật khẩu đã giao |
| GET | /orders/{id} | Tiến độ, mô tả theo lúc mua, items đã giao |
| GET | /wallet/ledger | Sổ ví của tài khoản |
| POST | /wallet/topups | Tạo QR nạp ví; cần Idempotency-Key |
| GET | /wallet/topups/{id} | Trạng thái QR nạp ví |
| POST | /warranty-claims | Gửi yêu cầu cho SKU thuộc đơn đã mua |
| GET | /warranty-claims | Danh sách phiếu bảo hành của tài khoản |
| GET | /warranty-claims/{id} | Theo dõi phiếu bảo hành |

Các endpoint danh sách nhận `?limit=50&before=ID`; limit 1–100. Lấy `data.next_cursor` làm `before` tiếp theo đến khi null. `/catalog/stock` trả toàn danh mục gọn, không dùng before. Không chỉ lấy trang đầu nếu shop có nhiều hơn 100 SKU.

Thành công: `{"success":true,"data":{...},"request_id":"..."}`. Lỗi: `{"success":false,"error":{"code":"...","message":"..."},"request_id":"..."}`. Lưu `X-Request-Id` hoặc `request_id` khi cần hỗ trợ. Không log toàn bộ response chi tiết đơn vì có thông tin hàng đã mua.

## 3. Đồng bộ giá và tồn

Đọc `/products` khi bắt đầu hoặc khi cần cập nhật tên/mô tả. Dùng `/catalog/stock` khoảng 5 giây/lần khi hệ thống đang nhận đơn, lưu header ETag và gửi `If-None-Match` ở lần sau. HTTP 304 không có body, giữ dữ liệu trước. Giá trong stock feed cũng là giá theo tài khoản. Không chia sẻ cache giá của tài khoản A cho B.

`stock` là số lượng hiện có thể nhận, đã xét nguồn, ví nguồn và các khoản giữ hàng/vốn. Các SKU dùng chung ví không có nghĩa bạn mua hết được tổng stock cộng lại. Tồn không phải cam kết giữ hàng. Tồn upstream có tuổi snapshot; poll 5 giây không đảm bảo upstream luôn mới mỗi 5 giây. `stock_updated_at` null với hàng kho nội bộ. `stock_status` có `available`, `sold_out`, `updating`; updating có thể là nguồn/giá đang cập nhật. Luôn xác nhận giá/tồn trước khi báo khách và dùng `max_total_vnd` khi mua.

Giới hạn hiện tại: 120 request/phút/key, 240/phút/IP trên một tiến trình. Tôn trọng `Retry-After` khi 429; thêm backoff/jitter, không chạy nhiều vòng polling trùng cùng đơn. Trang CTV làm mới khoảng 15 giây để dành ngân sách request cho hệ thống bán hàng của bạn.

Giá của các gói theo nguồn được cập nhật theo vốn cộng mức lãi của Shop, có thể tăng hoặc giảm. Giảm đại lý vẫn chịu sàn lãi của từng gói; không đảm bảo mức phần trăm danh nghĩa áp dụng đủ cho mọi SKU. Giá/điều kiện của đơn đã tạo được giữ nguyên. Gửi `max_total_vnd` để tránh mua vượt giá dự kiến; nếu nhận lỗi giá, tải lại SKU và xác nhận với khách trước khi tạo yêu cầu mới. Không tự đặt lại đơn đang xử lý.

## 4. Đặt hàng và theo dõi

Trước POST: lưu một `Idempotency-Key` duy nhất cùng payload vào đơn tại hệ thống của bạn. Key dài 8–128 ký tự chữ, số hoặc `_ . : -`. Giữ nguyên key và payload khi timeout, 5xx hoặc mất kết nối. Không tạo key mới để thử lại cùng giao dịch. Gửi body JSON, tối đa 16 KB.

```http
POST /api/shop/v1/orders?wait_seconds=15
Authorization: Bearer YOUR_SHOP_SHOP_KEY
Idempotency-Key: your-persisted-order-unique-id
Content-Type: application/json

{"product_id":"CURRENT_PRODUCT_ID","quantity":1,"max_total_vnd":50000}
```

`max_total_vnd` là giới hạn tổng tiền cho toàn đơn, không phải đơn giá. Số lượng hàng giao sẵn 1–100; dịch vụ theo email/tài khoản chỉ quantity=1. Hệ thống giao nguyên đơn, thiếu hàng/tiền thì từ chối trước khi trừ ví. 201 là tạo lần đầu; 200 với `replayed=true` là lấy lại cùng đơn. Không kết luận đã giao chỉ vì HTTP 200/201.

Ví dụ đơn đang xử lý:

```json
{"success":true,"data":{"id":"ORDER_ID","payment_ref":"DH...","status":"paid","fulfillment_status":"processing","quantity":1,"total_vnd":50000,"poll_after_seconds":2,"items":[]},"request_id":"..."}
```

Chỉ giao lại cho khách khi `status=delivered`, `fulfillment_status=delivered` và `items.length` đủ quantity. Mỗi item gồm `sku: "SC-..."` và `account` là dữ liệu bàn giao nguyên văn của sản phẩm. Lưu SKU cùng từng món để bảo hành đúng món; không tự bóc mọi payload bằng dấu `|` vì định dạng phụ thuộc gói.

`GET /orders/{id}?wait_seconds=15` chờ tối đa 15 giây khi đang processing, rồi trả trạng thái hiện tại. `POST /orders?wait_seconds=15` cũng hỗ trợ chờ. Không mặc định mạng trả trong đúng 15 giây: còn có xác thực, làm mới snapshot và đường truyền; đặt HTTP timeout đủ dài, ví dụ 60 giây. Nếu needs_support thì dừng mua lại, giữ đơn và liên hệ support. Tôn trọng poll_after_seconds và rate limit. Đơn kho nội bộ có thể giao ngay; nguồn API cần mua/nhận hàng; dịch vụ có thể xử lý lâu hoặc cần shop can thiệp. Không hứa mọi gói giao tức thì.

### Ví dụ Python (requests)

Thay ID/giới hạn tiền trước khi chạy. Code có lệnh mua thật. Biến `SHOP_ORDER_REQUEST_ID` phải được lưu cùng đơn trước lần gọi đầu, giữ nguyên khi chạy lại.

```python
import os, time
import requests

base = "https://your-shop.example/api/shop/v1"
headers = {"Authorization": "Bearer " + os.environ["SHOP_SHOP_KEY"]}
request_key = os.environ["SHOP_ORDER_REQUEST_ID"]
product_id = os.environ["SHOP_PRODUCT_ID"]
max_total = int(os.environ["SHOP_MAX_TOTAL_VND"])
payload = {"product_id": product_id, "quantity": 1, "max_total_vnd": max_total}

# Luu request_key + payload trong DB cua ban truoc POST.
response = requests.post(base + "/orders?wait_seconds=15", headers={
    **headers, "Idempotency-Key": request_key
}, json=payload, timeout=60)
# Timeout/5xx: retry cung request_key va payload, co backoff.
response.raise_for_status()
order = response.json()["data"]
deadline = time.monotonic() + 300
while order["fulfillment_status"] == "processing" and time.monotonic() < deadline:
    time.sleep(max(2, order.get("poll_after_seconds", 5)))
    response = requests.get(base + "/orders/" + order["id"] + "?wait_seconds=15",
                            headers=headers, timeout=60)
    response.raise_for_status()
    order = response.json()["data"]
if order["status"] == "delivered" and len(order["items"]) == order["quantity"]:
    # Luu hang trong kho ma hoa o server, giao lai cho khach.
    # Khong print/log order['items'].
    print("Delivered", order["id"], "items:", len(order["items"]))
elif order["fulfillment_status"] == "needs_support":
    print("Contact Shop support with order ID", order["id"])
else:
    # Qua moc cho nay van theo doi cung don sau do; khong mua lai.
    print("Continue tracking the same order", order["id"])
```

## 5. Dịch vụ cần đầu vào

Đọc `delivery_mode`, `requires_customer_input`, `input_fields`, `max_quantity`, `delivery_hint` của SKU trước khi xây form.

| delivery_mode | Cách giao | Đầu vào |
|---|---|---|
| stock | Tài khoản/mã từ kho Shop | Không gửi email, mật khẩu của khách |
| source_api | Đặt hàng nguồn sau khi nhận đơn | Không gửi email, mật khẩu của khách |
| email_service | Slot/mời vào gói trên email | customer_email, quantity=1 |
| account_upgrade | Nâng tài khoản khách theo dịch vụ | customer_account, quantity=1 |

Email service: thêm `"customer_email":"buyer@example.com"`, không gửi password/2FA. Account upgrade: thêm `"customer_account":{"email":"ten@gmail.com","password":"YOUR_GMAIL_PASSWORD","twofa":"JBSWY3DPEHPK3PXP","consent":true}`. Đây là dữ liệu minh họa định dạng, không dùng để đặt đơn thật. Đọc `input_schema` của SKU: Gmail đúng dạng, mật khẩu hiện tại 8–512 ký tự và khóa bí mật Base32 16–128 ký tự A–Z/2–7, không phải OTP 6 số. Hợp lệ định dạng không chứng minh mật khẩu đăng nhập thực sự đúng.

Phải được khách đồng ý trước khi gửi, chỉ truyền giữa server qua HTTPS, không log. Shop mã hóa thông tin khi lưu; response không trả lại các trường này. Không gửi chúng cho stock/source_api. Thiếu/sai input hoặc thiếu consent bị từ chối trước khi trừ ví.

Email service/nâng cấp trả biên nhận hoàn tất theo đúng loại hàng, không nhất thiết là tài khoản/mật khẩu mới. Một số nguồn key cần shop lấy thủ công; needs_support chưa phải đã giao, không có nghĩa cần đặt lại.

## 6. Bảo hành và hỗ trợ

Chính sách theo từng sản phẩm, xem `warranty`, description và delivery_guide snapshot của đơn đã mua. Không tự áp một hạn bảo hành cho toàn shop. POST `/warranty-claims` với `{"order_id":"ORDER_ID","sku":"SC-STOCK_ID","failure_stage":"first_login","description":"Mô tả lỗi cụ thể và thời điểm phát sinh, cách tái hiện"}`. Description 10–1000 ký tự. SKU phải thuộc đơn/tài khoản. Phiếu đang mở được trả lại thay vì tạo trùng.

Đơn mới có `warranty.requires_failure_stage=true` phải gửi đúng loại lỗi nằm trong `warranty.failure_stages`: credentials, first_login, wrong_product, activation, plan_loss hoặc after_use tùy gói. Không tự gán after_use cho hàng KBH/Muse: đã dùng được rồi mới khóa/xác minh là ngoài bảo hành ban đầu. Gói Full vẫn giữ bảo hành dài đã chốt. Tạo phiếu không tự động được đổi/hoàn; shop đối chiếu bằng chứng.

`warranty_status.initial_deadline` là giờ hết hạn đối chiếu sai thông tin/giao sai. `deadline` là giờ hết bảo hành của chính sách đó; có thể bằng hạn ban đầu hoặc hạn dài. Tính từ mốc trong đơn, không bắt đầu lại khi khách đăng nhập hay đại lý gửi tiếp. API giao hàng bắt đầu đồng hồ khi đủ hàng và chuyển delivered; hãy giao ngay cho khách cuối. Đơn cũ không có policy snapshot giữ chính sách cũ, không bị ép mốc mới.

Với API/key có hạn bắt đầu từ redeem hoặc hạn ngẫu nhiên, `requires_entitlement_verification=true` yêu cầu đối chiếu trang hạn/quota thật. `deadline=null` không có nghĩa bảo hành vô thời hạn. Hết quota, hết hạn, sai endpoint/model không tự thành lỗi giao hàng. Giữ giờ thử, ảnh lỗi đã che key và request ID.

Theo dõi GET danh sách/chi tiết: `open`, `with_supplier`, `resolved`, `rejected`. Tạo phiếu không tự xác nhận đủ điều kiện, không tự hoàn tiền. Khi nhắn support: payment_ref (ORD cho đơn mới, DH cho đơn cũ) hoặc order ID, SKU, thời gian nhận và lỗi, request_id nếu lỗi API; không gửi API key, password hoặc 2FA vào nhóm công khai.

## 7. Lỗi thường gặp

| HTTP / code | Cách xử lý |
|---|---|
| 400 | Kiểm tra JSON, ID, quantity, input dịch vụ, Idempotency-Key, wait_seconds (0–15) |
| 401 INVALID_API_KEY | Key sai/đã thu hồi; lấy key hiện tại, không tự đổi tiền tố |
| 403 ACCOUNT_DISABLED | Tài khoản/quyền API bị tắt hoặc bị chặn; liên hệ support |
| 402 | Ví thiếu tiền; kiểm tra /me, nạp rồi thử lại |
| 404 | SKU không bán qua API hoặc dữ liệu không thuộc tài khoản |
| 409 OUT_OF_STOCK | Tồn hiện không đủ; kiểm tra giá/tồn mới |
| 409 PRICE_UNAVAILABLE | Giá/sàn chưa sẵn sàng; ví chưa bị trừ |
| 409 PRICE_LIMIT_EXCEEDED | Giá vượt max_total_vnd; lấy chấp thuận mới trước khi đổi ngân sách |
| 409 IDEMPOTENCY_CONFLICT | Key đã dùng với payload khác; tìm lại payload gốc, không sửa đơn đã nhận |
| 409 FAILURE_STAGE_REQUIRED / OUTSIDE_WARRANTY_SCOPE | Chọn đúng loại lỗi được phép, không khai khác thực tế để vượt phạm vi |
| 409 WARRANTY_WINDOW_EXPIRED / WARRANTY_EXPIRED / INITIAL_WINDOW_EXPIRED | Hạn tương ứng đã hết; xem snapshot của đơn, không lấy lần login để tính lại |
| 413 | Body quá 16 KB |
| 429 | Chờ Retry-After, giảm polling, backoff |
| 500 / timeout | Kết quả có thể chưa rõ; giữ nguyên key/payload để tra hoặc retry, không mua bằng mã mới |

Request lỗi trước khi tạo đơn không giữ Idempotency-Key. Khi điều kiện thay đổi có thể thử lại cùng nội dung. Đơn đã nhận luôn giữ giá/input theo snapshot. Không thấy hàng trong response đang xử lý không phải lý do tạo thêm đơn.

Nguồn được đồng bộ nền khoảng 15 giây khi kết nối bình thường; việc đọc stock mỗi 5 giây không buộc nhà cung cấp đổi tồn ngay. Xem stock_updated_at, không hứa snapshot luôn là tồn thời gian thực. Khi có đủ hàng thật, worker giao ngay thay vì đợi vòng quét giao định kỳ; phần thời gian chờ nguồn hoặc nhân viên cấp key vẫn có thể dài hơn. Hiện chưa có cam kết SLA vài giây cho mọi sản phẩm.


## Dịch vụ nhận mã Muse (`code_service`)

Đọc `input_schema` của SKU trước khi hiện form. Với dịch vụ buff Muse, gửi `customer_code` gồm 4–32 chữ/số, không gửi email/mật khẩu. Một đơn `quantity=1` tương ứng **1 lượt vào 1 mã**, không phải mua tài khoản mới. Không tự suy ra tổng token thực nhận từ tên dịch vụ; kiểm tra điều kiện hiện tại của sản phẩm.

```json
{"product_id":"CURRENT_MUSE_SERVICE_ID","quantity":1,"customer_code":"AB12CD","max_total_vnd":15000}
```

Chỉ gửi `customer_code` cho SKU yêu cầu trường đó. Dịch vụ email dùng `customer_email`; nâng tài khoản dùng `customer_account`. Sai dạng đầu vào bị từ chối trước khi trừ ví. Nguồn có thể tiếp nhận rồi xử lý sau: tiếp tục polling cùng đơn, không mua lại. `delivered` của dịch vụ nghĩa nguồn đã xác nhận xử lý; khách vẫn cần kiểm tra kết quả trên tài khoản/email của mình.
