Ubox开放API

开放API(v20131118)目录开放API(v20131118)..........................................................................................................1交互图解.............................................................................................................................2交互详述.............................................................................................................................2API列表..............................................................................................................................3签名算法.............................................................................................................3获取商品信息.....................................................................................................3扫码下单请求.....................................................................................................4买取货码（支付结果通知）.............................................................................5出货结果通知（友宝通知第三方）.................................................................6出货结果询问.....................................................................................................6出货接口.............................................................................................................7搜索售货机接口.................................................................................................7根据售货机获取商品列表.................................................................................8根据商品和售货机买码接口.............................................................................9查询售货机货道是否售卖某个商品...............................................................10附录...................................................................................................................................10商品对象详细信息...........................................................................................10售货机或便利店对象详细信息.......................................................................11交互图解交互详述动作说明扫描二维码使用第三方客户端扫描售货机大屏或者柜子上的二维码，把解析出的字符串发送给第三方服务器，以便查询商品信息。获取商品信息第三方服务器使用扫描二维码得到的字符串，调用友宝获取商品信息接口，得到商品详情，并通过客户端展示给用户。下单（可选）用户查看商品详情后，在第三方客户端完成准备工作（确保余额充足等），然后第三方服务器调用友宝下单接口，建立订单。支付用户确认支付时，第三方服务器完成支付流程，支付成功后，调用友宝支付通知接口出货友宝服务器收到支付成功通知后，请求售货机出货出货结果通知在第三方服务器调用友宝支付通知接口时，友宝服务器立即返回如下三种结果之一：1）成功接收通知并准备出货；2）通知调用有误，友宝忽视此次调用；3）收到通知调用，但是不能出货（比如售货机断网）如果是上述情况1），售货机出货的真实结果将会通过异步接口通知第三方服务器：1）出货成功；2）出货失败出货结果通知的延迟大部分在几分钟至一两小时之内，售货机网络状况不佳时可能在24小时左右。API列表通用约定：1.所有参数通过post传递签名算法1.除去sign以外的所有参数，按照ascii顺序排序，把参数名和参数值按照键值对形式拼接，形如：”app_id=12345retain_period=600tran_id=t2211”2.假设上面所得的字符串是变量s，则进一步拼接：s=s+“_”+app_key3.对上述所得的s做sha1处理，取出16进制全小写字符串，赋值给sign。获取商品信息开发测试环境地址：参数：参数必填说明app_id是应用id，申请接入时分配sign是签名，签名算法见签名算法小节os否应用运行平台mac否设备mac地址，如果是ios6或7，则需要传递下面的两个参数IDFA,openudidIDFA否ios7设备标识openudid否用于标识ios6/7的设备qr_string是扫描二维码得到的字符串内容app_uid否第三方应用里的user_idapp_promotion_id否活动标识app_trace_code否第三方传入的会话标识，用于后续跟踪此次会话返回参数类型说明tran_idstring交易id，后续下单、支付、出货都应携带此参数productjson数组商品信息，详细内容见最下“商品对象详细信息”vmjson数组商品所在的售货机信息，详细内容请参考最下“售货机对象详细信息”return_codestring状态代码，表示状态，不同的代码含义见状态代码表。return_msgstring状态描述return_code说明200正常400参数错误401签名错误404无法识别的二维码字符串410该商品已经被买走扫码下单请求开发测试环境地址：参数：参数必填说明app_id是应用idsign是tran_id是扫码接口返回的交易idapp_tran_id是第三方应用的订单号app_uid是第三方useridretain_period否保留时长，单位是秒。如果支付后，经过retain_period这么多时间之后才通知友宝，则友宝不再出货。如果没有调用下单接口，或者未传递此参数，则友宝从扫码获取商品信息开始计算，如果收到支付结果通知时已超过5分钟，则不会出货。返回：参数类型说明return_codestringreturn_msgstringreturn_code说明200正常400参数错误401签名错误410该商品已经被买走409商品价格已经发生变化503当前售货机未联网，可能会造成出货失败买取货码（支付结果通知）开发测试环境地址：参数参数必填说明app_id是sign是tran_id是pay_time是用户支付的时间，unix时间戳。如果pay_time+retain_periodnow，则不会出货。app_current_time是第三方服务器的当前时间，unix时间戳。为避免第三方服务器与友宝服务器时间不一致，所以必须传递此参数。deliver_now否默认是true，是否立即出货。当前版本暂时只支持立即出货，后续可以开放稍候取货接口。返回参数类型说明return_codestringreturn_msgstringdelivery_codestring商品取货码vmidstring商品所在机器的编号expire_timeint取货码过期时间，unix时间戳box_numberstring盒子编号。如果购买的商品存放在柜子里，这里给出具体的盒子编号。return_code说明200正常400参数错误401签名错误408已超过商品保留时长。支付到现在的时间已经超过了下单时设定的retain_period长度。友宝将不会出货。410该商品已经被买走503售货机未联网出货结果通知（友宝通知第三方）友宝携带参数:参数类型说明tran_idstring交易idcodestring状态码，取值见最下msgstring状态说明timestampint尝试出货的时间，unix时间戳。signstring签名字符串try_numberint这是第几次发送通知。如果友宝发送通知未能得到返回，则会间隔一段时间后重试，间隔算法是：interval=(try_number-1)*10，单位是分钟。try_number从1开始，最大等于5，之后将放弃重试。app_trace_codestring第三方应用传递的跟踪标识第三方返回：1或0，1为成功接收，0为失败出货结果询问测试环境接口地址：该接口可以用于由第三方发起主动询问出货状态。如果长时间没有收到出货通知，可以通过此接口主动查询；也可用于收到出货失败通知、第三方应用需要退款时，调用此接口进行核实第三方收到的通知没有被篡改或伪造。参数：参数必填说明app_id是sign是tran_id是返回：参数类型说明return_codestringreturn_msgstringcodestring出货状态码，取值见最下。msgstring出货状态说明出货接口如果调用支付结果通知接口时并未要求立即出货(deliver_now=false)，则后续可以通过这个接口稍后取货。这个接口是阻塞的。测试环境接口地址：参数：参数必填说明app_id是sign是tran_id是返回：参数类型说明return_codestringreturn_msgstringcode出货状态码msg出货说明出货状态码(code)取值说明code说明200出货成功500出货失败202出货确认中搜索售货机接口测试环境接口地址：参数参数必填说明app_id是sign是lat否纬度，经纬度同时传递时，可以