{"openapi":"3.1.0","info":{"title":"LUONGMMO Partner Connector API","version":"1.1.0","description":"API server-to-server cho bot Đại lý. Mọi action nghiệp vụ dùng POST JSON, chữ ký HMAC-SHA256, nonce một lần, timestamp tối đa 5 phút và IP được ràng buộc lúc kích hoạt. API chỉ trả metadata; hàng được giao trực tiếp bằng bot shop đã liên kết."},"servers":[{"url":"https://www.luongmmo.io.vn/api/v1","description":"LUONGMMO production Partner API"}],"tags":[{"name":"System","description":"Trạng thái dịch vụ"},{"name":"Connector","description":"Các action dành cho bot Đại lý"}],"paths":{"/health":{"get":{"tags":["System"],"summary":"Kiểm tra API sẵn sàng","security":[],"responses":{"200":{"description":"Dịch vụ sẵn sàng","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/":{"post":{"tags":["Connector"],"summary":"Gọi một action connector","description":"Ký đúng raw JSON bằng công thức timestamp + newline + nonce + newline + SHA256(raw_json), sau đó HMAC-SHA256 bằng api_secret.","security":[{"PartnerKey":[],"PartnerTimestamp":[],"PartnerNonce":[],"PartnerSignature":[]}],"parameters":[{"name":"X-ML612-Client-Version","in":"header","required":false,"schema":{"type":"string","example":"connector-1.0"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/HeartbeatRequest"},{"$ref":"#/components/schemas/DashboardRequest"},{"$ref":"#/components/schemas/ProductsRequest"},{"$ref":"#/components/schemas/BalanceRequest"},{"$ref":"#/components/schemas/ShopConfigRequest"},{"$ref":"#/components/schemas/SetRetailPriceRequest"},{"$ref":"#/components/schemas/CreateOrderRequest"},{"$ref":"#/components/schemas/OrdersRequest"},{"$ref":"#/components/schemas/OrderStatusRequest"},{"$ref":"#/components/schemas/CommissionSummaryRequest"}],"discriminator":{"propertyName":"action"}},"examples":{"heartbeat":{"value":{"action":"heartbeat"}},"dashboard":{"value":{"action":"dashboard"}},"products":{"value":{"action":"products"}},"balance":{"value":{"action":"balance"}},"set_retail_price":{"value":{"action":"set_retail_price","product_id":12,"retail_price":150000}},"create_order":{"value":{"action":"create_order","external_order_id":"SHOP-ORDER-20260829-0001","idempotency_key":"order-20260829-0001-product-12-qty-1","product_id":12,"quantity":1,"buyer_telegram_id":123456789,"buyer_username":"khachhang"}},"orders":{"value":{"action":"orders","limit":10}},"order_status":{"value":{"action":"order_status","external_order_id":"SHOP-ORDER-20260829-0001"}}}}}},"responses":{"200":{"description":"Action thành công","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"securitySchemes":{"PartnerKey":{"type":"apiKey","in":"header","name":"X-ML612-Key","description":"API key được trả một lần sau kích hoạt."},"PartnerTimestamp":{"type":"apiKey","in":"header","name":"X-ML612-Timestamp","description":"Unix timestamp hiện tại, lệch tối đa 300 giây."},"PartnerNonce":{"type":"apiKey","in":"header","name":"X-ML612-Nonce","description":"Chuỗi ngẫu nhiên 16-96 ký tự, không tái sử dụng."},"PartnerSignature":{"type":"apiKey","in":"header","name":"X-ML612-Signature","description":"HMAC-SHA256(timestamp + newline + nonce + newline + SHA256(raw_json), api_secret)."}},"schemas":{"HealthResponse":{"type":"object","required":["ok","service","version","status","timestamp"],"properties":{"ok":{"type":"boolean","const":true},"service":{"type":"string"},"version":{"type":"string"},"status":{"type":"string","const":"ready"},"timestamp":{"type":"string","format":"date-time"}}},"ProductsRequest":{"type":"object","required":["action"],"properties":{"action":{"type":"string","const":"products"}}},"HeartbeatRequest":{"type":"object","required":["action"],"properties":{"action":{"type":"string","const":"heartbeat"}}},"DashboardRequest":{"type":"object","required":["action"],"properties":{"action":{"type":"string","const":"dashboard"}}},"BalanceRequest":{"type":"object","required":["action"],"properties":{"action":{"type":"string","const":"balance"}}},"ShopConfigRequest":{"type":"object","required":["action"],"properties":{"action":{"type":"string","const":"shop_config"}}},"SetRetailPriceRequest":{"type":"object","required":["action","product_id","retail_price"],"properties":{"action":{"type":"string","const":"set_retail_price"},"product_id":{"type":"integer","minimum":1},"retail_price":{"type":"integer","minimum":1,"description":"VND; phải lớn hơn hoặc bằng giá sỉ hiệu lực."}}},"CreateOrderRequest":{"type":"object","required":["action","external_order_id","idempotency_key","product_id","quantity","buyer_telegram_id"],"properties":{"action":{"type":"string","const":"create_order"},"external_order_id":{"type":"string","maxLength":100},"idempotency_key":{"type":"string","minLength":8,"maxLength":100},"product_id":{"type":"integer","minimum":1},"quantity":{"type":"integer","minimum":1,"maximum":20},"buyer_telegram_id":{"type":"integer","minimum":10000},"buyer_username":{"type":"string","maxLength":32}}},"OrdersRequest":{"type":"object","required":["action"],"properties":{"action":{"type":"string","const":"orders"},"limit":{"type":"integer","minimum":1,"maximum":50},"before_id":{"type":"integer","minimum":1},"status":{"type":"string","enum":["delivery_pending","delivering","delivered","delivery_failed"]}}},"OrderStatusRequest":{"type":"object","required":["action"],"properties":{"action":{"type":"string","const":"order_status"},"order_code":{"type":"string"},"external_order_id":{"type":"string"}},"anyOf":[{"required":["order_code"]},{"required":["external_order_id"]}]},"CommissionSummaryRequest":{"type":"object","required":["action"],"properties":{"action":{"type":"string","const":"commission_summary"},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"SuccessResponse":{"type":"object","required":["ok","data","request_id"],"properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","additionalProperties":true},"request_id":{"type":"string"}}},"ErrorResponse":{"type":"object","required":["ok","error","request_id"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"request_id":{"type":"string"}}}},"responses":{"BadRequest":{"description":"JSON hoặc request không hợp lệ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Thiếu/sai key, timestamp hoặc chữ ký","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InsufficientBalance":{"description":"Ví Đại lý không đủ số dư","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"IP hoặc action không được phép","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Conflict":{"description":"Idempotency, tồn kho, giá hoặc trạng thái xung đột","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ValidationError":{"description":"Dữ liệu nghiệp vụ không hợp lệ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"Vượt giới hạn request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalError":{"description":"Lỗi nội bộ không làm lộ dữ liệu kho/secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}