关联官方场景

• 点击这里进入奇门控制台（如果没有登录，则会跳转到登录页面），如下图所示

• 点击官方服务，可以看到当前已经关联的官方场景，如果之前没有关联过，则需要点击关联官方场景

• 点击关联官方场景，如下图所示

说明：

1. 对于官方场景，当前盒马开通了以下几种场景
   • 五道口支付：用于支付相关的业务流程
   • wdk-会员管理：用于获取会员信息。

• 关联了官方场景之后，点击官方服务可以看到当前已经关联的官方场景，如下图所示。

• 点击对应场景的管理，去配置实现这个场景下的接口，如下图所示

配置实现奇门接口

请求配置

这一步主要配置三方实现这个接口对外网可以访问的HTTP URL。奇门会请求这个URL，然后获取到结果。如下图所示

需要注意的点：

1. 配置的URL，必须要外网可以访问。
2. 配置的URL中如果有参数的话，对于参数的key不能出现开放平台保留的参数key，比如：这个URL，http://www.example.com/payment?method=xxx。其中method这个参数是开放平台保留的参数key，不能出现在配置的URL中。具体哪些参数key是保留的，参考这里

响应配置

这里主要是说明三方对于返回结果的json格式需要是什么样的结构。这里举例alibaba.wdk.payment.pay接口为例，要求的返回结构和实际返回的数据如下图所示

自测环境

用奇门提供的工具来测试自己的代码，以及返回是否是接口要求的格式，使用这个工具可以解耦开需要跟盒马的开发同学一起联调的问题。如下图所示

需要注意的点：

1. 这里最大的问题就是请求参数的配置，尤其是如果参数是一个复杂结构，需要填写json结构的参数时，会如果填写不正确，会出现参数校验错误的情况。对于简单结构的参数，按照类型填写即可，对于复杂结构，举例如下图所示

1. 如果调用测试不通，可以看一下右边的对应的请求示例和响应示例。

正式发布

测试完成之后就可以正式对外发布了。发布过程中还需要进行一些签名配置，具体的可以参考奇门官方的文档，点击这里访问。参考API服务签名验证部分。

授权配置

在正式发布之后需要授权盒马的appkey，允许盒马的appkey来调用你的服务。盒马的appkey是：23773503。操作步骤如下图所示。

1. 授权配置
   
2. 点击新增授权应用，输入盒马的appkey
   
3. 检查是否配置正确，点击第二步中的 配置奇门授权 如下图
   

如果实现的奇门接口在这里正式环境和测试环境都有了，那么就代表授权成功。否则在实际调用中会出现无法找到路由的错误。

开发最佳实践

使用开放平台的sdk开发

在写代码的时候一定要使用开放平台的sdk来开发，否则其中的签名，请求的方式等各种问题会搞的很花时间。举例如下：

import com.alibaba.fastjson.JSONObject;
import com.qimencloud.api.sceneqimen.request.*;
import com.qimencloud.api.sceneqimen.response.*;
import com.taobao.api.internal.spi.CheckResult;
import com.taobao.api.internal.spi.SpiUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;

@RequestMapping(value = "/payment_ack", method = {RequestMethod.GET,RequestMethod.POST})
@ResponseBody
public AlibabaWdkPaymentAckResponse paymentAck(HttpServletRequest request){
    try{
        CheckResult checkResult = SpiUtils.checkSign(request, appSecret);
        if (!checkResult.isSuccess()){
            AlibabaWdkPaymentAckResponse errResponse = new AlibabaWdkPaymentAckResponse();
            /**
             * 注意：这里设置的错误信息和错误code，一定要按照奇门接口配置的时候说明的错误返回内容严格设置
             * 否则在安全性校验上会不通过。
             */
            errResponse.setErrorMessage("Illegal request");
            errResponse.setErrorCode("sign-check-failure");
            errResponse.setSuccess(false);
            return errResponse;
        }else{
            JSONObject jsonObject = JSONObject.parseObject(checkResult.getRequestBody());

            AlibabaWdkPaymentAckRequest.AckParamDO paramDO = jsonObject.getJSONObject("ackParamDO").toJavaObject(AlibabaWdkPaymentAckRequest.AckParamDO.class);
            //TODO 实现自己的业务逻辑，然后返回
            return doPaymentAck(paramDO);
        }
    }catch (Exception e){
        log.error(e.getMessage(),e);
        AlibabaWdkPaymentAckResponse errResponse = new AlibabaWdkPaymentAckResponse();
        errResponse.setSuccess(false);
        errResponse.setErrorCode(String.valueOf(ErrorCode.PAYMENT_ACK_SYS_ERROR.getCode()));
        errResponse.setErrorMessage(e.getMessage());
        return errResponse;
    }
}

对于示例中的错误设置，参考接口实现配置中接口文档预览中的说明，如下图所示

FAQ