《担保收货商接口技术文档》 返回首页
最近更新时间:2014年9月19日,有任何问题请及时联系我们。

一、担保交易及自动下单接口简介

担保交易接口简介:担保交易接口的作用是:①调用比价器的数据自动定国外销售价和国内采购价; ②老外下单后自动发布到比价器收货; ③收货后发送信号给您,以便您自动发信通知顾客、财务统计或与您旧网站同步备份数据等。

担保交易会大幅提高您的自动化程度,不仅减少人工成本,还可以减少财务成本(支付宝批量付款手续费仅千分之一,每天批量付一次款即可,避免人工错误)。原理:请查看《担保交易指南》。欢迎点此免费自助开通担保交易收货帐号后认真体验一下。注:200元押金是可以随时退还的。
自动下单简介:担保交易系统所包含的自动下单功能,可大幅加快您的收货速度,减少恶意占单。原理:收货商在比价器担保交易系统发布收货需求后,系统会按最近一个月的订单取消率低于10%的价低者优先原则自动匹配库存商成交(不够的话再其余价低者优先),接着比价器报警通知他们(他)出货,若某个供应商5分钟内未查看订单我们还会自动短信通知他。

二、网关总序:(点击此处下载php代码开发包,代码同以下演示

(一) 请在比价器注册一个用户名后联系我们授权,审核后我们会告诉您用户编号(参数名为uid)和网关签名密码(参数名apikey)

(二) 如何与比价器交换信息?

    1、把要请求的数据和apikey一起计算出签名sign,然后再把要请求的数据和sign一起发到网关 http://api.bijiaqi.com/gateway.php

    2、请求参数:必要的请求参数有以下3个
参数名称 参数说明
cmd 接口请求的动作
uid 您在比价器的用户ID(数字ID非用户名)
sign 本次请求的数据签名,采用md5,计算方法如下实例
其他参数  

    3、一次完整的发送数据到比价器的过程示范
var data = {"youdata":456,"uid":123,"cmd":"getprice"}; //这里是您需要发送到比价器的数据
var sign_data = [],request_data = []; //初始化要签名的变量和发送到比价器网关的参数变量
foreach(var name in data){ //遍历要请求的变量
  if(name != "sign" && name != "apikey"){ //sign变量和apikey变量不要纳入计算
      sign_data.push(name+"="+data[name]);  //把要发送的数据用"参数=参数值"的字符串方式连接起来放入数组
      request_data.push(name+"="+urlencode(data[name])); //要发送的数据urlencode变量之后添加到数组
  }
}
sign_data.sort(); //参数排序:因为参数顺序不一样,md5之后的值不一样,所以需要排序
var sign = md5(apikey+sign_data.join("&")); //计算sign,sign_data排序后的数组用"&"连接起来,然后md5得到sign签名值
http.get("http://api.bijiaqi.com/gateway.php"?+request_data.join("&")+"&sign="+sign);  //发送数据到比价器网关
注:以上开发代码请参考 cls.bijiaqi.php ,点此下载,以下示例全部使用cls.bijiaqi.php演示

    4、比价器返回结果:比价器返回的结果为utf8编码的xml文件。如下图,数据分为base节点(请求状态)和data节点(数据信息)区域。
Bas参数名称 返回值 说明
status success(成功)fail(失败)  
errno 错误信息代码 如果成功则为空
error 错误信息 如果成功则为空
<?xml version=”1.0” encoding=”utf-8” ?>
<root>
<base><status>fail</status><errno>错误代码</errno><error>错误信息</error></base>
<data>其他数据</data>
</root>

三、收货需求发布接口-老外下单后自动发布到比价器担保交易收货,包含自动下单功能 (演示地址)

    1、请求参数列表
参数名称 参数说明 必须
cmd updateneed
uid 您在比价器的用户ID
sign 本次请求的数据签名,采用md5
gameid or gamecode 比价器的游戏ID或者游戏代码
serverid or servername 比价器的服务器ID或者服务器名
orderid 国外的订单号
charactername 收货ID:本参数不对外,只是方便你们查截图时把ID显示在截图上对照,对外的ID请放到下面的notice里
notice 供应商下单后看到的出货提示。您可将需对外显示的收货ID通过本参数发来,拍卖发货的物品名也可写在这里,还可包含一些其它注意事项。举例:“请面对面发货给以下老外ID:xxx。交易地点联盟在暴风城,部落在奥格瑞玛。发完务必在本页底部上传截图。黑金恕不结算。”再举例:“建议用拍卖插件进行拍卖,用法见上文,插件命令xxx@xxx(@前面是角色名,后面是物品名),不用插件拍错责任自负。拍完务必在本页底部上传截图。黑金恕不结算。”
price 采购价
quantity 需求的采购数量
minquantity 需求最小下单数量
quantitytype "quantity"代表的数量类型,"now"表示现需,"all"为总需,默认为总需求量"all"
ispublic 1表示发布,0表示隐藏
isline 0 =即时-当面
-1=即时-拍卖
-2=即时-邮寄
-3=需拍卖佣金
1 =需老外在线
2 =需老外确认
3 =登记库存
11=现金收S矿
12=现金收T矿
isah 下单数量必须是isah的整数倍,默认1
canceltime 自动取消订单的时间(单位是分钟):供应商下单后超过多少分钟若未点击“已发货”按钮则订单自动取消重新采购。比如:半小时发货的自动取消时间和48小时不一样的,半小时订单您可设为30分钟自动取消,48小时可设为60分钟。  
existsnoupdate 本参数是为了方便您通过接口修改已经存在的需求内容,您可只更新部分变量内容,并在existsnoupdate中指定无需更新的变量名,多个变量名用"^"分割,如"price^notice"

《比价器各服务器名称与ID对照表》请点http://www.bijiaqi.com/service/?action=hostlist下载后与贵站的服务器名称对照使用

require "cls.bijiaqi.php"; //引入比价器网关类
$bijiaqi = new bijiaqi("您的UID","您的APIKEY");
$bijiaqi->request(array(
  "cmd"=>"updateneed",
  "gameid"=>10,
  "serverid"=>1,
  "orderid"=>"No.1",
  "notice"=>"到这里来交易",
  "price"=>"0.0002",
  "quantity"=>1000,
  "minquantity"=>100,
  "ispublic"=>0,
  "isline"=>0,
  "isah"=>1000 //整数倍
));
2,数据区域返回格式
<need needid="1 [需求编号]" price="0.002 [价格]" quantity="1000 [数量]" minquantity="0 [最小数量]" ispublic="1 [是否发布需求]" isline="0 [交易类型]" />

    2、错误代码列表
错误代码 错误信息 区域
USER_NO_EXISTS 用户不存在,参数里面的UID错误 全局
USER_NO_ACCESS 您没有权限使用接口 全局
HOST_NO_ACCESS 客户端服务器ip没有权限 全局
NEED_GAME_ERROR 游戏ID或者游戏代码不存在 需求更新
NEED_SERVER_ERROR 服务器ID或者名称不存在 需求更新
NEED_ORDERID_ERROR 国外订单号为空 需求更新

四、通过接口修改订单状态等参数

    1、请求参数列表
参数名称 参数说明 必须
cmd updateorder
uid 您在比价器的用户ID
sign 本次请求的数据签名,采用md5
orderid 比价器的订单号
remark 订单备注  
notice 供应商下单后看到的出货提示。您可将需对外显示的收货ID通过本参数发来,拍卖发货的物品名也可写在这里,还可包含一些其它注意事项。举例:“请面对面发货给以下老外ID:xxx。交易地点联盟在暴风城,部落在奥格瑞玛。发完务必在本页底部上传截图。黑金恕不结算。”再举例:“建议用拍卖插件进行拍卖,用法见上文,插件命令xxx@xxx(@前面是角色名,后面是物品名),不用插件拍错责任自负。拍完务必在本页底部上传截图。黑金恕不结算。”
isselected 付款的时候是否选中该订单,"1"表示选中,"0"表示不选
status 订单状态,对照表见第五部分
require "cls.bijiaqi.php"; //引入比价器网关类
$bijiaqi = new bijiaqi("您的UID","您的APIKEY");
$bijiaqi->request(array(
  "cmd"=>"updateorder",
  "orderid"=>11,
  "remark"=>1
));
2,数据区域返回格式
<order orderid="1 [需求编号]" price="0.002 [价格]" quantity="1000 [数量]" minquantity="0 [最小数量]"  isline="0 [交易类型]" status="订单状态" />

    2、错误代码列表
错误代码 错误信息 区域
USER_NO_EXISTS 用户不存在,参数里面的UID错误 全局
USER_NO_ACCESS 您没有权限使用接口 全局
HOST_NO_ACCESS 客户端服务器ip没有权限 全局
ORDER_NOT_EXISTS 订单不存在 订单更新
ORDER_STATUS_ERROR  订单状态错误  订单更新

五、实时返回订单信号-订单状态变更时从比价器实时发信号给您自用,您可用它自动通知顾客、财务统计等

若您需实现本功能,请您联系客服预先设置好信号的接收地址(参数名为apiipn)。当订单状态变更时,比价器会使用http POST发送信号您预设的地址去,您可以使用apikey校正数据的有效性,PHP示例代码如下:

require "cls.bijiaqi.php"; //引入比价器网关类
$bijiaqi = new bijiaqi("您的UID","您的APIKEY");
if($_REQUEST['sign'] == $bijiaqi->sign($_POST)){
   //orderipn为订单状态通知
   if($_REQUEST['cmd'] == "orderipn"){
      if($_POST['status']=='COMPLETED'){
        //订单改成收货商确认收货后您的处理
        echo $_POST['needorderid'];
      }
  //orderalipay为批量打款之后接收支付宝返回的信息,方便您做财务处理
  }else if($_REQUEST['cmd']=="orderalipay"){
......
  }
}
下列为订单状态变更的变量清单:
变量名字 变量值
cmd orderipn
uid 您的用户ID
subid 子账号ID
sellname 供应商名称
sign 本次请求的数据签名,采用md5
needorderid 需求订单ID(您的国外订单ID)
needquantity 需求总数量(现需+已下单数量)
orderid 您的订单ID
price 当前订单价格
quantity 当前订单下单数量
total 订单总额
fee 订单手续费
filecount 该订单上传的文件数
status 订单状态:
收货商确认已收货 COMPLETED
超时未接受 TIMEOUT_NOACCEPT
未接受订单 NOTACCEPT
订单超时取消 TIMEOUT_CANCEL
请联系卖方接受 WAIT
待卖方发货 BUYER_SEND_READY
已发货待确认 BUYER_SEND_CONFIRM
供应商取消单 BUYER_CANCEL
保留订单 SELLER_SAVE
问题订单 STATUS_WRONG
支付宝有误 ALIPAY_WRONG
收货商取消单 SELLER_CANCEL
无惩罚取消单 NORMAL_CANCEL
2011年11月20日,新增加了支付宝批量支付之后的信号返回
变量名字 变量值
cmd orderalipay
uid 您的用户ID
sign 本次请求的数据签名,采用md5
notify_id 支付宝的通知ID
batch_no 支付宝的批次号
pay_user_name 支付人的姓名
pay_account_no 支付人的账号编号
success_details 支付宝返回的原始支付数据,请参考支付宝的批量支付文档
各个订单用"|"分割,列之间用"^"分割,依次为"比价器订单号^供应商支付宝email^供应商姓名^支付金额^支付状态(S才表支付成功)^流水号^处理时间|....."
fail_details 同上,此处为错误数据
success_orderlist 比价器的订单列表,和success_details的订单对应,各个订单用|分割,包含3列,列之间用"^"分割,依次为"订单比价器号^需求编号^你的国外订单编号|比价器订单号2^需求编号2^你的国外订单编号2|"
fail_orderlist 同上,此处为错误数据


六、如何通过接口自动调用比价器库存数据(点此人工查看比价器库存数据表)

比价器库存数据接口仅授权给自动下单量较多的一手担保交易收货商使用:

(一) 调用全区库存数据:既可用于您参考,又可用于您汇总后发布到国外直接销售(若您自己有库存亦可将自己的库存与之汇总)

    1、请求参数列表
参数名称 参数说明 是否必须
cmd getprice
uid 您在比价器的用户ID
stockgameid 需要显示库存的游戏ID(点此下载游戏ID对应表,多个ID用","分开,默认为魔兽美服10和欧服11)
stockstatus 显示的库存类型,all[包括过滤您的库存商],open[不包括过滤您的库存],默认值为"open"
sign 本次请求的数据签名,采用md5
require "cls.bijiaqi.php"; //引入比价器网关类
$bijiaqi = new bijiaqi("您的UID","您的APIKEY");
$bijiaqi->request(array("cmd"=>"getprice"));

    2、数据区域返回格式
<game>
<gameid>10 [游戏ID]</gameid>
<gamename>魔兽世界(美服) [游戏名称]</gamename>
<gamecode>WOWUS [游戏代码]</gamecode>
<argprice>0.0306 [全区扫货均价参考]</argprice>
<argstockprice>0.0504 [全区库存参考均价]</argstockprice>
<stock>
<item serverid="1 [服务器ID]" servername="Aegwynn US – Alliance [服务器名称]" quantity="120000 [库存量]" minquantity="5000 [最小下单数量]" stockprice="0.0230 [库存参考价格]" />
</stock>
...
<stock>
<item serverid="1 [服务器ID]" servername="Aegwynn US – Alliance [服务器名称]" language="de [服务器语言]" price="0.0230 [扫货价格]" />
</stock>
</game>

《比价器各服务器名称与ID对照表》请点http://www.bijiaqi.com/service/?action=hostlist下载后与贵站的服务器名称对照使用

    3、错误代码列表
错误代码 错误信息 区域
USER_NO_EXISTS 用户不存在,参数里面的UID错误 全局
USER_NO_ACCESS 您没有权限使用接口 全局

(二) 调用单区库存数据

    1、请求参数列表
参数名称 参数说明 是否必须
cmd showserver
serverid 比价器的服务器ID
uid 您在比价器的用户ID
sign 本次请求的数据签名,采用md5

《比价器各服务器名称与ID对照表》请点http://www.bijiaqi.com/service/?action=hostlist下载后与贵站的服务器名称对照使用

require "cls.bijiaqi.php"; //引入比价器网关类
$bijiaqi = new bijiaqi("您的UID","您的APIKEY");
$bijiaqi->request(array("cmd"=>"showserver","serverid"=>1));

    2、数据区域返回格式
<game>
<gameid>10 [游戏ID] </gameid>
<gamename>魔兽世界(美服) [游戏名称] </gamename>
<gamecode>WOWUS [游戏代码]</gamecode>
<avgprice>0.00295 [全区扫货均价参考]</avgprice>
<avgstockprice>0.00503 [全区库存参考均价] </avgstockprice>
</game>
<server>
<serverid>402 [服务器ID] </serverid>
<servername>Tichondrius US - Horde [服务器名称] </servername>
</server>
<stock>
<item serverid="402 [服务器id] " servername="Tichondrius US - Horde [服务器名称] " stockid="07e86b64 [库存编号] " quantity="75659 [库存数量] " minquantity="5000 [最小下单数量] " stockprice="0.00579 [库存参考价] " online="1 [用户是否登录比价器,1为在线] " failcount="65 [失败订单数] " successcount="955 [成功订单数] " orderopen="1 [用户是否对您开放下单] " ordertype="0 [下单类型,0表示只下您的即时收货订单,1表示非即时收货订单也下] " />
</stock>

    3、错误代码列表
错误代码 错误信息 区域
USER_NO_EXISTS 用户不存在,参数里面的UID错误 全局
USER_NO_ACCESS 您没有权限使用接口 全局

七、通过接口调用比价器的订单成交数据 (2014年9月19日新增)

比价器成交数据接口仅授权给自动下单量较多的一手担保交易收货商使用:

    1、请求参数列表
参数名称 参数说明 是否必须
cmd getorder
uid 您在比价器的用户ID
sign 本次请求的数据签名,采用md5
require "cls.bijiaqi.php"; //引入比价器网关类
$bijiaqi = new bijiaqi("您的UID","您的APIKEY");
$bijiaqi->request(array("cmd"=>"getorder"));

    2、数据区域返回格式
<order cachetime="5m">
<item serverid="1" ordertime="2014-09-18 13:00:00" price="0.0030000000" quantity="50000" status="COMPLETED" uid="8b533" />
<item serverid="1" ordertime="2014-09-18 12:00:00" price="0.0034000000" quantity="12899" status="COMPLETED" uid="00073" />
<item serverid="1" ordertime="2014-09-18 11:00:00" price="0.0024000000" quantity="42203" status="COMPLETED" uid="8b533" />
<item serverid="1" ordertime="2014-09-17 17:00:00" price="0.0020000000" quantity="12678" status="COMPLETED" uid="783ae" />
<item serverid="2" ordertime="2014-09-17 13:00:00" price="0.0025900000" quantity="42700" status="COMPLETED" uid="1ef4b" />
</order>

订单状态(status)有 已结算(COMPLETED)已确认收货(CONFIRMED)

    3、错误代码列表
错误代码 错误信息 区域
USER_NO_EXISTS 用户不存在,参数里面的UID错误 全局
USER_NO_ACCESS 您没有权限使用接口 全局

八、读取我的出货订单信息

   1、请求参数列表
参数名称 参数说明 是否必须
cmd getsellorders
uid 您在比价器的用户ID
startdate 出货订单的开始日期,格式为"20120101"或者"2012-01-01 00:00:00"
enddate 出货订单的结束日期,格式同上
sign 本次请求的数据签名,采用md5
require "cls.bijiaqi.php"; //引入比价器网关类
$bijiaqi = new bijiaqi("您的UID","您的APIKEY");
$bijiaqi->request(array("cmd"=>"getsellorders"));

    2、数据区域返回格式

<order>
<item orderid="订单编号" sitename="收货网站名称" serverid="比价器的服务器ID" price="出货价格" quantity="出货数量" total="订单总额" fee="手续费" status="PAID 订单状态,状态码参考(五:实时返回订单信息)" addtime="下单日期" oicq="出货填写的QQ号码" mobile="出货填写的手机号码" alipayname="出货填写的支付宝名称" alipayemail="出货填写的支付宝email" />
</order>

《比价器各服务器名称与ID对照表》请点http://www.bijiaqi.com/service/?action=hostlist下载后与贵站的服务器名称对照使用

    3、错误代码列表
错误代码 错误信息 区域
USER_NO_EXISTS 用户不存在,参数里面的UID错误 全局
USER_NO_ACCESS 您没有权限使用接口 全局
DATE_ERROR 起止日期有误