在平时工作中,经常会遇到的一种场景是:A公司要对接B公司的API方法,本篇是站在A公司的角度,去对接B公司API接口的实战。
一、背景
在平时工作中,经常会遇到的一种场景是:A公司要对接B公司的API方法,这时,A公司就要阅读B公司的接口文档,从接口文档中找到自己需要对接的API,并根据接口文档的要求,完成编码工作,最终完成对接工作。
本篇是站在A公司的角度,去对接B公司API接口的实战。
二、了解B公司接口的基础约定
一般情况下,B公司都会给出以下类似约定来满足基础对接,并且会提供测试环境和正式环境的两套信息。
appkey:A公司商户平台注册 id
appsecret:A公司商户平台获取到的 secret
三、基础域名
一般情况下,B公司会提供测试环境和生产环境两个基础域名。
例如:
测试环境 : https://******.com.cn
生产环境 : https://******.com.cn
四、请求及相应格式说明
一般情况下,B公司会提供请求及相应的基础格式说明。
例如:
1、请求方式
post
2、请求消息格式
application/json
3、响应消息格式
application/json
4、请求公共参数
例如,B公司有以下要求
所有接口均需要以 Http Header 方式传递以下参数;
名称 | 类型 | 必须 | 描述 |
---|---|---|---|
key | String | 是 | 调用key(必须以GET方式拼接在URL中) |
secret | String | 是 | 调用密钥 |
api_name | String | 是 | API接口名称(包括在请求地址中)[item_search,item_get,item_search_shop等] |
cache | String | 否 | [yes,no]默认yes,将调用缓存的数据,速度比较快 |
result_type | String | 否 | [json,jsonu,xml,serialize,var_export]返回数据格式,默认为json,jsonu输出的内容中文可以直接阅读 |
lang | String | 否 | [cn,en,ru]翻译语言,默认cn简体中文 |
version | String | 否 | API版本 |
当然,不同的公司提供的参数各不相同,因公司而异。
5、响应/回调参数说明
例如:B公司所有API都有响应,并且有的API还有回调响应,不论是响应还是回调响应,它们的参数格式都一样。
名称 | 类型 | 必须 | 示例值 | 描述 |
---|---|---|---|---|
item |
item[] | 1 | 宝贝详情数据 | |
num_iid |
Bigint | 1 | 520813250866 | 宝贝ID |
title |
String | 1 | 三刃木折叠刀过安检创意迷你钥匙扣钥匙刀军刀随身多功能小刀包邮 | 宝贝标题 |
desc_short |
String | 0 | 商品简介 | |
promotion_price |
Int | 0 | 优惠价 | |
price |
Float | 1 | 25.8 | 价格 |
total_price |
Float | 0 | 0 | |
suggestive_price |
Float | 0 | 0 | |
orginal_price |
String | 0 | 25.80 | 原价 |
nick |
String | 0 | 欢乐购客栈 | 掌柜昵称 |
num |
Int | 0 | 3836 | 库存 |
min_num |
Int | 0 | 0 | 最小购买数 |
detail_url |
String | 0 | http://item.taobao.com/item.htm?id=520813250866 | 宝贝链接 |
pic_url |
String | 1 | //gd2.alicdn.com/imgextra/i4/2596264565/TB2p30elFXXXXXQXpXXXXXXXXXX_!!2596264565.jpg | 宝贝图片 |
brand |
String | 0 | 三刃木 | 品牌名称 |
brandId |
Int | 0 | 8879363 | 品牌ID |
rootCatId |
Int | 0 | 50013886 | 顶级分类ID |
cid |
Int | 1 | 50014822 | |
crumbs |
Mix | 0 | [] | 导航菜单 |
created_time |
String | 0 | ||
modified_time |
String | 0 | ||
delist_time |
String | 0 | ||
desc |
String | 0 | 商品详情 | |
desc_img |
Mix | 0 | [] | 商品详情图片 |
item_imgs |
Mix | 0 | item_imgs[] | 商品图片 |
item_weight |
String | 0 | ||
item_size |
String | 0 | ||
location |
String | 0 | 发货地 | |
express_fee |
Float | 0 | 0.00 | 快递费用 |
ems_fee |
Float | 0 | EMS费用 | |
post_fee |
Float | 0 | 物流费用 | |
shipping_to |
String | 0 | 发货至 | |
has_discount |
Boolean | 0 | false | 是否有优惠 |
video |
video[] | 0 | 商品视频 | |
is_virtual |
String | 0 | ||
is_promotion |
Boolean | 0 | false | 是否促销 |
props_name |
String | 0 | 1627207:1347647754:颜色分类:长方形带开瓶器+送工具刀卡+链子;1627207:1347647753:颜色分类:椭圆形带开瓶器+送工具刀卡+链子; | 商品属性名。格式为pid1:vid1:name1:value1;pid1:vid2:name2:value2。 |
prop_imgs |
prop_imgs[] | 0 | 商品属性图片列表 | |
property_alias |
String | 0 | 20509:9974422:36;1627207:28326:红色;20509:9975710:38;1627207:28326:红色;20509:9981357:40;1627207:28326:红色 | 销售属性值别名。格式为pid1:vid1:alias1;pid1:vid2:alia2。 |
props |
Mix | 0 | [{ "name": "产地","value": "中国" }] | 商品属性 |
total_sold |
Int | 0 | ||
skus |
skus[] | 0 | 商品规格信息列表 | |
seller_id |
Int | 0 | 2844096782 | 卖家ID |
sales |
Int | 0 | 138 | 销量 |
shop_id |
Int | 0 | 151372205 | 店铺ID |
props_list |
Mix | 0 | {20509:9974422: 尺码:36} | 商品属性 |
seller_info |
seller_info[] | 1 | 卖家信息 | |
tmall |
Boolean | 0 | false | 是否天猫 |
error |
String | 0 | 错误信息 | |
warning |
String | 0 | 警告信息 | |
url_log |
Mix | 0 | [] | |
favcount |
Int | 0 | 0 | |
fanscount |
Int | 0 | 0 | |
method |
String | 0 | item_tmall:pget_item | |
promo_type |
String | 0 | ||
props_img |
Mix | 0 | 1627207:28326": "//img.alicdn.com/imgextra/i2/2844096782/O1CN01VrjpXt1zyCc9DvERE_!!2844096782.jpg | 属性图片 |
shop_item |
Mix | 0 | [] | |
relate_items |
Mix | 0 | [] |
6、针对异步回调的说明
例如:B公司对异步回调说明如下:
异步回调:
某些特定的接口需要异步返回结果,因此需商户A提供一个回调地址,将其进行base64 编码后,配置在 Http 请求 Header 中的 callback_url 里。
应答机制:
应答机制是指当商户A收到B公司数据通知时,必须回写 success 字符串,不区分大小写,B公司收到该“ success”,便认为商户A已收到通知; 否则会继续重复请求回调接口 3 次, 时间间隔为 1s, 5s, 30s。如果 4 次都访问不通,则会间隔 3h 继续轮询回调。
回调解密:
回调使用 aes 加密,需解密后使用。为避免由于网络波动造成回调失败,长时间未收到回调,请主动查询。
7、请求体加密说明及示例
数据采用AES加密,加密后作为data的值。
示例:
加密前:
加密后:
8、回调解密说明以及示例
数据采用AES解密,解密data值部分,解密后是json字符串
解密前:
解密后:
9、一般公司B还会对code值进行说明。
五、确定要对接哪些API
一般情况下,公司B会针对某个项目提供必要的API,我们往往只需要对接少部分API接口,因此,首先确认要对接哪些API方法。我们只需要按照API的要求进行对接即可。
六、根据API文档,编写一些基础工具类
工具类分两类。一类工具类,公司B会提供DEMO,我们拿来用即可。另外一类就需要自己根据API要求自己编写了。
七、根据API文档,编写必要的DTO
针对每个API,主要包含请求DTO,响应DTO,回调响应DTO,这个就要跟踪API要求,编写满足要求的DTO。
当然有些DTO是可以抽象成一个类,例如一般响应DTO和回调响应DTO都是一样的,这个时候就可以抽象为一个DTO了。
八、针对每个API方法,进行对接
做好以上准备工作,就可以一个个接口进行对接了。可采用下面方式一个一个接口进行对接。