{"openapi":"3.0.3","info":{"title":"Scoopy Shop Purchase API","version":"1.5.0","description":"API mua hàng số từ ví VND. Đây không phải endpoint gọi model AI. Lấy key trong @scoopyvn_bot bằng /api; quyền đại lý do admin cấp. Giá đại lý tính theo cấu hình phần trăm hoặc giá cố định; chưa đặt sẽ theo giá thường. Giao dịch API không cộng ưu đãi giới thiệu. Hỗ trợ hàng kho nội bộ, lấy trực tiếp qua API nguồn và dịch vụ nhận thông tin khách. Mức giảm riêng theo đại lý không cộng dồn %, chọn giá tốt hơn mức chung và vẫn giữ sàn."},"servers":[{"url":"https://scoopyvn.shop/api/shop/v1"}],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]}],"paths":{"/me":{"get":{"summary":"Quyền tài khoản và số dư ví","responses":{"200":{"description":"Thành công","content":{"application/json":{"schema":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"telegram_id":{"type":"string"},"tier":{"type":"string","enum":["user","dealer"]},"balance_vnd":{"type":"integer","format":"int64"},"currency":{"type":"string","enum":["VND"]},"dealer_discount_percent":{"type":"number","minimum":0,"maximum":90,"nullable":true}},"required":["telegram_id","tier","balance_vnd","currency"]},"request_id":{"type":"string","format":"uuid"}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/products":{"get":{"summary":"Danh mục và giá theo loại key","responses":{"200":{"description":"Thành công","content":{"application/json":{"schema":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"next_cursor":{"type":"string","nullable":true}},"required":["items","next_cursor"]},"request_id":{"type":"string","format":"uuid"}}}}}},"default":{"$ref":"#/components/responses/Error"}},"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"in":"query","name":"before","schema":{"type":"string","pattern":"^[1-9][0-9]{0,17}$"},"description":"next_cursor từ trang trước"}]}},"/products/{id}":{"get":{"summary":"Giá và tồn của một sản phẩm đang bán qua API","responses":{"200":{"description":"Thành công","content":{"application/json":{"schema":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Product"},"request_id":{"type":"string","format":"uuid"}}}}}},"default":{"$ref":"#/components/responses/Error"}},"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","pattern":"^[1-9][0-9]{0,17}$"}}]}},"/orders":{"get":{"summary":"Danh sách đơn thuộc tài khoản, không trả mật khẩu","responses":{"200":{"description":"Thành công","content":{"application/json":{"schema":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderSummary"}},"next_cursor":{"type":"string","nullable":true}},"required":["items","next_cursor"]},"request_id":{"type":"string","format":"uuid"}}}}}},"default":{"$ref":"#/components/responses/Error"}},"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"in":"query","name":"before","schema":{"type":"string","pattern":"^[1-9][0-9]{0,17}$"},"description":"next_cursor từ trang trước"}]},"post":{"summary":"Mua hàng nguyên đơn, giữ mã chống trùng và trừ ví một lần","description":"201 lần đầu; 200 khi lấy lại cùng đơn. Đơn đã nhận lưu Idempotency-Key. Hàng lấy trực tiếp từ nguồn có thể trả status=paid, items=[]; đọc lại GET /orders/{id} đến khi delivered. Không tạo đơn mới hoặc trừ ví lần nữa. Thiếu tiền/hết hàng không trừ ví; có thể thử lại khi điều kiện thay đổi. Sau timeout/5xx luôn giữ key và payload. Không tạo key mới để thử cùng một giao dịch. Đọc delivery_mode/input_fields của sản phẩm. Hàng nguồn không cần nhập trước vào kho Scoopy. Dịch vụ cần quantity=1 và thông tin hợp lệ; thiếu thông tin bị từ chối trước khi trừ ví. Dùng wait_seconds hoặc poll theo poll_after_seconds. needs_support chờ shop xử lý, không mua lại.","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{8,128}$"},"description":"Giữ nguyên mã và payload khi retry; phạm vi theo tài khoản và endpoint."},{"in":"query","name":"wait_seconds","schema":{"type":"integer","minimum":0,"maximum":15,"default":0},"description":"Chờ tối đa 15 giây để nhận cùng đơn khi giao xong; hết thời gian vẫn trả processing, không đặt lại."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["product_id","quantity"],"properties":{"product_id":{"type":"string","pattern":"^[1-9][0-9]{0,17}$"},"quantity":{"type":"integer","minimum":1,"maximum":100},"max_total_vnd":{"type":"integer","format":"int64","minimum":1,"description":"Giới hạn tổng tiền khách chấp nhận; nên luôn gửi."},"customer_code":{"type":"string","pattern":"^[A-Za-z0-9]{4,32}$","description":"Chỉ delivery_mode=code_service. Một đơn một mã Muse, quantity=1 tương ứng 1 lượt. Không phải tài khoản/email/2FA."},"customer_email":{"type":"string","format":"email","maxLength":254,"description":"Bắt buộc với delivery_mode=email_service. Mỗi đơn một email, không gửi mật khẩu."},"customer_account":{"type":"object","additionalProperties":false,"required":["email","password","twofa","consent"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8,"maxLength":512,"writeOnly":true},"twofa":{"type":"string","minLength":16,"maxLength":128,"writeOnly":true,"description":"Khóa bí mật Base32 A–Z, 2–7; không phải OTP 6 số."},"consent":{"type":"boolean","enum":[true]}},"description":"Chỉ dùng khi delivery_mode=account_upgrade. Gửi từ server HTTPS, không log; được mã hóa khi lưu."}}}}}},"responses":{"200":{"description":"Thành công","content":{"application/json":{"schema":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Order"},"request_id":{"type":"string","format":"uuid"}}}}}},"201":{"description":"Thành công","content":{"application/json":{"schema":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Order"},"request_id":{"type":"string","format":"uuid"}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/orders/{id}":{"get":{"summary":"Tra lại đơn và đầy đủ hàng đã mua","responses":{"200":{"description":"Thành công","content":{"application/json":{"schema":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Order"},"request_id":{"type":"string","format":"uuid"}}}}}},"default":{"$ref":"#/components/responses/Error"}},"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","pattern":"^[1-9][0-9]{0,17}$"}},{"in":"query","name":"wait_seconds","schema":{"type":"integer","minimum":0,"maximum":15,"default":0},"description":"Chờ tối đa 15 giây để nhận cùng đơn khi giao xong; hết thời gian vẫn trả processing, không đặt lại."}]}},"/wallet/ledger":{"get":{"summary":"Sổ biến động ví","responses":{"200":{"description":"Thành công","content":{"application/json":{"schema":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"amount_vnd":{"type":"integer","format":"int64"},"balance_after_vnd":{"type":"integer","format":"int64"},"kind":{"type":"string","enum":["purchase","topup","adjustment"]},"reference":{"type":"string"},"created_at":{"type":"string","format":"date-time"}},"required":["id","amount_vnd","balance_after_vnd","kind","reference","created_at"]}},"next_cursor":{"type":"string","nullable":true}},"required":["items","next_cursor"]},"request_id":{"type":"string","format":"uuid"}}}}}},"default":{"$ref":"#/components/responses/Error"}},"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"in":"query","name":"before","schema":{"type":"string","pattern":"^[1-9][0-9]{0,17}$"},"description":"next_cursor từ trang trước"}]}},"/wallet/topups":{"post":{"summary":"Tạo QR nạp ví VND","description":"Chuyển đúng số tiền/nội dung trong 30 phút; Giao dịch ngân hàng đã xác thực cộng ví tự động. Tối đa 5 yêu cầu còn hạn. Không phải lệnh nạp trực tiếp bằng API key.","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{8,128}$"},"description":"Giữ nguyên mã và payload khi retry; phạm vi theo tài khoản và endpoint."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["amount_vnd"],"properties":{"amount_vnd":{"type":"integer","format":"int64","minimum":10000,"maximum":1000000000}}}}}},"responses":{"201":{"description":"Thành công","content":{"application/json":{"schema":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Topup"},"request_id":{"type":"string","format":"uuid"}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/wallet/topups/{id}":{"get":{"summary":"Trạng thái yêu cầu nạp của tài khoản","responses":{"200":{"description":"Thành công","content":{"application/json":{"schema":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Topup"},"request_id":{"type":"string","format":"uuid"}}}}}},"default":{"$ref":"#/components/responses/Error"}},"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","pattern":"^[1-9][0-9]{0,17}$"}}]}},"/warranty-claims":{"get":{"summary":"Danh sách yêu cầu bảo hành thuộc tài khoản","responses":{"200":{"description":"Thành công","content":{"application/json":{"schema":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"next_cursor":{"type":"string","nullable":true}},"required":["items","next_cursor"]},"request_id":{"type":"string","format":"uuid"}}}}}},"default":{"$ref":"#/components/responses/Error"}},"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"in":"query","name":"before","schema":{"type":"string","pattern":"^[1-9][0-9]{0,17}$"},"description":"next_cursor từ trang trước"}]},"post":{"summary":"Gửi yêu cầu bảo hành cho SKU đã mua","description":"Yêu cầu đang mở được trả lại thay vì tạo trùng. Không tự động xác nhận đủ điều kiện bảo hành; shop xét chính sách tại thời điểm mua.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["order_id","sku","description"],"properties":{"order_id":{"type":"string"},"sku":{"type":"string","pattern":"^SC-[1-9][0-9]{0,17}$"},"description":{"type":"string","minLength":10,"maxLength":1000},"failure_stage":{"type":"string","enum":["credentials","first_login","wrong_product","activation","plan_loss","after_use"],"description":"Bắt buộc khi warranty.requires_failure_stage=true. Chỉ chọn giá trị được phép trong warranty.failure_stages của sản phẩm/đơn."}}}}}},"responses":{"201":{"description":"Thành công","content":{"application/json":{"schema":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"existing":{"type":"boolean"},"message":{"type":"string"}},"required":["id","status","message"]},"request_id":{"type":"string","format":"uuid"}}}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/warranty-claims/{id}":{"get":{"summary":"Theo dõi trạng thái bảo hành; không trả ghi chú nội bộ hoặc tài khoản đã giao","responses":{"200":{"description":"Thành công","content":{"application/json":{"schema":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Claim"},"request_id":{"type":"string","format":"uuid"}}}}}},"default":{"$ref":"#/components/responses/Error"}},"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","pattern":"^[1-9][0-9]{0,17}$"}}]}},"/catalog/stock":{"get":{"summary":"Giá và tồn toàn bộ SKU theo đúng tài khoản; cập nhật nhanh bằng ETag","description":"Poll khoảng 5 giây; gửi If-None-Match để nhận 304 nếu không đổi. Tồn đã xét ví nguồn và giữ vốn, không phải cam kết giữ hàng. GET /products/{id} và đặt đơn kiểm tra snapshot mới cho SKU khi cần.","responses":{"200":{"description":"Thành công","headers":{"ETag":{"schema":{"type":"string"},"description":"Dùng If-None-Match khi kiểm tra lần tiếp theo."}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"price_vnd":{"type":"integer","format":"int64"},"stock":{"type":"integer","minimum":0},"delivery_mode":{"type":"string","enum":["stock","source_api","email_service","account_upgrade","code_service"]},"stock_status":{"type":"string","enum":["available","sold_out","updating"]},"requires_customer_input":{"type":"boolean"},"stock_updated_at":{"type":"string","format":"date-time","nullable":true}}}},"checked_at":{"type":"string","format":"date-time"},"poll_after_seconds":{"type":"integer"}},"required":["items","checked_at","poll_after_seconds"]},"request_id":{"type":"string"}},"required":["success","data","request_id"]}}}},"304":{"description":"Danh mục giá/tồn không đổi, không có body."},"default":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"apiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}},"responses":{"Error":{"description":"Lỗi có mã ổn định; 400 đầu vào, 401 key, 403 quyền, 404 không tồn tại/không thuộc bạn, 402 thiếu tiền, 409 xung đột/thiếu hàng/giới hạn giá, 413 body lớn, 429 giới hạn tần suất, 500 lỗi nội bộ.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"request_id":{"type":"string"}},"required":["success","error","request_id"]}}}}},"schemas":{"Product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"group":{"type":"string"},"price_vnd":{"type":"integer","format":"int64"},"retail_price_vnd":{"type":"integer","format":"int64"},"currency":{"type":"string","enum":["VND"]},"stock":{"type":"integer","minimum":0},"delivery_mode":{"type":"string","enum":["stock","source_api","email_service","account_upgrade","code_service"]},"requires_customer_input":{"type":"boolean"},"input_fields":{"type":"array","items":{"type":"string"}},"max_quantity":{"type":"integer","minimum":1,"maximum":100},"delivery_hint":{"type":"string"},"stock_updated_at":{"type":"string","format":"date-time","nullable":true},"stock_status":{"type":"string","enum":["available","sold_out","updating"]},"input_schema":{"type":"object","description":"Định dạng, ví dụ và điều kiện từng trường. Kiểm tra trước khi đặt; hợp lệ định dạng không xác minh được mật khẩu thực tế."},"warranty":{"type":"object","nullable":true,"properties":{"mode":{"type":"string","enum":["initial","activation","term","delivery","provider"]},"report_minutes":{"type":"integer"},"term_minutes":{"type":"integer","nullable":true},"ends_after_success":{"type":"boolean"},"requires_failure_stage":{"type":"boolean"},"failure_stages":{"type":"array","items":{"type":"string"}},"summary":{"type":"string"}}}},"required":["id","name","description","group","price_vnd","retail_price_vnd","currency","stock"]},"Claim":{"type":"object","properties":{"id":{"type":"string"},"order_id":{"type":"string"},"sku":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["open","with_supplier","resolved","rejected"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"failure_stage":{"type":"string","nullable":true,"enum":["credentials","first_login","wrong_product","activation","plan_loss","after_use",null]}},"required":["id","order_id","sku","description","status","created_at","updated_at"]},"OrderSummary":{"type":"object","properties":{"id":{"type":"string"},"payment_ref":{"type":"string"},"product_id":{"type":"string"},"quantity":{"type":"integer"},"total_vnd":{"type":"integer","format":"int64"},"status":{"type":"string","enum":["paid","delivered"]},"created_at":{"type":"string","format":"date-time"},"fulfillment_status":{"type":"string","enum":["processing","needs_support","delivered"]}},"required":["id","payment_ref","product_id","quantity","total_vnd","status","created_at"]},"Order":{"type":"object","properties":{"id":{"type":"string"},"payment_ref":{"type":"string"},"status":{"type":"string","enum":["paid","delivered"]},"product_id":{"type":"string"},"product_name":{"type":"string"},"quantity":{"type":"integer"},"unit_price_vnd":{"type":"integer","format":"int64"},"total_vnd":{"type":"integer","format":"int64"},"currency":{"type":"string"},"tier":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"paid_at":{"type":"string","format":"date-time"},"delivered_at":{"type":"string","format":"date-time","nullable":true},"fulfillment_status":{"type":"string","enum":["processing","needs_support","delivered"]},"description":{"type":"string"},"delivery_guide":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"account":{"type":"string"}},"required":["sku","account"]}},"replayed":{"type":"boolean"},"delivery_mode":{"type":"string","enum":["stock","source_api","email_service","account_upgrade","code_service"]},"requires_customer_input":{"type":"boolean"},"input_fields":{"type":"array","items":{"type":"string"}},"max_quantity":{"type":"integer","minimum":1,"maximum":100},"delivery_hint":{"type":"string"},"stock_updated_at":{"type":"string","format":"date-time","nullable":true},"poll_after_seconds":{"type":"integer","minimum":0},"warranty":{"type":"object","nullable":true,"properties":{"mode":{"type":"string","enum":["initial","activation","term","delivery","provider"]},"report_minutes":{"type":"integer"},"term_minutes":{"type":"integer","nullable":true},"ends_after_success":{"type":"boolean"},"requires_failure_stage":{"type":"boolean"},"failure_stages":{"type":"array","items":{"type":"string"}},"summary":{"type":"string"}}},"warranty_status":{"type":"object","nullable":true,"properties":{"deadline":{"type":"string","format":"date-time","nullable":true},"initial_deadline":{"type":"string","format":"date-time","nullable":true},"expired":{"type":"boolean"},"requires_entitlement_verification":{"type":"boolean"}}}},"required":["id","payment_ref","status","product_id","product_name","quantity","unit_price_vnd","total_vnd","currency","tier","created_at","paid_at","description","delivery_guide","items"]},"Topup":{"type":"object","properties":{"id":{"type":"string"},"payment_ref":{"type":"string"},"transfer_content":{"type":"string","maxLength":48,"description":"Full bank transfer memo: a short wish followed by payment_ref. Use this text unchanged."},"amount_vnd":{"type":"integer","format":"int64"},"status":{"type":"string","enum":["pending","paid"]},"expires_at":{"type":"string","format":"date-time"},"paid_at":{"type":"string","format":"date-time","nullable":true},"bank_id":{"type":"string"},"bank_account":{"type":"string"},"bank_account_name":{"type":"string"},"qr_url":{"type":"string","format":"uri"}},"required":["id","payment_ref","amount_vnd","status","expires_at"]}}}}