{"openapi":"3.0.3","info":{"title":"HIOBuy Open Platform API","version":"1.0.4","description":"Unified China e-commerce sourcing API. Use channel (taobao, 1688, weidian). Default response_format is standard (normalized models); set response_format=upstream on supported POST routes for vendor raw JSON passthrough."},"servers":[{"url":"https://api.hiobuy.com"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Products","description":"Unified product APIs"},{"name":"Taobao Products","description":"Taobao IOP product routes"},{"name":"Taobao Orders","description":"Taobao purchase order routes"},{"name":"Orders","description":"1688 and unified order APIs"},{"name":"Fulfillment","description":"Warehouse-mode international fulfillment (packages, shipments, returns, VAS). Requires fulfillment_mode=warehouse."},{"name":"Fulfillment Finance","description":"Fulfillment wallet transactions and invoices"},{"name":"Support","description":"Support tickets (primarily warehouse fulfillment)"},{"name":"Commerce AI","description":"Preview / Invite Only. Capability preview for ecommerce translation, localization, image analysis, and asynchronous image processing. Not self-service and not approved for production use without a written HIOBuy invitation. Commercial pricing has not been announced."},{"name":"AI Credits","description":"AI balance, pricing, estimates, and ledger"},{"name":"Admin","description":"Internal admin (Portal token)"},{"name":"Admin Quota","description":"Plans, quotas, traffic packs, platform fuse"},{"name":"Admin Payments","description":"Internal payment reconciliation (Phase 3)"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"},"portalToken":{"type":"apiKey","in":"header","name":"X-Portal-Token","description":"Portal session token. User must have admin role and email in ADMIN_EMAILS."}},"schemas":{"ProductId":{"type":"string","description":"Search/detail `id`. Taobao = `mi_id` (pass to order `lines[].id`; `offer_id` / `mi_id` still accepted; rotates periodically — do not cache long-term). 1688 and Weidian = upstream `offerId`."},"SourceProductId":{"type":"string","description":"Channel-native id. 1688 and Weidian = `offerId` (same as `id`). Taobao = original `item_id` (not `mi_id`)."},"StandardProductIdentity":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ProductId"},"channel":{"type":"string","enum":["taobao","1688","weidian"]},"source_product_id":{"$ref":"#/components/schemas/SourceProductId"},"source_url":{"type":"string"}}},"VariantAttribute":{"type":"object","description":"Purchasable SKU option (color, size, …). Prefer prop_id+value_id for matching when present.","properties":{"name":{"type":"string","description":"Display attribute name (localized when language is set)","example":"Color Classification"},"value":{"type":"string","description":"Display attribute value (localized when language is set)"},"original_name":{"type":"string","description":"Stable Chinese attribute name for grouping","example":"颜色分类"},"original_value":{"type":"string","description":"Stable Chinese attribute value for matching"},"image":{"type":"string","nullable":true,"description":"Option image (1688 skuImageUrl/Trans; Taobao property_image_list via prop_id:value_id)"},"prop_id":{"type":"string","nullable":true,"description":"Upstream property id as string (Taobao prop_id; 1688 attributeId). Prefer over name text.","example":"1627207"},"value_id":{"type":"string","nullable":true,"description":"Upstream value id as string (Taobao value_id). 1688 has no valueId → null.","example":"43553464153"}},"required":["name","value","original_name","original_value"]},"ProductAttribute":{"type":"object","description":"Product-level CPV (display only; not used for SKU selection)","properties":{"attribute_id":{"type":"string","description":"1688 attributeId when present"},"name":{"type":"string"},"value":{"type":"string"},"original_name":{"type":"string"},"original_value":{"type":"string"}},"required":["name","value","original_name","original_value"]},"ProductVariant":{"type":"object","properties":{"sku_id":{"type":"string","description":"Pass as order line spec_id"},"upstream_sku_id":{"type":"string","nullable":true,"description":"1688 numeric skuId; Taobao same as sku_id"},"attributes":{"type":"array","items":{"$ref":"#/components/schemas/VariantAttribute"}},"price":{"type":"object","additionalProperties":true,"description":"SKU price in CNY yuan"},"stock":{"type":"number"},"image":{"type":"string","nullable":true},"shipping":{"type":"object","nullable":true,"additionalProperties":true,"description":"1688 package dimensions; Taobao null"},"min_order_quantity":{"type":"number","nullable":true},"distribution":{"type":"object","nullable":true,"additionalProperties":true}},"required":["sku_id","attributes","price","stock"]},"StandardProductDetail":{"type":"object","description":"Normalized product detail (response_format=standard)","properties":{"id":{"$ref":"#/components/schemas/ProductId"},"channel":{"type":"string","enum":["taobao","1688","weidian"]},"source_product_id":{"$ref":"#/components/schemas/SourceProductId"},"source_url":{"type":"string"},"title":{"type":"object","additionalProperties":true},"description":{"type":"object","nullable":true,"additionalProperties":true},"price":{"type":"object","additionalProperties":true},"images":{"type":"array","items":{"type":"object","additionalProperties":true}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/ProductVariant"}},"seller":{"type":"object","additionalProperties":true},"shipping":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true},"trade_score":{"type":"string","nullable":true},"min_order_quantity":{"type":"number","nullable":true},"distribution_min_quantity":{"type":"number","nullable":true},"price_tiers":{"type":"array","items":{"type":"object","additionalProperties":true}},"attributes":{"type":"array","items":{"$ref":"#/components/schemas/ProductAttribute"}},"videos":{"type":"object","nullable":true,"additionalProperties":true}},"required":["id","channel","source_product_id","variants"]},"StandardProductDetailResponse":{"type":"object","description":"Product detail / parse success envelope (response_format=standard)","properties":{"product":{"$ref":"#/components/schemas/StandardProductDetail"},"request_id":{"type":"string","example":"req_abc123"}},"required":["product","request_id"]},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"category":{"type":"string"},"field":{"type":"string"},"details":{"type":"object","description":"Safe structured context when available. Conflict responses may include an existing resource, conflicting tracking numbers, the idempotency key, or a retry delay.","additionalProperties":true,"properties":{"upstream_code":{"type":"string"},"upstream_message":{"type":"string"},"field":{"type":"string"},"idempotency_key":{"type":"string"},"retry_after_ms":{"type":"integer","minimum":0},"conflicting_tracking_numbers":{"type":"array","items":{"type":"string"}},"existing_resource":{"$ref":"#/components/schemas/ExistingResource"},"existing_resources":{"type":"array","items":{"$ref":"#/components/schemas/ExistingResource"}}}}}}}},"ExistingResource":{"type":"object","description":"A safe summary of the resource that caused a 409 conflict. Fields vary by resource type.","additionalProperties":true,"properties":{"type":{"type":"string","enum":["package","shipment","payment"]},"package_id":{"type":"string"},"shipment_id":{"type":"string"},"order_sn":{"type":"string"},"transaction_id":{"type":"string"},"tracking_number":{"type":"string"},"tracking_numbers":{"type":"array","items":{"type":"string"}},"external_order_id":{"type":"string"},"external_shipment_id":{"type":"string"},"status":{"type":"string"},"payment_status":{"type":"string"},"paid_at":{"type":"string","format":"date-time"}}},"ShipmentStatus":{"type":"string","description":"Current shipment lifecycle status.","enum":["PENDING","WAIT_PAYMENT","WAIT_SHIP","SHIPPED","SIGNED","CANCELLED"]},"ShipmentInterceptionStatus":{"type":"string","description":"Interception workflow status. This is independent of the shipment lifecycle status.","enum":["REQUESTED","PROCESSING","INTERCEPTED","FAILED"]},"ShipmentTimelineEventCode":{"type":"string","description":"Stable shipment timeline event code. New values may be added after the shared event dictionary is updated.","enum":["SHIPMENT_CREATED","SHIPMENT_PACKED","SHIPMENT_PAID","SHIPMENT_DISPATCHED","SHIPMENT_SIGNED","SHIPMENT_CANCELLED","SHIPMENT_INTERCEPTION_REQUESTED","SHIPMENT_INTERCEPTION_PROCESSING","SHIPMENT_INTERCEPTION_SUCCEEDED","SHIPMENT_INTERCEPTION_FAILED","PICKUP_STATION_ARRIVED","PICKUP_STATION_SHELVED","PICKUP_STATION_CHECKED_OUT","PICKUP_STATION_TRANSFERRED_OUT","DISTRIBUTION_CENTER_SORTED"]},"ShipmentTimelineEvent":{"type":"object","additionalProperties":false,"required":["code","status","title","occurred_at","details"],"properties":{"code":{"$ref":"#/components/schemas/ShipmentTimelineEventCode"},"status":{"$ref":"#/components/schemas/ShipmentStatus"},"title":{"type":"string","description":"Localized display text. Do not parse this field or use it for business logic."},"occurred_at":{"type":"string","format":"date-time","description":"Event time as timezone-aware ISO 8601."},"details":{"type":"object","description":"Structured event context. An empty object is returned when the event has no additional context.","additionalProperties":true,"properties":{"station_name":{"type":"string"},"facility_name":{"type":"string"},"reason":{"type":"string"},"remark":{"type":"string"},"failure_code":{"type":"string"},"failure_message":{"type":"string"}}}}},"ShipmentInterception":{"type":"object","nullable":true,"description":"Shipment interception workflow. It does not replace or overwrite the top-level shipment status.","required":["status"],"properties":{"status":{"$ref":"#/components/schemas/ShipmentInterceptionStatus"},"reason":{"type":"string"},"remark":{"type":"string","nullable":true},"failure_code":{"type":"string","nullable":true},"failure_message":{"type":"string","nullable":true}}},"UpstreamStep":{"type":"object","properties":{"upstream_api":{"type":"string","description":"Vendor API path or IOP route invoked in this step"},"upstream":{"type":"object","additionalProperties":true,"description":"Raw JSON body from that step"}},"required":["upstream_api","upstream"]},"UpstreamApiResponse":{"type":"object","description":"Vendor passthrough envelope when response_format=upstream","properties":{"channel":{"type":"string","example":"1688"},"response_format":{"type":"string","enum":["upstream"]},"upstream_api":{"type":"string","example":"com.alibaba.fenxiao.crossborder/product.search.keywordQuery"},"upstream":{"type":"object","additionalProperties":true,"description":"Official vendor JSON (1688 open API or Taobao IOP)"},"upstream_steps":{"type":"array","description":"Optional prior upstream calls (e.g. image upload before imageQuery)","items":{"type":"object","properties":{"upstream_api":{"type":"string","description":"Vendor API path or IOP route invoked in this step"},"upstream":{"type":"object","additionalProperties":true,"description":"Raw JSON body from that step"}},"required":["upstream_api","upstream"]}},"request_id":{"type":"string","example":"req_abc123"}},"required":["channel","response_format","upstream_api","upstream"]}}},"paths":{"/v1/products/channels":{"get":{"summary":"List product channels and capabilities","tags":["Products"],"responses":{"200":{"description":"Channel list"}}}},"/v1/products/detail":{"post":{"summary":"Product detail (standard or upstream)","description":"Identity: pass search `id` back as `id`. Taobao `id`/`mi_id` → upstream `mi_id`; 1688 and Weidian `id`/`product_id` → `offerId`. Weidian uses `vdian.item.getForBuyer` 1.1. Standard `variants[].attributes[]` includes stable property/value IDs when supplied upstream.","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"response_format":{"type":"string","enum":["standard","upstream"],"default":"standard","description":"Response shape: \"standard\" (default) returns HIOBuy unified models; \"upstream\" returns vendor raw JSON in `upstream` (see UpstreamApiResponse)."},"channel":{"type":"string","enum":["taobao","1688","weidian"]},"product_id":{"type":"string","description":"1688 or Weidian `offerId`. Taobao legacy `item_id`. Prefer `id` from search."},"url":{"type":"string"},"id":{"$ref":"#/components/schemas/ProductId"},"mi_id":{"type":"string","description":"Taobao `mi_id` (equivalent to `id`)"},"tao_password":{"type":"string","description":"Taobao 淘口令"},"language":{"type":"string","default":"en","description":"Target locale for translated product text. Mapped per channel: 1688 → offerQueryParam.country + form language; Taobao → IOP language (zh* → cn). Not the Portal UI locale — pass in JSON body. See docs/api/i18n.md.","example":"en"}},"required":["channel"]}}}},"responses":{"200":{"description":"standard: StandardProductDetailResponse; upstream: UpstreamApiResponse with vendor JSON","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/StandardProductDetailResponse"},{"$ref":"#/components/schemas/UpstreamApiResponse"}]}}}}}}},"/v1/products/search":{"post":{"summary":"Search products (standard or upstream)","description":"Each `items[].id` is Taobao `mi_id` or 1688/Weidian `offerId`. Pass it to `/v1/products/detail` as `id`. Weidian additionally requires `user_id`.","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"response_format":{"type":"string","enum":["standard","upstream"],"default":"standard","description":"Response shape: \"standard\" (default) returns HIOBuy unified models; \"upstream\" returns vendor raw JSON in `upstream` (see UpstreamApiResponse)."},"channel":{"type":"string","enum":["taobao","1688","weidian"]},"keyword":{"type":"string"},"user_id":{"type":"string","description":"Optional Weidian search user ID. Defaults to the authorized account openid."},"page":{"type":"integer","minimum":1,"maximum":400},"page_size":{"type":"integer","maximum":50},"sort":{"type":"string","enum":["PRICE_ASC","PRICE_DESC","SALE_QTY_ASC","SALE_QTY_DESC"],"description":"Official Taobao ItemSearch sort. Omit for default 综合 ranking. Alternative to sort_field+sort_order; also accepted as sort_field. Maps to 1688 {price|monthSold}."},"sort_field":{"type":"string","enum":["price","sales","credit","PRICE_ASC","PRICE_DESC","SALE_QTY_ASC","SALE_QTY_DESC"],"description":"price / sales / credit, or Taobao tokens PRICE_ASC / PRICE_DESC / SALE_QTY_ASC / SALE_QTY_DESC. 1688 maps to SDK sort JSON {price|monthSold|rePurchaseRate}. credit is 1688-only (Taobao ignores). Aliases: bid, sale, monthSold, rePurchaseRate."},"sort_order":{"type":"string","enum":["asc","desc"],"description":"Sort order (default asc). Used with unified sort_field (price/sales/credit). Ignored when sort_field is a Taobao token that already includes order."},"price_start":{"type":"number","description":"Min price in yuan (decimals allowed)"},"price_end":{"type":"number","description":"Max price in yuan (decimals allowed)"},"ship_within_hours":{"type":"integer","enum":[0,24,48],"description":"Ship within hours: 0=today (1688 only), 24, 48. Taobao ignores 0."},"experience_score_level":{"type":"integer","enum":[1,2,3,4],"description":"1688 only. Maps to totalEpScoreLv1..4 (Taobao ignores)"},"product_attrs":{"type":"string","description":"1688 only. Comma-separated attribute tags: isOnePsale,isOnePsaleFreePost,new7,new30,1688Selection,isQqyx (Taobao ignores)"},"filter":{"type":"string","description":"1688 only. Comma-separated filter keys; merged with semantic fields"},"category_ids":{"type":"string","description":"Comma-separated category IDs (1688 only; Taobao ignores)"},"category_id":{"type":"integer","description":"Deprecated. Prefer category_ids"},"category_id_list":{"type":"string","description":"Deprecated. Prefer category_ids"},"product_collection_id":{"type":"string","description":"1688 only. Business product pool ID"},"sale_filters":{"type":"array","description":"1688 only. Maps to saleFilterList","items":{"type":"object","properties":{"sale_type":{"type":"string","enum":["sales7","sales14","sales30","totalSales"]},"sale_start":{"type":"string"},"sale_end":{"type":"string"}},"required":["sale_type"]}},"keyword_translate":{"type":"boolean","description":"1688 only"},"language":{"type":"string","default":"en","description":"Target locale for translated product text. Mapped per channel: 1688 → offerQueryParam.country + form language; Taobao → IOP language (zh* → cn). Not the Portal UI locale — pass in JSON body. See docs/api/i18n.md.","example":"en"}},"required":["channel","keyword"]}}}},"responses":{"200":{"description":"standard: unified HIOBuy model; upstream: UpstreamApiResponse with vendor JSON","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"object","description":"Vendor passthrough envelope when response_format=upstream","properties":{"channel":{"type":"string","example":"1688"},"response_format":{"type":"string","enum":["upstream"]},"upstream_api":{"type":"string","example":"com.alibaba.fenxiao.crossborder/product.search.keywordQuery"},"upstream":{"type":"object","additionalProperties":true,"description":"Official vendor JSON (1688 open API or Taobao IOP)"},"upstream_steps":{"type":"array","description":"Optional prior upstream calls (e.g. image upload before imageQuery)","items":{"type":"object","properties":{"upstream_api":{"type":"string","description":"Vendor API path or IOP route invoked in this step"},"upstream":{"type":"object","additionalProperties":true,"description":"Raw JSON body from that step"}},"required":["upstream_api","upstream"]}},"request_id":{"type":"string","example":"req_abc123"}},"required":["channel","response_format","upstream_api","upstream"]}]}}}},"429":{"description":"Rate limit or channel quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quotaExceeded":{"value":{"error":{"code":"QUOTA_EXCEEDED","message":"Shared daily plan quota exceeded. Contact HIOBuy support.","request_id":"req_example"}}},"platformQuotaExceeded":{"value":{"error":{"code":"PLATFORM_QUOTA_EXCEEDED","message":"Channel capacity is temporarily unavailable. Contact HIOBuy support.","request_id":"req_example"}}}}}}}}}},"/v1/products/search-by-image":{"post":{"summary":"Image search (1688, Taobao, or Weidian; standard or upstream)","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"response_format":{"type":"string","enum":["standard","upstream"],"default":"standard","description":"Response shape: \"standard\" (default) returns HIOBuy unified models; \"upstream\" returns vendor raw JSON in `upstream` (see UpstreamApiResponse)."},"channel":{"type":"string","enum":["1688","taobao","weidian"]},"image_id":{"type":"string","description":"From POST /v1/products/upload-image; skips re-upload (maps to 1688 imageId / Taobao image_id)"},"image_url":{"type":"string","description":"Public image URL; required for Weidian image search"},"image_base64":{"type":"string","description":"Base64 image data; omit when image_id is provided. Request body max 6MB — reduce file size if rejected."},"image_address":{"type":"string","description":"1688/alicdn image URL passed to imageQuery"},"region":{"type":"string","description":"Crop region e.g. 266,799,48,581"},"filter":{"type":"string"},"sort":{"type":"string","description":"1688 upstream sort JSON, e.g. {\"price\":\"asc\"} | {\"monthSold\":\"desc\"} | {\"rePurchaseRate\":\"desc\"}, or Taobao tokens PRICE_ASC / PRICE_DESC / SALE_QTY_ASC / SALE_QTY_DESC. Overrides sort_field/sort_order. Unknown 1688 keys are ignored by 1688."},"sort_field":{"type":"string","enum":["price","sales","credit","bid","sale","monthSold","rePurchaseRate","PRICE_ASC","PRICE_DESC","SALE_QTY_ASC","SALE_QTY_DESC"],"description":"Same as keyword search: price / sales / credit (maps to price / monthSold / rePurchaseRate), or Taobao tokens. Legacy bid/sale/monthSold also accepted."},"sort_order":{"type":"string","enum":["asc","desc"],"description":"1688 only. Used with sort_field (default asc)"},"price_start":{"type":"string"},"price_end":{"type":"string"},"category_id":{"type":"integer"},"keyword":{"type":"string","description":"Refine within image results"},"auxiliary_text":{"type":"string"},"product_collection_id":{"type":"string"},"keyword_translate":{"type":"boolean"},"page":{"type":"integer"},"page_size":{"type":"integer","maximum":100,"description":"Maximum 100 for Weidian; 50 for 1688/Taobao"},"language":{"type":"string","default":"en","description":"Target locale for translated product text. Mapped per channel: 1688 → offerQueryParam.country + form language; Taobao → IOP language (zh* → cn). Not the Portal UI locale — pass in JSON body. See docs/api/i18n.md.","example":"en"}},"required":["channel"]}}}},"responses":{"200":{"description":"standard: unified HIOBuy model; upstream: UpstreamApiResponse with vendor JSON","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"object","description":"Vendor passthrough envelope when response_format=upstream","properties":{"channel":{"type":"string","example":"1688"},"response_format":{"type":"string","enum":["upstream"]},"upstream_api":{"type":"string","example":"com.alibaba.fenxiao.crossborder/product.search.keywordQuery"},"upstream":{"type":"object","additionalProperties":true,"description":"Official vendor JSON (1688 open API or Taobao IOP)"},"upstream_steps":{"type":"array","description":"Optional prior upstream calls (e.g. image upload before imageQuery)","items":{"type":"object","properties":{"upstream_api":{"type":"string","description":"Vendor API path or IOP route invoked in this step"},"upstream":{"type":"object","additionalProperties":true,"description":"Raw JSON body from that step"}},"required":["upstream_api","upstream"]}},"request_id":{"type":"string","example":"req_abc123"}},"required":["channel","response_format","upstream_api","upstream"]}]}}}}}}},"/v1/accounts/openuid/encrypt":{"post":{"summary":"1688 loginId to openUid (loginid.openuid.encrypt)","description":"Manual use only; do not batch. Requires 1688 OAuth on the app.","tags":["Accounts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"login_id":{"type":"string","description":"1688 loginId"}},"required":["login_id"]}}}},"responses":{"200":{"description":"open_uid for the given login_id"}}}},"/v1/accounts/openuid/wangwang-nick":{"post":{"summary":"1688 openUid to Wangwang nick (wangwangnick.openuid.decrypt)","description":"Manual Wangwang launch only; do not batch or display nick as plain PII. Requires 1688 OAuth.","tags":["Accounts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"open_uid":{"type":"string","description":"1688 openUid"}},"required":["open_uid"]}}}},"responses":{"200":{"description":"wangwang_nick to invoke Wangwang for open_uid"}}}},"/v1/accounts/openuid/wangwang-url":{"post":{"summary":"1688 openUid to Wangwang chat URL (account.wangwangUrl.get)","description":"Returns a URL to open Wangwang chat for the given openUid. Manual use only; do not batch. Requires 1688 OAuth.","tags":["Accounts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"open_uid":{"type":"string","description":"Chat target openUid (maps to upstream toOpenUid)"}},"required":["open_uid"]}}}},"responses":{"200":{"description":"wangwang_url to open chat for open_uid"}}}},"/v1/accounts/1688/register":{"post":{"summary":"1688 cross-border member register (account.user.register)","description":"Registers an end-user as a 1688 cross-border member. Caller supplies out_login_id and out_member_id (ISV-side user identifiers). Requires 1688 OAuth.","tags":["Accounts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string","description":"Country code (1688 enum, e.g. japan)"},"site":{"type":"string","description":"ISV site id: lowercase, no spaces, max 16 chars"},"out_login_id":{"type":"string","description":"End-user login id at ISV (max 60)"},"out_member_id":{"type":"string","description":"End-user unique id at ISV (max 60)"},"email":{"type":"string"},"mobile":{"type":"string"},"mobile_area":{"type":"string","description":"Mobile region (1688 enum, e.g. JP)"},"ip":{"type":"string","description":"User IPv4 address"}},"required":["country","site","out_login_id","out_member_id","email","mobile","mobile_area","ip"]}}}},"responses":{"200":{"description":"Registration result (registered=true on success)"}}}},"/v1/products/pool/total":{"post":{"summary":"1688 product pool total count (pool.product.total)","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["1688"]},"offer_pool_id":{"type":"string","description":"Pool/pallet ID"},"category_id":{"type":"string"}},"required":["channel","offer_pool_id"]}}}},"responses":{"200":{"description":"Total product count in pool"}}}},"/v1/products/pool/pull":{"post":{"summary":"Pull products from 1688 offer pool (pool.product.pull)","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["1688"]},"offer_pool_id":{"type":"string","description":"Pool ID from business partner"},"task_id":{"type":"string","description":"Same task_id for all pages of one pool sync"},"page":{"type":"integer"},"page_size":{"type":"integer","maximum":1000},"language":{"type":"string"},"category_id":{"type":"string"},"sort_field":{"type":"string","enum":["order1m","buyer1m"]},"sort_type":{"type":"string","enum":["ASC","DESC"]}},"required":["channel","offer_pool_id","task_id"]}}}},"responses":{"200":{"description":"Pool product offer IDs"}}}},"/v1/products/categories/get":{"post":{"summary":"1688 native category list by ID (alibaba.category.get)","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["1688"]},"category_id":{"type":"string","description":"Category ID; use 0 for all level-1 categories"}},"required":["channel","category_id"]}}}},"responses":{"200":{"description":"Native Chinese category list (3-level tree)"}}}},"/v1/products/categories/get-by-id":{"post":{"summary":"1688 category by ID with children (getById)","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["1688"]},"category_id":{"type":"string"},"language":{"type":"string","description":"e.g. ja, en"},"parent_category_id":{"type":"string"},"out_member_id":{"type":"string"}},"required":["channel","category_id","language"]}}}},"responses":{"200":{"description":"Category tree node with children"}}}},"/v1/products/categories/attributes":{"post":{"summary":"1688 leaf category attributes (alibaba.category.attribute.get)","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["1688"]},"category_id":{"type":"string","description":"Leaf category ID (categoryID)"},"web_site":{"type":"string","enum":["1688","alibaba"],"default":"1688"},"scene":{"type":"string","enum":["","processing"],"description":"Optional scene"}},"required":["channel","category_id"]}}}},"responses":{"200":{"description":"Category attributes and cascade map"}}}},"/v1/products/categories/search":{"post":{"summary":"1688 category lookup by name (getByKeyword)","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["1688"]},"language":{"type":"string","description":"e.g. ja, en"},"category_name":{"type":"string","description":"Fuzzy category name (cateName)"},"out_member_id":{"type":"string"}},"required":["channel","language","category_name"]}}}},"responses":{"200":{"description":"Category translation list"}}}},"/v1/products/seller/search":{"post":{"summary":"Search products within a 1688 or Weidian seller shop","description":"1688 uses querySellerOfferList and seller_open_id. Weidian uses vdian.item.getItemsForBuyer and shop_id, with optional item/update/category filters. Weidian supports response_format=upstream for the complete SKU and category payload.","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["1688","weidian"]},"seller_open_id":{"type":"string","description":"1688 sellerOpenId; accepted as a Weidian shop_id alias"},"shop_id":{"type":"string","description":"Required for Weidian — shop ID"},"keyword":{"type":"string","description":"Optional in-shop keyword filter"},"page":{"type":"integer"},"page_size":{"type":"integer","minimum":1,"maximum":50},"item_id":{"type":"string","description":"Weidian only — exact item ID filter"},"update_start":{"type":"string","description":"Weidian only — yyyy-MM-dd HH:mm:ss"},"update_end":{"type":"string","description":"Weidian only — yyyy-MM-dd HH:mm:ss"},"sort_rule":{"type":"integer","enum":[1,2,3,4],"description":"Weidian only — 1 sales asc, 2 sales desc, 3 price asc, 4 price desc"},"language":{"type":"string"},"currency":{"type":"string"},"filter":{"type":"string"},"sort":{"type":"string","description":"1688 upstream sort JSON, e.g. {\"price\":\"asc\"} | {\"monthSold\":\"desc\"} | {\"rePurchaseRate\":\"desc\"}, or Taobao tokens PRICE_ASC / PRICE_DESC / SALE_QTY_ASC / SALE_QTY_DESC. Overrides sort_field/sort_order. Unknown 1688 keys are ignored by 1688."},"sort_field":{"type":"string","enum":["price","sales","credit","bid","sale","monthSold","rePurchaseRate","PRICE_ASC","PRICE_DESC","SALE_QTY_ASC","SALE_QTY_DESC"],"description":"Same as keyword search: price / sales / credit (maps to price / monthSold / rePurchaseRate), or Taobao tokens. Legacy bid/sale/monthSold also accepted."},"sort_order":{"type":"string","enum":["asc","desc"],"description":"1688 only. Used with sort_field (default asc)"},"price_start":{"type":"string"},"price_end":{"type":"string"},"category_id":{"type":"integer"},"response_format":{"type":"string","enum":["standard","upstream"],"description":"upstream is currently supported for Weidian"}},"required":["channel"]}}}},"responses":{"200":{"description":"Product list for seller shop"}}}},"/v1/products/top-keywords":{"post":{"summary":"1688 category hot search keywords (topKeyword)","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["1688"]},"category_id":{"type":"string","description":"1688 category id (sourceId)"},"language":{"type":"string","default":"en"},"hot_keyword_type":{"type":"string","enum":["cate"],"default":"cate"}},"required":["channel","category_id"]}}}},"responses":{"200":{"description":"Hot keywords list"}}}},"/v1/products/top-list":{"post":{"summary":"1688 product rank list (product.topList.query)","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["1688"]},"rank_id":{"type":"string","description":"Rank id (category id)"},"rank_type":{"type":"string","description":"complex | hot | goodPrice (see 1688 cross-border guide)"},"limit":{"type":"integer","minimum":1,"maximum":20},"language":{"type":"string","default":"en"}},"required":["channel","rank_id","rank_type","limit"]}}}},"responses":{"200":{"description":"Rank list with products"}}}},"/v1/products/daily-sales-trend":{"post":{"summary":"1688 daily sell quantity trend (product.analyze.getPerdaySellQuantityTrend)","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["1688"]},"product_id":{"type":"string","description":"1688 offerId"},"start_date":{"type":"string","description":"Start date yyyyMMdd"},"end_date":{"type":"string","description":"End date yyyyMMdd (max 90-day span)"}},"required":["channel","product_id","start_date","end_date"]}}}},"responses":{"200":{"description":"Daily sales trend points"}}}},"/v1/products/freight/estimate":{"post":{"summary":"Domestic freight estimate (via order preview)","tags":["Products"],"description":"Uses the same request body as `POST /v1/orders/preview` (`channel`, `receiver`, `lines`).\nInternally calls order preview and returns **shipping only** (`freight` + per-seller breakdown).\nMore accurate than legacy province/city code freight APIs; supports **1688**, **taobao**, and **weidian**.\nWeidian uses `vdian.open.order.confirmOrder` v1.2 and returns `preview_id` for later formal order creation.\nBillable weight: **2** units (same upstream cost as preview).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["1688","taobao","weidian"]},"receiver":{"type":"object","description":"Domestic inbound address (same as order preview)","properties":{"name":{"type":"string"},"mobile":{"type":"string"},"province":{"type":"string"},"city":{"type":"string"},"district":{"type":"string"},"town":{"type":"string"},"address":{"type":"string"},"zip":{"type":"string"},"address_id":{"type":"string"},"district_code":{"type":"string"}},"required":["name","mobile","province","city","address"]},"lines":{"type":"array","minItems":1,"items":{"type":"object","properties":{"id":{"type":"string","description":"Preferred. Same as search/detail `id`. `offer_id` and `mi_id` remain compatible."},"offer_id":{"type":"string","description":"Compatible alias of `id`"},"mi_id":{"type":"string","description":"Compatible Taobao alias of `id`"},"spec_id":{"type":"string"},"quantity":{"type":"number","minimum":1}},"required":["spec_id","quantity"]}},"flow":{"type":"string","description":"1688 only; default general"},"need_supplychain_service":{"type":"boolean","description":"Taobao only; default false"},"note":{"type":"string","description":"Weidian buyer note"}},"required":["channel","receiver","lines"]}}}},"responses":{"200":{"description":"Shipping estimate in fen"}}}},"/v1/products/parse":{"post":{"summary":"Parse product URL (auto-detect channel)","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"language":{"type":"string"},"currency":{"type":"string"}},"required":["url"]}}}},"responses":{"200":{"description":"standard: StandardProductDetailResponse; upstream: UpstreamApiResponse with vendor JSON","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/StandardProductDetailResponse"},{"$ref":"#/components/schemas/UpstreamApiResponse"}]}}}}}}},"/v1/products/translate":{"post":{"summary":"Translate product fields","tags":["Products"],"responses":{"200":{"description":"Translated product"}}}},"/v1/orders":{"get":{"summary":"Orders (legacy hint)","tags":["Orders"],"responses":{"200":{"description":"Points to POST /v1/orders/list"}}},"post":{"summary":"Orders (legacy hint)","tags":["Orders"],"responses":{"200":{"description":"Points to POST /v1/orders/create or /v1/orders/1688/create / /v1/orders/taobao/create"}}}},"/v1/orders/refund/create":{"post":{"summary":"1688 or Weidian create refund application","description":"1688 uses alibaba.trade.createRefund fields. Weidian uses open.buyerCreateRefund with channel=weidian, item_id, sku_id, refund_type, refund_good_status, buyer_reason_id, refund_item_fee_cents, and refund_express_fee_cents. Amounts are in cents. Weidian supports response_format=upstream.","tags":["Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["1688","weidian"],"default":"1688"},"order_id":{"type":"string"},"item_id":{"type":"string","description":"Weidian only — refunded item ID"},"sku_id":{"type":"string","description":"Weidian only — SKU ID; use 0 for a single-SKU item"},"refund_type":{"type":"integer","enum":[1,2],"description":"Weidian only — 1 refund only, 2 return and refund"},"refund_good_status":{"type":"integer","enum":[0,1],"description":"Weidian only — 0 not received, 1 received"},"buyer_reason_id":{"type":"integer","minimum":1,"maximum":14,"description":"Weidian only — 1-6 if not received; 7-14 if received"},"refund_item_fee_cents":{"type":"integer","minimum":0,"description":"Weidian only — requested item refund in cents"},"refund_express_fee_cents":{"type":"integer","minimum":0,"description":"Weidian only — requested shipping refund in cents"},"order_entry_ids":{"type":"array","items":{"type":"string"}},"dispute_request":{"type":"string","enum":["refund","returnRefund"]},"apply_payment_cents":{"type":"integer"},"apply_carriage_cents":{"type":"integer"},"apply_reason_id":{"type":"string"},"description":{"type":"string","maxLength":200,"description":"1688 requires 2-150 characters; Weidian allows up to 200"},"goods_status":{"type":"string"},"vouchers":{"type":"array","maxItems":5,"items":{"type":"string"}},"entry_counts":{"type":"array","items":{"type":"object","properties":{"entry_id":{"type":"string"},"count":{"type":"integer"}}}},"custom_refund":{"type":"boolean"},"refund_remark":{"type":"string"},"response_format":{"type":"string","enum":["standard","upstream"],"description":"upstream is currently supported for Weidian"}},"required":["order_id"]}}}},"responses":{"201":{"description":"Refund created"}}}},"/v1/orders/refund/reasons":{"post":{"summary":"1688 and Weidian refund reason list","description":"1688 queries alibaba.trade.getRefundReasonList for a specific order. Weidian uses its fixed official reason catalog: refund_good_status=0 returns IDs 1-6, and refund_good_status=1 returns IDs 7-14.","tags":["Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"channel":{"type":"string","enum":["1688"]},"order_id":{"type":"string"},"order_entry_ids":{"type":"array","items":{"type":"string"}},"goods_status":{"type":"string","enum":["refundWaitSellerSend","refundWaitBuyerReceive","refundBuyerReceived","aftersaleBuyerNotReceived","aftersaleBuyerReceived"]}},"required":["order_id","order_entry_ids","goods_status"]},{"type":"object","properties":{"channel":{"type":"string","enum":["weidian"]},"refund_good_status":{"type":"integer","enum":[0,1],"description":"0 not received; 1 received"},"goods_status":{"type":"string","enum":["not_received","received"],"description":"Unified alias for refund_good_status; provide either field"}},"required":["channel"],"anyOf":[{"required":["refund_good_status"]},{"required":["goods_status"]}]}]}}}},"responses":{"200":{"description":"Refund reason list"}}}},"/v1/orders/refund/detail":{"post":{"summary":"Weidian buyer refund detail","description":"Calls open.buyerQueryRefundDetail by refund number. Standard mode maps the amount in cents, workflow statuses, merchant return address, and refunded item IDs. Supports response_format=upstream.","tags":["Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"response_format":{"type":"string","enum":["standard","upstream"],"default":"standard","description":"Response shape: \"standard\" (default) returns HIOBuy unified models; \"upstream\" returns vendor raw JSON in `upstream` (see UpstreamApiResponse)."},"channel":{"type":"string","enum":["weidian"]},"refund_id":{"type":"string","description":"Refund number; refund_no and refundNo are accepted aliases"}},"required":["channel","refund_id"]}}}},"responses":{"200":{"description":"standard: unified HIOBuy model; upstream: UpstreamApiResponse with vendor JSON","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"object","description":"Vendor passthrough envelope when response_format=upstream","properties":{"channel":{"type":"string","example":"1688"},"response_format":{"type":"string","enum":["upstream"]},"upstream_api":{"type":"string","example":"com.alibaba.fenxiao.crossborder/product.search.keywordQuery"},"upstream":{"type":"object","additionalProperties":true,"description":"Official vendor JSON (1688 open API or Taobao IOP)"},"upstream_steps":{"type":"array","description":"Optional prior upstream calls (e.g. image upload before imageQuery)","items":{"type":"object","properties":{"upstream_api":{"type":"string","description":"Vendor API path or IOP route invoked in this step"},"upstream":{"type":"object","additionalProperties":true,"description":"Raw JSON body from that step"}},"required":["upstream_api","upstream"]}},"request_id":{"type":"string","example":"req_abc123"}},"required":["channel","response_format","upstream_api","upstream"]}]}}}}}}},"/v1/orders/refund/list":{"post":{"summary":"Weidian buyer refund list","description":"Calls buyer.query.refund.list. Supports creation/update time ranges, 0-based page_num or 1-based page, and response_format=upstream. Standard mode preserves large IDs as strings and maps refund amounts in cents.","tags":["Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"response_format":{"type":"string","enum":["standard","upstream"],"default":"standard","description":"Response shape: \"standard\" (default) returns HIOBuy unified models; \"upstream\" returns vendor raw JSON in `upstream` (see UpstreamApiResponse)."},"channel":{"type":"string","enum":["weidian"]},"page":{"type":"integer","minimum":1,"default":1},"page_num":{"type":"integer","minimum":0,"default":0},"page_size":{"type":"integer","minimum":1,"maximum":50,"default":50},"add_start":{"type":"string"},"add_end":{"type":"string"},"update_start":{"type":"string"},"update_end":{"type":"string"},"create_start_time":{"type":"string"},"create_end_time":{"type":"string"},"modify_start_time":{"type":"string"},"modify_end_time":{"type":"string"}},"required":["channel"]}}}},"responses":{"200":{"description":"standard: unified HIOBuy model; upstream: UpstreamApiResponse with vendor JSON","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"object","description":"Vendor passthrough envelope when response_format=upstream","properties":{"channel":{"type":"string","example":"1688"},"response_format":{"type":"string","enum":["upstream"]},"upstream_api":{"type":"string","example":"com.alibaba.fenxiao.crossborder/product.search.keywordQuery"},"upstream":{"type":"object","additionalProperties":true,"description":"Official vendor JSON (1688 open API or Taobao IOP)"},"upstream_steps":{"type":"array","description":"Optional prior upstream calls (e.g. image upload before imageQuery)","items":{"type":"object","properties":{"upstream_api":{"type":"string","description":"Vendor API path or IOP route invoked in this step"},"upstream":{"type":"object","additionalProperties":true,"description":"Raw JSON body from that step"}},"required":["upstream_api","upstream"]}},"request_id":{"type":"string","example":"req_abc123"}},"required":["channel","response_format","upstream_api","upstream"]}]}}}}}}},"/v1/orders/refund/return-goods":{"post":{"summary":"1688 submit refund return logistics (alibaba.trade.refund.returnGoods)","description":"After seller approves return. Requires logistics company code from 1688 logistics API and optional voucher URLs from uploadRefundVoucher.","tags":["Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"refund_id":{"type":"string"},"logistics_company_no":{"type":"string"},"freight_bill":{"type":"string"},"description":{"type":"string","minLength":2,"maxLength":200},"vouchers":{"type":"array","maxItems":10,"items":{"type":"string"}}},"required":["refund_id","logistics_company_no","freight_bill"]}}}},"responses":{"200":{"description":"Return goods info submitted"}}}},"/v1/orders/refund/cancel":{"post":{"summary":"1688 cancel refund application (alibaba.trade.cancelRefund)","tags":["Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"refund_id":{"type":"string"}},"required":["refund_id"]}}}},"responses":{"200":{"description":"Refund application cancelled"}}}},"/v1/orders/refund/max-fee":{"post":{"summary":"1688 max refundable fee (alibaba.trade.getMaxRefundFee)","description":"Query max refundable goods/post/total fees when applying for refund. Amounts in cents.","tags":["Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"string"},"goods_status":{"type":"string","enum":["refundWaitSellerSend","refundWaitBuyerReceive","refundBuyerReceived","aftersaleBuyerNotReceived","aftersaleBuyerReceived"]},"items":{"type":"array","items":{"type":"object","properties":{"entry_id":{"type":"string"},"count":{"type":"integer"}},"required":["entry_id","count"]}},"refund_id":{"type":"string"}},"required":["order_id","goods_status","items"]}}}},"responses":{"200":{"description":"Max refund fee limits"}}}},"/v1/orders/memo":{"post":{"summary":"1688 add or replace order memo (alibaba.order.memoAdd)","description":"Overwrites previous memo. remark_icon: 1 red, 2 blue, 3 green, 4 yellow.","tags":["Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"string"},"memo":{"type":"string"},"remark_icon":{"type":"string","enum":["1","2","3","4"]}},"required":["order_id","memo","remark_icon"]}}}},"responses":{"200":{"description":"Memo updated"}}}},"/v1/orders/list":{"post":{"summary":"1688 and Weidian buyer order list (standard or upstream)","description":"Weidian buyer.order.list returns a lightweight list of order IDs. Call /v1/orders/detail for complete order data. Weidian accepts either page (1-based) or page_num (0-based), supports at most 10,000 records per query, and defaults to the latest 31 days when no complete creation range or update_start is supplied.","tags":["Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"response_format":{"type":"string","enum":["standard","upstream"],"default":"standard","description":"Response shape: \"standard\" (default) returns HIOBuy unified models; \"upstream\" returns vendor raw JSON in `upstream` (see UpstreamApiResponse)."},"channel":{"type":"string","enum":["1688","weidian"]},"page":{"type":"integer","minimum":1,"default":1},"page_num":{"type":"integer","minimum":0,"description":"Weidian native 0-based page number"},"page_size":{"type":"integer","minimum":1,"maximum":50,"default":50},"order_type":{"type":"string","enum":["unship","unpay","shiped","finish","close","all"],"description":"Weidian native order status"},"order_status":{"type":"string","description":"1688 status, or Weidian unified alias such as wait_payment, wait_shipment, wait_receive, completed, or closed"},"refund_status":{"type":"string"},"add_start":{"type":"string","description":"Weidian creation range start (yyyy-MM-dd HH:mm:ss)"},"add_end":{"type":"string","description":"Weidian creation range end (yyyy-MM-dd HH:mm:ss)"},"update_start":{"type":"string","description":"Weidian update range start (yyyy-MM-dd HH:mm:ss)"},"update_end":{"type":"string","description":"Weidian update range end (yyyy-MM-dd HH:mm:ss)"},"create_start_time":{"type":"string"},"create_end_time":{"type":"string"},"modify_start_time":{"type":"string"},"modify_end_time":{"type":"string"},"biz_types":{"type":"array","items":{"type":"string"}},"product_name":{"type":"string"},"seller_login_id":{"type":"string"}}}}}},"responses":{"200":{"description":"standard: unified HIOBuy model; upstream: UpstreamApiResponse with vendor JSON","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"object","description":"Vendor passthrough envelope when response_format=upstream","properties":{"channel":{"type":"string","example":"1688"},"response_format":{"type":"string","enum":["upstream"]},"upstream_api":{"type":"string","example":"com.alibaba.fenxiao.crossborder/product.search.keywordQuery"},"upstream":{"type":"object","additionalProperties":true,"description":"Official vendor JSON (1688 open API or Taobao IOP)"},"upstream_steps":{"type":"array","description":"Optional prior upstream calls (e.g. image upload before imageQuery)","items":{"type":"object","properties":{"upstream_api":{"type":"string","description":"Vendor API path or IOP route invoked in this step"},"upstream":{"type":"object","additionalProperties":true,"description":"Raw JSON body from that step"}},"required":["upstream_api","upstream"]}},"request_id":{"type":"string","example":"req_abc123"}},"required":["channel","response_format","upstream_api","upstream"]}]}}}}}}},"/v1/orders/logistics/info":{"post":{"summary":"1688 logistics info buyer view (getLogisticsInfos.buyerView)","description":"Sender, receiver, goods; pair with /logistics/trace for steps.","tags":["Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"string"},"website":{"type":"string","enum":["1688"],"default":"1688"},"fields":{"type":"string","description":"e.g. company.name,sender,receiver,sendgood"}},"required":["order_id"]}}}},"responses":{"200":{"description":"Logistics shipments with contacts and goods"}}}},"/v1/orders/logistics/trace":{"post":{"summary":"Unified logistics trace (1688 + Taobao + Weidian)","description":"1688: alibaba.trade.getLogisticsTraceInfo.buyerView by order_id (+ optional logistics_id). Taobao: resolves sub_purchase_order_id via purchase query, then /logistics/detail/get. Weidian: buyer.order.logistics by order_id + express_no. Supports response_format=upstream.","tags":["Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["1688","taobao","weidian"]},"order_id":{"type":"string","description":"1688 trade id, Taobao purchase_id, or Weidian order id"},"logistics_id":{"type":"string","description":"1688 only — filter by logistics bill id"},"website":{"type":"string","enum":["1688"],"default":"1688"},"express_no":{"type":"string","description":"Required for Weidian — logistics tracking number"},"response_format":{"type":"string","enum":["standard","upstream"]}},"required":["channel"]}}}},"responses":{"200":{"description":"Unified packages[] with trace steps"}}}},"/v1/orders/1688/logistics/trace":{"post":{"summary":"1688 logistics trace (shortcut)","tags":["Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"string"},"logistics_id":{"type":"string"},"website":{"type":"string","enum":["1688"],"default":"1688"}},"required":["order_id"]}}}},"responses":{"200":{"description":"Logistics trace"}}}},"/v1/orders/taobao/logistics/trace":{"post":{"summary":"Taobao logistics trace (shortcut)","tags":["Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"string","description":"Taobao purchase_id (main order)"}},"required":["order_id"]}}}},"responses":{"200":{"description":"Logistics trace"}}}},"/v1/orders/address/parse":{"post":{"summary":"1688 overseas address parse (trade.address.parseText)","description":"Parse country/province/city/area into standardized address_code. Requires 1688 OAuth.","tags":["Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string"},"province":{"type":"string"},"city":{"type":"string"},"area":{"type":"string"}},"required":["country","province","city","area"]}}}},"responses":{"200":{"description":"address_code and normalized country/province/city/area"}}}},"/v1/orders/address/update":{"post":{"summary":"1688 buyer update receive address (order.receiveAddress.buyerUpdate)","description":"Seller may need to confirm for remote areas or freight changes.","tags":["Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"string"},"receive_address":{"type":"object","required":["address_id","full_name","mobile","phone","post_code","province_text","province_code","city_text","city_code","area_text","area_code","town_text","town_code","address","district_code"]}},"required":["order_id","receive_address"]}}}},"responses":{"200":{"description":"address_update_accepted boolean from upstream"}}}},"/v1/warehouse":{"get":{"summary":"Warehouse status","tags":["Warehouse"],"responses":{"200":{"description":"OK"}}}},"/v1/shipments":{"post":{"summary":"Create shipment","tags":["Shipping"],"responses":{"201":{"description":"Created"}}}},"/v1/tracking":{"get":{"summary":"Track shipment","tags":["Tracking"],"responses":{"200":{"description":"OK"}}}},"/v1/orders/preview":{"post":{"summary":"Order preview (1688, Taobao, or Weidian)","tags":["Orders"],"description":"Unified preview: **`channel`**, **`receiver`** (domestic inbound address), **`lines`**.\n\n| `channel` | Required line fields | Upstream |\n| --- | --- | --- |\n| `1688` | `id` (or `offer_id`), `spec_id`, `quantity` | `alibaba.createOrder.preview` |\n| `taobao` | `id` (or `mi_id` / `offer_id`), `spec_id`, `quantity` | auto `batch-check` → `/purchase/order/render` |\n| `weidian` | `id` (or `offer_id`), `spec_id` (`0` for a no-SKU item), `quantity` | `vdian.open.order.confirmOrder` v1.2 |\n\nWeidian returns `preview_id`, which must be retained for formal order creation. Amounts are in CNY fen. This upstream API is available only to invited applications.\n\nPrefer `lines[].id` = search/detail `id`; it is copied to `offer_id`. If both are sent, **`offer_id` wins**. `mi_id` stays compatible. Do **not** pass Taobao `source_product_id`. Taobao `id`/`mi_id` rotates periodically — re-fetch before preview. Numeric values skip batch-check (already mpId).\n\nPreview is read-only and calls the marketplace directly in both self and warehouse procurement modes. Warehouse mode uses the App's stored warehouse channel token; it does not forward preview to the warehouse procurement API.\n\nBillable weight: **2** units.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"response_format":{"type":"string","enum":["standard","upstream"],"default":"standard","description":"Response shape: \"standard\" (default) returns HIOBuy unified models; \"upstream\" returns vendor raw JSON in `upstream` (see UpstreamApiResponse)."},"channel":{"type":"string","enum":["1688","taobao"]},"receiver":{"type":"object","description":"Domestic inbound / warehouse address. Same shape for 1688, Taobao, and Weidian.","properties":{"name":{"type":"string","description":"Recipient name"},"mobile":{"type":"string","description":"Contact mobile (single field; no separate phone required)"},"province":{"type":"string","description":"Province / state"},"city":{"type":"string"},"district":{"type":"string","description":"District / area (1688 area_text); required without address_id"},"town":{"type":"string","description":"Town / sub-district (1688 town_text); optional"},"address":{"type":"string","description":"Street address"},"zip":{"type":"string"},"country":{"type":"string","default":"中国"},"address_id":{"type":"string","description":"1688 saved address id (optional)"},"district_code":{"type":"string","description":"1688 district code (optional)"}},"required":["name","mobile","province","city","address"]},"lines":{"type":"array","description":"Order lines. Prefer `id` + `spec_id` + `quantity` (same `id` as search/detail). `offer_id` and `mi_id` remain compatible aliases of `id`.","items":{"type":"object","properties":{"id":{"type":"string","description":"Preferred. Same as search/detail `id` (1688/Weidian `offerId`; Taobao `mi_id`). Taobao `id` rotates periodically — do not cache long-term."},"offer_id":{"type":"string","description":"Compatible alias of `id`. Existing clients may keep sending `offer_id`."},"mi_id":{"type":"string","description":"Compatible Taobao alias of `id`. Existing clients may keep sending `mi_id`."},"spec_id":{"type":"string","description":"1688: `specId` from detail `variants[].sku_id`. Taobao: traffic `sku_id` from detail variants (or already-resolved mpSkuId)."},"item_id":{"type":"string","description":"Deprecated alias of `id` / `offer_id` (Taobao)"},"sku_id":{"type":"string","description":"Deprecated alias of spec_id (Taobao)"},"quantity":{"type":"number","minimum":1}},"required":["spec_id","quantity"]},"minItems":1},"flow":{"type":"string","enum":["general","fenxiao","saleproxy","paired","boutiquefenxiao","boutiquepifa"],"description":"1688 only; default general"},"need_supplychain_service":{"type":"boolean","default":false,"description":"Taobao only. false = domestic warehouse inbound (default); true = cross-border supply chain"},"isv_biz_type":{"type":"string","description":"1688 only"},"out_order_id":{"type":"string"},"note":{"type":"string","description":"Weidian buyer note (`param.note`); buyer_message/message/order_remark are accepted aliases"}},"required":["channel","receiver","lines"]}}}},"responses":{"200":{"description":"standard: normalized StandardOrderPreviewResult; upstream: raw vendor status in UpstreamApiResponse","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Normalized preview. success=true means the payable total, seller groups, requested lines, availability, and applicable trade mode passed validation.","properties":{"channel":{"type":"string","enum":["1688","taobao","weidian"]},"success":{"type":"boolean"},"preview_id":{"type":"string","description":"Weidian pre-order id required by the formal order API"},"total":{"type":"object","properties":{"merchandise":{"description":"Money in minor units. null means unknown; a known zero is Money(amount=0).","oneOf":[{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},{"type":"null"}]},"shipping":{"description":"Money in minor units. null means unknown; a known zero is Money(amount=0).","oneOf":[{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},{"type":"null"}]},"payment":{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]}},"required":["merchandise","shipping","payment"]},"unavailable_lines":{"type":"array","items":{"type":"object","properties":{"offer_id":{"type":"string"},"spec_id":{"type":"string"},"quantity":{"type":"number","minimum":1},"unit_price":{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},"line_total":{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},"shipping_from":{"oneOf":[{"type":"string"},{"type":"null"}]},"estimated_delivery":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["offer_id","spec_id"]}},"sellers":{"type":"array","items":{"type":"object","properties":{"seller_id":{"oneOf":[{"type":"string"},{"type":"null"}]},"seller_name":{"oneOf":[{"type":"string"},{"type":"null"}]},"shipping_fee":{"description":"Money in minor units. null means unknown; a known zero is Money(amount=0).","oneOf":[{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},{"type":"null"}]},"order_fee":{"description":"Money in minor units. null means unknown; a known zero is Money(amount=0).","oneOf":[{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"offer_id":{"type":"string"},"spec_id":{"type":"string"},"quantity":{"type":"number","minimum":1},"unit_price":{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},"line_total":{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},"shipping_from":{"oneOf":[{"type":"string"},{"type":"null"}]},"estimated_delivery":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["offer_id","spec_id"]}}},"required":["seller_id","seller_name","shipping_fee","order_fee","lines"]}},"trade_types":{"type":"array","description":"1688 only when applicable.","items":{"type":"object","properties":{"trade_type":{"type":"string"},"trade_type_name":{"type":"string"},"op_support":{"type":"boolean"}},"required":["trade_type"]}},"pay_channels":{"type":"array","items":{}},"promotions":{"type":"object","properties":{"shop":{"type":"array","items":{}},"cargo":{"type":"array","items":{}}}},"code":{"type":"string"},"message":{"type":"string"},"monetary_unit":{"type":"string","enum":["CNY_minor"]},"request_id":{"type":"string"}},"required":["channel","success","total","unavailable_lines","sellers","monetary_unit","request_id"]},{"type":"object","description":"Vendor passthrough envelope when response_format=upstream","properties":{"channel":{"type":"string","example":"1688"},"response_format":{"type":"string","enum":["upstream"]},"upstream_api":{"type":"string","example":"com.alibaba.fenxiao.crossborder/product.search.keywordQuery"},"upstream":{"type":"object","additionalProperties":true,"description":"Official vendor JSON (1688 open API or Taobao IOP)"},"upstream_steps":{"type":"array","description":"Optional prior upstream calls (e.g. image upload before imageQuery)","items":{"type":"object","properties":{"upstream_api":{"type":"string","description":"Vendor API path or IOP route invoked in this step"},"upstream":{"type":"object","additionalProperties":true,"description":"Raw JSON body from that step"}},"required":["upstream_api","upstream"]}},"request_id":{"type":"string","example":"req_abc123"}},"required":["channel","response_format","upstream_api","upstream"]}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid API key or channel authorization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or channel quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quotaExceeded":{"value":{"error":{"code":"QUOTA_EXCEEDED","message":"Shared daily plan quota exceeded. Contact HIOBuy support.","request_id":"req_example"}}},"platformQuotaExceeded":{"value":{"error":{"code":"PLATFORM_QUOTA_EXCEEDED","message":"Channel capacity is temporarily unavailable. Contact HIOBuy support.","request_id":"req_example"}}}}}}},"502":{"description":"Technical/upstream failure; 1688 business failures retain this legacy envelope for compatibility","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orders/create":{"post":{"summary":"Create order (1688, Taobao, or Weidian)","tags":["Orders"],"description":"Unified create: same **`receiver`** + **`lines`** as preview, plus optional external order id and buyer message.\n\n**1688 defaults:** `isv_biz_type=cross`, `use_red_envelope=y` (auto-retry with `n` if upstream error mentions 红包).\n\n**Taobao defaults:** `channel_order_type=PANAMA_DG`, `support_partial_success=false`, `need_supplychain_service=false`.\nAuto-generates `outer_purchase_id` when omitted; auto-fills `purchase_amount` from preview when omitted.\n\n**Weidian:** send `preview_id` returned by preview within 10 minutes. `direct_pay=true` by default creates the order and debits balance; use `false` to create without payment.\n\nBillable weight: **2** units.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"response_format":{"type":"string","enum":["standard","upstream"],"default":"standard","description":"Response shape: \"standard\" (default) returns HIOBuy unified models; \"upstream\" returns vendor raw JSON in `upstream` (see UpstreamApiResponse)."},"channel":{"type":"string","enum":["1688","taobao"]},"receiver":{"type":"object","description":"Domestic inbound / warehouse address. Same shape for 1688, Taobao, and Weidian.","properties":{"name":{"type":"string","description":"Recipient name"},"mobile":{"type":"string","description":"Contact mobile (single field; no separate phone required)"},"province":{"type":"string","description":"Province / state"},"city":{"type":"string"},"district":{"type":"string","description":"District / area (1688 area_text); required without address_id"},"town":{"type":"string","description":"Town / sub-district (1688 town_text); optional"},"address":{"type":"string","description":"Street address"},"zip":{"type":"string"},"country":{"type":"string","default":"中国"},"address_id":{"type":"string","description":"1688 saved address id (optional)"},"district_code":{"type":"string","description":"1688 district code (optional)"}},"required":["name","mobile","province","city","address"]},"lines":{"type":"array","minItems":1,"items":{"type":"object","properties":{"id":{"type":"string","description":"Preferred. Same as search/detail `id` (1688/Weidian `offerId`; Taobao `mi_id`). Taobao `id` rotates periodically — do not cache long-term."},"offer_id":{"type":"string","description":"Compatible alias of `id`. Existing clients may keep sending `offer_id`."},"mi_id":{"type":"string","description":"Compatible Taobao alias of `id`. Existing clients may keep sending `mi_id`."},"spec_id":{"type":"string","description":"1688: `specId` from detail `variants[].sku_id`. Taobao: traffic `sku_id` from detail variants (or already-resolved mpSkuId)."},"item_id":{"type":"string","description":"Deprecated alias of `id` / `offer_id` (Taobao)"},"sku_id":{"type":"string","description":"Deprecated alias of spec_id (Taobao)"},"quantity":{"type":"number","minimum":1}},"required":["spec_id","quantity"]}},"flow":{"type":"string","enum":["general","fenxiao","saleproxy","paired","boutiquefenxiao","boutiquepifa"],"description":"1688 only; default general"},"need_supplychain_service":{"type":"boolean","default":false,"description":"Taobao only"},"buyer_message":{"type":"string","description":"Buyer note — maps to 1688 message / Taobao order_remark"},"message":{"type":"string","description":"1688 buyer note alias"},"order_remark":{"type":"string","description":"Taobao buyer note alias (max 50)"},"external_order_id":{"type":"string","description":"External order ref — 1688 outOrderId / Taobao seller_order_number"},"out_order_id":{"type":"string","description":"1688 external order id alias"},"seller_order_number":{"type":"string","description":"Taobao external order id alias"},"trade_type":{"type":"string","description":"1688 trade type from preview"},"isv_biz_type":{"type":"string","default":"cross","description":"1688 only"},"use_red_envelope":{"type":"string","enum":["y","n"],"default":"y","description":"1688 red envelope; auto-retry with n if upstream mentions 红包"},"outer_purchase_id":{"type":"string","description":"Taobao ISV idempotency key; auto-generated when omitted"},"purchase_amount":{"type":"number","description":"Taobao planned amount (fen); auto from preview when omitted"},"order_source":{"type":"string","description":"Taobao buyer platform name"},"channel_order_type":{"type":"string","enum":["PANAMA_DG","PANAMA"],"default":"PANAMA_DG"},"support_partial_success":{"type":"boolean","default":false}},"required":["channel","receiver","lines"]},{"type":"object","properties":{"response_format":{"type":"string","enum":["standard","upstream"],"default":"standard","description":"Response shape: \"standard\" (default) returns HIOBuy unified models; \"upstream\" returns vendor raw JSON in `upstream` (see UpstreamApiResponse)."},"channel":{"type":"string","enum":["weidian"]},"preview_id":{"type":"string","description":"ID returned by Weidian order preview; valid for 10 minutes"},"direct_pay":{"type":"boolean","default":true,"description":"true: create and debit balance; false: create only"}},"required":["channel","preview_id"]}]}}}},"responses":{"201":{"description":"standard: unified HIOBuy model; upstream: UpstreamApiResponse with vendor JSON","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"object","description":"Vendor passthrough envelope when response_format=upstream","properties":{"channel":{"type":"string","example":"1688"},"response_format":{"type":"string","enum":["upstream"]},"upstream_api":{"type":"string","example":"com.alibaba.fenxiao.crossborder/product.search.keywordQuery"},"upstream":{"type":"object","additionalProperties":true,"description":"Official vendor JSON (1688 open API or Taobao IOP)"},"upstream_steps":{"type":"array","description":"Optional prior upstream calls (e.g. image upload before imageQuery)","items":{"type":"object","properties":{"upstream_api":{"type":"string","description":"Vendor API path or IOP route invoked in this step"},"upstream":{"type":"object","additionalProperties":true,"description":"Raw JSON body from that step"}},"required":["upstream_api","upstream"]}},"request_id":{"type":"string","example":"req_abc123"}},"required":["channel","response_format","upstream_api","upstream"]}]}}}}}}},"/v1/orders/1688/preview":{"post":{"summary":"1688 order preview (channel shortcut)","tags":["Orders"],"description":"Same body as `POST /v1/orders/preview` (`channel` omitted).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"response_format":{"type":"string","enum":["standard","upstream"],"default":"standard","description":"Response shape: \"standard\" (default) returns HIOBuy unified models; \"upstream\" returns vendor raw JSON in `upstream` (see UpstreamApiResponse)."},"receiver":{"type":"object","description":"Domestic inbound / warehouse address. Same shape for 1688, Taobao, and Weidian.","properties":{"name":{"type":"string","description":"Recipient name"},"mobile":{"type":"string","description":"Contact mobile (single field; no separate phone required)"},"province":{"type":"string","description":"Province / state"},"city":{"type":"string"},"district":{"type":"string","description":"District / area (1688 area_text); required without address_id"},"town":{"type":"string","description":"Town / sub-district (1688 town_text); optional"},"address":{"type":"string","description":"Street address"},"zip":{"type":"string"},"country":{"type":"string","default":"中国"},"address_id":{"type":"string","description":"1688 saved address id (optional)"},"district_code":{"type":"string","description":"1688 district code (optional)"}},"required":["name","mobile","province","city","address"]},"lines":{"type":"array","items":{"type":"object","properties":{"offer_id":{"type":"string"},"spec_id":{"type":"string"},"quantity":{"type":"number","minimum":1}},"required":["offer_id","spec_id","quantity"]},"minItems":1},"flow":{"type":"string","enum":["general","fenxiao","saleproxy","paired","boutiquefenxiao","boutiquepifa"]},"isv_biz_type":{"type":"string"},"out_order_id":{"type":"string"}},"required":["receiver","lines"]}}}},"responses":{"200":{"description":"standard: normalized StandardOrderPreviewResult; upstream: raw vendor status in UpstreamApiResponse","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Normalized preview. success=true means the payable total, seller groups, requested lines, availability, and applicable trade mode passed validation.","properties":{"channel":{"type":"string","enum":["1688","taobao","weidian"]},"success":{"type":"boolean"},"preview_id":{"type":"string","description":"Weidian pre-order id required by the formal order API"},"total":{"type":"object","properties":{"merchandise":{"description":"Money in minor units. null means unknown; a known zero is Money(amount=0).","oneOf":[{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},{"type":"null"}]},"shipping":{"description":"Money in minor units. null means unknown; a known zero is Money(amount=0).","oneOf":[{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},{"type":"null"}]},"payment":{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]}},"required":["merchandise","shipping","payment"]},"unavailable_lines":{"type":"array","items":{"type":"object","properties":{"offer_id":{"type":"string"},"spec_id":{"type":"string"},"quantity":{"type":"number","minimum":1},"unit_price":{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},"line_total":{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},"shipping_from":{"oneOf":[{"type":"string"},{"type":"null"}]},"estimated_delivery":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["offer_id","spec_id"]}},"sellers":{"type":"array","items":{"type":"object","properties":{"seller_id":{"oneOf":[{"type":"string"},{"type":"null"}]},"seller_name":{"oneOf":[{"type":"string"},{"type":"null"}]},"shipping_fee":{"description":"Money in minor units. null means unknown; a known zero is Money(amount=0).","oneOf":[{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},{"type":"null"}]},"order_fee":{"description":"Money in minor units. null means unknown; a known zero is Money(amount=0).","oneOf":[{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"offer_id":{"type":"string"},"spec_id":{"type":"string"},"quantity":{"type":"number","minimum":1},"unit_price":{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},"line_total":{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},"shipping_from":{"oneOf":[{"type":"string"},{"type":"null"}]},"estimated_delivery":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["offer_id","spec_id"]}}},"required":["seller_id","seller_name","shipping_fee","order_fee","lines"]}},"trade_types":{"type":"array","description":"1688 only when applicable.","items":{"type":"object","properties":{"trade_type":{"type":"string"},"trade_type_name":{"type":"string"},"op_support":{"type":"boolean"}},"required":["trade_type"]}},"pay_channels":{"type":"array","items":{}},"promotions":{"type":"object","properties":{"shop":{"type":"array","items":{}},"cargo":{"type":"array","items":{}}}},"code":{"type":"string"},"message":{"type":"string"},"monetary_unit":{"type":"string","enum":["CNY_minor"]},"request_id":{"type":"string"}},"required":["channel","success","total","unavailable_lines","sellers","monetary_unit","request_id"]},{"type":"object","description":"Vendor passthrough envelope when response_format=upstream","properties":{"channel":{"type":"string","example":"1688"},"response_format":{"type":"string","enum":["upstream"]},"upstream_api":{"type":"string","example":"com.alibaba.fenxiao.crossborder/product.search.keywordQuery"},"upstream":{"type":"object","additionalProperties":true,"description":"Official vendor JSON (1688 open API or Taobao IOP)"},"upstream_steps":{"type":"array","description":"Optional prior upstream calls (e.g. image upload before imageQuery)","items":{"type":"object","properties":{"upstream_api":{"type":"string","description":"Vendor API path or IOP route invoked in this step"},"upstream":{"type":"object","additionalProperties":true,"description":"Raw JSON body from that step"}},"required":["upstream_api","upstream"]}},"request_id":{"type":"string","example":"req_abc123"}},"required":["channel","response_format","upstream_api","upstream"]}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid API key or channel authorization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or channel quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quotaExceeded":{"value":{"error":{"code":"QUOTA_EXCEEDED","message":"Shared daily plan quota exceeded. Contact HIOBuy support.","request_id":"req_example"}}},"platformQuotaExceeded":{"value":{"error":{"code":"PLATFORM_QUOTA_EXCEEDED","message":"Channel capacity is temporarily unavailable. Contact HIOBuy support.","request_id":"req_example"}}}}}}},"502":{"description":"Technical/upstream failure; 1688 business failures retain this legacy envelope for compatibility","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orders/1688/create":{"post":{"summary":"1688 cross-border order create (channel shortcut)","tags":["Orders"],"description":"Same as `POST /v1/orders/create` with channel=1688.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"response_format":{"type":"string","enum":["standard","upstream"],"default":"standard","description":"Response shape: \"standard\" (default) returns HIOBuy unified models; \"upstream\" returns vendor raw JSON in `upstream` (see UpstreamApiResponse)."},"receiver":{"type":"object","description":"Domestic inbound / warehouse address. Same shape for 1688, Taobao, and Weidian.","properties":{"name":{"type":"string","description":"Recipient name"},"mobile":{"type":"string","description":"Contact mobile (single field; no separate phone required)"},"province":{"type":"string","description":"Province / state"},"city":{"type":"string"},"district":{"type":"string","description":"District / area (1688 area_text); required without address_id"},"town":{"type":"string","description":"Town / sub-district (1688 town_text); optional"},"address":{"type":"string","description":"Street address"},"zip":{"type":"string"},"country":{"type":"string","default":"中国"},"address_id":{"type":"string","description":"1688 saved address id (optional)"},"district_code":{"type":"string","description":"1688 district code (optional)"}},"required":["name","mobile","province","city","address"]},"lines":{"type":"array","minItems":1,"items":{"type":"object","properties":{"id":{"type":"string","description":"Preferred. Same as search/detail `id` (1688/Weidian `offerId`; Taobao `mi_id`). Taobao `id` rotates periodically — do not cache long-term."},"offer_id":{"type":"string","description":"Compatible alias of `id`. Existing clients may keep sending `offer_id`."},"mi_id":{"type":"string","description":"Compatible Taobao alias of `id`. Existing clients may keep sending `mi_id`."},"spec_id":{"type":"string","description":"1688: `specId` from detail `variants[].sku_id`. Taobao: traffic `sku_id` from detail variants (or already-resolved mpSkuId)."},"item_id":{"type":"string","description":"Deprecated alias of `id` / `offer_id` (Taobao)"},"sku_id":{"type":"string","description":"Deprecated alias of spec_id (Taobao)"},"quantity":{"type":"number","minimum":1}},"required":["spec_id","quantity"]}},"flow":{"type":"string","enum":["general","fenxiao","paired","boutiquefenxiao","boutiquepifa"]},"buyer_message":{"type":"string","description":"Buyer note — maps to 1688 message / Taobao order_remark"},"message":{"type":"string","description":"1688 buyer note alias"},"order_remark":{"type":"string","description":"Taobao buyer note alias (max 50)"},"external_order_id":{"type":"string","description":"External order ref — 1688 outOrderId / Taobao seller_order_number"},"out_order_id":{"type":"string","description":"1688 external order id alias"},"seller_order_number":{"type":"string","description":"Taobao external order id alias"},"trade_type":{"type":"string","description":"1688 trade type from preview"},"isv_biz_type":{"type":"string","default":"cross","description":"1688 only"},"use_red_envelope":{"type":"string","enum":["y","n"],"default":"y","description":"1688 red envelope; auto-retry with n if upstream mentions 红包"},"outer_purchase_id":{"type":"string","description":"Taobao ISV idempotency key; auto-generated when omitted"},"purchase_amount":{"type":"number","description":"Taobao planned amount (fen); auto from preview when omitted"},"order_source":{"type":"string","description":"Taobao buyer platform name"},"channel_order_type":{"type":"string","enum":["PANAMA_DG","PANAMA"],"default":"PANAMA_DG"},"support_partial_success":{"type":"boolean","default":false}},"required":["receiver","lines"]}}}},"responses":{"201":{"description":"standard: unified HIOBuy model; upstream: UpstreamApiResponse with vendor JSON","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"object","description":"Vendor passthrough envelope when response_format=upstream","properties":{"channel":{"type":"string","example":"1688"},"response_format":{"type":"string","enum":["upstream"]},"upstream_api":{"type":"string","example":"com.alibaba.fenxiao.crossborder/product.search.keywordQuery"},"upstream":{"type":"object","additionalProperties":true,"description":"Official vendor JSON (1688 open API or Taobao IOP)"},"upstream_steps":{"type":"array","description":"Optional prior upstream calls (e.g. image upload before imageQuery)","items":{"type":"object","properties":{"upstream_api":{"type":"string","description":"Vendor API path or IOP route invoked in this step"},"upstream":{"type":"object","additionalProperties":true,"description":"Raw JSON body from that step"}},"required":["upstream_api","upstream"]}},"request_id":{"type":"string","example":"req_abc123"}},"required":["channel","response_format","upstream_api","upstream"]}]}}}}}}},"/v1/orders/taobao/preview":{"post":{"summary":"Taobao order preview (channel shortcut)","tags":["Taobao Orders"],"description":"Same body as `POST /v1/orders/preview` with channel=taobao. Requires per-app Taobao OAuth.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"response_format":{"type":"string","enum":["standard","upstream"],"default":"standard","description":"Response shape: \"standard\" (default) returns HIOBuy unified models; \"upstream\" returns vendor raw JSON in `upstream` (see UpstreamApiResponse)."},"receiver":{"type":"object","description":"Domestic inbound / warehouse address. Same shape for 1688, Taobao, and Weidian.","properties":{"name":{"type":"string","description":"Recipient name"},"mobile":{"type":"string","description":"Contact mobile (single field; no separate phone required)"},"province":{"type":"string","description":"Province / state"},"city":{"type":"string"},"district":{"type":"string","description":"District / area (1688 area_text); required without address_id"},"town":{"type":"string","description":"Town / sub-district (1688 town_text); optional"},"address":{"type":"string","description":"Street address"},"zip":{"type":"string"},"country":{"type":"string","default":"中国"},"address_id":{"type":"string","description":"1688 saved address id (optional)"},"district_code":{"type":"string","description":"1688 district code (optional)"}},"required":["name","mobile","province","city","address"]},"lines":{"type":"array","items":{"type":"object","properties":{"offer_id":{"type":"string"},"spec_id":{"type":"string"},"item_id":{"type":"string","description":"Deprecated alias of offer_id"},"sku_id":{"type":"string","description":"Deprecated alias of spec_id"},"quantity":{"type":"number","minimum":1}},"required":["offer_id","spec_id","quantity"]},"minItems":1},"need_supplychain_service":{"type":"boolean","default":false}},"required":["receiver","lines"]}}}},"responses":{"200":{"description":"standard: normalized StandardOrderPreviewResult; upstream: raw vendor status in UpstreamApiResponse","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Normalized preview. success=true means the payable total, seller groups, requested lines, availability, and applicable trade mode passed validation.","properties":{"channel":{"type":"string","enum":["1688","taobao","weidian"]},"success":{"type":"boolean"},"preview_id":{"type":"string","description":"Weidian pre-order id required by the formal order API"},"total":{"type":"object","properties":{"merchandise":{"description":"Money in minor units. null means unknown; a known zero is Money(amount=0).","oneOf":[{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},{"type":"null"}]},"shipping":{"description":"Money in minor units. null means unknown; a known zero is Money(amount=0).","oneOf":[{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},{"type":"null"}]},"payment":{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]}},"required":["merchandise","shipping","payment"]},"unavailable_lines":{"type":"array","items":{"type":"object","properties":{"offer_id":{"type":"string"},"spec_id":{"type":"string"},"quantity":{"type":"number","minimum":1},"unit_price":{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},"line_total":{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},"shipping_from":{"oneOf":[{"type":"string"},{"type":"null"}]},"estimated_delivery":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["offer_id","spec_id"]}},"sellers":{"type":"array","items":{"type":"object","properties":{"seller_id":{"oneOf":[{"type":"string"},{"type":"null"}]},"seller_name":{"oneOf":[{"type":"string"},{"type":"null"}]},"shipping_fee":{"description":"Money in minor units. null means unknown; a known zero is Money(amount=0).","oneOf":[{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},{"type":"null"}]},"order_fee":{"description":"Money in minor units. null means unknown; a known zero is Money(amount=0).","oneOf":[{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"offer_id":{"type":"string"},"spec_id":{"type":"string"},"quantity":{"type":"number","minimum":1},"unit_price":{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},"line_total":{"type":"object","properties":{"currency":{"type":"string","example":"CNY"},"amount":{"type":"number","minimum":0,"description":"Minor-unit amount; for CNY, 100 means RMB 1.00."}},"required":["currency","amount"]},"shipping_from":{"oneOf":[{"type":"string"},{"type":"null"}]},"estimated_delivery":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["offer_id","spec_id"]}}},"required":["seller_id","seller_name","shipping_fee","order_fee","lines"]}},"trade_types":{"type":"array","description":"1688 only when applicable.","items":{"type":"object","properties":{"trade_type":{"type":"string"},"trade_type_name":{"type":"string"},"op_support":{"type":"boolean"}},"required":["trade_type"]}},"pay_channels":{"type":"array","items":{}},"promotions":{"type":"object","properties":{"shop":{"type":"array","items":{}},"cargo":{"type":"array","items":{}}}},"code":{"type":"string"},"message":{"type":"string"},"monetary_unit":{"type":"string","enum":["CNY_minor"]},"request_id":{"type":"string"}},"required":["channel","success","total","unavailable_lines","sellers","monetary_unit","request_id"]},{"type":"object","description":"Vendor passthrough envelope when response_format=upstream","properties":{"channel":{"type":"string","example":"1688"},"response_format":{"type":"string","enum":["upstream"]},"upstream_api":{"type":"string","example":"com.alibaba.fenxiao.crossborder/product.search.keywordQuery"},"upstream":{"type":"object","additionalProperties":true,"description":"Official vendor JSON (1688 open API or Taobao IOP)"},"upstream_steps":{"type":"array","description":"Optional prior upstream calls (e.g. image upload before imageQuery)","items":{"type":"object","properties":{"upstream_api":{"type":"string","description":"Vendor API path or IOP route invoked in this step"},"upstream":{"type":"object","additionalProperties":true,"description":"Raw JSON body from that step"}},"required":["upstream_api","upstream"]}},"request_id":{"type":"string","example":"req_abc123"}},"required":["channel","response_format","upstream_api","upstream"]}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid API key or channel authorization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or channel quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quotaExceeded":{"value":{"error":{"code":"QUOTA_EXCEEDED","message":"Shared daily plan quota exceeded. Contact HIOBuy support.","request_id":"req_example"}}},"platformQuotaExceeded":{"value":{"error":{"code":"PLATFORM_QUOTA_EXCEEDED","message":"Channel capacity is temporarily unavailable. Contact HIOBuy support.","request_id":"req_example"}}}}}}},"502":{"description":"Technical/upstream failure; 1688 business failures retain this legacy envelope for compatibility","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orders/taobao/create":{"post":{"summary":"Taobao create purchase order (channel shortcut)","tags":["Taobao Orders"],"description":"Same as `POST /v1/orders/create` with channel=taobao.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"response_format":{"type":"string","enum":["standard","upstream"],"default":"standard","description":"Response shape: \"standard\" (default) returns HIOBuy unified models; \"upstream\" returns vendor raw JSON in `upstream` (see UpstreamApiResponse)."},"receiver":{"type":"object","description":"Domestic inbound / warehouse address. Same shape for 1688, Taobao, and Weidian.","properties":{"name":{"type":"string","description":"Recipient name"},"mobile":{"type":"string","description":"Contact mobile (single field; no separate phone required)"},"province":{"type":"string","description":"Province / state"},"city":{"type":"string"},"district":{"type":"string","description":"District / area (1688 area_text); required without address_id"},"town":{"type":"string","description":"Town / sub-district (1688 town_text); optional"},"address":{"type":"string","description":"Street address"},"zip":{"type":"string"},"country":{"type":"string","default":"中国"},"address_id":{"type":"string","description":"1688 saved address id (optional)"},"district_code":{"type":"string","description":"1688 district code (optional)"}},"required":["name","mobile","province","city","address"]},"lines":{"type":"array","minItems":1,"items":{"type":"object","properties":{"id":{"type":"string","description":"Preferred. Same as search/detail `id` (1688/Weidian `offerId`; Taobao `mi_id`). Taobao `id` rotates periodically — do not cache long-term."},"offer_id":{"type":"string","description":"Compatible alias of `id`. Existing clients may keep sending `offer_id`."},"mi_id":{"type":"string","description":"Compatible Taobao alias of `id`. Existing clients may keep sending `mi_id`."},"spec_id":{"type":"string","description":"1688: `specId` from detail `variants[].sku_id`. Taobao: traffic `sku_id` from detail variants (or already-resolved mpSkuId)."},"item_id":{"type":"string","description":"Deprecated alias of `id` / `offer_id` (Taobao)"},"sku_id":{"type":"string","description":"Deprecated alias of spec_id (Taobao)"},"quantity":{"type":"number","minimum":1}},"required":["spec_id","quantity"]}},"need_supplychain_service":{"type":"boolean","default":false},"buyer_message":{"type":"string","description":"Buyer note — maps to 1688 message / Taobao order_remark"},"message":{"type":"string","description":"1688 buyer note alias"},"order_remark":{"type":"string","description":"Taobao buyer note alias (max 50)"},"external_order_id":{"type":"string","description":"External order ref — 1688 outOrderId / Taobao seller_order_number"},"out_order_id":{"type":"string","description":"1688 external order id alias"},"seller_order_number":{"type":"string","description":"Taobao external order id alias"},"trade_type":{"type":"string","description":"1688 trade type from preview"},"isv_biz_type":{"type":"string","default":"cross","description":"1688 only"},"use_red_envelope":{"type":"string","enum":["y","n"],"default":"y","description":"1688 red envelope; auto-retry with n if upstream mentions 红包"},"outer_purchase_id":{"type":"string","description":"Taobao ISV idempotency key; auto-generated when omitted"},"purchase_amount":{"type":"number","description":"Taobao planned amount (fen); auto from preview when omitted"},"order_source":{"type":"string","description":"Taobao buyer platform name"},"channel_order_type":{"type":"string","enum":["PANAMA_DG","PANAMA"],"default":"PANAMA_DG"},"support_partial_success":{"type":"boolean","default":false}},"required":["receiver","lines"]}}}},"responses":{"200":{"description":"Success","headers":{"X-Quota-Channel":{"schema":{"type":"string"}},"X-Quota-Remaining-Day":{"schema":{"type":"string"}}}},"201":{"description":"Success","headers":{"X-Quota-Channel":{"schema":{"type":"string"}},"X-Quota-Remaining-Day":{"schema":{"type":"string"}}}},"429":{"description":"Rate limit or channel quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quotaExceeded":{"value":{"error":{"code":"QUOTA_EXCEEDED","message":"Shared daily plan quota exceeded. Contact HIOBuy support.","request_id":"req_example"}}},"platformQuotaExceeded":{"value":{"error":{"code":"PLATFORM_QUOTA_EXCEEDED","message":"Channel capacity is temporarily unavailable. Contact HIOBuy support.","request_id":"req_example"}}}}}}}}}},"/v1/orders/cancel":{"post":{"summary":"Cancel order (1688, Taobao, or Weidian)","description":"Unified cancel for 1688 `alibaba.trade.cancel`, Taobao `/purchase/order/asyn/cancel`, and Weidian `buyer.order.cancel`. `channel` and `order_id` are required (`order_id` = Taobao create `order_id`). Weidian accepts `reason` or `cancel_reason` and only allows cancellation of unpaid buyer orders. Taobao cancel is async: `pending: true` means accepted; confirm via purchase query. Set response_format=upstream for vendor raw JSON.","tags":["Orders"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Recommended for cancellation. Use a new key for each logical cancellation and reuse it for retries. Same key + same request replays the stored response; different parameters return 409. If the upstream result is uncertain, check order status before taking further action."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"response_format":{"type":"string","enum":["standard","upstream"],"default":"standard","description":"Response shape: \"standard\" (default) returns HIOBuy unified models; \"upstream\" returns vendor raw JSON in `upstream` (see UpstreamApiResponse)."},"channel":{"type":"string","enum":["1688","taobao","weidian"]},"order_id":{"type":"string","description":"1688 tradeID / Taobao purchase_id / Weidian order ID"},"sub_order_ids":{"type":"array","items":{"type":"string"},"description":"Taobao partial cancel only"},"cancel_reason":{"type":"string"},"reason":{"type":"string","description":"Weidian cancellation reason; cancel_reason is accepted as an alias"},"remark":{"type":"string","description":"1688 remark"},"cancel_remark":{"type":"string","description":"Taobao cancel remark"},"website":{"type":"string","enum":["1688"],"default":"1688"}},"required":["channel","order_id"]}}}},"responses":{"200":{"description":"standard: unified HIOBuy model; upstream: UpstreamApiResponse with vendor JSON","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"object","description":"Vendor passthrough envelope when response_format=upstream","properties":{"channel":{"type":"string","example":"1688"},"response_format":{"type":"string","enum":["upstream"]},"upstream_api":{"type":"string","example":"com.alibaba.fenxiao.crossborder/product.search.keywordQuery"},"upstream":{"type":"object","additionalProperties":true,"description":"Official vendor JSON (1688 open API or Taobao IOP)"},"upstream_steps":{"type":"array","description":"Optional prior upstream calls (e.g. image upload before imageQuery)","items":{"type":"object","properties":{"upstream_api":{"type":"string","description":"Vendor API path or IOP route invoked in this step"},"upstream":{"type":"object","additionalProperties":true,"description":"Raw JSON body from that step"}},"required":["upstream_api","upstream"]}},"request_id":{"type":"string","example":"req_abc123"}},"required":["channel","response_format","upstream_api","upstream"]}]}}}},"409":{"description":"Idempotency conflict, cancellation already in progress, or earlier cancellation result is unknown"}}}},"/v1/orders/1688/cancel":{"post":{"summary":"1688 cancel trade (channel shortcut)","tags":["Orders"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Recommended for cancellation. Use a new key for each logical cancellation and reuse it for retries. Same key + same request replays the stored response; different parameters return 409. If the upstream result is uncertain, check order status before taking further action."}],"description":"Same as POST /v1/orders/cancel with channel=1688. Body may omit channel.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"response_format":{"type":"string","enum":["standard","upstream"],"default":"standard","description":"Response shape: \"standard\" (default) returns HIOBuy unified models; \"upstream\" returns vendor raw JSON in `upstream` (see UpstreamApiResponse)."},"channel":{"type":"string","enum":["1688"],"default":"1688"},"order_id":{"type":"string","description":"1688 tradeID"},"website":{"type":"string","enum":["1688"],"default":"1688"},"cancel_reason":{"type":"string","enum":["buyerCancel","sellerGoodsLack","other"]},"remark":{"type":"string"}},"required":["order_id","cancel_reason"]}}}},"responses":{"200":{"description":"standard: unified HIOBuy model; upstream: UpstreamApiResponse with vendor JSON","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"object","description":"Vendor passthrough envelope when response_format=upstream","properties":{"channel":{"type":"string","example":"1688"},"response_format":{"type":"string","enum":["upstream"]},"upstream_api":{"type":"string","example":"com.alibaba.fenxiao.crossborder/product.search.keywordQuery"},"upstream":{"type":"object","additionalProperties":true,"description":"Official vendor JSON (1688 open API or Taobao IOP)"},"upstream_steps":{"type":"array","description":"Optional prior upstream calls (e.g. image upload before imageQuery)","items":{"type":"object","properties":{"upstream_api":{"type":"string","description":"Vendor API path or IOP route invoked in this step"},"upstream":{"type":"object","additionalProperties":true,"description":"Raw JSON body from that step"}},"required":["upstream_api","upstream"]}},"request_id":{"type":"string","example":"req_abc123"}},"required":["channel","response_format","upstream_api","upstream"]}]}}}},"409":{"description":"Idempotency conflict, cancellation already in progress, or earlier cancellation result is unknown"}}}},"/v1/orders/taobao/cancel":{"post":{"summary":"Taobao async cancel purchase order (channel shortcut)","tags":["Taobao Orders"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Recommended for cancellation. Use a new key for each logical cancellation and reuse it for retries. Same key + same request replays the stored response; different parameters return 409. If the upstream result is uncertain, check order status before taking further action."}],"description":"Same as POST /v1/orders/cancel with channel=taobao. Body may omit channel.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"response_format":{"type":"string","enum":["standard","upstream"],"default":"standard","description":"Response shape: \"standard\" (default) returns HIOBuy unified models; \"upstream\" returns vendor raw JSON in `upstream` (see UpstreamApiResponse)."},"channel":{"type":"string","enum":["taobao"],"default":"taobao"},"order_id":{"type":"string","description":"Taobao purchase_id returned as order_id from create"},"sub_order_ids":{"type":"array","items":{"type":"string"},"description":"Partial cancel; omit or empty to cancel entire order"},"cancel_reason":{"type":"string","description":"Upstream cancel reason string"},"cancel_remark":{"type":"string"}},"required":["order_id","cancel_reason"]}}}},"responses":{"200":{"description":"standard: unified HIOBuy model; upstream: UpstreamApiResponse with vendor JSON","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"object","description":"Vendor passthrough envelope when response_format=upstream","properties":{"channel":{"type":"string","example":"1688"},"response_format":{"type":"string","enum":["upstream"]},"upstream_api":{"type":"string","example":"com.alibaba.fenxiao.crossborder/product.search.keywordQuery"},"upstream":{"type":"object","additionalProperties":true,"description":"Official vendor JSON (1688 open API or Taobao IOP)"},"upstream_steps":{"type":"array","description":"Optional prior upstream calls (e.g. image upload before imageQuery)","items":{"type":"object","properties":{"upstream_api":{"type":"string","description":"Vendor API path or IOP route invoked in this step"},"upstream":{"type":"object","additionalProperties":true,"description":"Raw JSON body from that step"}},"required":["upstream_api","upstream"]}},"request_id":{"type":"string","example":"req_abc123"}},"required":["channel","response_format","upstream_api","upstream"]}]}}}},"409":{"description":"Idempotency conflict, cancellation already in progress, or earlier cancellation result is unknown"}}}},"/v1/orders/detail":{"post":{"summary":"Order detail (1688, Taobao, or Weidian)","description":"Unified detail for one order. 1688: `alibaba.trade.get.buyerView`. Taobao: `/purchase/orders/query` by `purchase_id`. Weidian: `buyer.order.get` v1.1 by `order_id`. Standard amounts remain CNY fen; `status` / `refund_status` are cross-channel enums. Taobao self-mode `order.total` uses a usable CNY payment amount, or the CNY purchase amount when payment amount is foreign-currency, missing, invalid, or zero before payment. Postage is not added again. Legacy currency-less amounts retain their CNY interpretation. An explicitly identified CNY purchase amount takes precedence over an unlabelled payment amount. No exchange rate is inferred; an unusable CNY total returns CHANNEL_UPSTREAM_ERROR (502). Upstream format preserves the original amounts and currencies.","tags":["Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"response_format":{"type":"string","enum":["standard","upstream"],"default":"standard","description":"Response shape: \"standard\" (default) returns HIOBuy unified models; \"upstream\" returns vendor raw JSON in `upstream` (see UpstreamApiResponse)."},"channel":{"type":"string","enum":["1688","taobao","weidian"]},"order_id":{"type":"string"},"website":{"type":"string","enum":["1688"],"default":"1688"},"include_fields":{"type":"string"},"out_order_id":{"type":"string"}},"required":["channel","order_id"]}}}},"responses":{"200":{"description":"standard: unified HIOBuy model; upstream: UpstreamApiResponse with vendor JSON","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"object","description":"Vendor passthrough envelope when response_format=upstream","properties":{"channel":{"type":"string","example":"1688"},"response_format":{"type":"string","enum":["upstream"]},"upstream_api":{"type":"string","example":"com.alibaba.fenxiao.crossborder/product.search.keywordQuery"},"upstream":{"type":"object","additionalProperties":true,"description":"Official vendor JSON (1688 open API or Taobao IOP)"},"upstream_steps":{"type":"array","description":"Optional prior upstream calls (e.g. image upload before imageQuery)","items":{"type":"object","properties":{"upstream_api":{"type":"string","description":"Vendor API path or IOP route invoked in this step"},"upstream":{"type":"object","additionalProperties":true,"description":"Raw JSON body from that step"}},"required":["upstream_api","upstream"]}},"request_id":{"type":"string","example":"req_abc123"}},"required":["channel","response_format","upstream_api","upstream"]}]}}}}}}},"/v1/orders/1688/detail":{"post":{"summary":"1688 order detail (channel shortcut)","tags":["Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"response_format":{"type":"string","enum":["standard","upstream"],"default":"standard","description":"Response shape: \"standard\" (default) returns HIOBuy unified models; \"upstream\" returns vendor raw JSON in `upstream` (see UpstreamApiResponse)."},"channel":{"type":"string","enum":["1688"],"default":"1688"},"order_id":{"type":"string"},"website":{"type":"string","enum":["1688"],"default":"1688"},"include_fields":{"type":"string"},"out_order_id":{"type":"string"}},"required":["order_id"]}}}},"responses":{"200":{"description":"standard: unified HIOBuy model; upstream: UpstreamApiResponse with vendor JSON","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"object","description":"Vendor passthrough envelope when response_format=upstream","properties":{"channel":{"type":"string","example":"1688"},"response_format":{"type":"string","enum":["upstream"]},"upstream_api":{"type":"string","example":"com.alibaba.fenxiao.crossborder/product.search.keywordQuery"},"upstream":{"type":"object","additionalProperties":true,"description":"Official vendor JSON (1688 open API or Taobao IOP)"},"upstream_steps":{"type":"array","description":"Optional prior upstream calls (e.g. image upload before imageQuery)","items":{"type":"object","properties":{"upstream_api":{"type":"string","description":"Vendor API path or IOP route invoked in this step"},"upstream":{"type":"object","additionalProperties":true,"description":"Raw JSON body from that step"}},"required":["upstream_api","upstream"]}},"request_id":{"type":"string","example":"req_abc123"}},"required":["channel","response_format","upstream_api","upstream"]}]}}}}}}},"/v1/orders/taobao/detail":{"post":{"summary":"Taobao purchase order detail (channel shortcut)","description":"Same CNY-fen amount mapping as /v1/orders/detail with channel=taobao. Foreign-currency upstream pay_amount is never relabeled as CNY; the CNY purchase amount is used instead. Upstream format is unchanged.","tags":["Taobao Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"response_format":{"type":"string","enum":["standard","upstream"],"default":"standard","description":"Response shape: \"standard\" (default) returns HIOBuy unified models; \"upstream\" returns vendor raw JSON in `upstream` (see UpstreamApiResponse)."},"channel":{"type":"string","enum":["taobao"],"default":"taobao"},"order_id":{"type":"string","description":"Taobao purchase_id"}},"required":["order_id"]}}}},"responses":{"200":{"description":"standard: unified HIOBuy model; upstream: UpstreamApiResponse with vendor JSON","content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"object","description":"Vendor passthrough envelope when response_format=upstream","properties":{"channel":{"type":"string","example":"1688"},"response_format":{"type":"string","enum":["upstream"]},"upstream_api":{"type":"string","example":"com.alibaba.fenxiao.crossborder/product.search.keywordQuery"},"upstream":{"type":"object","additionalProperties":true,"description":"Official vendor JSON (1688 open API or Taobao IOP)"},"upstream_steps":{"type":"array","description":"Optional prior upstream calls (e.g. image upload before imageQuery)","items":{"type":"object","properties":{"upstream_api":{"type":"string","description":"Vendor API path or IOP route invoked in this step"},"upstream":{"type":"object","additionalProperties":true,"description":"Raw JSON body from that step"}},"required":["upstream_api","upstream"]}},"request_id":{"type":"string","example":"req_abc123"}},"required":["channel","response_format","upstream_api","upstream"]}]}}}}}}},"/v1/orders/pay":{"post":{"summary":"Pay order (1688, Taobao, or Weidian)","description":"Unified pay for 1688 `alibaba.trade.pay.protocolPay.preparePay`, Taobao `/purchase/order/batch/pay`, and Weidian `buyer.order.pay` (one order per request). `channel` and `order_id` are required (`order_id` = create `order_id`). Set response_format=upstream for vendor raw JSON. In Taobao self procurement mode, standard success=true requires a follow-up order query to confirm payment. The official payment API is asynchronous submission: will_pay_purchase_order_ids lists submitted orders, not settled payments. code=0 does not prove settlement. Evaluate the target order's rejection/submission evidence; aggregate BATCH_PAY_ERROR alone does not prove that order failed. pending=true means payment is not yet confirmed by the Gateway; it is not an official Taobao queue/acceptance status. payment_status is success, pending, failed, or unknown. Do not initiate a new payment for pending/unknown; query order detail or reuse the same Idempotency-Key. payment_submission_status separates submitted, rejected, and unknown submission evidence from settlement. Legacy success without submission evidence remains unknown. Unconfirmed, timed-out, and stale Taobao self standard replays refresh order status without another payment. Confirmed results are persisted. payment_recovery.action is none, query_order, retry_with_new_key, or manual_review. After 15 minutes from the original attempt, unresolved keyed results become unknown/manual_review; this is a Gateway review threshold, not an upstream expiry or proof of failure. Start a new logical attempt only after correcting an explicit rejection and checking the order is still payable, or after manual confirmation that the earlier attempt ended without payment or deduction. An unpaid order alone is insufficient. Upstream format remains raw and is not verified by a follow-up query.","tags":["Orders"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Optional, recommended for payment. Reuse the same key for retries of one payment attempt; a new key submits a new real payment. Taobao self standard uncertain results, including transport-unknown or stale attempts, refresh order status read-only and persist confirmed success. Different parameters return 409. Do not automatically change keys for pending/unknown. Follow payment_recovery and verify marketplace payment records before any new attempt."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"response_format":{"type":"string","enum":["standard","upstream"],"default":"standard","description":"Response shape: \"standard\" (default) returns HIOBuy unified models; \"upstream\" returns vendor raw JSON in `upstream` (see UpstreamApiResponse)."},"channel":{"type":"string","enum":["1688","taobao","weidian"]},"order_id":{"type":"string","description":"Channel order id returned by create"},"pay_channel":{"type":"string","description":"Optional pay channel, e.g. ALIPAY / kjpayV2"},"pay_amount":{"type":"integer","description":"Optional total pay amount in fen"},"op_request_id":{"type":"string","description":"Legacy 1688 upstream request identifier. Prefer the Idempotency-Key header for Gateway-wide protection."},"website":{"type":"string","enum":["1688"],"default":"1688"}},"required":["channel","order_id"]}}}},"responses":{"200":{"description":"Standard payment result or raw upstream envelope. In Taobao self procurement mode, standard success=true requires a follow-up order query to confirm payment. The official payment API is asynchronous submission: will_pay_purchase_order_ids lists submitted orders, not settled payments. code=0 does not prove settlement. Evaluate the target order's rejection/submission evidence; aggregate BATCH_PAY_ERROR alone does not prove that order failed. pending=true means payment is not yet confirmed by the Gateway; it is not an official Taobao queue/acceptance status. payment_status is success, pending, failed, or unknown. Do not initiate a new payment for pending/unknown; query order detail or reuse the same Idempotency-Key. payment_submission_status separates submitted, rejected, and unknown submission evidence from settlement. Legacy success without submission evidence remains unknown. Unconfirmed, timed-out, and stale Taobao self standard replays refresh order status without another payment. Confirmed results are persisted. payment_recovery.action is none, query_order, retry_with_new_key, or manual_review. After 15 minutes from the original attempt, unresolved keyed results become unknown/manual_review; this is a Gateway review threshold, not an upstream expiry or proof of failure. Start a new logical attempt only after correcting an explicit rejection and checking the order is still payable, or after manual confirmation that the earlier attempt ended without payment or deduction. An unpaid order alone is insufficient. Upstream format remains raw and is not verified by a follow-up query.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["channel","order_id","success","request_id"],"additionalProperties":true,"properties":{"channel":{"type":"string","enum":["1688","taobao","weidian"]},"order_id":{"type":"string"},"success":{"type":"boolean","description":"Taobao self: true only when payment is confirmed by order query."},"pending":{"type":"boolean","description":"Optional Taobao self field: outcome is not final. Do not submit another payment."},"payment_status":{"type":"string","enum":["success","pending","failed","unknown"],"description":"Optional Taobao self payment confirmation status."},"payment_submission_status":{"type":"string","enum":["submitted","rejected","unknown"],"description":"Optional Taobao self submission evidence, distinct from settlement. Legacy/no-evidence submissions are unknown."},"payment_recovery":{"type":"object","required":["action","reason"],"description":"Optional Gateway recovery guidance, not an automatic debit instruction. Taobao self standard results and explicit 1688 paySuccess outcomes; uncertain 409 errors may carry it in error.details. The 15-minute review threshold never proves failure or permits automatic retry.","properties":{"action":{"type":"string","enum":["none","query_order","retry_with_new_key","manual_review"]},"reason":{"type":"string","enum":["PAYMENT_CONFIRMED","PAYMENT_REJECTED","AWAITING_CONFIRMATION","SUBMISSION_UNCONFIRMED","CONFIRMATION_OVERDUE","ORDER_CLOSED"]},"elapsed_seconds":{"type":"integer","minimum":0,"description":"When available, age from the original attempt; replays do not reset it."}}},"order_status":{"type":"string","description":"Latest normalized order status used for confirmation, when available."},"order_status_raw":{"type":"string","description":"Official order status from the confirmation query."},"upstream_request_id":{"type":"string","description":"Official payment API request id, when supplied; distinct from request_id."},"pay_success":{"type":"boolean"},"pay_channel":{"type":"string"},"error_code":{"type":"string"},"error_message":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"}}},{"type":"object","description":"Vendor passthrough envelope when response_format=upstream","properties":{"channel":{"type":"string","example":"1688"},"response_format":{"type":"string","enum":["upstream"]},"upstream_api":{"type":"string","example":"com.alibaba.fenxiao.crossborder/product.search.keywordQuery"},"upstream":{"type":"object","additionalProperties":true,"description":"Official vendor JSON (1688 open API or Taobao IOP)"},"upstream_steps":{"type":"array","description":"Optional prior upstream calls (e.g. image upload before imageQuery)","items":{"type":"object","properties":{"upstream_api":{"type":"string","description":"Vendor API path or IOP route invoked in this step"},"upstream":{"type":"object","additionalProperties":true,"description":"Raw JSON body from that step"}},"required":["upstream_api","upstream"]}},"request_id":{"type":"string","example":"req_abc123"}},"required":["channel","response_format","upstream_api","upstream"]}]}}}},"409":{"description":"Idempotency conflict, payment already in progress, or earlier payment result is unknown. Unknown/stale payment errors add error.details.original_request_id and payment_recovery guidance. Taobao self standard same-key uncertain attempts instead perform a read-only reconciliation and return HTTP 200 with the current standard outcome; sandbox, raw format, and other modes retain 409 behavior."}}}},"/v1/orders/1688/pay":{"post":{"summary":"1688 protocol pay (channel shortcut)","tags":["Orders"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Optional, recommended for payment. Reuse the same key for retries of one payment attempt; a new key submits a new real payment. Taobao self standard uncertain results, including transport-unknown or stale attempts, refresh order status read-only and persist confirmed success. Different parameters return 409. Do not automatically change keys for pending/unknown. Follow payment_recovery and verify marketplace payment records before any new attempt."}],"description":"Same as POST /v1/orders/pay with channel=1688. Body may omit channel.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"response_format":{"type":"string","enum":["standard","upstream"],"default":"standard","description":"Response shape: \"standard\" (default) returns HIOBuy unified models; \"upstream\" returns vendor raw JSON in `upstream` (see UpstreamApiResponse)."},"channel":{"type":"string","enum":["1688"],"default":"1688"},"order_id":{"type":"string","description":"1688 tradeID (create order_id)"},"pay_channel":{"type":"string","description":"Optional pay channel, e.g. ALIPAY / kjpayV2"},"pay_amount":{"type":"integer","description":"Optional total pay amount in fen"},"op_request_id":{"type":"string","description":"Legacy 1688 upstream request identifier. Prefer the Idempotency-Key header for Gateway-wide protection."},"website":{"type":"string","enum":["1688"],"default":"1688"}},"required":["order_id"]}}}},"responses":{"200":{"description":"Standard payment result or raw upstream envelope. In Taobao self procurement mode, standard success=true requires a follow-up order query to confirm payment. The official payment API is asynchronous submission: will_pay_purchase_order_ids lists submitted orders, not settled payments. code=0 does not prove settlement. Evaluate the target order's rejection/submission evidence; aggregate BATCH_PAY_ERROR alone does not prove that order failed. pending=true means payment is not yet confirmed by the Gateway; it is not an official Taobao queue/acceptance status. payment_status is success, pending, failed, or unknown. Do not initiate a new payment for pending/unknown; query order detail or reuse the same Idempotency-Key. payment_submission_status separates submitted, rejected, and unknown submission evidence from settlement. Legacy success without submission evidence remains unknown. Unconfirmed, timed-out, and stale Taobao self standard replays refresh order status without another payment. Confirmed results are persisted. payment_recovery.action is none, query_order, retry_with_new_key, or manual_review. After 15 minutes from the original attempt, unresolved keyed results become unknown/manual_review; this is a Gateway review threshold, not an upstream expiry or proof of failure. Start a new logical attempt only after correcting an explicit rejection and checking the order is still payable, or after manual confirmation that the earlier attempt ended without payment or deduction. An unpaid order alone is insufficient. Upstream format remains raw and is not verified by a follow-up query.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["channel","order_id","success","request_id"],"additionalProperties":true,"properties":{"channel":{"type":"string","enum":["1688","taobao","weidian"]},"order_id":{"type":"string"},"success":{"type":"boolean","description":"Taobao self: true only when payment is confirmed by order query."},"pending":{"type":"boolean","description":"Optional Taobao self field: outcome is not final. Do not submit another payment."},"payment_status":{"type":"string","enum":["success","pending","failed","unknown"],"description":"Optional Taobao self payment confirmation status."},"payment_submission_status":{"type":"string","enum":["submitted","rejected","unknown"],"description":"Optional Taobao self submission evidence, distinct from settlement. Legacy/no-evidence submissions are unknown."},"payment_recovery":{"type":"object","required":["action","reason"],"description":"Optional Gateway recovery guidance, not an automatic debit instruction. Taobao self standard results and explicit 1688 paySuccess outcomes; uncertain 409 errors may carry it in error.details. The 15-minute review threshold never proves failure or permits automatic retry.","properties":{"action":{"type":"string","enum":["none","query_order","retry_with_new_key","manual_review"]},"reason":{"type":"string","enum":["PAYMENT_CONFIRMED","PAYMENT_REJECTED","AWAITING_CONFIRMATION","SUBMISSION_UNCONFIRMED","CONFIRMATION_OVERDUE","ORDER_CLOSED"]},"elapsed_seconds":{"type":"integer","minimum":0,"description":"When available, age from the original attempt; replays do not reset it."}}},"order_status":{"type":"string","description":"Latest normalized order status used for confirmation, when available."},"order_status_raw":{"type":"string","description":"Official order status from the confirmation query."},"upstream_request_id":{"type":"string","description":"Official payment API request id, when supplied; distinct from request_id."},"pay_success":{"type":"boolean"},"pay_channel":{"type":"string"},"error_code":{"type":"string"},"error_message":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"}}},{"type":"object","description":"Vendor passthrough envelope when response_format=upstream","properties":{"channel":{"type":"string","example":"1688"},"response_format":{"type":"string","enum":["upstream"]},"upstream_api":{"type":"string","example":"com.alibaba.fenxiao.crossborder/product.search.keywordQuery"},"upstream":{"type":"object","additionalProperties":true,"description":"Official vendor JSON (1688 open API or Taobao IOP)"},"upstream_steps":{"type":"array","description":"Optional prior upstream calls (e.g. image upload before imageQuery)","items":{"type":"object","properties":{"upstream_api":{"type":"string","description":"Vendor API path or IOP route invoked in this step"},"upstream":{"type":"object","additionalProperties":true,"description":"Raw JSON body from that step"}},"required":["upstream_api","upstream"]}},"request_id":{"type":"string","example":"req_abc123"}},"required":["channel","response_format","upstream_api","upstream"]}]}}}},"409":{"description":"Idempotency conflict, payment already in progress, or earlier payment result is unknown. Unknown/stale payment errors add error.details.original_request_id and payment_recovery guidance. Taobao self standard same-key uncertain attempts instead perform a read-only reconciliation and return HTTP 200 with the current standard outcome; sandbox, raw format, and other modes retain 409 behavior."}}}},"/v1/orders/taobao/pay":{"post":{"summary":"Taobao pay purchase order (channel shortcut)","tags":["Taobao Orders"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Optional, recommended for payment. Reuse the same key for retries of one payment attempt; a new key submits a new real payment. Taobao self standard uncertain results, including transport-unknown or stale attempts, refresh order status read-only and persist confirmed success. Different parameters return 409. Do not automatically change keys for pending/unknown. Follow payment_recovery and verify marketplace payment records before any new attempt."}],"description":"Same as POST /v1/orders/pay with channel=taobao. Body may omit channel. In Taobao self procurement mode, standard success=true requires a follow-up order query to confirm payment. The official payment API is asynchronous submission: will_pay_purchase_order_ids lists submitted orders, not settled payments. code=0 does not prove settlement. Evaluate the target order's rejection/submission evidence; aggregate BATCH_PAY_ERROR alone does not prove that order failed. pending=true means payment is not yet confirmed by the Gateway; it is not an official Taobao queue/acceptance status. payment_status is success, pending, failed, or unknown. Do not initiate a new payment for pending/unknown; query order detail or reuse the same Idempotency-Key. payment_submission_status separates submitted, rejected, and unknown submission evidence from settlement. Legacy success without submission evidence remains unknown. Unconfirmed, timed-out, and stale Taobao self standard replays refresh order status without another payment. Confirmed results are persisted. payment_recovery.action is none, query_order, retry_with_new_key, or manual_review. After 15 minutes from the original attempt, unresolved keyed results become unknown/manual_review; this is a Gateway review threshold, not an upstream expiry or proof of failure. Start a new logical attempt only after correcting an explicit rejection and checking the order is still payable, or after manual confirmation that the earlier attempt ended without payment or deduction. An unpaid order alone is insufficient. Upstream format remains raw and is not verified by a follow-up query.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"response_format":{"type":"string","enum":["standard","upstream"],"default":"standard","description":"Response shape: \"standard\" (default) returns HIOBuy unified models; \"upstream\" returns vendor raw JSON in `upstream` (see UpstreamApiResponse)."},"channel":{"type":"string","enum":["taobao"],"default":"taobao"},"order_id":{"type":"string","description":"Taobao purchase_id from create order_id"}},"required":["order_id"]}}}},"responses":{"200":{"description":"Standard payment result or raw upstream envelope. In Taobao self procurement mode, standard success=true requires a follow-up order query to confirm payment. The official payment API is asynchronous submission: will_pay_purchase_order_ids lists submitted orders, not settled payments. code=0 does not prove settlement. Evaluate the target order's rejection/submission evidence; aggregate BATCH_PAY_ERROR alone does not prove that order failed. pending=true means payment is not yet confirmed by the Gateway; it is not an official Taobao queue/acceptance status. payment_status is success, pending, failed, or unknown. Do not initiate a new payment for pending/unknown; query order detail or reuse the same Idempotency-Key. payment_submission_status separates submitted, rejected, and unknown submission evidence from settlement. Legacy success without submission evidence remains unknown. Unconfirmed, timed-out, and stale Taobao self standard replays refresh order status without another payment. Confirmed results are persisted. payment_recovery.action is none, query_order, retry_with_new_key, or manual_review. After 15 minutes from the original attempt, unresolved keyed results become unknown/manual_review; this is a Gateway review threshold, not an upstream expiry or proof of failure. Start a new logical attempt only after correcting an explicit rejection and checking the order is still payable, or after manual confirmation that the earlier attempt ended without payment or deduction. An unpaid order alone is insufficient. Upstream format remains raw and is not verified by a follow-up query.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["channel","order_id","success","request_id"],"additionalProperties":true,"properties":{"channel":{"type":"string","enum":["1688","taobao","weidian"]},"order_id":{"type":"string"},"success":{"type":"boolean","description":"Taobao self: true only when payment is confirmed by order query."},"pending":{"type":"boolean","description":"Optional Taobao self field: outcome is not final. Do not submit another payment."},"payment_status":{"type":"string","enum":["success","pending","failed","unknown"],"description":"Optional Taobao self payment confirmation status."},"payment_submission_status":{"type":"string","enum":["submitted","rejected","unknown"],"description":"Optional Taobao self submission evidence, distinct from settlement. Legacy/no-evidence submissions are unknown."},"payment_recovery":{"type":"object","required":["action","reason"],"description":"Optional Gateway recovery guidance, not an automatic debit instruction. Taobao self standard results and explicit 1688 paySuccess outcomes; uncertain 409 errors may carry it in error.details. The 15-minute review threshold never proves failure or permits automatic retry.","properties":{"action":{"type":"string","enum":["none","query_order","retry_with_new_key","manual_review"]},"reason":{"type":"string","enum":["PAYMENT_CONFIRMED","PAYMENT_REJECTED","AWAITING_CONFIRMATION","SUBMISSION_UNCONFIRMED","CONFIRMATION_OVERDUE","ORDER_CLOSED"]},"elapsed_seconds":{"type":"integer","minimum":0,"description":"When available, age from the original attempt; replays do not reset it."}}},"order_status":{"type":"string","description":"Latest normalized order status used for confirmation, when available."},"order_status_raw":{"type":"string","description":"Official order status from the confirmation query."},"upstream_request_id":{"type":"string","description":"Official payment API request id, when supplied; distinct from request_id."},"pay_success":{"type":"boolean"},"pay_channel":{"type":"string"},"error_code":{"type":"string"},"error_message":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"}}},{"type":"object","description":"Vendor passthrough envelope when response_format=upstream","properties":{"channel":{"type":"string","example":"1688"},"response_format":{"type":"string","enum":["upstream"]},"upstream_api":{"type":"string","example":"com.alibaba.fenxiao.crossborder/product.search.keywordQuery"},"upstream":{"type":"object","additionalProperties":true,"description":"Official vendor JSON (1688 open API or Taobao IOP)"},"upstream_steps":{"type":"array","description":"Optional prior upstream calls (e.g. image upload before imageQuery)","items":{"type":"object","properties":{"upstream_api":{"type":"string","description":"Vendor API path or IOP route invoked in this step"},"upstream":{"type":"object","additionalProperties":true,"description":"Raw JSON body from that step"}},"required":["upstream_api","upstream"]}},"request_id":{"type":"string","example":"req_abc123"}},"required":["channel","response_format","upstream_api","upstream"]}]}}}},"409":{"description":"Idempotency conflict, payment already in progress, or earlier payment result is unknown. Unknown/stale payment errors add error.details.original_request_id and payment_recovery guidance. Taobao self standard same-key uncertain attempts instead perform a read-only reconciliation and return HTTP 200 with the current standard outcome; sandbox, raw format, and other modes retain 409 behavior."}}}},"/v1/products/similar":{"post":{"summary":"Taobao similar product recommendations (/product/recommend)","tags":["Taobao Products"],"description":"Billable weight: **2** units. Pass a **fresh** Taobao `id` / `mi_id` — it rotates periodically and must not be cached long-term.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"channel":{"type":"string","enum":["taobao"],"default":"taobao"}}},{"type":"object","properties":{"id":{"$ref":"#/components/schemas/ProductId"},"product_id":{"type":"string","description":"Legacy Taobao `item_id`. Prefer `id` or `mi_id`."},"mi_id":{"type":"string","description":"TaoWorld `mi_id`. Equivalent to `id`."},"url":{"type":"string"},"tao_password":{"type":"string"},"img_url":{"type":"string"},"image_id":{"type":"string"}}}]}}}},"responses":{"200":{"description":"Success","headers":{"X-Quota-Channel":{"schema":{"type":"string"}},"X-Quota-Remaining-Day":{"schema":{"type":"string"}},"X-Quota-Pack-Remaining":{"schema":{"type":"string"}},"X-Quota-Billable-Units":{"schema":{"type":"string"},"description":"1 for standard routes; 2 for heavy routes (search, purchase, etc.)"}}},"429":{"description":"Rate limit or channel quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quotaExceeded":{"value":{"error":{"code":"QUOTA_EXCEEDED","message":"Shared daily plan quota exceeded. Contact HIOBuy support.","request_id":"req_example"}}},"platformQuotaExceeded":{"value":{"error":{"code":"PLATFORM_QUOTA_EXCEEDED","message":"Channel capacity is temporarily unavailable. Contact HIOBuy support.","request_id":"req_example"}}}}}}}}}},"/v1/products/batch-check":{"post":{"summary":"Taobao batch distribution check (/batch/src/products/check)","tags":["Taobao Products"],"description":"Billable weight: **2** units.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["taobao"]},"items":{"type":"array","items":{"type":"object","properties":{"item_id":{"type":"string"},"sku_id":{"type":"string"}}}}},"required":["items"]}}}},"responses":{"200":{"description":"Success","headers":{"X-Quota-Channel":{"schema":{"type":"string"}},"X-Quota-Remaining-Day":{"schema":{"type":"string"}},"X-Quota-Pack-Remaining":{"schema":{"type":"string"}},"X-Quota-Billable-Units":{"schema":{"type":"string"},"description":"1 for standard routes; 2 for heavy routes (search, purchase, etc.)"}}},"429":{"description":"Rate limit or channel quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quotaExceeded":{"value":{"error":{"code":"QUOTA_EXCEEDED","message":"Shared daily plan quota exceeded. Contact HIOBuy support.","request_id":"req_example"}}},"platformQuotaExceeded":{"value":{"error":{"code":"PLATFORM_QUOTA_EXCEEDED","message":"Channel capacity is temporarily unavailable. Contact HIOBuy support.","request_id":"req_example"}}}}}}}}}},"/v1/products/themes/dimensions":{"post":{"summary":"Taobao theme dimension list (/traffic/theme/getThemeDimList)","tags":["Taobao Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["taobao"],"default":"taobao"}}}}}},"responses":{"200":{"description":"Success","headers":{"X-Quota-Channel":{"schema":{"type":"string"}},"X-Quota-Remaining-Day":{"schema":{"type":"string"}},"X-Quota-Pack-Remaining":{"schema":{"type":"string"}},"X-Quota-Billable-Units":{"schema":{"type":"string"},"description":"1 for standard routes; 2 for heavy routes (search, purchase, etc.)"}}},"429":{"description":"Rate limit or channel quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quotaExceeded":{"value":{"error":{"code":"QUOTA_EXCEEDED","message":"Shared daily plan quota exceeded. Contact HIOBuy support.","request_id":"req_example"}}},"platformQuotaExceeded":{"value":{"error":{"code":"PLATFORM_QUOTA_EXCEEDED","message":"Channel capacity is temporarily unavailable. Contact HIOBuy support.","request_id":"req_example"}}}}}}}}}},"/v1/products/themes/items":{"post":{"summary":"Taobao theme ranking items (/traffic/theme/getThemeDetail)","tags":["Taobao Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["taobao"],"default":"taobao"}}}}}},"responses":{"200":{"description":"Success","headers":{"X-Quota-Channel":{"schema":{"type":"string"}},"X-Quota-Remaining-Day":{"schema":{"type":"string"}},"X-Quota-Pack-Remaining":{"schema":{"type":"string"}},"X-Quota-Billable-Units":{"schema":{"type":"string"},"description":"1 for standard routes; 2 for heavy routes (search, purchase, etc.)"}}},"429":{"description":"Rate limit or channel quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quotaExceeded":{"value":{"error":{"code":"QUOTA_EXCEEDED","message":"Shared daily plan quota exceeded. Contact HIOBuy support.","request_id":"req_example"}}},"platformQuotaExceeded":{"value":{"error":{"code":"PLATFORM_QUOTA_EXCEEDED","message":"Channel capacity is temporarily unavailable. Contact HIOBuy support.","request_id":"req_example"}}}}}}}}}},"/v1/products/spus/list":{"post":{"summary":"Taobao distribution SPUs (/product/spus/get)","tags":["Taobao Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["taobao"],"default":"taobao"}}}}}},"responses":{"200":{"description":"Success","headers":{"X-Quota-Channel":{"schema":{"type":"string"}},"X-Quota-Remaining-Day":{"schema":{"type":"string"}},"X-Quota-Pack-Remaining":{"schema":{"type":"string"}},"X-Quota-Billable-Units":{"schema":{"type":"string"},"description":"1 for standard routes; 2 for heavy routes (search, purchase, etc.)"}}},"429":{"description":"Rate limit or channel quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quotaExceeded":{"value":{"error":{"code":"QUOTA_EXCEEDED","message":"Shared daily plan quota exceeded. Contact HIOBuy support.","request_id":"req_example"}}},"platformQuotaExceeded":{"value":{"error":{"code":"PLATFORM_QUOTA_EXCEEDED","message":"Channel capacity is temporarily unavailable. Contact HIOBuy support.","request_id":"req_example"}}}}}}}}}},"/v1/products/freight/batch-mp":{"post":{"summary":"Taobao batch domestic freight (/product/batchGetProductLogisticPrice)","tags":["Taobao Products"],"description":"Billable weight: **2** units.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["taobao"],"default":"taobao"}}}}}},"responses":{"200":{"description":"Success","headers":{"X-Quota-Channel":{"schema":{"type":"string"}},"X-Quota-Remaining-Day":{"schema":{"type":"string"}},"X-Quota-Pack-Remaining":{"schema":{"type":"string"}},"X-Quota-Billable-Units":{"schema":{"type":"string"},"description":"1 for standard routes; 2 for heavy routes (search, purchase, etc.)"}}},"429":{"description":"Rate limit or channel quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quotaExceeded":{"value":{"error":{"code":"QUOTA_EXCEEDED","message":"Shared daily plan quota exceeded. Contact HIOBuy support.","request_id":"req_example"}}},"platformQuotaExceeded":{"value":{"error":{"code":"PLATFORM_QUOTA_EXCEEDED","message":"Channel capacity is temporarily unavailable. Contact HIOBuy support.","request_id":"req_example"}}}}}}}}}},"/v1/products/upload-image":{"post":{"summary":"Upload image (1688 product.image.upload, Taobao /upload/image, or Weidian upload)","tags":["Products"],"description":"Returns image_id for 1688/Taobao search-by-image, or image_url for Weidian refundVoucher. Weidian accepts jpg/jpeg/png/gif up to 3MB. Billable weight: **2** units.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["1688","taobao","weidian"]},"image_base64":{"type":"string","description":"Base64 image (data URL prefix supported). Required for Taobao and Weidian. Request body max 6MB."},"image_url":{"type":"string","description":"1688 only. Public image URL; fetched server-side when image_base64 omitted"},"out_member_id":{"type":"string","description":"1688 only. Maps to upstream outMemberId"},"content_type":{"type":"string","enum":["image/jpeg","image/png","image/gif"],"description":"Weidian only. Required when image_base64 has no data URL prefix."},"file_name":{"type":"string","description":"Weidian only. Optional custom file name."},"media_group":{"type":"string","default":"0","description":"Weidian only. Media group ID."}},"required":["channel"]}}}},"responses":{"200":{"description":"Success","headers":{"X-Quota-Channel":{"schema":{"type":"string"}},"X-Quota-Remaining-Day":{"schema":{"type":"string"}},"X-Quota-Pack-Remaining":{"schema":{"type":"string"}},"X-Quota-Billable-Units":{"schema":{"type":"string"},"description":"1 for standard routes; 2 for heavy routes (search, purchase, etc.)"}}},"429":{"description":"Rate limit or channel quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quotaExceeded":{"value":{"error":{"code":"QUOTA_EXCEEDED","message":"Shared daily plan quota exceeded. Contact HIOBuy support.","request_id":"req_example"}}},"platformQuotaExceeded":{"value":{"error":{"code":"PLATFORM_QUOTA_EXCEEDED","message":"Channel capacity is temporarily unavailable. Contact HIOBuy support.","request_id":"req_example"}}}}}}}}}},"/v1/orders/purchase/query":{"post":{"summary":"Taobao query purchase orders (/purchase/orders/query)","tags":["Taobao Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Success","headers":{"X-Quota-Channel":{"schema":{"type":"string"}},"X-Quota-Remaining-Day":{"schema":{"type":"string"}},"X-Quota-Pack-Remaining":{"schema":{"type":"string"}},"X-Quota-Billable-Units":{"schema":{"type":"string"},"description":"1 for standard routes; 2 for heavy routes (search, purchase, etc.)"}}},"429":{"description":"Rate limit or channel quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quotaExceeded":{"value":{"error":{"code":"QUOTA_EXCEEDED","message":"Shared daily plan quota exceeded. Contact HIOBuy support.","request_id":"req_example"}}},"platformQuotaExceeded":{"value":{"error":{"code":"PLATFORM_QUOTA_EXCEEDED","message":"Channel capacity is temporarily unavailable. Contact HIOBuy support.","request_id":"req_example"}}}}}}}}}},"/v1/fulfillment/balance":{"get":{"summary":"Fulfillment wallet balance","description":"Warehouse-mode only. Amounts are fen (`monetary_unit: CNY_minor` on Public responses).","tags":["Fulfillment"],"responses":{"200":{"description":"Available / frozen balance"}}}},"/v1/fulfillment/transactions":{"get":{"summary":"List fulfillment wallet transactions","tags":["Fulfillment Finance"],"parameters":[{"name":"type","in":"query","description":"Exact single value: CREDIT | DEBIT | REFUND | ADJUSTMENT","schema":{"type":"string","enum":["CREDIT","DEBIT","REFUND","ADJUSTMENT"]}},{"name":"category","in":"query","description":"Exact single value: TOP_UP | PROCUREMENT | SHIPPING | VALUE_ADDED_SERVICE | RETURN | STORAGE | TRANSFER | REFUND | MANUAL_ADJUSTMENT | OTHER","schema":{"type":"string","enum":["TOP_UP","PROCUREMENT","SHIPPING","VALUE_ADDED_SERVICE","RETURN","STORAGE","TRANSFER","REFUND","MANUAL_ADJUSTMENT","OTHER"]}},{"name":"invoice_status","in":"query","description":"Exact single value: NOT_INVOICED | AVAILABLE | INVOICE_PENDING | INVOICED","schema":{"type":"string","enum":["NOT_INVOICED","AVAILABLE","INVOICE_PENDING","INVOICED"]}},{"name":"related_resource_type","in":"query","description":"Exact single value: PACKAGE | SHIPMENT | RETURN | SERVICE_REQUEST | INBOUND","schema":{"type":"string","enum":["PACKAGE","SHIPMENT","RETURN","SERVICE_REQUEST","INBOUND"]}},{"name":"related_resource_id","in":"query","description":"Exact related resource id","schema":{"type":"string"}},{"name":"created_from","in":"query","description":"created_at >= (ISO-8601)","schema":{"type":"string","format":"date-time"}},{"name":"created_to","in":"query","description":"created_at <= (ISO-8601)","schema":{"type":"string","format":"date-time"}},{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1}},{"name":"page_size","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}}],"responses":{"200":{"description":"Transaction list"}}}},"/v1/fulfillment/transactions/{transaction_id}":{"get":{"summary":"Fulfillment transaction detail","tags":["Fulfillment Finance"],"parameters":[{"name":"transaction_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Transaction detail"}}}},"/v1/fulfillment/invoices":{"get":{"summary":"List fulfillment invoices","tags":["Fulfillment Finance"],"parameters":[{"name":"status","in":"query","description":"Exact single value: PENDING | ISSUED | REJECTED | CANCELLED","schema":{"type":"string","enum":["PENDING","ISSUED","REJECTED","CANCELLED"]}},{"name":"created_from","in":"query","description":"created_at >= (ISO-8601)","schema":{"type":"string","format":"date-time"}},{"name":"created_to","in":"query","description":"created_at <= (ISO-8601)","schema":{"type":"string","format":"date-time"}},{"name":"issued_from","in":"query","description":"issued_at >= (ISO-8601); excludes invoices with null issued_at","schema":{"type":"string","format":"date-time"}},{"name":"issued_to","in":"query","description":"issued_at <= (ISO-8601); excludes invoices with null issued_at","schema":{"type":"string","format":"date-time"}},{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1}},{"name":"page_size","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}}],"responses":{"200":{"description":"Invoice list"}}},"post":{"summary":"Request an overseas commercial invoice","description":"Bill-to overseas invoice for fulfillment wallet charges. Not a Chinese VAT invoice. Server totals selected AVAILABLE transactions.","tags":["Fulfillment Finance"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"transaction_ids":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Eligible transaction ids (invoice_status=AVAILABLE)"},"invoice_title":{"type":"string","maxLength":200,"description":"Bill-to name (company or individual legal name)"},"billing_address":{"type":"object","description":"Bill-to address on the overseas invoice","properties":{"address1":{"type":"string"},"address2":{"type":"string","nullable":true},"city":{"type":"string"},"state":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"country_code":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"}},"required":["address1","city","country_code"]},"tax_number":{"type":"string","maxLength":64,"description":"Optional overseas tax ID / VAT ID"},"email":{"type":"string","format":"email","description":"Optional delivery email for the PDF / notification"},"remark":{"type":"string","description":"Optional free-text note"}},"required":["transaction_ids","invoice_title","billing_address"]}}}},"responses":{"201":{"description":"Overseas invoice request created (pending issue)"}}}},"/v1/fulfillment/invoices/{invoice_id}":{"get":{"summary":"Fulfillment invoice detail","tags":["Fulfillment Finance"],"parameters":[{"name":"invoice_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Invoice detail"}}}},"/v1/fulfillment/invoices/{invoice_id}/download":{"get":{"summary":"Download issued invoice file","description":"Only when invoice status is ISSUED.","tags":["Fulfillment Finance"],"parameters":[{"name":"invoice_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Download URL / file metadata"}}}},"/v1/fulfillment/shipping/quotes":{"post":{"summary":"Estimate international shipping charges","description":"Declared-data estimate supporting either a single-package shorthand or an explicit packages array. Use KG for weight and CM for dimensions; do not combine the two request forms. Channel, region, service, money, and billing terminology matches GET /v1/fulfillment/shipping/channels. A complete quote is still subject to warehouse measurement and review.","tags":["Fulfillment"],"parameters":[{"name":"Language","in":"header","required":false,"schema":{"type":"string","enum":["en","en-US","zh","zh-CN","zh-TW","cn","hk"],"default":"en"},"description":"Localization language for channel names, messages, and warnings"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["destination"],"oneOf":[{"title":"Single-package shorthand","required":["weight_kg"],"not":{"required":["packages"]}},{"title":"Known multi-package shipment","required":["packages"],"not":{"anyOf":[{"required":["weight_kg"]},{"required":["length_cm"]},{"required":["width_cm"]},{"required":["height_cm"]}]}}],"properties":{"destination":{"type":"object","additionalProperties":false,"required":["country_code"],"properties":{"country_code":{"type":"string","minLength":2,"maxLength":2},"subdivision_code":{"type":"string","pattern":"^[A-Za-z]{2}-[A-Za-z0-9]{1,3}$"},"region":{"type":"string","maxLength":200},"postal_code":{"type":"string","maxLength":32}}},"weight_kg":{"type":"number","minimum":0,"exclusiveMinimum":true,"maximum":100000,"description":"Estimated total shipment weight in kilograms"},"length_cm":{"type":"number","minimum":0,"exclusiveMinimum":true,"maximum":10000,"description":"Estimated consolidated package length in centimeters; provide all three dimensions together"},"width_cm":{"type":"number","minimum":0,"exclusiveMinimum":true,"maximum":10000,"description":"Estimated consolidated package width in centimeters; provide all three dimensions together"},"height_cm":{"type":"number","minimum":0,"exclusiveMinimum":true,"maximum":10000,"description":"Estimated consolidated package height in centimeters; provide all three dimensions together"},"packages":{"type":"array","minItems":1,"maxItems":200,"description":"Use only when the package split is already known; do not combine with the single-package shorthand fields","items":{"type":"object","additionalProperties":false,"required":["weight"],"properties":{"reference":{"type":"string","maxLength":100},"weight":{"type":"object","additionalProperties":false,"required":["value","unit"],"properties":{"value":{"type":"number","minimum":0,"exclusiveMinimum":true,"maximum":100000},"unit":{"type":"string","enum":["KG"]}}},"dimensions":{"type":"object","additionalProperties":false,"required":["length","width","height","unit"],"properties":{"length":{"type":"number","minimum":0,"exclusiveMinimum":true,"maximum":10000},"width":{"type":"number","minimum":0,"exclusiveMinimum":true,"maximum":10000},"height":{"type":"number","minimum":0,"exclusiveMinimum":true,"maximum":10000},"unit":{"type":"string","enum":["CM"]}}}}}},"declared_value":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","minimum":0,"maximum":100000000000,"description":"Declared value in CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}}},"attributes":{"type":"array","maxItems":100,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":64}},"services":{"type":"object","additionalProperties":false,"properties":{"channel":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["code","quantity"],"properties":{"code":{"type":"string","minLength":1,"maxLength":64},"quantity":{"type":"integer","minimum":1,"maximum":999}}}},"outbound":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["code","quantity"],"properties":{"code":{"type":"string","minLength":1,"maxLength":64},"quantity":{"type":"integer","minimum":1,"maximum":999}}}},"inbound":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["code","quantity"],"properties":{"code":{"type":"string","minLength":1,"maxLength":64},"quantity":{"type":"integer","minimum":1,"maximum":999}}}}}},"channel_codes":{"type":"array","minItems":1,"maxItems":100,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":64}}}}}}},"responses":{"200":{"description":"Normalized complete, partial, review-required, and unavailable quote options","content":{"application/json":{"schema":{"type":"object","required":["success","estimate_type","completeness","warnings","quotes","monetary_unit","generated_at","request_id","disclaimer"],"properties":{"success":{"type":"boolean","enum":[true]},"estimate_type":{"type":"string","enum":["DECLARED"]},"completeness":{"type":"object","description":"Input coverage; not an accuracy or deliverability guarantee"},"warnings":{"type":"array","items":{"type":"object"}},"quotes":{"type":"array","description":"Complete quotes first, partial/review quotes next, unavailable channels last","items":{"type":"object","required":["channel","available","quote_status","unavailable_reason","matched_region","packages","weights","transit_time","charges","total","warnings","service_adjustment_possible"],"properties":{"channel":{"type":"object","description":"Uses the same code/name/description/tags terminology as the channel catalog","properties":{"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"logo_url":{"type":"string","format":"uri","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"capabilities":{"type":"object","description":"Optional additive channel capability snapshot. Existing clients may ignore this object. delivery_methods uses the same stable codes as the shipping channel catalog and is returned for available and unavailable quotes.","properties":{"delivery_methods":{"type":"array","description":"Supported last-mile delivery methods for this channel. The array may contain multiple methods.","items":{"type":"string","enum":["DOOR_DELIVERY","PICKUP","POST_OFFICE_PICKUP"]}}}}}},"available":{"type":"boolean"},"quote_status":{"type":"string","enum":["COMPLETE","PARTIAL","REVIEW_REQUIRED","UNAVAILABLE"]},"unavailable_reason":{"type":"object","nullable":true},"attribute_evaluation":{"type":"object","nullable":true,"description":"Optional per-channel evaluation of the declared item attributes. Added compatibly; clients may ignore it.","properties":{"status":{"type":"string","enum":["SUPPORTED","UNSUPPORTED","NOT_DECLARED"]},"declared_attributes":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}}},"accepted_attributes":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}}},"unsupported_attributes":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}}}}},"matched_region":{"type":"object","nullable":true,"description":"Uses the same region code/name/match_type terminology as the channel catalog"},"packages":{"type":"array","items":{"type":"object"}},"weights":{"type":"object","nullable":true},"billing_quantity":{"type":"object"},"pricing_selector":{"type":"object"},"transit_time":{"type":"object","nullable":true,"description":"Structured estimated business-day range for the matched region","properties":{"text":{"type":"string"},"min_days":{"type":"integer","minimum":0},"max_days":{"type":"integer","minimum":0},"day_type":{"type":"string","enum":["BUSINESS_DAY"]},"min_business_days":{"type":"integer","minimum":0},"max_business_days":{"type":"integer","minimum":0}}},"charges":{"type":"object","properties":{"base_freight":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}}},"channel_services":{"type":"object","required":["amount","currency","known_amount","calculation_status","items"],"properties":{"amount":{"type":"integer","nullable":true,"description":"Aggregated CNY minor units after rule selection and cap"},"currency":{"type":"string","enum":["CNY"]},"known_amount":{"type":"integer","description":"CNY minor units included in the current estimate"},"calculation_status":{"type":"string"},"missing_fields":{"type":"array","items":{"type":"string"}},"items":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","nullable":true},"rule_id":{"type":"string","nullable":true,"description":"ERP rule identifier for diagnostics only"},"name":{"type":"string"},"category":{"type":"string"},"source":{"type":"string","enum":["MANDATORY","DEVELOPER_SELECTED","RULE_ENGINE"]},"pricing_basis":{"type":"string"},"quantity":{"type":"number"},"unit_price":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true},"amount":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true},"estimated":{"type":"boolean"},"calculation_status":{"type":"string"},"included_in_total":{"type":"boolean"},"outcome":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true,"description":"Localized fallback explanation; do not parse for program logic"},"condition_match":{"type":"string","enum":["ALL","ANY"],"nullable":true},"matched_conditions":{"type":"array","items":{"type":"object","required":["parameter","operator","actual_value","threshold_value","unit"],"properties":{"parameter":{"type":"string","description":"Stable rule parameter. New values may be added without changing existing meanings.","enum":["SHIPMENT_CHARGEABLE_WEIGHT","SHIPMENT_ACTUAL_WEIGHT","SHIPMENT_VOLUMETRIC_WEIGHT","PACKAGE_CHARGEABLE_WEIGHT","PACKAGE_ACTUAL_WEIGHT","PACKAGE_VOLUMETRIC_WEIGHT","AVERAGE_PACKAGE_WEIGHT","LONGEST_SIDE","SECOND_LONGEST_SIDE","THREE_SIDE_SUM","TWO_SIDE_SUM","GIRTH","VOLUME","PACKAGE_COUNT","DECLARED_VALUE","BASE_FREIGHT","ADDRESS_TAG","REMOTE_AREA"]},"operator":{"type":"string","enum":["GT","GTE","LT","LTE","EQ","CONTAINS"]},"actual_value":{"description":"Actual shipment value; monetary values use a Money object.","oneOf":[{"type":"number"},{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}}}],"nullable":true},"threshold_value":{"description":"Configured rule threshold in the same type and unit as actual_value.","oneOf":[{"type":"number"},{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}}}],"nullable":true},"unit":{"type":"string","enum":["KG","CM","M3","KG_M3"],"nullable":true}}}},"rule_type":{"type":"string","enum":["PER_SHIPMENT","PER_BOX","PER_CHARGEABLE_WEIGHT","FORBIDDEN","FORBID_ORDERING","ADVANCED"],"nullable":true},"charge_mode":{"type":"string","enum":["FIXED","DECLARED_VALUE_PERCENT","BASE_FREIGHT_PERCENT","FORMULA"],"nullable":true},"charge_value":{"description":"Configured potential rate, not necessarily charged by this estimate","oneOf":[{"type":"number"},{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}}}],"nullable":true},"min_charge":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true},"max_charge":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true},"formula":{"type":"object","nullable":true},"applied_packages":{"type":"array","items":{"type":"string"}}}}},"aggregation":{"type":"string","enum":["SUM_ALL","HIGHEST_ONLY"],"description":"SUM_ALL charges all matched rules; HIGHEST_ONLY charges the highest-priced rule in the matched region"},"cap":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true,"description":"Cap applied after aggregation. Null or zero means no cap."}}},"channel_rules":{"type":"object","required":["amount","currency","known_amount","calculation_status","items"],"properties":{"amount":{"type":"integer","nullable":true,"description":"Aggregated CNY minor units after rule selection and cap"},"currency":{"type":"string","enum":["CNY"]},"known_amount":{"type":"integer","description":"CNY minor units included in the current estimate"},"calculation_status":{"type":"string"},"missing_fields":{"type":"array","items":{"type":"string"}},"items":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","nullable":true},"rule_id":{"type":"string","nullable":true,"description":"ERP rule identifier for diagnostics only"},"name":{"type":"string"},"category":{"type":"string"},"source":{"type":"string","enum":["MANDATORY","DEVELOPER_SELECTED","RULE_ENGINE"]},"pricing_basis":{"type":"string"},"quantity":{"type":"number"},"unit_price":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true},"amount":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true},"estimated":{"type":"boolean"},"calculation_status":{"type":"string"},"included_in_total":{"type":"boolean"},"outcome":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true,"description":"Localized fallback explanation; do not parse for program logic"},"condition_match":{"type":"string","enum":["ALL","ANY"],"nullable":true},"matched_conditions":{"type":"array","items":{"type":"object","required":["parameter","operator","actual_value","threshold_value","unit"],"properties":{"parameter":{"type":"string","description":"Stable rule parameter. New values may be added without changing existing meanings.","enum":["SHIPMENT_CHARGEABLE_WEIGHT","SHIPMENT_ACTUAL_WEIGHT","SHIPMENT_VOLUMETRIC_WEIGHT","PACKAGE_CHARGEABLE_WEIGHT","PACKAGE_ACTUAL_WEIGHT","PACKAGE_VOLUMETRIC_WEIGHT","AVERAGE_PACKAGE_WEIGHT","LONGEST_SIDE","SECOND_LONGEST_SIDE","THREE_SIDE_SUM","TWO_SIDE_SUM","GIRTH","VOLUME","PACKAGE_COUNT","DECLARED_VALUE","BASE_FREIGHT","ADDRESS_TAG","REMOTE_AREA"]},"operator":{"type":"string","enum":["GT","GTE","LT","LTE","EQ","CONTAINS"]},"actual_value":{"description":"Actual shipment value; monetary values use a Money object.","oneOf":[{"type":"number"},{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}}}],"nullable":true},"threshold_value":{"description":"Configured rule threshold in the same type and unit as actual_value.","oneOf":[{"type":"number"},{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}}}],"nullable":true},"unit":{"type":"string","enum":["KG","CM","M3","KG_M3"],"nullable":true}}}},"rule_type":{"type":"string","enum":["PER_SHIPMENT","PER_BOX","PER_CHARGEABLE_WEIGHT","FORBIDDEN","FORBID_ORDERING","ADVANCED"],"nullable":true},"charge_mode":{"type":"string","enum":["FIXED","DECLARED_VALUE_PERCENT","BASE_FREIGHT_PERCENT","FORMULA"],"nullable":true},"charge_value":{"description":"Configured potential rate, not necessarily charged by this estimate","oneOf":[{"type":"number"},{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}}}],"nullable":true},"min_charge":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true},"max_charge":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true},"formula":{"type":"object","nullable":true},"applied_packages":{"type":"array","items":{"type":"string"}}}}},"aggregation":{"type":"string","enum":["SUM_ALL","HIGHEST_ONLY"],"description":"SUM_ALL charges all matched rules; HIGHEST_ONLY charges the highest-priced rule in the matched region"},"cap":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true,"description":"Cap applied after aggregation. Null or zero means no cap."}}},"outbound_services":{"type":"object","required":["amount","currency","known_amount","calculation_status","items"],"properties":{"amount":{"type":"integer","nullable":true,"description":"Aggregated CNY minor units after rule selection and cap"},"currency":{"type":"string","enum":["CNY"]},"known_amount":{"type":"integer","description":"CNY minor units included in the current estimate"},"calculation_status":{"type":"string"},"missing_fields":{"type":"array","items":{"type":"string"}},"items":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","nullable":true},"rule_id":{"type":"string","nullable":true,"description":"ERP rule identifier for diagnostics only"},"name":{"type":"string"},"category":{"type":"string"},"source":{"type":"string","enum":["MANDATORY","DEVELOPER_SELECTED","RULE_ENGINE"]},"pricing_basis":{"type":"string"},"quantity":{"type":"number"},"unit_price":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true},"amount":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true},"estimated":{"type":"boolean"},"calculation_status":{"type":"string"},"included_in_total":{"type":"boolean"},"outcome":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true,"description":"Localized fallback explanation; do not parse for program logic"},"condition_match":{"type":"string","enum":["ALL","ANY"],"nullable":true},"matched_conditions":{"type":"array","items":{"type":"object","required":["parameter","operator","actual_value","threshold_value","unit"],"properties":{"parameter":{"type":"string","description":"Stable rule parameter. New values may be added without changing existing meanings.","enum":["SHIPMENT_CHARGEABLE_WEIGHT","SHIPMENT_ACTUAL_WEIGHT","SHIPMENT_VOLUMETRIC_WEIGHT","PACKAGE_CHARGEABLE_WEIGHT","PACKAGE_ACTUAL_WEIGHT","PACKAGE_VOLUMETRIC_WEIGHT","AVERAGE_PACKAGE_WEIGHT","LONGEST_SIDE","SECOND_LONGEST_SIDE","THREE_SIDE_SUM","TWO_SIDE_SUM","GIRTH","VOLUME","PACKAGE_COUNT","DECLARED_VALUE","BASE_FREIGHT","ADDRESS_TAG","REMOTE_AREA"]},"operator":{"type":"string","enum":["GT","GTE","LT","LTE","EQ","CONTAINS"]},"actual_value":{"description":"Actual shipment value; monetary values use a Money object.","oneOf":[{"type":"number"},{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}}}],"nullable":true},"threshold_value":{"description":"Configured rule threshold in the same type and unit as actual_value.","oneOf":[{"type":"number"},{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}}}],"nullable":true},"unit":{"type":"string","enum":["KG","CM","M3","KG_M3"],"nullable":true}}}},"rule_type":{"type":"string","enum":["PER_SHIPMENT","PER_BOX","PER_CHARGEABLE_WEIGHT","FORBIDDEN","FORBID_ORDERING","ADVANCED"],"nullable":true},"charge_mode":{"type":"string","enum":["FIXED","DECLARED_VALUE_PERCENT","BASE_FREIGHT_PERCENT","FORMULA"],"nullable":true},"charge_value":{"description":"Configured potential rate, not necessarily charged by this estimate","oneOf":[{"type":"number"},{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}}}],"nullable":true},"min_charge":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true},"max_charge":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true},"formula":{"type":"object","nullable":true},"applied_packages":{"type":"array","items":{"type":"string"}}}}},"aggregation":{"type":"string","enum":["SUM_ALL","HIGHEST_ONLY"],"description":"SUM_ALL charges all matched rules; HIGHEST_ONLY charges the highest-priced rule in the matched region"},"cap":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true,"description":"Cap applied after aggregation. Null or zero means no cap."}}},"inbound_services":{"type":"object","required":["amount","currency","known_amount","calculation_status","items"],"properties":{"amount":{"type":"integer","nullable":true,"description":"Aggregated CNY minor units after rule selection and cap"},"currency":{"type":"string","enum":["CNY"]},"known_amount":{"type":"integer","description":"CNY minor units included in the current estimate"},"calculation_status":{"type":"string"},"missing_fields":{"type":"array","items":{"type":"string"}},"items":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","nullable":true},"rule_id":{"type":"string","nullable":true,"description":"ERP rule identifier for diagnostics only"},"name":{"type":"string"},"category":{"type":"string"},"source":{"type":"string","enum":["MANDATORY","DEVELOPER_SELECTED","RULE_ENGINE"]},"pricing_basis":{"type":"string"},"quantity":{"type":"number"},"unit_price":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true},"amount":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true},"estimated":{"type":"boolean"},"calculation_status":{"type":"string"},"included_in_total":{"type":"boolean"},"outcome":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true,"description":"Localized fallback explanation; do not parse for program logic"},"condition_match":{"type":"string","enum":["ALL","ANY"],"nullable":true},"matched_conditions":{"type":"array","items":{"type":"object","required":["parameter","operator","actual_value","threshold_value","unit"],"properties":{"parameter":{"type":"string","description":"Stable rule parameter. New values may be added without changing existing meanings.","enum":["SHIPMENT_CHARGEABLE_WEIGHT","SHIPMENT_ACTUAL_WEIGHT","SHIPMENT_VOLUMETRIC_WEIGHT","PACKAGE_CHARGEABLE_WEIGHT","PACKAGE_ACTUAL_WEIGHT","PACKAGE_VOLUMETRIC_WEIGHT","AVERAGE_PACKAGE_WEIGHT","LONGEST_SIDE","SECOND_LONGEST_SIDE","THREE_SIDE_SUM","TWO_SIDE_SUM","GIRTH","VOLUME","PACKAGE_COUNT","DECLARED_VALUE","BASE_FREIGHT","ADDRESS_TAG","REMOTE_AREA"]},"operator":{"type":"string","enum":["GT","GTE","LT","LTE","EQ","CONTAINS"]},"actual_value":{"description":"Actual shipment value; monetary values use a Money object.","oneOf":[{"type":"number"},{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}}}],"nullable":true},"threshold_value":{"description":"Configured rule threshold in the same type and unit as actual_value.","oneOf":[{"type":"number"},{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}}}],"nullable":true},"unit":{"type":"string","enum":["KG","CM","M3","KG_M3"],"nullable":true}}}},"rule_type":{"type":"string","enum":["PER_SHIPMENT","PER_BOX","PER_CHARGEABLE_WEIGHT","FORBIDDEN","FORBID_ORDERING","ADVANCED"],"nullable":true},"charge_mode":{"type":"string","enum":["FIXED","DECLARED_VALUE_PERCENT","BASE_FREIGHT_PERCENT","FORMULA"],"nullable":true},"charge_value":{"description":"Configured potential rate, not necessarily charged by this estimate","oneOf":[{"type":"number"},{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}}}],"nullable":true},"min_charge":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true},"max_charge":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true},"formula":{"type":"object","nullable":true},"applied_packages":{"type":"array","items":{"type":"string"}}}}},"aggregation":{"type":"string","enum":["SUM_ALL","HIGHEST_ONLY"],"description":"SUM_ALL charges all matched rules; HIGHEST_ONLY charges the highest-priced rule in the matched region"},"cap":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true,"description":"Cap applied after aggregation. Null or zero means no cap."}}},"adjustments":{"type":"object","required":["amount","currency","known_amount","calculation_status","items"],"properties":{"amount":{"type":"integer","nullable":true,"description":"Aggregated CNY minor units after rule selection and cap"},"currency":{"type":"string","enum":["CNY"]},"known_amount":{"type":"integer","description":"CNY minor units included in the current estimate"},"calculation_status":{"type":"string"},"missing_fields":{"type":"array","items":{"type":"string"}},"items":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","nullable":true},"rule_id":{"type":"string","nullable":true,"description":"ERP rule identifier for diagnostics only"},"name":{"type":"string"},"category":{"type":"string"},"source":{"type":"string","enum":["MANDATORY","DEVELOPER_SELECTED","RULE_ENGINE"]},"pricing_basis":{"type":"string"},"quantity":{"type":"number"},"unit_price":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true},"amount":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true},"estimated":{"type":"boolean"},"calculation_status":{"type":"string"},"included_in_total":{"type":"boolean"},"outcome":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true,"description":"Localized fallback explanation; do not parse for program logic"},"condition_match":{"type":"string","enum":["ALL","ANY"],"nullable":true},"matched_conditions":{"type":"array","items":{"type":"object","required":["parameter","operator","actual_value","threshold_value","unit"],"properties":{"parameter":{"type":"string","description":"Stable rule parameter. New values may be added without changing existing meanings.","enum":["SHIPMENT_CHARGEABLE_WEIGHT","SHIPMENT_ACTUAL_WEIGHT","SHIPMENT_VOLUMETRIC_WEIGHT","PACKAGE_CHARGEABLE_WEIGHT","PACKAGE_ACTUAL_WEIGHT","PACKAGE_VOLUMETRIC_WEIGHT","AVERAGE_PACKAGE_WEIGHT","LONGEST_SIDE","SECOND_LONGEST_SIDE","THREE_SIDE_SUM","TWO_SIDE_SUM","GIRTH","VOLUME","PACKAGE_COUNT","DECLARED_VALUE","BASE_FREIGHT","ADDRESS_TAG","REMOTE_AREA"]},"operator":{"type":"string","enum":["GT","GTE","LT","LTE","EQ","CONTAINS"]},"actual_value":{"description":"Actual shipment value; monetary values use a Money object.","oneOf":[{"type":"number"},{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}}}],"nullable":true},"threshold_value":{"description":"Configured rule threshold in the same type and unit as actual_value.","oneOf":[{"type":"number"},{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}}}],"nullable":true},"unit":{"type":"string","enum":["KG","CM","M3","KG_M3"],"nullable":true}}}},"rule_type":{"type":"string","enum":["PER_SHIPMENT","PER_BOX","PER_CHARGEABLE_WEIGHT","FORBIDDEN","FORBID_ORDERING","ADVANCED"],"nullable":true},"charge_mode":{"type":"string","enum":["FIXED","DECLARED_VALUE_PERCENT","BASE_FREIGHT_PERCENT","FORMULA"],"nullable":true},"charge_value":{"description":"Configured potential rate, not necessarily charged by this estimate","oneOf":[{"type":"number"},{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}}}],"nullable":true},"min_charge":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true},"max_charge":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true},"formula":{"type":"object","nullable":true},"applied_packages":{"type":"array","items":{"type":"string"}}}}},"aggregation":{"type":"string","enum":["SUM_ALL","HIGHEST_ONLY"],"description":"SUM_ALL charges all matched rules; HIGHEST_ONLY charges the highest-priced rule in the matched region"},"cap":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true,"description":"Cap applied after aggregation. Null or zero means no cap."}}}},"nullable":true},"display_charges":{"type":"object"},"total":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}},"nullable":true},"known_total":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"CNY minor units (fen)"},"currency":{"type":"string","enum":["CNY"]}}},"warnings":{"type":"array","items":{"type":"object"}},"service_adjustment_possible":{"type":"boolean"}}}},"monetary_unit":{"type":"string","enum":["CNY_minor"]},"generated_at":{"type":"string","format":"date-time"},"request_id":{"type":"string"},"disclaimer":{"type":"string"}}}}}}}}},"/v1/fulfillment/shipping/channels":{"get":{"summary":"List international shipping channels","description":"Returns normalized channel capabilities, supported and unsupported item attributes, billing metadata, logo_url, structured reference transit times, and a channel-rule summary. country_code strictly filters destination applicability; channels for other countries are omitted. unsupported_attributes is an additive optional field for backward compatibility. Use include=regions,services,rate_cards,rules for optional expansions. Service region_prices use PERCENT for percentage points (10 means 10%) and MINOR_UNIT for fixed CNY amounts in fen. pricing_basis determines whether the value is applied to base freight, declared value, each shipment, box, weight unit, volume unit, or package count. rule_summary.aggregation and rule_summary.cap use the same vocabulary as quote charges.channel_rules. Catalog formulas describe possible configuration; obtain matched charges and shipment-specific amounts from POST /v1/fulfillment/shipping/quotes.","tags":["Fulfillment"],"parameters":[{"name":"channel_code","in":"query","required":false,"schema":{"type":"string","maxLength":64},"description":"Exact stable shipping channel code"},{"name":"country_code","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2},"description":"ISO 3166-1 alpha-2 destination country"},{"name":"Language","in":"header","required":false,"schema":{"type":"string","enum":["en","en-US","zh","zh-CN","zh-TW","cn","hk"],"default":"en"},"description":"Localization language for channel names and descriptions"},{"name":"include","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated expansions: regions, services, rate_cards, rules. Omit for channel summaries."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"Shipping channel catalog; monetary_unit is CNY_minor and all rate cards are reference-only"}}}},"/v1/fulfillment/shipping/channels/{shipping_channel_code}":{"get":{"summary":"Get an international shipping channel","description":"Returns one channel using exactly the same normalized fields as an item from the channel list under the same filters. Reference rate cards are included by default; channel rules are omitted by default. Use include=regions,services,rate_cards,rules to select expansions explicitly. A channel that is missing, not visible to the bound warehouse, or excluded by country_code returns CHANNEL_NOT_FOUND.","tags":["Fulfillment"],"parameters":[{"name":"shipping_channel_code","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64},"description":"Exact stable shipping channel code; database IDs are not accepted"},{"name":"country_code","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2},"description":"Optional ISO 3166-1 alpha-2 destination filter"},{"name":"Language","in":"header","required":false,"schema":{"type":"string","enum":["en","en-US","zh","zh-CN","zh-TW","cn","hk"],"default":"en"}},{"name":"include","in":"query","required":false,"schema":{"type":"string","default":"rate_cards"},"description":"Comma-separated expansions: regions, services, rate_cards, rules"}],"responses":{"200":{"description":"A single normalized channel object, identical to a matching list item"},"404":{"description":"CHANNEL_NOT_FOUND"}}}},"/v1/fulfillment/shipments/create":{"post":{"summary":"Create international shipment","tags":["Fulfillment"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Recommended for safe retries. Reusing a key with the same request replays the original result; reusing it with a different request returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tracking_numbers":{"type":"array","items":{"type":"string"}},"receiver":{"type":"object","properties":{"name":{"type":"string"},"mobile":{"type":"string"},"email":{"type":"string"},"country_code":{"type":"string"},"province":{"type":"string"},"city":{"type":"string"},"district":{"type":"string","nullable":true},"postal_code":{"type":"string"},"address_line1":{"type":"string"},"address_line2":{"type":"string"},"personal_code":{"type":"string","description":"Optional personal customs clearance code (e.g. Korea PCCC); route-dependent."}},"required":["name","mobile","country_code","address_line1"]},"shipping_channel_code":{"type":"string"},"external_shipment_id":{"type":"string"},"services":{"type":"array","items":{"type":"object"}},"remark":{"type":"string"},"language":{"type":"string","default":"en"}},"required":["tracking_numbers","receiver","shipping_channel_code"]}}}},"responses":{"201":{"description":"Public id = warehouse numeric PK as string; order_sn; typically status PENDING"},"409":{"description":"Duplicate external shipment/tracking number, idempotency conflict, or another request with the same key is in progress. details may include existing_resource, existing_resources, conflicting_tracking_numbers, idempotency_key, or retry_after_ms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/fulfillment/shipments/{shipment_id}/pay":{"post":{"summary":"Pay international shipment from wallet","description":"Accepts either the HioBuy shipment ID or the external_shipment_id supplied at create time. Numeric-only path values use shipment_id; prefixed/non-numeric values use external_shipment_id. Empty body is allowed.","tags":["Fulfillment"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Recommended for safe retries. Reusing a key with the same request replays the original result; reusing it with a different request returns 409."},{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string"},"description":"HioBuy shipment ID or external_shipment_id supplied at create time. Numeric-only values are resolved as HioBuy internal IDs; any value containing a non-digit is resolved as external_shipment_id. Prefix developer identifiers (for example, shp_MY-ORDER-001)."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Payment result / updated status"},"409":{"description":"Already paid, idempotency conflict, or another payment with the same key is in progress. details may include existing_resource, idempotency_key, or retry_after_ms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/fulfillment/shipments/{shipment_id}/cancel":{"post":{"summary":"Cancel international shipment","description":"Accepts either the HioBuy shipment ID or the external_shipment_id supplied at create time. Numeric-only path values use shipment_id; prefixed/non-numeric values use external_shipment_id.","tags":["Fulfillment"],"parameters":[{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string"},"description":"HioBuy shipment ID or external_shipment_id supplied at create time. Numeric-only values are resolved as HioBuy internal IDs; any value containing a non-digit is resolved as external_shipment_id. Prefix developer identifiers (for example, shp_MY-ORDER-001)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cancel_reason":{"type":"string"}},"required":["cancel_reason"]}}}},"responses":{"200":{"description":"Cancelled"}}}},"/v1/fulfillment/shipments/{shipment_id}/intercept":{"post":{"summary":"Request interception of an in-progress shipment","description":"Ask the warehouse to stop a shipment that has entered outbound (WAIT_SHIP / SHIPPED). The independent interception.status progresses through REQUESTED, PROCESSING, and INTERCEPTED or FAILED; it does not replace or overwrite the shipment lifecycle status. Warehouse upstream is POST …/shipments/set-exceptional with `{ shipment_id, reason, remark }`. reason is a fixed CODE; remark is required when reason is OTHER.","tags":["Fulfillment"],"parameters":[{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","enum":["CUSTOMER_REQUEST","ADDRESS_ISSUE","ORDER_CHANGE","PAYMENT_ISSUE","COMPLIANCE_ISSUE","PACKAGE_ISSUE","OTHER"]},"remark":{"type":"string"}},"required":["reason"]}}}},"responses":{"200":{"description":"Interception requested (status REQUESTED)"}}}},"/v1/fulfillment/shipments":{"get":{"summary":"List international shipments","description":"Lightweight shipment rows (status, receiver, channel, services, totals). Public `id` is the warehouse numeric PK as a string (e.g. `\"115\"`); `order_sn` is the warehouse order number. Full boxes / files / legs / charges stay on GET …/{id}. Warehouse upstream is POST …/shipments/index. Amounts are CNY fen.","tags":["Fulfillment"],"parameters":[{"name":"status","in":"query","schema":{"type":"string"},"description":"Comma-separated or repeated shipment status CODEs: PENDING, WAIT_PAYMENT, WAIT_SHIP, SHIPPED, SIGNED, CANCELLED. Warehouse index commonly filters PENDING, WAIT_SHIP, SHIPPED, SIGNED."},{"name":"created_from","in":"query","schema":{"type":"string"},"description":"Created-at lower bound (YYYY-MM-DD or datetime). Maps to warehouse create_from."},{"name":"created_to","in":"query","schema":{"type":"string"},"description":"Created-at upper bound. Maps to warehouse create_to."},{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"page_size","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Lightweight shipment list"}}}},"/v1/fulfillment/shipments/{shipment_id}":{"get":{"summary":"International shipment detail","description":"Rich shipment view: source packages, outbound boxes, packing media, international_tracking, warehouse business timeline, charge lines, and the independent interception workflow. timeline events contain required code, status, title, occurred_at, and details fields and are returned newest first. Accepts the HioBuy shipment ID or external_shipment_id; numeric-only path values use the internal ID and prefixed/non-numeric values use external_shipment_id. shipping_legs stay empty until first/last-mile numbers exist. Carrier scan events stay on GET …/tracking. Amounts are CNY fen.","tags":["Fulfillment"],"parameters":[{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string"},"description":"HioBuy shipment ID or external_shipment_id supplied at create time. Numeric-only values are resolved as HioBuy internal IDs; any value containing a non-digit is resolved as external_shipment_id. Prefix developer identifiers (for example, shp_MY-ORDER-001)."},{"name":"language","in":"query","required":false,"schema":{"type":"string","default":"en"},"description":"Display language for localized labels (default en)"}],"responses":{"200":{"description":"Shipment detail","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"required":["status","timeline"],"properties":{"status":{"$ref":"#/components/schemas/ShipmentStatus"},"interception":{"$ref":"#/components/schemas/ShipmentInterception"},"timeline":{"type":"array","description":"Newest-first shipment events. Every event uses a stable non-null code and a timezone-aware occurred_at value.","items":{"$ref":"#/components/schemas/ShipmentTimelineEvent"}}}}}}}}}},"/v1/fulfillment/shipments/{shipment_id}/tracking":{"get":{"summary":"International shipment tracking","description":"Warehouse → overseas recipient scan events. timeline events contain required code, status, title, occurred_at, and details fields and are returned newest first. Event code and status are stable; title may be localized. Accepts the HioBuy shipment ID or external_shipment_id; numeric-only path values use shipment_id and prefixed/non-numeric values use external_shipment_id. Replaces retired POST …/shipments/logistics/trace. Not domestic procurement trace and not package warehouse timeline.","tags":["Fulfillment"],"parameters":[{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string"},"description":"HioBuy shipment ID or external_shipment_id supplied at create time. Numeric-only values are resolved as HioBuy internal IDs; any value containing a non-digit is resolved as external_shipment_id. Prefix developer identifiers (for example, shp_MY-ORDER-001)."},{"name":"language","in":"query","required":false,"schema":{"type":"string","default":"en"},"description":"Display language for localized labels (default en)"}],"responses":{"200":{"description":"Shipment tracking (detail-aligned subset)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"required":["status","timeline"],"properties":{"status":{"$ref":"#/components/schemas/ShipmentStatus"},"interception":{"$ref":"#/components/schemas/ShipmentInterception"},"timeline":{"type":"array","description":"Newest-first shipment events. Every event uses a stable non-null code and a timezone-aware occurred_at value.","items":{"$ref":"#/components/schemas/ShipmentTimelineEvent"}}}}}}}}}},"/v1/fulfillment/tracking":{"get":{"summary":"Track a shipment by serial number","description":"Looks up international carrier scan events using a logistics number (logistics_sn), warehouse order number (order_sn), or developer-supplied external shipment number (client_order_sn). timeline events contain required code, status, title, occurred_at, and details fields and are returned newest first. Event code and status are stable; title may be localized. The sn value is forwarded unchanged and the warehouse determines its type. Requires the tracking:read scope.","tags":["Fulfillment"],"parameters":[{"name":"sn","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Logistics number, warehouse order number, or developer-supplied external shipment number."},{"name":"language","in":"query","required":false,"schema":{"type":"string","default":"en"},"description":"Display language for localized labels (default en)"}],"responses":{"200":{"description":"Shipment tracking (detail-aligned subset)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"required":["status","timeline"],"properties":{"status":{"$ref":"#/components/schemas/ShipmentStatus"},"interception":{"$ref":"#/components/schemas/ShipmentInterception"},"timeline":{"type":"array","description":"Newest-first shipment events. Every event uses a stable non-null code and a timezone-aware occurred_at value.","items":{"$ref":"#/components/schemas/ShipmentTimelineEvent"}}}}}}}}}},"/v1/fulfillment/shipments/item-attributes":{"get":{"summary":"List shipment item attributes","tags":["Fulfillment"],"parameters":[{"name":"language","in":"query","required":false,"schema":{"type":"string","default":"en"},"description":"Display language for localized labels (default en)"},{"name":"destination_country_code","in":"query","schema":{"type":"string"}},{"name":"shipping_channel_code","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Attribute catalog"}}}},"/v1/fulfillment/shipments/services":{"post":{"summary":"List shipment value-added services catalog","tags":["Fulfillment"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Services with prices (fen)"}}}},"/v1/fulfillment/inbounds/create":{"post":{"summary":"Create inbound notice (pre-advise package)","description":"Returns package_id (pkg_*). Same ID is used for package list/detail; there is no separate inbound_id.","tags":["Fulfillment"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Recommended for safe retries. Reusing a key with the same request replays the original result; reusing it with a different request returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tracking_number":{"type":"string"},"package_count":{"type":"integer"},"total_value":{"type":"number"},"currency":{"type":"string"},"items":{"type":"array","items":{"type":"object"}},"external_order_id":{"type":"string"},"language":{"type":"string","default":"en"}},"required":["tracking_number","items"]}}}},"responses":{"201":{"description":"package_id + PENDING status"},"409":{"description":"Duplicate tracking/external order, idempotency conflict, or another request with the same key is in progress. details may include existing_resource, idempotency_key, or retry_after_ms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/fulfillment/inbounds/{package_id}":{"delete":{"summary":"Cancel inbound notice","description":"Accepts the HioBuy package ID or a developer-provided external identifier supported by the warehouse. The path value is forwarded as packageNum.","tags":["Fulfillment"],"parameters":[{"name":"package_id","in":"path","required":true,"schema":{"type":"string"},"description":"HioBuy package ID or a developer-provided external package/order identifier supported by the warehouse. Numeric-only values are reserved for HioBuy internal IDs; prefix developer identifiers (for example, pkg_MY-ORDER-001) to avoid ambiguity."}],"responses":{"200":{"description":"Cancelled"}}}},"/v1/fulfillment/packages":{"get":{"summary":"List warehouse packages","tags":["Fulfillment"],"parameters":[{"name":"status","in":"query","schema":{"type":"string"},"description":"Comma-separated or repeated Package Status CODEs"},{"name":"tracking_number","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"page_size","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Lightweight package list"}}}},"/v1/fulfillment/packages/{package_id}":{"get":{"summary":"Package detail","tags":["Fulfillment"],"parameters":[{"name":"package_id","in":"path","required":true,"schema":{"type":"string"},"description":"HioBuy package ID or a developer-provided external package/order identifier supported by the warehouse. Numeric-only values are reserved for HioBuy internal IDs; prefix developer identifiers (for example, pkg_MY-ORDER-001) to avoid ambiguity."}],"responses":{"200":{"description":"Full package detail"}}}},"/v1/fulfillment/packages/{package_id}/tracking":{"get":{"summary":"HioBuy fulfillment package timeline","description":"Inbound → warehouse → consolidate → ship milestones. Not international last-mile detail.","tags":["Fulfillment"],"parameters":[{"name":"package_id","in":"path","required":true,"schema":{"type":"string"},"description":"HioBuy package ID or a developer-provided external package/order identifier supported by the warehouse. Numeric-only values are reserved for HioBuy internal IDs; prefix developer identifiers (for example, pkg_MY-ORDER-001) to avoid ambiguity."}],"responses":{"200":{"description":"Timeline events with stable event.code"}}}},"/v1/fulfillment/unclaimed-packages":{"get":{"summary":"List unclaimed packages","description":"Tracking numbers are masked.","tags":["Fulfillment"],"parameters":[{"name":"carrier","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"page_size","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Unclaimed list (ucp_*)"}}}},"/v1/fulfillment/unclaimed-packages/claim":{"post":{"summary":"Claim an unclaimed package","description":"Exact full domestic tracking match → creates a normal package. No unclaimed_id in the path.","tags":["Fulfillment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tracking_number":{"type":"string"}},"required":["tracking_number"]}}}},"responses":{"200":{"description":"Claimed package"}}}},"/v1/fulfillment/returns":{"get":{"summary":"List return-to-seller requests","tags":["Fulfillment"],"parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"package_id","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"page_size","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Return list"}}},"post":{"summary":"Create return-to-seller request","tags":["Fulfillment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"package_id":{"type":"string"},"reason":{"type":"string"},"items":{"type":"array","items":{"type":"object"}},"seller_return":{"type":"object"},"remark":{"type":"string"}},"required":["package_id","reason","items","seller_return"]}}}},"responses":{"201":{"description":"Return PENDING with server-calculated fee"}}}},"/v1/fulfillment/returns/{return_id}":{"get":{"summary":"Return request detail","tags":["Fulfillment"],"parameters":[{"name":"return_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Return detail"}}}},"/v1/fulfillment/returns/{return_id}/confirm":{"post":{"summary":"Confirm return fee and authorize processing","tags":["Fulfillment"],"parameters":[{"name":"return_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fee_amount":{"type":"number"},"currency":{"type":"string","default":"CNY"}},"required":["fee_amount"]}}}},"responses":{"200":{"description":"Confirmed (idempotent)"}}}},"/v1/fulfillment/returns/{return_id}/cancel":{"post":{"summary":"Cancel pending return request","tags":["Fulfillment"],"parameters":[{"name":"return_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled / voided"}}}},"/v1/fulfillment/locations":{"get":{"summary":"List fulfillment warehouse locations","tags":["Fulfillment"],"parameters":[{"name":"destination_country","in":"query","schema":{"type":"string"},"description":"ISO 3166-1 alpha-2, e.g. KR"},{"name":"receiving_status","in":"query","schema":{"type":"string","enum":["OPEN","PAUSED","CLOSED"]}},{"name":"status","in":"query","schema":{"type":"string","enum":["ACTIVE","INACTIVE"]}}],"responses":{"200":{"description":"Location list","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","name","country","province","city","district","address"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"country":{"type":"string"},"province":{"type":"string"},"city":{"type":"string"},"district":{"type":"string","description":"District or county containing the warehouse location"},"address":{"type":"object","required":["recipient","phone","postal_code","address_line"],"properties":{"recipient":{"type":"string"},"phone":{"type":"string"},"postal_code":{"type":"string"},"address_line":{"type":"string"}}},"supported_destinations":{"type":"array","items":{"type":"string"}},"supported_services":{"type":"array","items":{"type":"string"}},"recommended":{"type":"boolean"},"status":{"type":"string","enum":["ACTIVE","INACTIVE"]},"receiving_status":{"type":"string","enum":["OPEN","PAUSED","CLOSED"]},"business_hours":{"type":"object"},"notice":{"type":"string","nullable":true},"updated_at":{"type":"string","format":"date-time"}}}},"request_id":{"type":"string"}}}}}}}}},"/v1/fulfillment/value-added-services":{"get":{"summary":"List warehouse value-added services catalog","tags":["Fulfillment"],"parameters":[{"name":"language","in":"query","required":false,"schema":{"type":"string","default":"en"},"description":"Display language for localized labels (default en)"},{"name":"stage","in":"query","schema":{"type":"string","enum":["INBOUND","OUTBOUND"]}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["ACTIVE","INACTIVE"]}}],"responses":{"200":{"description":"VAS catalog"}}}},"/v1/fulfillment/service-requests":{"get":{"summary":"List value-added service requests","tags":["Fulfillment"],"parameters":[{"name":"resource_type","in":"query","schema":{"type":"string","enum":["PACKAGE","SHIPMENT"]}},{"name":"resource_id","in":"query","schema":{"type":"string"}},{"name":"service_code","in":"query","schema":{"type":"string"}},{"name":"stage","in":"query","schema":{"type":"string","enum":["INBOUND","OUTBOUND"]}},{"name":"status","in":"query","description":"Multi-value: comma-separated or repeated status= (PENDING, AWAITING_CONFIRMATION, PROCESSING, COMPLETED, FAILED, CANCELLED)","schema":{"type":"string"}},{"name":"created_from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"created_to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"page_size","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Service request list"}}},"post":{"summary":"Create value-added service request(s)","tags":["Fulfillment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"package_id":{"type":"string"},"services":{"type":"array","items":{"type":"object"}}},"required":["package_id","services"]}}}},"responses":{"201":{"description":"Service request created"}}}},"/v1/fulfillment/service-requests/{request_id}":{"get":{"summary":"Service request detail","tags":["Fulfillment"],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Service request detail"}}}},"/v1/fulfillment/service-requests/{request_id}/confirm":{"post":{"summary":"Confirm service request fee","tags":["Fulfillment"],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fee_amount":{"type":"number"},"currency":{"type":"string","default":"CNY"}}}}}},"responses":{"200":{"description":"Confirmed"}}}},"/v1/support/tickets":{"get":{"summary":"List support tickets","tags":["Support"],"parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"page_size","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Ticket list"}}},"post":{"summary":"Create support ticket","tags":["Support"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"priority":{"type":"string"},"related_resource":{"type":"object"}},"required":["category","subject","body"]}}}},"responses":{"201":{"description":"Ticket created (tkt_*)"}}}},"/v1/support/tickets/{ticket_id}":{"get":{"summary":"Support ticket detail","tags":["Support"],"parameters":[{"name":"ticket_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ticket with messages"}}}},"/v1/support/tickets/{ticket_id}/messages":{"post":{"summary":"Reply to support ticket","tags":["Support"],"parameters":[{"name":"ticket_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string"}},"required":["body"]}}}},"responses":{"201":{"description":"Message appended"}}}},"/v1/ai/workspaces/upsert":{"post":{"tags":["Commerce AI"],"summary":"Create or update an AI workspace (Invite Only)","description":"Creates the tenant credit workspace. This public route never grants credits.","parameters":[{"name":"X-Shop-Domain","in":"header","required":true,"schema":{"type":"string"},"description":"Stable tenant/store identifier, for example store.example.com."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shop":{"type":"string"},"currency":{"type":"string","example":"USD"},"language":{"type":"string","example":"en"}}}}}},"responses":{"200":{"description":"AI workspace"},"400":{"description":"Invalid AI request"},"401":{"description":"Invalid API key"},"402":{"description":"Insufficient AI credits"},"403":{"description":"AI feature is not enabled for this application"},"500":{"description":"AI provider or processing failure"}}}},"/v1/ai/credits":{"get":{"tags":["AI Credits"],"summary":"Get AI credit balance","parameters":[{"name":"X-Shop-Domain","in":"header","required":true,"schema":{"type":"string"},"description":"Stable tenant/store identifier, for example store.example.com."}],"responses":{"200":{"description":"Current workspace balance"},"400":{"description":"Invalid AI request"},"401":{"description":"Invalid API key"},"402":{"description":"Insufficient AI credits"},"403":{"description":"AI feature is not enabled for this application"},"500":{"description":"AI provider or processing failure"}}}},"/v1/ai/credits/pricing":{"get":{"tags":["AI Credits"],"summary":"List effective AI feature prices","description":"Returns application-specific prices. Do not hard-code the documentation price table.","responses":{"200":{"description":"Effective AI credit pricing rules"},"400":{"description":"Invalid AI request"},"401":{"description":"Invalid API key"},"402":{"description":"Insufficient AI credits"},"403":{"description":"AI feature is not enabled for this application"},"500":{"description":"AI provider or processing failure"}}}},"/v1/ai/credits/estimate":{"post":{"tags":["AI Credits"],"summary":"Estimate credits before an AI operation","parameters":[{"name":"X-Shop-Domain","in":"header","required":true,"schema":{"type":"string"},"description":"Stable tenant/store identifier, for example store.example.com."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["feature"],"properties":{"feature":{"type":"string","enum":["text.translate","product.localize","pricing.suggest","image.analyze","image.remove_chinese_text","image.replace_chinese_text","image.background","image.enhance","image.lifestyle"]},"count":{"type":"integer","minimum":1,"default":1}}}}}},"responses":{"200":{"description":"Affordability and required credits"},"400":{"description":"Invalid AI request"},"401":{"description":"Invalid API key"},"402":{"description":"Insufficient AI credits"},"403":{"description":"AI feature is not enabled for this application"},"500":{"description":"AI provider or processing failure"}}}},"/v1/ai/credits/transactions":{"get":{"tags":["AI Credits"],"summary":"List AI credit ledger entries","parameters":[{"name":"X-Shop-Domain","in":"header","required":true,"schema":{"type":"string"},"description":"Stable tenant/store identifier, for example store.example.com."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"before","in":"query","schema":{"type":"string"},"description":"pagination.next_cursor"}],"responses":{"200":{"description":"Credit transactions and pagination"},"400":{"description":"Invalid AI request"},"401":{"description":"Invalid API key"},"402":{"description":"Insufficient AI credits"},"403":{"description":"AI feature is not enabled for this application"},"500":{"description":"AI provider or processing failure"}}}},"/v1/ai/text/translate":{"post":{"tags":["Commerce AI"],"summary":"Translate ecommerce titles, descriptions, chat, and SKU values","description":"Faithful batch translation. Billing units round up per 1,000 source characters. Use e-commerce-title for titles and short SKU option values.","parameters":[{"name":"X-Shop-Domain","in":"header","required":true,"schema":{"type":"string"},"description":"Stable tenant/store identifier, for example store.example.com."},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Recommended for billable operations and required for safe retries."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["texts","target_language"],"properties":{"texts":{"type":"array","minItems":1,"items":{"type":"string"}},"source_language":{"type":"string","default":"auto"},"target_language":{"type":"string","example":"en"},"format_type":{"type":"string","enum":["text","html"],"default":"text"},"scene":{"type":"string","enum":["e-commerce-title","e-commerce-description","e-commerce-chat","e-commerce-cpv"],"default":"e-commerce-title"}}},"example":{"texts":["夏季纯棉短袖T恤","白色","加大码"],"source_language":"zh","target_language":"en","scene":"e-commerce-title"}}}},"responses":{"200":{"description":"Translations, character usage, and remaining credits"},"400":{"description":"Invalid AI request"},"401":{"description":"Invalid API key"},"402":{"description":"Insufficient AI credits"},"403":{"description":"AI feature is not enabled for this application"},"500":{"description":"AI provider or processing failure"}}}},"/v1/ai/product/localize":{"post":{"tags":["Commerce AI"],"summary":"Localize a complete product listing","description":"Generates localized merchandising copy. Production apps should prefer the asynchronous jobs route.","parameters":[{"name":"X-Shop-Domain","in":"header","required":true,"schema":{"type":"string"},"description":"Stable tenant/store identifier, for example store.example.com."},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Recommended for billable operations and required for safe retries."}],"responses":{"200":{"description":"Localized product fields"},"400":{"description":"Invalid AI request"},"401":{"description":"Invalid API key"},"402":{"description":"Insufficient AI credits"},"403":{"description":"AI feature is not enabled for this application"},"500":{"description":"AI provider or processing failure"}}}},"/v1/ai/product/localize/jobs":{"post":{"tags":["Commerce AI"],"summary":"Create an asynchronous product localization job","parameters":[{"name":"X-Shop-Domain","in":"header","required":true,"schema":{"type":"string"},"description":"Stable tenant/store identifier, for example store.example.com."},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Recommended for billable operations and required for safe retries."}],"responses":{"200":{"description":"Existing idempotent job"},"202":{"description":"Job queued"},"400":{"description":"Invalid AI request"},"401":{"description":"Invalid API key"},"402":{"description":"Insufficient AI credits"},"403":{"description":"AI feature is not enabled for this application"},"500":{"description":"AI provider or processing failure"}}}},"/v1/ai/pricing/suggest":{"post":{"tags":["Commerce AI"],"summary":"Suggest a selling price","parameters":[{"name":"X-Shop-Domain","in":"header","required":true,"schema":{"type":"string"},"description":"Stable tenant/store identifier, for example store.example.com."},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Recommended for billable operations and required for safe retries."}],"responses":{"200":{"description":"Price suggestion"},"400":{"description":"Invalid AI request"},"401":{"description":"Invalid API key"},"402":{"description":"Insufficient AI credits"},"403":{"description":"AI feature is not enabled for this application"},"500":{"description":"AI provider or processing failure"}}}},"/v1/ai/image/analyze":{"post":{"tags":["Commerce AI"],"summary":"Analyze ecommerce image readiness","parameters":[{"name":"X-Shop-Domain","in":"header","required":true,"schema":{"type":"string"},"description":"Stable tenant/store identifier, for example store.example.com."},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Recommended for billable operations and required for safe retries."}],"responses":{"200":{"description":"Image quality and recommended actions"},"400":{"description":"Invalid AI request"},"401":{"description":"Invalid API key"},"402":{"description":"Insufficient AI credits"},"403":{"description":"AI feature is not enabled for this application"},"500":{"description":"AI provider or processing failure"}}}},"/v1/ai/image/jobs":{"post":{"tags":["Commerce AI"],"summary":"Create an asynchronous ecommerce image job","description":"The source must be a publicly reachable HTTPS image. Credits are reserved when queued and refunded if processing fails.","parameters":[{"name":"X-Shop-Domain","in":"header","required":true,"schema":{"type":"string"},"description":"Stable tenant/store identifier, for example store.example.com."},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Recommended for billable operations and required for safe retries."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","image_url"],"properties":{"type":{"type":"string","enum":["remove_chinese_text","replace_chinese_text","white_background","replace_background","enhance","upscale","lifestyle_generation"]},"image_url":{"type":"string","format":"uri"},"target_language":{"type":"string","description":"Required by replace_chinese_text"},"prompt":{"type":"string","description":"Optional instruction for generative job types"}}},"examples":{"translateImage":{"summary":"Translate text inside an image","value":{"type":"replace_chinese_text","image_url":"https://cdn.example.com/product.jpg","target_language":"en"}},"removeAds":{"summary":"Remove text, labels, and promotional badges","value":{"type":"remove_chinese_text","image_url":"https://cdn.example.com/product.jpg"}},"whiteBackground":{"value":{"type":"white_background","image_url":"https://cdn.example.com/product.jpg"}},"enhance":{"value":{"type":"enhance","image_url":"https://cdn.example.com/product.jpg"}}}}}},"responses":{"200":{"description":"Existing idempotent job"},"202":{"description":"Job queued"},"400":{"description":"Invalid AI request"},"401":{"description":"Invalid API key"},"402":{"description":"Insufficient AI credits"},"403":{"description":"AI feature is not enabled for this application"},"500":{"description":"AI provider or processing failure"}}}},"/v1/ai/jobs/{job_id}":{"get":{"tags":["Commerce AI"],"summary":"Get AI job status and output","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"queued, running, completed, failed, or refunded job"},"404":{"description":"Job not found"}}}},"/v1/ai/assets/{job_id}.webp":{"get":{"tags":["Commerce AI"],"summary":"Download a processed image","description":"Temporary integration asset. Re-host it before persisting it in a merchant catalog.","security":[],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Processed WebP image"},"404":{"description":"Asset not found"}}}},"/portal/v1/admin/apps/pending":{"get":{"summary":"List apps pending review","tags":["Admin"],"security":[{"portalToken":[]}],"responses":{"200":{"description":"Pending applications"}}}},"/portal/v1/admin/apps":{"get":{"summary":"Search applications","tags":["Admin"],"security":[{"portalToken":[]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"fulfillment_mode","in":"query","schema":{"type":"string","enum":["self","warehouse"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["created_desc","created_asc"]}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"App list with plan info"}}}},"/portal/v1/admin/hiofulfill/apps":{"get":{"summary":"List applications using HioBuy Fulfillment","tags":["Admin"],"security":[{"portalToken":[]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"subscription_state","in":"query","schema":{"type":"string","enum":["active","expired"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"HioFulfill apps with masked WH-DEV and subscription state"}}}},"/portal/v1/admin/apps/{appId}/review":{"post":{"summary":"Approve or reject an application","tags":["Admin"],"security":[{"portalToken":[]}],"parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["approve","reject"]},"review_note":{"type":"string"}},"required":["action"]}}}},"responses":{"200":{"description":"Review recorded"}}}},"/portal/v1/admin/plans":{"get":{"summary":"List plans with per-channel quotas","tags":["Admin Quota"],"security":[{"portalToken":[]}],"responses":{"200":{"description":"Plans"}}},"post":{"summary":"Create a plan","tags":["Admin Quota"],"security":[{"portalToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"tier":{"type":"integer"}},"required":["code","name"]}}}},"responses":{"201":{"description":"Plan created"}}}},"/portal/v1/admin/plans/{planId}/quotas":{"put":{"summary":"Set plan channel quotas","tags":["Admin Quota"],"security":[{"portalToken":[]}],"parameters":[{"name":"planId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quotas":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string","enum":["1688","taobao","weidian"]},"daily_quota":{"type":"integer"},"monthly_quota":{"type":"integer","nullable":true},"rpm_limit":{"type":"integer","nullable":true}},"required":["channel","daily_quota"]}}},"required":["quotas"]}}}},"responses":{"200":{"description":"Quotas updated"}}}},"/portal/v1/admin/platform-budgets":{"get":{"summary":"Platform monthly fuse status per channel","tags":["Admin Quota"],"security":[{"portalToken":[]}],"responses":{"200":{"description":"Platform budgets with month usage"}}}},"/portal/v1/admin/platform-budgets/{channel}":{"put":{"summary":"Configure platform monthly circuit breaker","tags":["Admin Quota"],"security":[{"portalToken":[]}],"parameters":[{"name":"channel","in":"path","required":true,"schema":{"type":"string","enum":["1688","taobao","weidian"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"monthly_budget":{"type":"integer","nullable":true,"description":"null disables fuse"},"status":{"type":"string","enum":["active","paused"]},"note":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"Budget updated"}}}},"/portal/v1/admin/apps/{appId}/subscription":{"get":{"summary":"Get app plan subscription","tags":["Admin Quota"],"security":[{"portalToken":[]}],"parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Subscription"}}},"put":{"summary":"Assign plan or override quotas","tags":["Admin Quota"],"security":[{"portalToken":[]}],"parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan_id":{"type":"string"},"override_quotas":{"type":"object"},"note":{"type":"string"},"status":{"type":"string"}}}}}},"responses":{"200":{"description":"Subscription updated"}}}},"/portal/v1/admin/apps/{appId}/quota-usage":{"get":{"summary":"Per-channel quota usage and traffic packs","tags":["Admin Quota"],"security":[{"portalToken":[]}],"parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Usage snapshot"}}}},"/portal/v1/admin/traffic-pack-products":{"get":{"summary":"List internal traffic pack products","tags":["Admin Quota"],"security":[{"portalToken":[]}],"responses":{"200":{"description":"Products"}}},"post":{"summary":"Create traffic pack product","tags":["Admin Quota"],"security":[{"portalToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"channel":{"type":"string"},"units":{"type":"integer"},"validity_days":{"type":"integer"}},"required":["code","name","channel","units","validity_days"]}}}},"responses":{"201":{"description":"Product created"}}}},"/portal/v1/admin/apps/{appId}/traffic-packs":{"get":{"summary":"List traffic pack grants for an app","tags":["Admin Quota"],"security":[{"portalToken":[]}],"parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Grants"}}},"post":{"summary":"Grant a traffic pack to an app","tags":["Admin Quota"],"security":[{"portalToken":[]}],"parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product_id":{"type":"string"},"channel":{"type":"string"},"units":{"type":"integer"},"validity_days":{"type":"integer"},"note":{"type":"string"}}}}}},"responses":{"201":{"description":"Grant created"}}}},"/portal/v1/admin/quota-payments":{"get":{"summary":"List internal quota payment orders (reconciliation)","tags":["Admin Payments"],"security":[{"portalToken":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","fulfilled","cancelled"]}},{"name":"app_id","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Payment orders"}}},"post":{"summary":"Create pending payment order (no traffic pack until confirmed)","tags":["Admin Payments"],"security":[{"portalToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"app_id":{"type":"string"},"product_id":{"type":"string"},"channel":{"type":"string","enum":["1688","taobao"]},"units":{"type":"integer"},"validity_days":{"type":"integer"},"amount_cents":{"type":"integer","nullable":true},"currency":{"type":"string","default":"CNY"},"payment_method":{"type":"string","enum":["bank_transfer","alipay","wechat","contract","other"]},"external_reference":{"type":"string"},"note":{"type":"string"}},"required":["app_id","payment_method"]}}}},"responses":{"201":{"description":"Pending order created"}}}},"/portal/v1/admin/quota-payments/{orderId}":{"get":{"summary":"Get payment order detail","tags":["Admin Payments"],"security":[{"portalToken":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order detail"}}}},"/portal/v1/admin/quota-payments/{orderId}/confirm":{"post":{"summary":"Confirm payment received and auto-grant traffic pack","tags":["Admin Payments"],"security":[{"portalToken":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"paid_at":{"type":"string","format":"date-time"},"external_reference":{"type":"string"},"note":{"type":"string"}}}}}},"responses":{"200":{"description":"Order fulfilled with grant"}}}},"/portal/v1/admin/quota-payments/{orderId}/cancel":{"post":{"summary":"Cancel pending payment order","tags":["Admin Payments"],"security":[{"portalToken":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order cancelled"}}}},"/portal/v1/admin/apps/{appId}/traffic-packs/{grantId}/revoke":{"post":{"summary":"Revoke a traffic pack grant","tags":["Admin Quota"],"security":[{"portalToken":[]}],"parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string"}},{"name":"grantId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Grant revoked"}}}}}}