淘宝开放平台

请求地址：

环境	HTTP请求地址
正式环境	http://qimen.api.taobao.com/router/qm
测试环境	http://qimen.api.taobao.com/router/qmtest

公共请求参数：

名称	类型	是否必须	描述
method	String	是	API接口名称。
app_key	String	是	TOP分配给应用的AppKey。
session	String	否	用户登录授权成功后，TOP颁发给应用的授权信息，详细介绍请点击这里。当此API的标签上注明：“需要授权”，则此参数必传；“不需要授权”，则此参数不需要传；“可选授权”，则此参数为可选。
timestamp	String	是	时间戳，格式为yyyy-MM-dd HH:mm:ss，时区为GMT+8，例如：2015-01-01 12:00:00。淘宝API服务端允许客户端请求最大时间误差为10分钟。
format	String	否	响应格式。默认为xml格式，可选值：xml，json。
v	String	是	API协议版本，可选值：2.0。
customerId	String	是	WMS颁发给用户的ID
sign_method	String	是	签名的摘要算法，md5。
sign	String	是	API输入参数签名结果，签名算法介绍请点击这里。

名称	类型	是否必须	示例值	更多限制	描述
request	LogisticOrderCreateRequest	必须			请求参数
└ traceId String 必须 53656q47732567324 平台日志id 用于平台排查问题每次请求不同 additionalServices LogisticServiceDTO [] 可选集运专用增值服务集运场景专用 └ serviceCode String 可选 MJ01 增值服务code 双方系统识别增值服务 └ serviceName String 可选拆标签增值服务名称 └ effectScope Number 可选 2 /** * 集运订单维度代表全局维度服务如打木架等增值服务 / ORDER(1), /* * 包裹维度 */ PACKAGE(2); └ chargeType String 可选 volumeWeight 计费要素, 计费要素为当前值则体积的长宽高重量必须回传 volumeWeight("volumeWeight","体积重"), 计费要素为当前值则重量必须回传 weight("weight","体积重"), 计费要素为当前值则包裹数量必回传 packageNum("packageNum","包裹数量"), 计费要素为当前值则商品数量必回传 itemNum("itemNum","商品数量"), └ mailNos String [] 可选物流单号列表, 当effectScope=1 则该字段为空，当effectScope=2 则该字段不为空 └ totalFee String 可选 560 增值服务费用描述 └ totalFeeDesc String 可选 - 增值服务费用 └ subTicketId Number 可选 5353523 增值服务子单号，集运商需存储下来，后续发货回传带给平台 pickUpInfo PickUpInfo 可选废弃揽收信息 addressInfo AddressInfo 可选揽收地址 └ zip String 可选 - 邮编 └ lastName String 可选张姓 └ firstName String 可选张三名/姓名当lastName为空时用firstName即可 └ addressDetail String 可选 - 详细地址 └ phone String 可选 - 固话 └ city String 可选市城市 └ countryCode String 可选 CN 国家code └ district String 可选区区 └ mobileNo String 可选 15068797865 手机号 └ state String 可选省省 certificateInfo CertificateInfo 可选证件信息 └ idType String 可选 id_card 证件类型如 id_card代表身份证 └ idNumber String 可选 - 证件号 └ email String 可选 - 邮箱 └ street String 可选 - 街道 └ expectPickUpEarliestTime String 可选 1642407251524 期望最早揽收时间 └ expectPickUpLatestTime String 可选 1642407251580 期望最晚揽收时间 └ logisticServiceCode String 必须 5400 物流服务(渠道)编码（集运商根据配送方式不同在千牛维护自己的编码） receiverContactInfo ReceiverContactInfo 必须收件人信息 └ zip String 可选 - 邮编 └ lastName String 可选张姓 └ city String 可选 - 市 └ mobileNo String 可选 - 手机 certificateInfo CertificateInfo 可选证件信息 └ idType String 可选 id_card 证件类型如id_card代表身份证 └ idNumber String 可选 52245677445343224667 证件号 └ firstName String 可选张三名/姓名当lastName为空时用firstName即可 └ addressDetail String 必须 - 详细地址 └ phone String 可选 - 固话 └ countryCode String 可选 CA 国家二字编码 └ district String 可选 - 区 └ state String 可选 - 省 └ email String 可选 - 邮箱 └ street String 可选 - 街道 └ country String 可选韩国国家名称 └ remark String 可选备注信息备注限100字符 └ openUserId String 必须 fgafga2423423f 集运专用平台买家id(已加密，不可逆) packageList DeliveryOrderPackageDTO [] 必须包裹列表 └ mailNo String 必须 VL43534253535 在集运场景下：对应预报单的物流单号，使用该字段识别预报单在普通场景下：为物流服务商提前分配的物流号段的物流单号 └ width Number 可选 22 包裹宽 cm └ length Number 可选 43 包裹长 cm └ packageId String 可选 - 包裹id └ weight Number 可选 23 包裹重量 g productList LogisticProductDTO [] 必须商品列表 └ payAmount Number 必须 342 实际支付金额分 └ quantity Number 必须 1 数量 └ skuName String 必须测试商品中文商品名 └ price Number 可选 23 单价分 └ length Number 可选 23 商品长 cm └ width Number 可选 53 商品宽 cm └ weight Number 可选 32 商品重 g └ currency String 必须 RMB 币种如 RMB └ skuCode String 必须 4353425 商品sku 不是淘宝商品id └ height Number 可选 42 商品高 cm └ skuEnName String 可选 t-shirt 英文商品名 └ hsCode String 可选 - hsCode 海关编码 └ categoryId String 可选 3543424 叶子类目id └ categoryName String 可选卫衣叶子类目名称 └ picUrl String 可选 - 商品图片URL └ height Number 可选 12 包裹高 cm senderContactInfo SenderContactInfo 可选废弃发件人信息 └ zip String 可选 50000 邮编 └ lastName String 可选张姓 └ firstName String 可选张三名/姓名当lastName为空时用firstName即可 └ addressDetail String 可选 - 详细地址 └ phone String 可选 3705987 固话 └ city String 可选 - 城市 └ countryCode String 可选 - 国家编码 └ district String 可选 - 区 └ mobileNo String 可选 15124353435 手机 └ state String 可选 - 省 certificateInfo CertificateInfo 可选证件信息 └ idType String 可选 id_card 证件类型 └ idNumber String 可选 522425645546464535 证件号 └ email String 可选 - 邮箱 └ street String 可选 - 街道 └ platformOrderId String 可选 4354326356356 平台物流单id 业务主键，保证幂等 logisticFeeCaculate LogisticFeeCaculateDTO 可选物流运费计费逻辑 └ roundingWeight String 可选 0.1 免尾重量 kg └ terminalDeliveryFee String 可选 12 末端附加费元 └ continueWeightFee String 可选 88 续重费用元 └ continueWeight String 可选 2 续重 kg └ firstWeightFee String 可选 150 首重费用元 └ firstWeight String 可选 10 首重 kg └ weight String 可选 10 计费重量 kg └ caculateType Number 可选 1 计费类型 1 重量计费， 2体积重计费 └ volumeFactor String 可选 6000 体积系数(合单时，会将包裹的体积除以体积重系数得到折算后的重量) └ totalFreight String 可选 250 总运费元 additionalServicesCalcList AdditionalServicesCalcDTO [] 可选增值服务费用列表用例子说明各金额取值，示例订单：物流服务金额100元+增值服务（增值服务A：10元、增值服务B：20元）+ 附加费用金额80元，优惠金额5元。。。下发字段如下： totalFreight(总支付费用)：205。 logisticServiceFee(物流服务费用)： 175。 additionalServicesCalcList(增值费用)： 10+20。 otherFee(附加费用)：80。。。注意点：其中otherFee(附加费用)的80包含在了logisticServiceFee(物流服务费用)的175里了。 └ payFee String 可选 10 增值服务金额元 └ serviceCode String 可选 JH05835 增值服务code 双方系统识别增值服务 └ logisticServiceFee String 可选 175.2 物流服务费用单位:元； logisticServiceFee = 物流渠道费用（如海运特快）+附加费用(other_fee)-优惠(店铺优惠) └ otherFee String 可选 43.5 附加费用单位元 └ providerUserCode String 可选 56sg535623 废弃字段 └ dutyType String 可选 U 税费费用承担方式(可选值：U、P); U：DDU由收件人支付关税; P：DDP 由寄件方支付关税 └ pccCode String 可选 5356353 Personal Customs Code 如韩国税号用于申报 └ passportNo String 可选 354643746 护照号用于申报 └ vatNo String 可选 SDF2324 VAT税号(数字或字母)；欧盟国家(含英国)使用的增值税号； └ iossNo String 可选 - IOSS号码 └ ticketId String 可选 T02454551 ticketId 工单号，针对远洋地区会先下发这个单号，此时不会下发platformOrderId字段，等仓库完成打包称重并完成了增值服务之后。再回传打包状态给平台，之后平台算出运费并通知用户支付运费。支付完成运费好，再下发platformOrderId字段给集运商。 └ packType String 可选 KEEP_INTACT 打包要求类型 ("KEEP_INTACT"，"保留包裹外包装"）,("OUT_PACKING"，"去除包裹外包装"）, ("OUT_ITEM_PACKING","去除商品外包装") └ logisticChargeType String 可选 weight 计费要素, 计费要素为当前值则体积的长宽高重量必须回传volumeWeight("volumeWeight","体积重"), 计费要素为当前值则重量必须回传 weight("weight","重量"), └ orderType String 可选 logisticOrder 物流订单类型枚举ticket(工单)， logisticOrder(物流订单)。。。枚举1 orderType = ticket 针对远洋地区，我们会先下发这个类型的单，让仓库去作业，并且回传给我们相关的计费要素(如增值服务完成情况，物流服务完成情况，体积重量等)，当orderType为该类型，则订单不能直接发货而应该在回传计费要素给平台后挂起。直到用户在手淘支付完运费后，以orderType=logisticOrder再次下发之后，订单才能发货)。。。。。。。。。。。。。。。。。。。。枚举2 orderType = logisticOrder case1 （针对近洋地区如中国台湾，接收到的集运单为已支付过运费的集运单，集运仓正常出库，回传发货信息给平台），，，， case2 作为远洋地区如日韩等，继orderType = ticket回传之后，会再下发该类型的数据，表示支持完了运费，集运商可以继续出库）。。。。。。 └ shippingType String 可选 HOME_DELIVERY 配送方式,HOME_DELIVERY("送货上门"), PICKUP_IN_STORES("自提"); 如果为空，默认为HOME_DELIVERY。 └ selfPickupCode String 可选 7842KD 自提点编码 ---配送方式为自提时使用。该值为集运商在淘宝的自提点管理页维护的值,每个自提点有1个唯一值。 └ selfPickupType String 可选 STORE 自提点类型 STORE("STORE", "自提门店"), CABINET("CABINET", "自提柜"), CAR("CAR", "自提车"), MINIMART("MINIMART", "便利店"), POST_OFFICE("POST_OFFICE", "邮局"), PROPERTY("PROPERTY", "物业"), OTHER("OTHER", "其他")。当配送方式为自提时使用

名称	类型	示例值	描述
success	Boolean	false	接口调用结果 true/false
data	LogisticOrderCreateResponse		返回业务数据
└ mailNo String VL24552265602042 物流单号，非集运场景下创建物流单需同步返回该字段 └ orderId String 63356325622T34 物流商的物流单id
failCode	String	-	错误码
failMessage	String	-	错误信息

{"request":{"traceId":"53656q47732567324","additionalServices":[{"effectScope":2,"subTicketId":5353523,"serviceCode":"MJ01","totalFee":"560","chargeType":"volumeWeight","totalFeeDesc":"-","serviceName":"拆标签","mailNos":[""]}],"passportNo":"354643746","dutyType":"U","pccCode":"5356353","orderType":"logisticOrder","logisticServiceCode":"5400","providerUserCode":"56sg535623","vatNo":"SDF2324","logisticChargeType":"weight","packType":"KEEP_INTACT","shippingType":"HOME_DELIVERY","remark":"备注信息","openUserId":"fgafga2423423f","packageList":[{"mailNo":"VL43534253535","width":22,"length":43,"packageId":"-","weight":23,"productList":[{"quantity":1,"length":23,"weight":32,"categoryName":"卫衣","skuName":"测试商品","picUrl":"-","payAmount":342,"hsCode":"-","price":23,"skuEnName":"t-shirt","width":53,"currency":"RMB","skuCode":"4353425","categoryId":"3543424","height":42}],"height":12}],"pickUpInfo":{"addressInfo":{"zip":"-","lastName":"张","city":"市","mobileNo":"15068797865","certificateInfo":{"idType":"id_card","idNumber":"-"},"firstName":"张三","addressDetail":"-","phone":"-","countryCode":"CN","street":"-","district":"区","state":"省","email":"-"},"expectPickUpEarliestTime":"1642407251524","expectPickUpLatestTime":"1642407251580"},"logisticFeeCaculate":{"firstWeight":"10","logisticServiceFee":"175.2","continueWeightFee":"88","totalFreight":"250","otherFee":"43.5","roundingWeight":"0.1","weight":"10","firstWeightFee":"150","additionalServicesCalcList":[{"payFee":"10","serviceCode":"JH05835"}],"volumeFactor":"6000","continueWeight":"2","terminalDeliveryFee":"12","caculateType":1},"selfPickupType":"STORE","iossNo":"-","receiverContactInfo":{"zip":"-","lastName":"张","country":"韩国","city":"-","mobileNo":"-","certificateInfo":{"idType":"id_card","idNumber":"52245677445343224667"},"firstName":"张三","addressDetail":"-","phone":"-","countryCode":"CA","street":"-","district":"-","state":"-","email":"-"},"platformOrderId":"4354326356356","selfPickupCode":"7842KD","senderContactInfo":{"zip":"50000","lastName":"张","city":"-","mobileNo":"15124353435","certificateInfo":{"idType":"id_card","idNumber":"522425645546464535"},"firstName":"张三","addressDetail":"-","phone":"3705987","countryCode":"-","street":"-","district":"-","state":"-","email":"-"},"ticketId":"T02454551"}}

{
    "success":false,
    "data":{
        "mailNo":"VL24552265602042",
        "orderId":"63356325622T34"
    },
    "failCode":"-",
    "failMessage":"-"
}

{"success":"false","failCode":"sign-check-failure","failMessage":"Illegal request"}

错误码	错误描述	解决方案
response-body-parse-error
isp.http-read-timeout
isp.http-connection-timeout

错误码查询工具 SDK下载

千帆计划

qimen.alibaba.ovs.logistic.order.create (物流单创建)

公共参数

请求参数

响应参数

请求示例

响应示例

验签示例

错误码解释

API工具

FAQ