eBay_ePacket_API_V2_Readme

eBay 国际 e 邮宝 API V2 说明文档 Page 1 of 38 eBay 国际 e 邮宝 API V2 说明文档 eBay CBT 03/02/2011 eBay 国际 e 邮宝 API V2 说明文档 Page 2 of 38 Table of Contents 1 概述................................................................................................................................................. 3 1.1 写作目的 ................................................................................................................................. 3 1.2 本文读者 ................................................................................................................................. 3 1.3 范围 ......................................................................................................................................... 3 2 交互方式......................................................................................................................................... 3 2.1 通信方式 ................................................................................................................................. 3 2.2 错误处理 ................................................................................................................................. 3 2.3 接口数据 ................................................................................................................................. 4 3 接口说明......................................................................................................................................... 5 3.1 Shipping Tool 提供的接口 ...................................................................................................... 5 3.1.1 AddAPACShippingPackage ............................................................................................... 6 3.1.2 GetAPACShippingLabel .................................................................................................. 12 3.1.3 ConfirmAPACShippingPackage ....................................................................................... 14 3.1.4 CancelAPACShippingPackage ......................................................................................... 15 3.1.5 GetAPACShippingPackage .............................................................................................. 16 3.1.6 VerifyAPACShippingUser ................................................................................................ 21 3.1.7 GetAPACShippingPackageStatus .................................................................................... 22 3.1.8 GetAPACShippingRate .................................................................................................... 24 3.1.9 RecreateAPACShippingPackage ..................................................................................... 26 3.1.10 GetAPACShippingTrackCode .......................................................................................... 27 3.1.11 GetAPACShippingLabels ................................................................................................. 28 4 附录............................................................................................................................................... 30 4.1 错误代码 ............................................................................................................................... 30 4.1.1 API Level Errors .............................................................................................................. 30 4.1.2 Request Level Errors ...................................................................................................... 30 4.2 收件人国家代码 ................................................................................................................... 32 4.3 货币符号 ............................................................................................................................... 33 4.4 eBay 站点列表 ...................................................................................................................... 33 4.5 揽收地址代码 ....................................................................................................................... 33 eBay 国际 e 邮宝 API V2 说明文档 Page 3 of 38 1 概述 1.1 写作目的 本文档提供给期望通过 Shipping API 使用国际 e 邮宝的第三方开发商及相关人员进行沟通开发参考。 第三方开发技术人员应该以此文档为基础进行数据交互程序的开发工作。 1.2 本文读者 本文主要读者为第三方开发商的程序设计员、开发员、测试员。 读者应该具有 Web Service 基础知识。 1.3 范围 基于 WebService 的方式，本文档提供第三方平台与 Shipping Tool 进行数据访问的接口说明。请以网 上发布的版本为准。 2 交互方式 2.1 通信方式 Shipping Tool 通过 标准 excel标准偏差excel标准偏差函数exl标准差函数国标检验抽样标准表免费下载红头文件格式标准下载 Web Service SOAP 方式对外提供应用服务。 沙盒测试地址为：http://epacketws.pushauction.net/orderservice.asmx 正式运作地址为：http://shippingapi.ebay.cn/production/v2/orderservice.asmx WSDL 请在测试地址获取。 2.2 错误处理 如在不控错误下，如因网络问题无法成功呼叫，Web Service 将抛出异常，请调用方处理异常，如使 用 Try..Catch。 通过返回的 Ack 值检查 呼叫是否出错。返回的 Message 值是异常消息，其中存在错误明细说明。 eBay 国际 e 邮宝 API V2 说明文档 Page 4 of 38 2.3 接口数据  功能说明：本 WS 实现的主要功能介绍。  调 用：Shipping Tool 调用远程对象名称、实现方法。  传入参数： o 英文名称：Web Service 中的参数名。 o 中文名称：参数的中文解释。 o 类 型：参数数值类型 o 对 照 表：为当前参数值，由 Shipping Tool API 提供标准数据表。 o String 字符串 ( ) 表示数值长度及精度 Integer 整数 Boolean 布尔类型 Double 小数 GUID GUID Optional 可选输入 Required 不允许为空 Always 有返回值 Conditional 根据条件决定是否有返回值 o 返回值：Web Service 返回给调用方的数值。 o 常见错误：Web Service 执行过程中，遇到参数或业务异常，则抛出异常给调用方处理。 eBay 国际 e 邮宝 API V2 说明文档 Page 5 of 38 3 接口说明 3.1 Shipping Tool 提供的接口 接口名称 描述 使用方 AddAPACShippingPackage 用于上传包裹信息到 ShippingTool 第三方开发商 GetAPACShippingLabel 用于打印详情单，包括 A4 标签格式的详情单和 热敏标签格式的详情单 第三方开发商 ConfirmAPACShippingPackage 确认并交运包裹信息 第三方开发商 CancelAPACShippingPackage 取消并删除包裹信息 第三方开发商 GetAPACShippingPackage 获取包裹信息详情 第三方开发商 VerifyAPACShippingUser 验证用户授权是否成功 第三方开发商 GetAPACShippingRate 计算包裹运费 第三方开发商 GetAPACShippingPackageStatus 获取包裹最新状态 第三方开发商 RecreateAPACShippingPackage 重新发货 第三方开发商 GetAPACShippingTrackCode 查询物品的包裹跟踪号 第三方开发商 eBay 国际 e 邮宝 API V2 说明文档 Page 6 of 38 3.1.1 AddAPACShippingPackage Shipping Tool 用户通过调用该方法上传一个需要发货的包裹信息，Shipping Tool 将返回申请到的包裹 追踪号。 每次呼叫只限上传一个包裹，一个包裹可以包含多个物品。 每个物品必须为在 eBay 成交的物品。 3.1.1.1 Request Element Type Required / Cardinality 说明 APIDevUserID String Required 开发商用户名 APIPassword String Required 开发商签名 APISellerUserID String Required 卖家 eBay 账户 MessageID String(36) Optional 调用方为每次调用提供的唯一标 识。 Version String Required Shipping Tool API 版本，可用值： 2.0.0 OrderDetail Cardinality - One OrderDetail / EMSPickUpType Integer Required 揽收方式，可用值： 0 - 上门揽收 1 - 卖家自送 OrderDetail/ PickUpAddress Cardinality - Zero to One 揽收地址信息，如此包裹需要 EMS 上门揽收，该地址信息必须填写完 整。 揽收地址现阶段只支持部分城市， province/city/district 值请参考附表 4.5。 如为卖家自送，则可不添加此栏。 （上门揽收时为必须，OrderDetail /EMSPickUpType = 0） ../PickUpAddres/ Contact String(64) Required 联系人 ../PickUpAddres/ Company String(128) Optional 公司 ../PickUpAddres/ Street String(200) Required 街道 eBay 国际 e 邮宝 API V2 说明文档 Page 7 of 38 ../PickUpAddres/ District String(64) Required 区，输入相应区的代码，请参考揽 收地址代码表 ../PickUpAddres/ City String(64) Required 城市，输入相应城市的代码，请参 考揽收地址代码表 ../PickUpAddres/ Province String(64) Required 省，输入相应省份的代码，请参考 揽收地址代码表 ../PickUpAddres/ Postcode String(6) Required 邮编 ../PickUpAddres/ Country String(64) Required 国家 ../PickUpAddres/ Email String(128) Required 电邮 ../PickUpAddres/ Mobile String(32) Required 手机；方便揽收人员上门揽收前联 系，必须填写。 ../PickUpAddres/ Phone String(32) Required 固话 OrderDetail/ ShipFromAddress Cardinality - One 寄件人地址信息，必须以英文填写。 此地址将被打印在标签的寄件人地 址一栏中。 ../ShipFromAddress/ Contact String(64) Required 联系人 ../ShipFromAddress/ Company String(128) Optional 公司 ../ShipFromAddress/ Street String(200) Required 街道 ../ShipFromAddress/ District String(64) Required 区 ../ShipFromAddress/ City String(64) Required 城市 ../ShipFromAddress/ Province String(64) Required 省 ../ShipFromAddress/ Postcode String(6) Required 邮编 ../ShipFromAddress/ Country String(64) Required 国家 eBay 国际 e 邮宝 API V2 说明文档 Page 8 of 38 ../ShipFromAddress/ Email String(128) Required 电邮 ../ShipFromAddress/ Mobile String(32) Required 手机号 OrderDetail/ ShipToAddress Cardinality - One 收件人地址信息。此地址将被打印 在标签的收件人地址一栏中。 ../ShipToAddress/ Contact String(64) Required 联系人 ../ShipToAddress/ Company String(128) Optional 公司 ../ShipToAddress/ Street String(200) Required 街道 ../ShipToAddress/ City String(64) Required 城市 ../ShipToAddress/ Province String(64) Required 省 ../ShipToAddress/ Country String(64) Required 国家 ../ShipToAddress/ CountryCode String(2) Required 国家代码，与 eBay API 里的标准国 家代码一致。 可用值： US,AA,GU,PR,AS,FM,MH,MP,PW,PR, VI ../ShipToAddress/ Postcode String(32) Required 邮编 ../ShipToAddress/ Phone String(32) Optional 固话 ../ShipToAddress/ Email String(128) Required 电邮 OrderDetail/ ItemList Cardinality - One OrderDetail/ ItemList / Item Cardinality - One to Many 货品信息 ../Item/ String(32) Required eBay 物品号 eBay 国际 e 邮宝 API V2 说明文档 Page 9 of 38 eBayItemID ../Item/ eBayTransactionID String(20) Required eBay 交易号，拍卖的物品请输入 0 ../Item/ eBayBuyerID String(64) Required eBay 买家 ID ../Item/ eBayItemTitle String(55) Optional eBay 商品标题 ../Item/ eBayEmail String(128) Optional 买家 eBay 电邮 ../Item/ SoldQTY Integer Optional 卖出数量 ../Item/ PostedQTY Integer Optional 寄货数量 ../Item/ SalesRecordNumber Int Optional 用户从 eBay 上下载的时 eBay 销售 编号 ../Item/ OrderSalesRecordNumber int Optional 订单销售编号，如果在 eBay 上合并 订单，会产生一个新的 SalesRecordNumber ../Item/ OrderID String(16) Optional eBay 合并订单时生成的一个新的 Order ID ../Item/ eBaySiteID Integer Optional 站点 ID ../Item/ ReceivedAmount Double Optional 实际收到金额 ../Item/ PaymentDate Datetime Optional 买家付款日期 ../Item/ SoldPrice Double Optional 卖出价格 ../Item/ SoldDate Datetime Optional 卖出日期 ../Item/ CurrencyCode String(3) Optional 货币符号，可用值： USD ../Item/ EBayMessage String(256) Optional 买家 eBay 留言 ../Item/ String(128) Optional 买家 PayPal 电邮地址 eBay 国际 e 邮宝 API V2 说明文档 Page 10 of 38 PayPalEmail ../Item/ PayPalMessage String(256) Optional 买家 PayPal 留言 ../Item/ Note String(256) Optional 附注 OrderDetail/ ItemList/ Item/ SKU Cardinality - One 产品报关信息。此信息将被打印在 标签内件信息一栏中。 ../SKU/ SKUID String(50) Optional SKU ID ../SKU/ DeclaredValue Double Required 物品申报价值 ../SKU/ Weight Double Required 物品重量 ../SKU/ CustomsTitleCN String(55) Required 中文报关名称 ../SKU/ CustomsTitleEN String(55) Required 英文报关名称 ../SKU/ OriginCountryCode String(64) Required 原产地 3.1.1.2 Response Element Type Available / Cardinality 说明 Ack Enum Always API 呼叫返回状态，可用值：  Failure  Success  Partial Failure  Warning 错误信息可参考 Message 栏 Message String Always 信息，一般为错误信息 Timestamp String Always 相应返回时间，格式为： yyyy-mm-dd hh:mm:ss:SSS InvocationID String(36) Conditional 与调用者提供的 MessageID 相同 eBay 国际 e 邮宝 API V2 说明文档 Page 11 of 38 Version String Always API 版本，返回值： 2.0.0 OrderResponse Cardinality - One OrderResponse/ TrackCode String(16) Conditionally 从 EMS 获取的包裹跟踪号，仅当 Ack 为 Success 时返回。 eBay 国际 e 邮宝 API V2 说明文档 Page 12 of 38 3.1.2 GetAPACShippingLabel 用于打印详情单，呼叫成功后会返回标签流。 3.1.2.1 Request Element Type Required / Cardinality 说明 APIDevUserID String Required 开发商用户名 APIPassword String Required 开发商签名 APISellerUserID String Required 卖家 eBay 账户 MessageID String(36) Optional 调用方为每次调用提供的唯一标识。 Version String Required Shipping Tool API 版本，可用值： 2.0.0 TrackDetail Cardinality - One TrackDetail/ PageType Integer Required 标签格式，可用值： 0 - 适用于打印 A4 格式标签 1 – 适用于打印 4寸 的热敏标签纸格式 标签 TrackDetail/ TrackCode String (30) Required 包裹跟踪号 3.1.2.2 Response Element Type Available / Cardinality 说明 Ack Enum Always API 呼叫返回状态，可用值：  Failure  Success  Partial Failure  Warning 错误信息可参考 Message 栏 Message String Always 信息，一般为错误信息 Timestamp String Always 相应返回时间，格式为： yyyy-mm-dd hh:mm:ss:SSS InvocationID String(36) Conditional 与调用者提供的 MessageID 相同 Version String Always API 版本，返回值： eBay 国际 e 邮宝 API V2 说明文档 Page 13 of 38 2.0.0 LabelResponse Cardinality - One LabelResponse/ Label Byte Array Conditional 标签流，仅当 Ack 为 Success 时返回 eBay 国际 e 邮宝 API V2 说明文档 Page 14 of 38 3.1.3 ConfirmAPACShippingPackage 用于确认订单，确认订单成功之后，订单会上传到 EMS 的系统当中。 3.1.3.1 Request Element Type Required / Cardinality 说明 APIDevUserID String Required 开发商用户名 APIPassword String Required 开发商签名 APISellerUserID String Required 卖家 eBay 账户 MessageID String(36) Optional 调用方为每次调用提供的唯一标识。 Version String Required Shipping Tool API 版本，可用值： 2.0.0 Order Cardinality - One Order / TrackCode String (30) Required 包裹跟踪号 3.1.3.2 Response Element Type Available / Cardinality 说明 Ack Enum Always API 呼叫返回状态，可用值：  Failure  Success  Partial Failure  Warning 错误信息可参考 Message 栏 Message String Always 信息，一般为错误信息 Timestamp String Always 相应返回时间，格式为： yyyy-mm-dd hh:mm:ss:SSS InvocationID String(36) Conditional 与调用者提供的 MessageID 相同 Version String Always API 版本，返回值： 2.0.0 eBay 国际 e 邮宝 API V2 说明文档 Page 15 of 38 3.1.4 CancelAPACShippingPackage 用于取消并删除在交运前的订单 3.1.4.1 Request Element Type Required / Cardinality 说明 APIDevUserID String Required 开发商用户名 APIPassword String Required 开发商签名 APISellerUserID String Required 卖家 eBay 账户 MessageID String(36) Optional 调用方为每次调用提供的唯一标识。 Version String Required Shipping Tool API 版本，可用值： 2.0.0 Order Cardinality - One Order / TrackCode String (30) Required 包裹跟踪号 3.1.4.2 Response Element Type Available / Cardinality 说明 Ack Enum Always API 呼叫返回状态，可用值：  Failure  Success  Partial Failure  Warning 错误信息可参考 Message 栏 Message String Always 信息，一般为错误信息 Timestamp String Always 相应返回时间，格式为： yyyy-mm-dd hh:mm:ss:SSS InvocationID String(36) Conditional 与调用者提供的 MessageID 相同 Version String Always API 版本，返回值： 2.0.0 eBay 国际 e 邮宝 API V2 说明文档 Page 16 of 38 3.1.5 GetAPACShippingPackage 用于获取包裹的详细信息 3.1.5.1 Request Element Type Required / Cardinality 说明 APIDevUserID String Required 开发商用户名 APIPassword String Required 开发商签名 APISellerUserID String Required 卖家 eBay 账户 MessageID String(36) Optional 调用方为每次调用提供的唯一标识。 Version String Required Shipping Tool API 版本，可用值： 2.0.0 Order Cardinality - One Order / TrackCode String (30) Required 包裹跟踪号 3.1.5.2 Response Element Type Available / Cardinality 说明 Ack Enum Always API 呼叫返回状态，可用值：  Failure  Success  Partial Failure  Warning 错误信息可参考 Message 栏 Message String Always 信息，一般为错误信息 Timestamp String Always 相应返回时间，格式为： yyyy-mm-dd hh:mm:ss:SSS InvocationID String(36) Conditional 与调用者提供的 MessageID 相同 Version String Always API 版本，返回值： 2.0.0 OrderDetail Cardinality - One OrderDetail / EMSPickUpType Integer Always 揽收方式，可用值： 0 - 上门揽收 1 - 卖家自送 eBay 国际 e 邮宝 API V2 说明文档 Page 17 of 38 OrderDetail/ PickUpAddress Cardinality - Zero to One 揽收地址信息。 卖家自送类型时不返回该值。 ../PickUpAddres/ Contact String(64) Conditional 联系人 ../PickUpAddres/ Company String(128) Conditional 公司 ../PickUpAddres/ Street String(200) Conditional 街道 ../PickUpAddres/ District String(64) Conditional 区，输入相应区的代码，请参考揽收地 址代码表 ../PickUpAddres/ City String(64) Conditional 城市，输入相应城市的代码，请参考揽 收地址代码表 ../PickUpAddres/ Province String(64) Conditional 省，输入相应省份的代码，请参考揽收 地址代码表 ../PickUpAddres/ Postcode String(6) Conditional 邮编 ../PickUpAddres/ Country String(64) Conditional 国家 ../PickUpAddres/ Email String(128) Conditional 电邮 ../PickUpAddres/ Mobile String(32) Conditional 手机；方便揽收人员上门揽收前联系， 必须填写。 ../PickUpAddres/ Phone String(32) Conditional 固话 OrderDetail/ ShipFromAddress Cardinality - One 寄件人地址信息。 ../ShipFromAddress/ Contact String(64) Always 联系人 ../ShipFromAddress/ Company String(128) Always 公司 ../ShipFromAddress/ Street String(200) Always 街道 ../ShipFromAddress/ District String(64) Always 区 ../ShipFromAddress/ String(64) Always 城市 eBay 国际 e 邮宝 API V2 说明文档 Page 18 of 38 City ../ShipFromAddress/ Province String(64) Always 省 ../ShipFromAddress/ Postcode String(6) Always 邮编 ../ShipFromAddress/ Country String(64) Always 国家 ../ShipFromAddress/ Email String(128) Always 电邮 ../ShipFromAddress/ Mobile String(32) Always 手机号 OrderDetail/ ShipToAddress Cardinality - One 收件人地址信息 ../ShipToAddress/ Contact String(64) Always 联系人 ../ShipToAddress/ Company String(128) Conditional 公司 ../ShipToAddress/ Street String(200) Always 街道 ../ShipToAddress/ City String(64) Always 城市 ../ShipToAddress/ Province String(64) Always 省 ../ShipToAddress/ Country String(64) Always 国家 ../ShipToAddress/ CountryCode String(2) Always 国家代码，与 eBay API 里的标准国家 代码一致。 可用值： US,AA,GU,PR,AS,FM,MH,MP,PW,PR,VI ../ShipToAddress/ Postcode String(32) Always 邮编 ../ShipToAddress/ Phone String(32) Conditional 固话 ../ShipToAddress/ Email String(128) Always 电邮 eBay 国际 e 邮宝 API V2 说明文档 Page 19 of 38 OrderDetail/ ItemList Cardinality - One OrderDetail/ ItemList / Item Cardinality - One to Many 货品信息 ../Item/ eBayItemID String(32) Always eBay 物品号 ../Item/ eBayTransactionID String(20) Always eBay 交易号 ../Item/ eBayBuyerID String(64) Always eBay 买家 ID ../Item/ eBayItemTitle String(55) Conditional eBay 商品标题 ../Item/ eBayEmail String(128) Conditional 买家 eBay 电邮 ../Item/ SoldQTY Integer Conditional 卖出数量 ../Item/ PostedQTY Integer Conditional 寄货数量 ../Item/ SalesRecordNumber Int Conditional 用户从 eBay上下载的时 eBay销售编号 ../Item/ OrderSalesRecordNumber int Conditional 订单销售编号，如果在 eBay 上合并订 单，会产生一个新的 SalesRecordNumber ../Item/ OrderID String(16) Conditional eBay 合并订单时生成的一个新的 Order ID ../Item/ eBaySiteID Integer Conditional 站点 ../Item/ ReceivedAmount Double Conditional 收到金额 ../Item/ PaymentDate Datetime Conditional 付款日期 ../Item/ SoldPrice Double Conditional 卖出价格 ../Item/ SoldDate Datetime Conditional 卖出日期 eBay 国际 e 邮宝 API V2 说明文档 Page 20 of 38 ../Item/ CurrencyCode String(3) Conditional 货币符号，可用值： USD ../Item/ EBayMessage String(256) Conditional eBay 留言 ../Item/ PayPalEmail String(128) Conditional 买家 PayPal 电邮 ../Item/ PayPalMessage String(256) Conditional PayPal 留言 ../Item/ Note String(256) Conditional 附注 OrderDetail/ ItemList/ Item/ SKU Cardinality - One 产品报关信息 ../SKU/ SKUID String(50) Conditional SKU ID ../SKU/ DeclaredValue Double Always 申报价值 ../SKU/ Weight Double Always 重量 ../SKU/ CustomsTitleCN String(55) Always 中文报关名称 ../SKU/ CustomsTitleEN String(55) Always 英文报关名称 ../SKU/ OriginCountryCode String(64) Always 原产地 eBay 国际 e 邮宝 API V2 说明文档 Page 21 of 38 3.1.6 VerifyAPACShippingUser 用于验证用户授权是否成功。 3.1.6.1 Request Element Type Required / Cardinality 说明 APIDevUserID String Required 开发商用户名 APIPassword String Required 开发商签名 APISellerUserID String Required 卖家 eBay 账户 MessageID String(36) Optional 调用方为每次调用提供的唯一标 识。 Version String Required Shipping Tool API 版本，可用值： 2.0.0 3.1.6.2 Response Element Type Available / Cardinality 说明 Ack Enum Always API 呼叫返回状态，可用值：  Failure  Success  Partial Failure  Warning 错误信息可参考 Message 栏 Message String Always 信息，一般为错误信息 Timestamp String Always 相应返回时间，格式为： yyyy-mm-dd hh:mm:ss:SSS InvocationID String(36) Conditional 与调用者提供的 MessageID 相同 Version String Always API 版本，返回值： 2.0.0 eBay 国际 e 邮宝 API V2 说明文档 Page 22 of 38 3.1.7 GetAPACShippingPackageStatus 获取一