HackMDCross-Border National Site Solution - Full API Documentation
Note:
1. The interfaces linked below will be synchronized directly to the Cross-Border National Site Solution later. The interfaces and input/output parameters will not change. Currently, you only need to review the interface names, input/output parameters in the linked documentation; no need to pay attention to the associated solutions.
2. This document is the full solution documentation for cross-border national site providers to access as needed.
I. Categories
Currently in Chinese, will be converted to multiple languages in the future, expected in October.
1.1 Query Category by Category ID
II. Products
2.1 Multilingual Keyword Query
product.search.keywordQuery
| Input | ||
|---|---|---|
| Field | Type | Description |
| keyword | String | Keyword |
| categoryId | Long | 1688 Category ID |
| beginPage | Integer | Start Page |
| pageSize | Integer | Page Size |
| filter | String | Filter |
| sort | String | Sorting Content K:V structure K:Sorting Field V:Sorting Order (asc-ascending, desc-descending) { "onePPrice": "asc" } |
| outMemberId | String | Downstream Buyer ID |
| priceStart | String | Price Range Start |
| priceEnd | String | Price Range End |
| country | String | Country |
{
"success": true,
"code": "S0000",
"message": "success",
"data" : {
"totalRecords": "Total Records",
"totalPage": "Total Pages",
"pageSize": "Page Size",
"currentPage": "Current Page",
"searchOfferModelList":[
{
"imageUrl": "Main Image of the Product",
"subject": "Title",
"priceInfo": {
"price": "Wholesale Price",
"jxhyPrice": "Selected Supply Price"
},
"offerId": "Product ID",
"isJxhy": "Is Selected Supply"
}
]},
"result": true
}
2.2 Image Upload
product.image.upload
| Input | ||
|---|---|---|
| Field | Type | Description |
| imageBase64 | String | Compressed Image Base64 |
| outMemberId | String | User ID |
{
"success": true,
"code": "S0000",
"message": "success",
"data" : "1490507813791335080", //imageId
"result": true
}
2.3 Multilingual Image Search
product.search.imageQuery
| Input | ||
|---|---|---|
| Field | Type | Description |
| imageId | String | Image ID |
| imageAddress | String | Image Address (Note: Not recommended to use this parameter, frequent timeouts in cross-border scenarios) |
| categoryId | Long | 1688 Category ID |
| beginPage | Integer | Start Page |
| pageSize | Integer | Page Size |
| filter | String | Filter, choiceKey collection, separated by commas |
| sort | String | Sorting Content K:V structure K:Sorting Field V:Sorting Order (asc-ascending, desc-descending) { "onePPrice": "asc" } |
| priceStart | String | Price Range Start |
| priceEnd | String | Price Range End |
| outMemberId | String | Downstream Buyer ID |
| country | String | Country (Reference point nine) |
{
"success": true,
"code": "S0000",
"message": "success",
"data" : {
"totalRecords": "Total Records",
"totalPage": "Total Pages",
"pageSize": "Page Size",
"currentPage": "Current Page",
"searchOfferModelList":[
{
"imageUrl": "Main Image of the Product",
"subject": "Title",
"priceInfo": {
"price": "Wholesale Price",
"jxhyPrice": "Selected Supply Price"
},
"offerId": "Product ID",
"isJxhy": "Is Selected Supply"
}
]
},
"result": true
}
2.4 Multilingual Product Details
product.search.queryProductDetail
| Input | ||
|---|---|---|
| Field | Type | Description |
| offerId | Long | Product ID |
| outMemberId | String | User ID |
| country | String | Country (Reference point nine) |
{
"success": true,
"code": "S0000",
"message": "success",
"data":{
"offerId": "Product ID",
"subject": "Title",
"subjectTrans": "Title - Multilingual",
"description": "Product Description",
"mainVideo": "Main Video",
"detailVideo": "Detail Video",
"productImage":{
"images":[
"Image 1",
"Image 2"
]
},
"productAttribute":[
{ //Product Attribute
"attributeId": 2176,
"attributeName": "Brand",
"value": "Wei Pai"
}
],
"productSkuInfos":[
{
"amountOnSale":"Inventory",
"price":"Wholesale Price",
"jxhyPrice":"Selected Supply Price",
"skuId":"Sku ID",
"specId":"Specification ID",
"skuAttribute":{
"attributeID":"Attribute ID",
"attributeName":"Attribute Name",
"attributeNameTrans":"Attribute Name - Translation",
"value":"Attribute Value",
"valueTrans":"Attribute Value - Translation",
"skuImageUrl":"Attribute Image"
}
}
],
"productSaleInfo":{
"priceRanges":[
{
"startQuantity":"Price Range Minimum Order Quantity",
"price":"Price"
}
],
"amountOnSale":"Product Inventory"
},
"productShippingInfo":{
"sendGoodsAddressText":"Shipping Origin"
},
"categoryId":"Category ID",
"categoryName":"Category Name",
"isJxhy":"Selected Supply Tag",
"sellerOpenId":"Desensitized Seller Unique ID",
"minOrderQuantity":"Minimum Order Quantity"
},
"result":true
}
2.5 Multilingual Filtering Configuration
product.filterData.queryConfig
| Input | ||
|---|---|---|
| Field | Type | Description |
| outMemberId | String | Downstream User ID |
| country | String | Country (Reference point nine) |
[ {
"configList": [{
"choiceKey": "certifiedFactory",
"filterName": "Certified Factory",
"type": "0"
}, {
"filterName": "Comprehensive Experience Score",
"type": "1",
"valueList": [{
"choiceKey": "totalEpScoreLv1",
"choiceName": "5 Stars"
}, {
"choiceKey": "totalEpScoreLv2",
"choiceName": "4.5 Stars-5.0 Stars"
}, {
"choiceKey": "totalEpScoreLv3",
"choiceName": "4 Stars-4.5 Stars"
}, {
"choiceKey": "totalEpScoreLv4",
"choiceName": "Below 4 Stars"
}]
}, {
"filterName": "24-Hour Collection Rate",
"type": "1",
"valueList": [{
"choiceKey": "getRate24HLv3",
"choiceName": ">=99%"
}, {
"choiceKey": "getRate24HLv2",
"choiceName": ">=95%"
}, {
"choiceKey": "getRate24HLv1",
"choiceName": "<95%"
}]
}, {
"filterName": "48-Hour Collection Rate",
"type": "1",
"valueList": [{
"choiceKey": "getRate48HLv3",
"choiceName": ">=99%"
}, {
"choiceKey": "getRate48HLv2",
"choiceName": ">=95%"
}, {
"choiceKey": "getRate48HLv1",
"choiceName": "<95%"
}]
}],
"configName": "Service Quality",
"configType": "filter"
}, {
"configList": [{
"choiceKey": "freeCredit",
"filterName": "Free Credit",
"type": "0"
}, {
"choiceKey": "shipInToday",
"filterName": "Ship Today",
"type": "0"
}, {
"choiceKey": "shipIn24Hours",
"filterName": "Ship in 24 Hours",
"type": "0"
}, {
"choiceKey": "shipIn48Hours",
"filterName": "Ship in 48 Hours",
"type": "0"
}, {
"choiceKey": "noReason7DReturn",
"filterName": "7-Day No Reason Return",
"type": "0"
}, {
"choiceKey": "isOnePsale",
"filterName": "Support One-Piece Delivery",
"type": "0"
}, {
"choiceKey": "isOnePsaleFreePost",
"filterName": "Support Free Shipping",
"type": "0"
}, {
"choiceKey": "dyCiphertext",
"filterName": "Support Douyin Ciphertext Printing",
"type": "0"
}, {
"choiceKey": "ksCiphertext",
"filterName": "Support Kuaishou Ciphertext Printing",
"type": "0"
}],
"configName": "Service Assurance",
"configType": "filter"
}, {
"configList": [{
"choiceKey": "onePPrice",
"filterName": "Price Sorting",
"type": "2"
}, {
"choiceKey": "rePurchaseRate",
"filterName": "30-Day Repurchase Rate",
"type": "2"
}, {
"choiceKey": "monthSoldOut",
"filterName": "30-Day Sales",
"type": "2"
}],
"configName": "Comprehensive Sorting",
"configType": "sort"
}]
III. Orders
3.1 Preview Before Creating an Order
3.2 Create Order
3.3 Order Details
3.4 Order List
3.5 Cancel Unpaid Orders
3.6 Order Logistics Information (Sender and Receiver)
3.7 Order Logistics Tracking Information
3.8 One-Stage Order Flow (Synchronization after Successful Payment of One-Stage Order)
| Input | ||
|---|---|---|
| Field | Type | Description |
| orderParam | Object(OrderParam) | This parameter is the input parameter |
| orderId | Long | Order ID |
| createTime | Date | Creation Time |
| payTime | Date | Payment Time |
| endTime | Date | End Time |
| payStatus | String | Payment Status (payed-paid, success-successful transaction, close-transaction closed) |
| refundStatus | String | Refund Status |
| outUserId | String | Downstream Buyer Account |
| offerId | Long | Product ID |
| skuId | Long | SKU ID |
| buyAmount | Long | Purchase Quantity |
| paidFee | Long | Actual Payment Amount |
| refundFee | Long | Refund Amount |
| contry | String | Country (Reference point nine) |
| Order Type | String | Order Type: 0-Purchase Type, 1-Stock Type |
| subOrderList | List<OrderParam> | Suborder |
{
"success": true,
"code": "S0000",
"message": "success",
"data" : true,
"result": true
}
3.9 Synchronize the Relationship Between One-Stage and Two-Stage Orders (One-Stage Purchase Completed)
| Input | ||
|---|---|---|
| Field | Type | Description |
| nationalOrderRelationParamList | List<NationalOrderRelationParam> | NationalOrderRelationParam, the fields corresponding to this model are as follows |
| nationalSubOrderId | Long | Downstream Buyer Suborder |
| cbuSubOrderId | Long | Purchase Order Suborder |
| nationalOrderId | Long | Downstream Buyer Main Order |
| cbuOrderId | Long | Purchase Order Main Order |
{
"success": true,
"code": "S0000",
"message": "success",
"data" : true,
"result": true
}
3.10 Complete One-Stage Order Status Promotion (Order Completion Promotion after Successful Payment)
| Input | ||
|---|---|---|
| Field | Type | Description |
| orderStatusSyncParam | Object(OrderStatusSyncParam) | This parameter is the input parameter |
| orderId | Long | Order ID |
| payStatus | Date | Order Status (payed-paid, success-successful transaction, close-transaction closed) |
| endTime | Date | End Time |
| refundStatus | Int | Refund Status 0-Not Refunded (Refund Closed, Not Applied) 1-Refund |
| subOrderStatusSyncParamList | List<OrderStatusSyncParam> | Suborder Status |
3.11 Logistics Order Flow (One-Stage Order Shipped)
| Input | ||
|---|---|---|
| Field | Type | Description |
| logisticsOrderParam | Object(LogisticsOrderParam) | This parameter is the input parameter |
| logisticsOrderId | Long | Order ID |
| logisticsId | String | Logistics Order |
| createTime | Date | Creation Time |
| logisticsStatus | String | Logistics Status: send-shipped, sign-received, partSign-partially received, refund-returned |
| endTime | String | End Time |
| attrs | longtext | Tracking Information |
| contry | String | Country (Reference point nine) |
{
"success": true,
"code": "S0000",
"message": "success",
"data" : true,
"result": true
}
3.12 Completion Promotion of Logistics Order Status (Completion Promotion of One-Stage Logistics)
| Input | ||
|---|---|---|
| Field | Type | Description |
| logisticsId | Long | Logistics Order |
| logisticsStatus | String | Logistics Status: send-shipped, sign-received, partSign-partially received, refund-returned |
| modifiedTime | Date | Update Time |
{
"success": true,
"code": "S0000",
"message": "success",
"data" : true,
"result": true
}
IV. Payment
4.1 Batch Retrieval of Order Payment Links
https://open.1688.com/api/apidocdetail.htm?id=com.alibaba.trade:alibaba.alipay.url.get-1
4.2 Retrieving Payment Links Using Cross-Border Bao Payment
https://open.1688.com/api/apidocdetail.htm?id=com.alibaba.trade:alibaba.crossBorderPay.url.get-1
4.3 Retrieving Payment Links Using Cheng E Zhe Payment
https://open.1688.com/api/apidocdetail.htm?id=com.alibaba.trade:alibaba.creditPay.url.get-1
4.4 Buyer Viewing All Account Credit Periods Obtained
4.5 Querying Supported Payment Channels for Orders
https://open.1688.com/api/apidocdetail.htm?id=com.alibaba.trade:alibaba.trade.payWay.query-1
4.6 Querying Whether No-Password Payment is Enabled
4.7 Initiating No-Password Payment
Five, Logistics
5.1 Buyer Retrieves Saved Shipping Address Information List
5.2 Parsing Area Codes Based on Address
5.3 List of Logistics Companies - All Logistics Company Codes
Six, Reverse (Returns and Refunds)
6.1 Query Refund Order Details - Based on Order ID (Buyer's View)
6.2 Refund Order Operation Record List (Buyer's View)
6.3 Query Refund Order Details - Based on Refund Order ID (Buyer's View)
6.4 Query Refund Order List (Buyer's View)
6.5 Querying Order Numbers Corresponding to Claim or Insurance Numbers
6.6 Create Refund and Return Application
https://open.1688.com/api/apidocdetail.htm?id=com.alibaba.trade:alibaba.trade.createRefund-1
6.7 Query Refund and Return Reasons (Used for Creating Refund and Return)
https://open.1688.com/api/apidocdetail.htm?id=com.alibaba.trade:alibaba.trade.getRefundReasonList-1
6.8 Upload Refund and Return Voucher
https://open.1688.com/api/apidocdetail.htm?id=com.alibaba.trade:alibaba.trade.uploadRefundVoucher-1
6.9 Buyer Submits Refund Goods Information
https://open.1688.com/api/apidocdetail.htm?id=com.alibaba.trade:alibaba.trade.refund.returnGoods-1
Seven, Membership
7.1 1688 Member Registration
account.user.register
| Input | ||
|---|---|---|
| Field | Type | Description |
| countryAccount | Object(CountryAccount) | Input object model, specific fields are as follows. |
| country | String | Country name in English. Required. Parameters see [Nine, Enumerated Parameters]. |
| site | String | Country site. Required. Such as sniff. Please contact 1688 for this input before planning. |
| outLoginName | String | Login name of foreign users on the national site. Required. Up to 32 characters. |
| outMemberId | String | Unique user identifier of foreign users on the national site. Required. Up to 64 characters. |
| String | Email. Either mobile phone or email is required. | |
| mobile | String | Mobile phone number. Either mobile phone or email is required. |
| mobileArea | String | Area where the mobile phone number is located. If mobile is provided, this field is required. Such as JP for Japan. |
| ip | String | Caller's IP address. Real user IP. |
| Return value success & result represent successful registration, otherwise registration failed, and the failure reason can be found in the message. | ||
| { "success": true, "code": "S0000", "message": "success", "result": true } |
Eight, Messages
| Transaction | 1688 Order Creation (Buyer's View) / order created (buyer view) | ORDER_BUYER_VIEW_BUYER_MAKE | View Link |
|---|---|---|---|
| 1688 Order Price Modification (Buyer's View) / order price modification (buyer view) | ORDER_BUYER_VIEW_ORDER_PRICE_MODIFY | View Link | |
| 1688 Transaction Payment (Buyer's View) / 1688 transaction payment (buyer view) | ORDER_BUYER_VIEW_ORDER_PAY | View Link | |
| 1688 Order Shipment (Buyer's View) / 1688 order delivery (buyer view) | ORDER_BUYER_VIEW_ANNOUNCE_SENDGOODS | View Link | |
| 1688 Partial Shipment of Order (Buyer's View) / Partial delivery of 1688 order (buyer view) | ORDER_BUYER_VIEW_PART_PART_SENDGOODS | View Link | |
| 1688 Order Receipt Confirmation (Buyer's View) / order receipt confirmation (buyer view) | ORDER_BUYER_VIEW_ORDER_COMFIRM_RECEIVEGOODS | View Link | |
| 1688 Transaction Success (Buyer's View) | ORDER_BUYER_VIEW_ORDER_SUCCESS | View Link | |
| 1688 Buyer Closing Order (Buyer's View) / buyer closing order (buyer view) | ORDER_BUYER_VIEW_ORDER_BUYER_CLOSE | View Link | |
| 1688 Seller Closing Order (Buyer's View) / seller closing order (buyer view) | ORDER_BUYER_VIEW_ORDER_SELLER_CLOSE | View Link | |
| 1688 Operations Backstage Closing Order (Buyer's View) | ORDER_BUYER_VIEW_ORDER_BOPS_CLOSE | View Link | |
| 1688 Order In-Sales Refund (Buyer's View) | ORDER_BUYER_VIEW_ORDER_BUYER_REFUND_IN_SALES | View Link | |
| 1688 Order After-Sales Refund (Buyer's View) | ORDER_BUYER_VIEW_ORDER_REFUND_AFTER_SALES | View Link | |
| 1688 Order Stage Payment (Buyer's View) | ORDER_BUYER_VIEW_ORDER_STEP_PAY | View Link | |
| 1688 Order Batch Payment Status Synchronization Message | ORDER_BATCH_PAY | View Link | |
| Logistics | Logistics Order Status Change (Buyer's View) | LOGISTICS_BUYER_VIEW_TRACE | View Link |
| Logistics Order Number Modification Message | LOGISTICS_MAIL_NO_CHANGE | View Link |
Nine, Enumerated Parameters
9.1 Supported Country Enumerations for 'country'
| Enumeration Value | Description |
|---|---|
| japan | Japan |
| vietnam | Vietnam |
| malaysia | Malaysia |
| … | … |
9.2 Supported Mobile Phone Area Enumerations for 'mobileArea'
| Enumeration Value | Description |
|---|---|
| JP | Japan |
| VN | Vietnam |
| MY | Malaysia |
| … | … |
