SHOP / SHOP API / V1

Tích hợp mua hàng tại Shop.

Danh mục, giá theo quyền, ví trả trước và giao hàng qua API. Dùng cho tool cá nhân hoặc hệ thống bán lại của đại lý.

Bảng giá & hỗ trợ CTV Hướng dẫn tích hợp đầy đủ Tải đặc tả OpenAPI 3.0 JSON ↗

Bắt đầu trong bot

  1. Mở @your_shop_bot, gửi /api và bấm tạo API key. Tạo lại sẽ thu hồi key cũ; lưu key được hiển thị một lần.
  2. Key scu_live_… dành cho khách thường; scd_live_… dành cho đại lý được shop cấp quyền. Mỗi khách có một ví và một key hoạt động; tạo lại key giữ nguyên ví/lịch sử.
  3. Nạp ví bằng /napapi 100000 trong bot hoặc POST /wallet/topups với {"amount_vnd":100000}. Chuyển đúng số tiền/nội dung trong 30 phút. Ví tự cộng sau khi ngân hàng xác nhận; dùng GET /me để kiểm tra.
  4. Gọi danh mục, chọn ID và giá rồi mới mua. API này bán hàng số; không phải key gọi model AI.
BASE URL
https://digital.letridev.cloud/api/shop/v1
XÁC THỰC
Authorization: Bearer YOUR_SHOP_SHOP_KEY

Có thể dùng header X-API-Key thay cho Bearer. Không đặt key trong URL, frontend, log hoặc source công khai. API chỉ nhận HTTPS khi dùng trên Shop.

Giá khách thường và giá đại lý

Quyền do shop cấp, không thể đổi bằng body request hoặc sửa tiền tố key. Khách thường nhận giá thường. Đại lý nhận giá theo phần trăm giá lẻ hiện tại hoặc giá cố định được shop đặt; chưa đặt thì theo giá thường. Giá theo phần trăm làm tròn lên 100đ và có sàn, nên mức giảm thực tế có thể thấp hơn khi đang sale. Một số gói sale sâu hoặc đang cập nhật giá có thể tạm ngừng nhận đơn đại lý. Đơn đã tạo giữ giá lúc đặt.

price_vnd trong danh mục là giá thực áp dụng cho bạn. stock là hàng đang sẵn bán, không phải cam kết giữ hàng. Giá và kho có thể đổi; gửi max_total_vnd khi mua để chặn vượt ngân sách. Mọi số tiền là số nguyên VND. Không cộng dồn ưu đãi giới thiệu vào đơn API.

Hàng lấy từ nguồn API và dịch vụ

Đại lý mua được hàng Shop lấy trực tiếp từ API nguồn, không cần shop nhập sẵn vào kho. Đọc delivery_mode trong mỗi sản phẩm: stock giao từ kho; source_api tự lấy hàng nguồn; email_service nhận email; code_service nhận mã Muse qua customer_code (1 lượt/1 mã); account_upgrade nhận thông tin tài khoản để nâng cấp.

Đơn nguồn trả status=paid, fulfillment_status=processing, items=[] khi đang xử lý. Đây là đơn đã nhận tiền, không phải lỗi “chỉ cấp từ kho thủ công”. Chỉ giao lại cho khách khi status=delivered và đủ items. Gọi POST /orders?wait_seconds=15 để chờ ngắn, hoặc tra cùng mã bằng GET /orders/{id}?wait_seconds=15. Không đổi Idempotency-Key để mua lại. needs_support nghĩa cần shop đối soát/cấp key; một số nguồn như gói key xử lý thủ công không thể hứa giao tức thì.

Dịch vụ email gửi {"product_id":"ID","quantity":1,"customer_email":"buyer@example.com","max_total_vnd":100000}. Dịch vụ nâng cấp tài khoản dùng customer_account theo input_fields và đặc tả OpenAPI; mật khẩu/2FA chỉ gửi server qua HTTPS, không log. Dịch vụ được giao theo tiến độ nguồn/shop; API không biến thời gian xử lý dịch vụ thành tức thì.

Cập nhật tồn và giá

Dùng GET /catalog/stock khoảng 5 giây/lần cho nhiều SKU, giữ ETag và gửi lại bằng If-None-Match; HTTP 304 nghĩa không đổi. stock là số hiện có thể nhận, đã tính tiền nguồn và đơn giữ vốn. Không cộng sức mua các SKU cùng ví. stock_status=updating là đang cập nhật, khác sold_out. Nhìn stock_updated_at để biết tuổi snapshot. Kiểm tra GET /products/{id} trước mua khi cần giá/tồn mới; gửi max_total_vnd để chặn giá vượt dự kiến.

Ưu đãi riêng theo đại lý

Giá chung theo SKU vẫn được giữ. Nếu shop cấp mức giảm riêng, hệ thống so giá theo mức riêng với giá chung, chọn giá có lợi hơn và giữ sàn vốn + lãi tối thiểu. Hai phần trăm không cộng dồn. Giá trả trong danh mục đã là giá cuối dành cho chính tài khoản của bạn; không tự tính giảm lần nữa. Đổi ưu đãi không đổi key và không tính lại đơn đã mua.

Từ kết nối đến đơn đầu tiên

  1. Nạp ví trong Shop Bot, tạo key API riêng. Giữ key ở server; không đặt trong JavaScript công khai.
  2. Gọi GET /me để kiểm tra số dư/quyền. GET /products để lấy giá dành riêng cho bạn; không tính giảm lần nữa. Giá theo nguồn có thể tăng/giảm; ưu đãi vẫn chịu sàn của từng gói. Giá đơn đã tạo được giữ nguyên.
  3. Đọc delivery_mode, input_schema và warranty trước khi hiển thị hàng cho khách. Không biến hàng xử lý thủ công thành giao ngay. code_service nhận customer_code theo input_schema; Muse chỉ quantity=1, một lượt cho một mã. Không gửi email/mật khẩu vào trường mã.
  4. Khi khách thanh toán cho bạn, tạo một Idempotency-Key cho đơn đó. Gửi POST /orders?wait_seconds=15 kèm max_total_vnd.
  5. Nếu processing, tra cùng order_id theo poll_after_seconds. Nếu timeout/mất mạng, thử lại cùng body và cùng Idempotency-Key; không tạo key mới để mua lại.
  6. Chỉ giao khi delivered và đủ items. Lưu sku từng tài khoản để báo lỗi đúng món. Cần hỗ trợ: gửi order_id/payment_ref và request_id cho @your_support_username, che key và tài khoản.

Luồng chuẩn không cần ngâm hàng. Dịch vụ cần nhận email/tài khoản có thời gian xử lý riêng, không được hứa giống hàng giao sẵn.

Hạn báo lỗi và dữ liệu cần lưu

Product.warranty mô tả chính sách. Order.warranty là bản đã chốt tại lúc mua, không đổi khi shop sửa sản phẩm. warranty_status.initial_deadline là hạn đối chiếu sai thông tin/giao sai; warranty_status.deadline là hạn bảo hành. Hiển thị giờ hết hạn cụ thể cho khách, không tính lại từ lúc khách đăng nhập.

Hàng lỗi ban đầu chỉ nhận credentials, first_login hoặc wrong_product theo failure_stages; tài khoản đã dùng được rồi mới bị khóa không thuộc gói đó. Gửi failure_stage khi tạo phiếu. Tạo phiếu không tự động được đổi hàng/hoàn tiền; giữ giờ thử đầu, ảnh/video lỗi đã che thông tin nhạy cảm để đối chiếu.

Với API tính hạn từ redeem/lần dùng đầu, requires_entitlement_verification=true nghĩa cần đối chiếu trang quota/hạn thật. Không suy ra hạn từ giờ thanh toán và không hiểu deadline=null là bảo hành vô thời hạn. Hết quota/hết hạn, sai base URL/model hoặc lỗi công cụ của khách không mặc định là lỗi key.

Đại lý nên giao ngay khi Shop trả hàng; khoảng chậm do đại lý giữ hàng không làm gia hạn chính sách. Giữ một mã đơn, một yêu cầu và một phiếu theo SKU để tránh trùng chi phí.

Mua hàng và chống trùng

  1. Tạo một Idempotency-Key duy nhất cho mỗi đơn ở hệ thống của bạn và lưu cùng payload trước khi gọi.
  2. Gửi ID sản phẩm, số lượng 1–100 và tổng tiền tối đa. Key chống trùng dài 8–128 ký tự: chữ, số, dấu _ . : -.
  3. Thành công trả HTTP 201, số tiền, mã đơn, danh sách items gồm sku và account, mô tả/hướng dẫn tại lúc mua. Lưu dữ liệu ở server của bạn.
  4. Nếu timeout/5xx, gửi lại cùng key và payload: HTTP 200 trả cùng đơn, replayed=true. Không dùng key mới cho cùng giao dịch.

Trừ ví một lần và lưu đơn trong một transaction. Hàng sẵn giao ngay; tài khoản lấy từ nguồn API (Muse, ChatGPT Apple Pay Full) trả trạng thái paid và items rỗng trong lúc xử lý, sau đó chuyển delivered. Đọc GET /orders/{id} cách nhau ít nhất 5 giây; không đặt lại hoặc dùng Idempotency-Key mới. Thiếu tiền hoặc thiếu hàng thì không trừ ví, không giao một phần. Các yêu cầu thất bại trước khi tạo đơn không giữ mã chống trùng; sau khi có tiền/hàng bạn có thể thử lại. Cùng key đã mua thành công nhưng payload khác sẽ báo 409.

cURL · Linux / macOS
curl 'https://digital.letridev.cloud/api/shop/v1/orders?wait_seconds=15' \
  -H "Authorization: Bearer $SHOP_SHOP_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: your-unique-order-20261031-001' \
  -d '{"product_id":"PRODUCT_ID","quantity":1,"max_total_vnd":50000}'
Python · requests
import os, requests

base = "https://digital.letridev.cloud/api/shop/v1"
headers = {"Authorization": "Bearer " + os.environ["SHOP_SHOP_KEY"]}
print(requests.get(base + "/me", headers=headers, timeout=60).json())
print(requests.get(base + "/products", headers=headers, timeout=60).json())

# Lưu mã này cùng đơn của bạn TRƯỚC khi gọi mua.
request_key = os.environ["SHOP_ORDER_REQUEST_ID"]
payload = {"product_id": "PRODUCT_ID", "quantity": 1, "max_total_vnd": 50000}
# Thay PRODUCT_ID và giới hạn giá trước khi chạy mua thật.
# Nếu timeout/5xx: gọi lại với CÙNG request_key và payload.
response = requests.post(base + "/orders", json=payload,
    headers={**headers, "Idempotency-Key": request_key}, timeout=60)
response.raise_for_status()
order = response.json()["data"]
# Khong log items: du lieu giao hang co the chua mat khau.
print(response.status_code, order["id"], order["fulfillment_status"], len(order["items"]))

Để lấy lại hàng sau này: GET /orders/{id}. Danh sách đơn không chứa mật khẩu; chi tiết đơn chỉ trả hàng thuộc tài khoản của bạn. Snapshot mô tả và hướng dẫn giữ theo lúc mua.

Danh sách endpoints

MethodPathMục đích
GET/meQuyền tài khoản, số dư VND
GET/productsGiá và tồn theo loại key
POST/ordersMua hàng bằng ví; bắt buộc Idempotency-Key
GET/ordersDanh sách đơn của bạn
GET/orders/{id}Tra lại đầy đủ hàng đã mua
GET/wallet/ledgerSổ ví, nạp và mua
POST/wallet/topupsTạo QR nạp ví; bắt buộc Idempotency-Key
GET/wallet/topups/{id}Kiểm tra tiền đã vào ví chưa
POST/warranty-claimsGửi yêu cầu cho SKU đã mua
GET/catalog/stockGiá / tồn gọn, ETag và If-None-Match
GET/products/{id}Giá / kho một sản phẩm
GET/warranty-claimsDanh sách yêu cầu bảo hành
GET/warranty-claims/{id}Theo dõi trạng thái bảo hành

Danh sách hỗ trợ ?limit=50&before=ID, tối đa 100. Dùng data.next_cursor cho trang tiếp. Header X-Request-Id và field request_id giúp shop tra lỗi; không gửi key khi báo lỗi.

BODY · POST /wallet/topups
{
  "amount_vnd": 100000
}

Yêu cầu nạp trả QR, thông tin ngân hàng, mã chuyển khoản và expires_at. Tối đa 5 yêu cầu nạp còn hạn. Trạng thái pending cần đọc cùng expires_at; không chuyển tiền sau hạn. Khoản chuyển sai/hết hạn cần shop đối soát, không tự cộng nhầm.

Mã lỗi và retry

  • 400: JSON/tham số sai.
  • 401: key sai hoặc thu hồi; 403: quyền/tài khoản bị dừng.
  • 402 INSUFFICIENT_BALANCE: thiếu số dư, chưa trừ tiền.
  • 404: sản phẩm/đơn không tồn tại, đang ẩn hoặc không thuộc bạn.
  • 409 OUT_OF_STOCK: thiếu hàng; PRICE_LIMIT_EXCEEDED: vượt giá; PRICE_UNAVAILABLE: giá đại lý đang cập nhật, ví chưa bị trừ; IDEMPOTENCY_CONFLICT: key đã dùng với payload khác.
  • 413: body vượt 16 KB.
  • 429: chờ theo Retry-After. Giới hạn 120 yêu cầu/phút/key, 240/phút/IP trên một tiến trình.
  • 500 hoặc timeout: giữ nguyên mã chống trùng và payload, chờ rồi thử lại; không tạo đơn mới.

Phản hồi lỗi: {"success":false,"error":{"code":"...","message":"..."},"request_id":"..."}. Retry nên có backoff, không lặp vô hạn. HTTP 201/200 phải kiểm tra cả success, mã đơn và trạng thái. Chỉ xử lý hàng khi status=delivered và đủ số item; status=paid là đang xử lý hoặc cần hỗ trợ, không phải lý do tạo đơn mới.

Gửi bảo hành theo từng SKU

BODY · POST /warranty-claims
{
  "order_id": "YOUR_ORDER_ID",
  "sku": "SC-YOUR_STOCK_ID",
  "failure_stage": "first_login",
  "description": "Mô tả lỗi cụ thể, thời điểm phát sinh và cách tái hiện."
}

SKU lấy từ đơn, không tự tạo. Yêu cầu đang mở sẽ được trả lại thay vì tạo trùng. Tiếp nhận không có nghĩa tự chấp nhận bảo hành; áp dụng chính sách tại lúc mua. Gửi thêm bằng chứng cần thiết cho @your_support_username. Hoàn/đền được shop đối soát, API không tự hoàn tiền hay bán lại tài khoản lỗi.

Dùng GET /warranty-claims để liệt kê phiếu của tài khoản hoặc GET /warranty-claims/{id} để theo dõi open, with_supplier, resolved, rejected. Kết quả không chứa ghi chú nội bộ hay tài khoản đã giao. Poll có giãn cách và tuân thủ giới hạn request.