帮助中心

详情请参考 使用说明.接口规范

本项目以接口形式对外提供服务，主要的服务内容包括基础信息类、商品类、订单类、售后类等整个电商各环节的接口。

主要对接有订单需求的客户，如果用户需要我们发货、售后等，可以对接我们对应的接口，在我们收到订单信息并且支付成功后，我们会对订单进行全流程的处理，包括配货、发货、售后等。

通常对接流程大致步骤分为三步：
①. 初始化基础信息
初始化基础信息包括：省市区、商品分类、商品品牌与贵司业务系统数据做映射，在请求我司接口时，按照我司系统的数据进行传输
②. 对接订单正向、逆向流程，与贵司业务结合
贵司业务系统用户订单生成的时候，调用我司创建订单接口，在贵司业务系统用户支付成功后，调用我司订单支付接口，注意：订单创建成功后，可调用取消接口，取消订单，30分钟内未支付的订单会自动取消，已取消的订单，无法再进行支付。
③. 对接商品信息变更、订单状态变更回调

接口调用频次为300次/分钟，在满足业务需求的情况下，应尽量减少非必要的接口调用。

当接口返回数据异常是，请提供接口名称、请求及响应的报文信息，联系我司技术人员协助排查。

本系统总计有两类回调：
①. 商品信息变更回调
②. 订单状态变更
用户业务系统接受到回调后，通常的处理方案是，接受到回调时，业务系统获取到商品ID或订单编号，然后主动调用我司商品详情、订单详情接口，来获取商品、订单的最新信息。我司强烈建议使用此种方式，因为回调通知数据量较大，我们是分批次异步回调，并且有对应的重试机制，这样可能会导致用户收到的信息并非实时最新的信息，所以建议收到回调后，主动调用下我们对应详情的接口。

通常情况下，用户在接口对接的最开始阶段，做好业务系统与我司省市区地址的匹配，当用户计算运费、下单的时候，传输我司地址信息，调用响应接口获取所需数据。

以国家民政部划分的行政区划代码为准，我司省市区接口返回数据包含民政部全部的省市区，用户业务系统省市区可以国家行政区划代码为桥梁，做好与我司省市区地址信息的匹配，遇到无法匹配的，可参考我司 物料信息 自行进行拼配。
注：接口需要地址信息，遇到直辖市【上海除外】时，做如下处理 省id--》直辖市id，市id--》直辖市的区id，区id--》0, 示例：
直辖市：id:132, name:北京市, id:133, name:东城区，传输的时候：province:132,city:133,area:0
现阶段我国行政区划直辖市有：北京市、天津市、上海市、重庆市

举例说明： 现有一款商品保温杯，规格名称有颜色、容量；规格值-颜色： 红色、白色、黑色； 规格值-容量：1升，1.5升，则此款商品的基础数据格式为:

商品存储结构说明

商品规格信息json结构
{"goodsId":10000,"specName1":"颜色","specName2":"容量","specName3":"","specName4":"","specs":[{"specId":20001,"specValue1":"红色","specValue2":"1升","price":100,"marketPrice":1000},{"specId":20002,"specValue1":"白色","specValue2":"1升","price":110,"marketPrice":10010},{"specId":20003,"specValue1":"黑色","specValue2":"1升","price":109,"marketPrice":10080},{"specId":20004,"specValue1":"红色","specValue2":"1.5升","price":100,"marketPrice":1000},{"specId":20005,"specValue1":"白色","specValue2":"1.5升","price":110,"marketPrice":10010},{"specId":20006,"specValue1":"黑色","specValue2":"1.5升","price":109,"marketPrice":10080}]}

其中商品规格名，最多有4个，分别对应 specName1,specName2,specName3,specName4，每个规格名对应的值，可以有多个，spu 生成规则为：最多spu的数量为 各规格的 笛卡尔积，最少数量为 1，其中每个规格都有唯一的specId，标识为唯一的一款具体商品，系统交互时真正需要传输该字段。

商品详情接口:

关键字段详细说明

按商品和规格两个维度进行解释：
①商品维度:
goodsId：商品id，商品有多规格时，会是同一个goodsId 多个specId
goodsType：商品类型，1礼品，只能兑换不允许直接售卖；2礼品销售形式不限制
onOffStatus：上下架状态，1上架；2下架，只有上架、未禁售、库存充足的商品才能正常下单
closeStatus：禁售状态，0正常；1禁售，只有上架、未禁售、库存充足的商品才能正常下单
price：商品价格，单位：分；
marketPrice：商品市场价，单位：分；
samplingNum：商品采样量，购买商品，选择运输方式为快递时，购买此数量，不再受起订量、打包数的限制，可直接购买；
defaultSpec：商品默认规格specId
specName1：specName2，specName3，specName4 商品规格名称，颜色、容量等，最多4个，最少1个
defaultSpec：商品默认规格specId
②规格维度：spec字段
specId：商品规格id，specId，具体到规格的唯一标识
specValue1：specValue2，specValue3，specValue4 商品规格值
price：该规格商品价格，单位 分；下单时扣除储备金的金额
marketPrice：该规格商品市场价格，单位 分
packageNum：打包数，购买商品时，非采样量并且大于起订量时，则购买数量必须是打包数的倍数
moq：快递起订量，选择运输方式为快递，购买数量非采样量时，则购买数量不得小于起订量
wlMoq：物流起订量，选择运输方式为物流时，则购买数量不得小于该物流起订量
注：V2版本商品维度新增nonPackage：是否零散购买，1是，2否。当规格维度packageNum大于1，商品维度nonPackage为1时，标识该商品支持不按打包数购买，接口版本大于等于V2版时可用

1、正常情况，系统上线时，建议初始化一下所有商品的信息，以后再以回调通知或者以周为单位每周主动更新一下产品库。商品数据存储，应该根据接口返回数据、结合自身业务系统商品存储结构，存储到数据库。
2、初始化商品步骤：可直接调用 3.5 全部在售商品 接口，返回此刻全部在售商品goodsId，然后根据goodsId调用 3.2 商品详情 接口，根据该接口返回该的商品所有详情信息，初始化基础数据到自身的业务系统。

1、建议封装独立处理 “商品信息” 的消费队列，队列任务职责：
①调用商品详情接口，获取在线商品最新详情信息；
②与自身业务系统关键信息做对比，并且更新自身业务系统商品信息：例如上下架、修改价格等；
2、商品更新策略：
①收到我司商品信息变更通知后，生产 “商品信息” 队列数据；
②在订单预览、订单创建接口如果返回商品价格变更时，生产 “商品信息” 队列数据；
③商品更新策略：商品最后更新、生产订单等超过7天时，自动生产 “商品信息” 队列数据；

现阶段商品类型（goodsType）主要有两类：1、礼品商品；2、通货商品
两种类型商品主要区别：礼品商品不允许直接以人民币的方式进行销售，只能以积分、金豆等形式进行兑换，通货商品对于销售形式没有限制；

①购买数量为采样量（商品字段samplingNum）时，运输方式为快递时可直接购买，运输方式为物流时则必须大于等于物流起订量
②运输方式为快递时：快递起订量（规格字段moq），购买商品的数量，不得小于快递起订量，并且是打包数（规格字段packageNum）的倍数
③运输方式为物流时：物流起订量（规格字段wlMoq），购买商品的数量，不得小于物流起订量，并且必须是打包数（规格字段packageNum）的倍数

①购买数量为采样量（商品字段samplingNum）时，运输方式为快递时可直接购买，运输方式为物流时则必须大于等于物流起订量
②运输方式为快递时：快递起订量（规格字段moq），购买商品的数量，不得小于快递起订量，新增allowNonPackage字段（是否支持形成散件订单：1是，2否），传2否时则下单数量必须是打包数（规格字段packageNum）的倍数
③运输方式为物流时：物流起订量（规格字段wlMoq），购买商品的数量，不得小于物流起订量，新增allowNonPackage字段（是否支持形成散件订单：1是，2否），传2否时则下单数量必须是打包数（规格字段packageNum）的倍数
④allowNonPackage字段仅在下单的商品的规格packageNum大于1，并且商品维度nonPackage字段（是否支持散件购买：1是，2否）为1时才有意义

根据用户的收货地址，选择运输方式，调用运费计算，可获取该商品订单应收取的运费；调用订单预览接口、订单生成接口、订单支付接口，订单支付同步返回成功后，标识订单支付成功，我司会处理后续拣货、配货、发货等流程，并且订单在状态变更的时间点，都会有对应的回调通知各业务方。

根据用户选择的商品、数量、收货地址、运输方式，接口返回对应的运费金额，其中快递运费在线收取，物流运费线下到付。

1、运输方式说明:
①. 物流运费到付，如需物流送货上门请联系 当地物流网点。
②. 德邦物流若超过起步价需要加18元保险费用。快递费用太高，建议选用物流。
③. 下单地址超出物流/快递配送范围的，需要客户根据快递/物流分配的最近网点/驿站/代收点等安排自提。
2、运输方式计算规则
①. 普通快递
货品总件：1 运费费率：5件以内 7.50元 /首重6件13.00元，每 增加6件，增加运费13.00元
友情提示：物流运费标准为零担（小批量）物流价 格，大宗订单请联系客服，我们会为您提供更为便 宜、优质的物流服务商。
②. 德邦快递
货品总件：1 运费费率：5件以内 13.00元 /首重6件16.00元， 每增加6件，增加运费15.00元
友情提示：物流运费标准为零担（小批量）物流价 格，大宗订单请联系客服，我们会为您提供更为便 宜、优质的物流服务商。
③. 普通物流
货品总重：1.2公斤 运费费率：起步价30.00元 ，每公斤0.6元
友情提示：物流运费标准为零担（小批量）物流价 格，大宗订单请联系客服，我们会为您提供更为便 宜、优质的物流服务商。
④. 德邦物流
货品总重：1.2公斤 运费费率：起步价48.00元 ，每公斤0.7元
友情提示：物流运费标准为零担（小批量）物流价 格，大宗订单请联系客服，我们会为您提供更为便 宜、优质的物流服务商。

1、收货地址物料使用方式：用户业务系统的省市区地址信息与我司的省市区地址做好映射，在C端用户下单后，业务系统可调用我司运费计算、订单预览、订单创建等需要用到地址的接口，使用我司的省市区对应的id。
2、直辖市处理：收货地址为省市区id，直辖市时【上海除外】，province:直辖市id,city:直辖市区id，area:0。
3、关于街道、乡镇村等级别的收货地址：我司收货地址支持国家行政区划的省、市、区三级地址，如果用户业务系统有街道、乡镇村级别的四级收货地址时，必须将四级地址的街道、乡镇村等，拼接到详细地址字段前面，例如：XX街道XX路XX号XX小区，或者XX乡XX村等。

①. 按照国家三包政策进行处理，质量问题情况下，确认收货后，7天内退换货处理，15天内换货处理；
②. 订单发货后，可以调用确认收货按钮，表示订单已确认收货；发货后10天还没确认收货的，系统会自动确认收货

创建售后有两种方式：
①. 是线上调用 创建预约服务 接口；
②. 线下联系我们客服，发送订单号及对应的售后诉求，我司客服基本会实时进行处理【推荐使用 线下方式，时效性更高】