文档中心 > 商家经营工具-开发指引

奇门官方API场景接入流程

更新时间：2024/08/01 访问次数：210606

接入流程

接入流程

1. 入驻奇门

入驻奇门 -> 选择官方场景 -> API实现 -> API自测 -> 发布上线 -> 配置授权 -> 对方调用。

1）API发布并配置了授权后意味着接口可以给授权方调用该接口，对于某些场景，可能需要调用对方，那么需要对方也按着流程来发布接口。

2）配置授权的时候可以选择测试环境和线上环境，测试环境可以用来联调。具体参考下面的配置授权说明。

2. 选择官方场景

如图，找到对应的官方场景并选择关联。如果列表为空或者找不到对应的官方场景，请联系运营小二。如果奇门仓储的官方场景，请参考仓储接入流程。

如果帐号还没有创建过应用，则需要在应用管理里面创建一个应用再做关联。

3. API实现

1）API预览

在api预览页面可以了解api的入参，出参情况。

2）接口实现

按照之前定义的API来实现服务的逻辑。

3）验签

为了防止接口被人乱掉用，需要在服务端做验签的逻辑，校验请求的合法性。那么， API服务后端如何进行验签？由于API请求带有targetAppkey，而API服务后端可以通过应用管理拿到对应的appSecret，将奇门云网关生成的签名，与自己服务后端代码生成的签名进行校验，当然TOP API SDK也提供了相关的验签工具（SpiUtils），需要在执行接口逻辑前完成验签校验逻辑。

验签返回报文

验签的返回内容需要和响应失败的格式（参考上文响应失败参数）对应的上，系统要求如下：

奇门参数名	类型映射值	参数值
flag	以实际配置为准	满足失败条件
sub_code	以实际配置为准	sign-check-failure
sub_message	以实际配置为准	Illegal request

其中参数名为系统要求的值，如果映射值不同，则以实际映射值为准。返回格式可以参考『接口文档预览』页面的验签demo。如果没有完成验签逻辑，API发布时候会提示验签失败。

java代码示例如下：

/**
* 使用该方法同时请务必要阅读该方法的源码，大致了解该方法的实现。
*
* 如果验签失败则需要返回验签失败的结果，并且需要和配置对应的上，系统才认为是验签成功；
*
* 如果正确的请求老是误认为验签错误了，则确认以下几点：1编码是否UTF82 2密钥是否写错了 3request如果是json,xml类型则（form则忽略）确认inputstream是否被读取过了？如果需要使用body但不想改动麻烦，可以先执行验签，
* 然后在验签结果中获取body（checkResult.getRequestBody()方法）来执行业务逻辑
*
*/
CheckResult result = SpiUtils.checkSign(request, targetAppSecret);? //这里执行验签逻辑
if(!result.isSuccess()) {  //如果验签失败则需要返回 验签失败的结果，并且需要和配置对应的上，系统才认为是验签成功
   HttpSampleResponse httpSampleResponse = new HttpSampleResponse();
   httpSampleResponse.setErrorMessage("Illegal request");
   httpSampleResponse.setErrorCode("sign-check-failure");
   httpSampleResponse.setFlag("failure);
   //return
}

4）验签算法规范化校验

点击“发起验证”后，系统会发出一条正常的请求，但是会混杂其他参数，要求服务方动态把参数加入到验签逻辑中。

举个例子，验证逻辑会多带参数abc=123请求到后端，验签拼接逻辑需要把abc123也拼接在签名逻辑中。**要求验签能正常通过**，否则会有“验签的参数不能写死”的提示。

如果出现上述提示，要求检查签名逻辑，检查为什么验签不通过的原因（要求验签通过）。

4. API自测

这里的测试环境和正式环境分别对应前面填写的正式和测试的两个地址。

注意：API没有发布之前无法选择正式环境，请选择测试环境。因为API还没上线，选择线上环境会提示ApiName不合法。

5. API发布

如果自测通过，则可以点击『自测通过请发起服务验证』，此时系统会发起非法请求请求服务后端，如果后端不满足验签逻辑则提示错误。具体验签逻辑参考上文。验证通过可以点击发布上线。

注：发布上线后，请在自测页面选择正式环境测试是否成功发布成功。

6. 添加/修改授权

**注意！ **如果场景是奇门仓储，或者ERP-CRM官方场景，ERP-POS奇门官方场景，线上OMS-线下ERP奇门官方场景，授权配置请参考货主类授权配置。

API上线后想让别的应用调用还需要在后台配置授权。如图中步骤添加即可，把对方的appkey填写进来。

如图，表示允许23212537的appkey来调用服务。

7. SDK的使用

API发布后，别人想调用可以通过SDK来调用。注意必须API发布后下载的SDK的结构才是没问题的，如果变更了API需要重新上线并重新生成SDK才能看到对应的数据结构。

1）SDK的下载

点击『应用管理』，『SDK下载』可以下载SDK。

2）SDK的使用

appkey 和 targetAppkey分别表示什么意思呢？

appkey就是调用方的appkey；

targetAppkey就是被调方，也就是服务提供方的appkey。

如果在api自测环节，可以用appkey=targetAppkey 也就是自己调用自己。

如果是在联调环节，targetAppkey就是服务提供方的appkey，appkey填写的是调用方的appkey，此时需要服务提供方在授权配置页面添加对调用方的授权才能调用的通。

String appkey = "";
String appSecret = "";
String format = "JSON";
/*
 * 后缀如果测试环境地址则为/router/qmtest，如果是正式地址则为/router/qm
 * 注意！这里的URL不能写错，更不能写成仓储的特有URL
 */
String url = "https://qimen.api.taobao.com/router/qmtest";
String apiName = "";
String targetAppkey = "";
DefaultQimenCloudClient client = new DefaultQimenCloudClient(url, appkey, appSecret, format);
QimenCloudRequest request = new QimenCloudRequest();
request.setApiMethodName(apiName);
//注意！ 千万不能少了这一步
request.setTargetAppKey(targetAppkey);
//添加参数
//request.addQueryParam(key, value);
QimenCloudResponse response = null;
try {
    response = client.execute(request);
} catch (ApiException e) {
    e.printStackTrace();
}

8. 名词解释

appkey：调用方的appkey。

targetAppkey：被调方，也就是服务提供方的appkey。

授权：调用的许可，如果没有对调用方的appkey授权那么对方是不可以调用服务的。

验签：为了防止接口被人乱掉用，需要在服务端做验签的逻辑，校验请求的合法性。

9. 注意点

PHP的SDK不支持整形字段，必须用String来传。

FAQ

关于此文档暂时还没有FAQ

有用(116) 我要提问

淘宝开放平台

商家经营工具-开发指引