{"openapi":"3.1.0","info":{"title":"Upstream Provider API","version":"1.0.0","description":"Dujiao-Next compatible upstream product, order, fulfillment and callback API."},"servers":[{"url":"https:\/\/dmap.example.com\/api\/v1\/upstream"}],"security":[{"DujiaoNextSignature":[]}],"components":{"securitySchemes":{"DujiaoNextSignature":{"type":"apiKey","in":"header","name":"Dujiao-Next-Signature","description":"Required headers: Dujiao-Next-Api-Key, Dujiao-Next-Timestamp, Dujiao-Next-Signature. Signature string is METHOD + newline + path + newline + timestamp + newline + md5(raw JSON body), signed with HMAC-SHA256 and the downstream client API secret."}},"schemas":{"LocalizedText":{"type":"object","additionalProperties":{"type":"string"},"example":{"zh-CN":"Telegram Premium","zh-TW":"Telegram Premium","en-US":"Telegram Premium"}},"ErrorResponse":{"type":"object","required":["ok","error_code","error_message"],"properties":{"ok":{"type":"boolean","example":false},"error_code":{"type":"string","example":"bad_request"},"error_message":{"type":"string","example":"The given request payload is invalid."},"retry_after":{"type":["integer","null"],"example":30}}},"MaintenanceStatus":{"type":"object","properties":{"enabled":{"type":"boolean","example":false},"mode":{"type":"string","example":"off"},"title":{"type":["string","null"],"example":null},"message":{"type":["string","null"],"example":null},"expected_restore_at":{"type":["string","null"],"example":null},"error_code":{"type":"string","example":"site_maintenance"},"retry_after":{"type":"integer","example":1800}}},"PingResponse":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"site_name":{"type":"string","example":"DMAP"},"protocol_version":{"type":"string","example":"1.0"},"user_id":{"type":"integer","example":12},"balance":{"type":"string","example":"5988.50"},"currency":{"type":"string","example":"CNY"},"member_level":{"type":["string","null"],"example":null},"maintenance":{"$ref":"#\/components\/schemas\/MaintenanceStatus"}}},"Category":{"type":"object","properties":{"id":{"type":"integer","example":1},"parent_id":{"type":"integer","example":0},"slug":{"type":"string","example":"membership"},"name":{"$ref":"#\/components\/schemas\/LocalizedText"},"icon":{"type":"string","example":"https:\/\/static.example.com\/icons\/member.png"},"sort_order":{"type":"integer","example":10}}},"CategoriesResponse":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"categories":{"type":"array","items":{"$ref":"#\/components\/schemas\/Category"}}}},"ManualFormField":{"type":"object","properties":{"key":{"type":"string","example":"username"},"type":{"type":"string","enum":["text","textarea","select","radio","checkbox"],"example":"text"},"required":{"type":"boolean","example":true},"label":{"$ref":"#\/components\/schemas\/LocalizedText"},"placeholder":{"$ref":"#\/components\/schemas\/LocalizedText"},"regex":{"type":["string","null"],"example":"^[A-Za-z0-9_]{3,32}$"},"max_len":{"type":["integer","null"],"example":64},"options":{"type":"array","items":{"type":"string"},"example":["monthly","yearly"]}}},"ManualFormSchema":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#\/components\/schemas\/ManualFormField"}}}},"ProductSku":{"type":"object","properties":{"id":{"type":"integer","example":1001},"sku_code":{"type":"string","example":"TG-PREMIUM-1M"},"name":{"$ref":"#\/components\/schemas\/LocalizedText"},"spec_values":{"$ref":"#\/components\/schemas\/LocalizedText"},"price_amount":{"type":"string","example":"38.00"},"original_price":{"type":["string","null"],"example":null},"member_price":{"type":["string","null"],"example":null},"currency":{"type":"string","example":"CNY"},"stock_status":{"type":"string","enum":["out_of_stock","low_stock","in_stock","unlimited"],"example":"in_stock"},"stock_quantity":{"type":"integer","example":120},"is_active":{"type":"boolean","example":true}}},"Product":{"type":"object","properties":{"id":{"type":"integer","example":101},"slug":{"type":"string","example":"telegram-premium"},"title":{"$ref":"#\/components\/schemas\/LocalizedText"},"description":{"$ref":"#\/components\/schemas\/LocalizedText"},"content":{"$ref":"#\/components\/schemas\/LocalizedText"},"seo_meta":{"type":"object","properties":{"title":{"$ref":"#\/components\/schemas\/LocalizedText"},"keywords":{"$ref":"#\/components\/schemas\/LocalizedText"},"description":{"$ref":"#\/components\/schemas\/LocalizedText"}}},"images":{"type":"array","items":{"type":"string"},"example":["https:\/\/static.example.com\/products\/tg.png"]},"tags":{"type":"array","items":{"type":"string"},"example":["membership","instant"]},"price_amount":{"type":"string","example":"38.00"},"original_price":{"type":["string","null"],"example":null},"member_price":{"type":["string","null"],"example":null},"currency":{"type":"string","example":"CNY"},"fulfillment_type":{"type":"string","enum":["auto","manual"],"example":"manual"},"manual_form_schema":{"oneOf":[{"$ref":"#\/components\/schemas\/ManualFormSchema"},{"type":"null"}]},"is_active":{"type":"boolean","example":true},"category_id":{"type":["integer","null"],"example":1},"skus":{"type":"array","items":{"$ref":"#\/components\/schemas\/ProductSku"}},"created_at":{"type":["string","null"],"format":"date-time","example":"2026-06-13T02:10:09.000000Z"},"updated_at":{"type":["string","null"],"format":"date-time","example":"2026-06-13T03:10:09.000000Z"}}},"ProductsResponse":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"items":{"type":"array","items":{"$ref":"#\/components\/schemas\/Product"}},"total":{"type":"integer","example":58},"page":{"type":"integer","example":1},"page_size":{"type":"integer","example":20}}},"ProductResponse":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"product":{"$ref":"#\/components\/schemas\/Product"}}},"OrderCreateRequest":{"type":"object","required":["sku_id","quantity"],"properties":{"sku_id":{"type":"integer","example":1001},"quantity":{"type":"integer","minimum":1,"example":1},"manual_form_data":{"type":["object","null"],"additionalProperties":true,"example":{"username":"telegram_user"}},"downstream_order_no":{"type":["string","null"],"maxLength":120,"example":"TEST-202606130001"},"trace_id":{"type":["string","null"],"maxLength":120,"example":"trace-202606130001"},"callback_url":{"type":["string","null"],"format":"uri","maxLength":1000,"example":"https:\/\/shop.example.com\/api\/v1\/upstream\/callback"}}},"OrderCreateResponse":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"order_id":{"type":"integer","example":9001},"order_no":{"type":"string","example":"DJ202606130001ABCDEF"},"status":{"type":"string","example":"paid"},"amount":{"type":"string","example":"38.00"},"currency":{"type":"string","example":"CNY"}}},"OrderItem":{"type":"object","properties":{"product_id":{"type":"integer","example":101},"sku_id":{"type":"integer","example":1001},"title":{"$ref":"#\/components\/schemas\/LocalizedText"},"quantity":{"type":"integer","example":1},"unit_price":{"type":"string","example":"38.00"},"total_price":{"type":"string","example":"38.00"},"currency":{"type":"string","example":"CNY"},"fulfillment_type":{"type":"string","example":"manual"}}},"OrderFulfillment":{"type":"object","properties":{"type":{"type":"string","example":"manual"},"status":{"type":"string","example":"delivered"},"payload":{"type":["object","array","string","null"],"example":{"card_no":"ABCD-1234"}},"delivery_data":{"type":["object","array","string","null"],"example":{"account":"demo@example.com"}},"delivered_at":{"type":["string","null"],"format":"date-time","example":"2026-06-13T04:10:09.000000Z"}}},"OrderDetailResponse":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"order_id":{"type":"integer","example":9001},"order_no":{"type":"string","example":"DJ202606130001ABCDEF"},"status":{"type":"string","enum":["paid","fulfilling","partially_delivered","delivered","completed","canceled","refunded","failed"],"example":"delivered"},"amount":{"type":"string","example":"38.00"},"currency":{"type":"string","example":"CNY"},"items":{"type":"array","items":{"$ref":"#\/components\/schemas\/OrderItem"}},"fulfillment":{"$ref":"#\/components\/schemas\/OrderFulfillment"}}},"OrderCancelResponse":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"order_id":{"type":"integer","example":9001},"order_no":{"type":"string","example":"DJ202606130001ABCDEF"},"status":{"type":"string","example":"canceled"}}},"OrderCallbackPayload":{"type":"object","properties":{"event":{"type":"string","example":"order.status_changed"},"order_id":{"type":"integer","example":9001},"order_no":{"type":"string","example":"DJ202606130001ABCDEF"},"downstream_order_no":{"type":["string","null"],"example":"TEST-202606130001"},"status":{"type":"string","example":"delivered"},"timestamp":{"type":"integer","example":1781313600},"amount":{"type":"string","example":"38.00"},"currency":{"type":"string","example":"CNY"},"fulfillment":{"$ref":"#\/components\/schemas\/OrderFulfillment"}}}},"responses":{"Unauthorized":{"description":"Missing, expired or invalid signature headers.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"ok":false,"error_code":"invalid_signature","error_message":"Invalid request signature."}}}},"Forbidden":{"description":"API key disabled, unknown or rejected by IP whitelist.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"ok":false,"error_code":"invalid_api_key","error_message":"Invalid API key."}}}},"RateLimited":{"description":"Client-level rate limit reached.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"ok":false,"error_code":"bad_request","error_message":"Too many API requests.","retry_after":30}}}}}},"paths":{"\/ping":{"post":{"summary":"Connectivity test","description":"Validate credentials, balance currency and current maintenance status.","parameters":[],"responses":{"200":{"description":"Successful response.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PingResponse"},"example":{"ok":true,"site_name":"DMAP","protocol_version":"1.0","user_id":12,"balance":"5988.50","currency":"CNY","member_level":null,"maintenance":{"enabled":false,"mode":"off","title":null,"message":null,"expected_restore_at":null,"error_code":"site_maintenance","retry_after":1800}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/RateLimited"}}}},"\/categories":{"get":{"summary":"List product categories","description":"Return enabled product categories for downstream display or mapping.","parameters":[],"responses":{"200":{"description":"Successful response.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CategoriesResponse"},"example":{"ok":true,"categories":[{"id":1,"parent_id":0,"slug":"membership","name":{"zh-CN":"\u4f1a\u5458\u8ba2\u9605","zh-TW":"\u6703\u54e1\u8a02\u95b1","en-US":"Membership"},"icon":"https:\/\/static.example.com\/icons\/member.png","sort_order":10}]}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/RateLimited"}}}},"\/products":{"get":{"summary":"List products","description":"Return visible and active products with active SKUs. Prices are converted to the downstream client settlement currency when available.","parameters":[{"name":"page","in":"query","required":false,"description":"Page number, minimum 1.","schema":{"type":"integer","minimum":1},"example":1},{"name":"page_size","in":"query","required":false,"description":"Page size, 1 to 100.","schema":{"type":"integer","minimum":1,"maximum":100},"example":20}],"responses":{"200":{"description":"Successful response.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ProductsResponse"},"example":{"ok":true,"items":[{"id":101,"slug":"telegram-premium","title":{"zh-CN":"Telegram Premium","zh-TW":"Telegram Premium","en-US":"Telegram Premium"},"description":{"zh-CN":"Telegram \u4f1a\u5458\u8ba2\u9605\u81ea\u52a8\u91c7\u8d2d\u3002","en-US":"Telegram membership subscription fulfillment."},"content":{"zh-CN":"\u4e0b\u5355\u65f6\u8bf7\u586b\u5199\u9700\u8981\u5145\u503c\u7684\u7528\u6237\u540d\u3002","en-US":"Submit the target username when creating an order."},"seo_meta":{"title":{"zh-CN":"Telegram Premium"},"keywords":{"zh-CN":"telegram,premium,\u4f1a\u5458"},"description":{"zh-CN":"Telegram Premium \u4e0a\u6e38\u4f9b\u8d27\u63a5\u53e3\u5546\u54c1\u3002"}},"images":["https:\/\/static.example.com\/products\/tg.png"],"tags":["membership","instant"],"price_amount":"38.00","original_price":null,"member_price":null,"currency":"CNY","fulfillment_type":"manual","manual_form_schema":{"fields":[{"key":"username","type":"text","required":true,"label":{"zh-CN":"Telegram \u7528\u6237\u540d","en-US":"Telegram username"},"placeholder":{"zh-CN":"\u8bf7\u8f93\u5165\u7528\u6237\u540d","en-US":"Enter username"},"regex":"^[A-Za-z0-9_]{3,32}$","max_len":32}]},"is_active":true,"category_id":1,"skus":[{"id":1001,"sku_code":"TG-PREMIUM-1M","name":{"zh-CN":"1 \u4e2a\u6708","en-US":"1 month"},"spec_values":{"zh-CN":"1 \u4e2a\u6708","zh-TW":"1 \u500b\u6708","en-US":"1 month"},"price_amount":"38.00","original_price":null,"member_price":null,"currency":"CNY","stock_status":"in_stock","stock_quantity":120,"is_active":true}],"created_at":"2026-06-13T02:10:09.000000Z","updated_at":"2026-06-13T03:10:09.000000Z"}],"total":58,"page":1,"page_size":20}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/RateLimited"}}}},"\/products\/{product}":{"get":{"summary":"Product detail","description":"Return one active product with SKU list, localized content, SEO metadata, images, tags and manual form schema.","parameters":[{"name":"product","in":"path","required":true,"description":"Product ID.","schema":{"type":"integer"},"example":1}],"responses":{"200":{"description":"Successful response.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ProductResponse"},"example":{"ok":true,"product":{"id":101,"slug":"telegram-premium","title":{"zh-CN":"Telegram Premium","zh-TW":"Telegram Premium","en-US":"Telegram Premium"},"description":{"zh-CN":"Telegram \u4f1a\u5458\u8ba2\u9605\u81ea\u52a8\u91c7\u8d2d\u3002","en-US":"Telegram membership subscription fulfillment."},"content":{"zh-CN":"\u4e0b\u5355\u65f6\u8bf7\u586b\u5199\u9700\u8981\u5145\u503c\u7684\u7528\u6237\u540d\u3002","en-US":"Submit the target username when creating an order."},"seo_meta":{"title":{"zh-CN":"Telegram Premium"},"keywords":{"zh-CN":"telegram,premium,\u4f1a\u5458"},"description":{"zh-CN":"Telegram Premium \u4e0a\u6e38\u4f9b\u8d27\u63a5\u53e3\u5546\u54c1\u3002"}},"images":["https:\/\/static.example.com\/products\/tg.png"],"tags":["membership","instant"],"price_amount":"38.00","original_price":null,"member_price":null,"currency":"CNY","fulfillment_type":"manual","manual_form_schema":{"fields":[{"key":"username","type":"text","required":true,"label":{"zh-CN":"Telegram \u7528\u6237\u540d","en-US":"Telegram username"},"placeholder":{"zh-CN":"\u8bf7\u8f93\u5165\u7528\u6237\u540d","en-US":"Enter username"},"regex":"^[A-Za-z0-9_]{3,32}$","max_len":32}]},"is_active":true,"category_id":1,"skus":[{"id":1001,"sku_code":"TG-PREMIUM-1M","name":{"zh-CN":"1 \u4e2a\u6708","en-US":"1 month"},"spec_values":{"zh-CN":"1 \u4e2a\u6708","zh-TW":"1 \u500b\u6708","en-US":"1 month"},"price_amount":"38.00","original_price":null,"member_price":null,"currency":"CNY","stock_status":"in_stock","stock_quantity":120,"is_active":true}],"created_at":"2026-06-13T02:10:09.000000Z","updated_at":"2026-06-13T03:10:09.000000Z"}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/RateLimited"},"404":{"description":"Product not found or unavailable.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"ok":false,"error_code":"product_not_found","error_message":"Product does not exist."}}}}}}},"\/orders":{"post":{"summary":"Create upstream order","description":"Create an upstream order. downstream_order_no is idempotent per API key. callback_url must be public HTTP\/HTTPS when supplied.","parameters":[],"responses":{"200":{"description":"Successful response.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/OrderCreateResponse"},"example":{"ok":true,"order_id":9001,"order_no":"DJ202606130001ABCDEF","status":"paid","amount":"38.00","currency":"CNY"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/RateLimited"},"400":{"description":"Validation, SKU, product or callback URL error.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"ok":false,"error_code":"bad_request","error_message":"downstream_order_no is required."}}}},"402":{"description":"Wallet balance is insufficient.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"ok":false,"error_code":"insufficient_balance","error_message":"Wallet balance is insufficient."}}}},"409":{"description":"Stock or channel preflight rejected the order.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"ok":false,"error_code":"insufficient_stock","error_message":"SKU stock is insufficient."}}}},"502":{"description":"Channel preflight returned an unexpected failure.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"ok":false,"error_code":"channel_preflight_failed","error_message":"Channel preflight check failed."}}}},"503":{"description":"Channel temporarily unavailable.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"ok":false,"error_code":"channel_preflight_failed","error_message":"Channel preflight check failed."}}}}},"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/OrderCreateRequest"},"example":{"sku_id":1001,"quantity":1,"manual_form_data":{"username":"telegram_user"},"downstream_order_no":"TEST-202606130001","trace_id":"trace-202606130001","callback_url":"https:\/\/shop.example.com\/api\/v1\/upstream\/callback"}}}}}},"\/orders\/{order}":{"get":{"summary":"Order detail","description":"Return order status, amount, items and fulfillment data when delivered.","parameters":[{"name":"order","in":"path","required":true,"description":"Order ID.","schema":{"type":"integer"},"example":1}],"responses":{"200":{"description":"Successful response.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/OrderDetailResponse"},"example":{"ok":true,"order_id":9001,"order_no":"DJ202606130001ABCDEF","status":"delivered","amount":"38.00","currency":"CNY","items":[{"product_id":101,"sku_id":1001,"title":{"zh-CN":"Telegram Premium","en-US":"Telegram Premium"},"quantity":1,"unit_price":"38.00","total_price":"38.00","currency":"CNY","fulfillment_type":"manual"}],"fulfillment":{"type":"manual","status":"delivered","payload":{"username":"telegram_user"},"delivery_data":{"account":"telegram_user","duration":"1 month"},"delivered_at":"2026-06-13T04:10:09.000000Z"}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/RateLimited"},"404":{"description":"Order not found for the current downstream client.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"ok":false,"error_code":"order_not_found","error_message":"Order does not exist."}}}}}}},"\/orders\/{order}\/cancel":{"post":{"summary":"Cancel order when allowed","description":"Cancel an order if downstream cancellation is enabled and the current status is cancellable.","parameters":[{"name":"order","in":"path","required":true,"description":"Order ID.","schema":{"type":"integer"},"example":1}],"responses":{"200":{"description":"Successful response.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/OrderCancelResponse"},"example":{"ok":true,"order_id":9001,"order_no":"DJ202606130001ABCDEF","status":"canceled"}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/RateLimited"},"404":{"description":"Order not found for the current downstream client.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"ok":false,"error_code":"order_not_found","error_message":"Order does not exist."}}}},"409":{"description":"Cancellation disabled or current order status cannot be canceled.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"},"example":{"ok":false,"error_code":"cancel_not_allowed","error_message":"Current order status cannot be canceled."}}}}}}}},"x-signature-example":{"string_to_sign":"POST\n\/api\/v1\/upstream\/orders\n1760000000\nmd5(json_body)","algorithm":"HMAC-SHA256","headers":["Dujiao-Next-Api-Key","Dujiao-Next-Timestamp","Dujiao-Next-Signature"]},"x-callback":{"method":"POST","signature":"Callbacks use the same Dujiao-Next signature headers.","payload_schema":"#\/components\/schemas\/OrderCallbackPayload"}}