Coupang Open API 测试指引

0. OPEN API调用开发流程

酷澎为了卖家的成功提供了多种OPEN API。但对于不熟悉IT服务开发的卖家，可能会困惑，不知道该从哪入手。一般要使用API的业务，基本按照以下流程进行。

第一阶段：确认并了解API详情

酷澎通过开发者入口(http://developers.coupang.com)提供所有API的详情（specification）。

卖家须提前通过该网站确认能提供哪些API，需要哪些数据，可以提供哪些数据。

第二阶段：基于信息（message）调用的OPEN API调用测试

确认API详情后，基于实际HTTP信息调用API
在该过程中，了解信息数据如何构成，确认实际API如何运行
通过该过程，在实现下个阶段，即基于代码的API调用服务时，可以轻松掌握多种问题的原因。

第三阶段：开发实际API调用代码

酷澎除了通过开发者入口提供API详情，还提供用各种开发语言实现的例子。
以此为基础进行实际API调用服务的开发阶段。
此时发生的各种问题是数据构成的问题还是代码开发上的错误，可通过上一阶段学习的OPEN API调用测试进行比较/检验。

这里基于信息调用OPEN API的方法会通过一个叫做Postman的免费软件来说明。

1. 获取OPENAPI Key

为了使用酷澎中的OPEN API，首先要在卖家系统(WING)中注册成为卖家，获取OPEN API的key。注册卖家须营业执照，详细流程点击这里查看。

2. 安装POSTMAN

2-1. Postman?

Postman是一个免费安装的API测试工作。

提供直观且便利的UI功能，付费版本还提供合作功能。

2-2. 下载及安装

请根据自己的OS环境，在https://www.getpostman.com/中下载相应的安装文件。

Postman支持Windows, Mac and Linux环境。

Note

Postman并非由酷澎提供的工具，因此仅介绍一般安装方法，不介绍postman本身的安装及使用信息。

3. Postman环境设置

对postman中常用的参数值（API调用时使用的参数值），可提前以key/value成对的形式进行定义，必要时变更后使用。

本指南中，建议将如下值安装到环境中使用。

VendorID：卖家ID（可在Wing中确认）
OPEN API key：酷澎Wing中获取的OPEN API key
SECRECT key：酷澎Wing中获取的OPEN API secret key

您可以通过点击右上角组合框来修改或者设置环境

点击Environment set列表，可新增、变更或删除。

在这里使用Wing 里面提供的相应信息设置以上变量

注意
当您的 vendor ID 或者 Openapi key 信息是一对时,您可以不必设置环境，通过自行输入这些信息来进行API 请求。只是设置环境会让API 测试更容易一些。

4. API Test

Lets investigate how to call product list paging query API using Postman.

4. API 测试

接下来看一下如何使用Postman来调用“分页查看商品列表API”。

4-1. 输入URI & Method

在开发者入口查看该API的URI(Path) 和Method (GET/POST/PUT/DELETE等)。此时也一同查看Path segment parameter是否存在在URI中。这里sellerProductId为必须。

基于开发者入口中确认的内容，按照以上图片设置API请求。

设置环境

查看前面内容说明的环境是否设置正确。

使用绑定参数 (:参数名)

您可以直接在URI输入框中输入sellerProdcutId值，但改变该值进行测试时，可同上，以“参数名”的形式组成URI，在Params tab中以key/value的形式输入该项的值。

4-2. 输入Request header

调用API时，处了URI和Method，还要发送Parameter 和Header值。酷澎的OPENAPI需要'Authorization' 和'X-Requested-By'这两个Header值。

Authorization :为进行API认证，必须发送HMAC字符串，通过即将在4-4章中说明的pre-script动态生成并提供。在输入\{\{signature\}\}等格式时，pre-request script中创建的值会参照global variable格式发送。

X-Reqeusted-By : 为查看API请求者的VendorId，以\{\{vendorId\}\} 格式输入,自动提供Environment中设置的VendorId。

4-3. 输入Request Parameter

如下方的查看发货地址API，URI‘？’后，如searchType=FULL的参数叫做'Querystring Parameter'参数。如下图所示，URI框内输入的querystring parameter也在下方Params tab中标示了出来，这里更改的值也同时更新到了URI框中。

按照开发者入库中确认的API调用详情，输入/创建Header 和Query String参数。

4-4. 输入pre-script，创建HMAC

OPEN API测试需要HMAC(Hash-based Message Authentication Code)字符串。Postman通过pre-request script功能，动态创建HMAC，pre-request script代码如下：

var CLIENT_KEY = pm.environment.get('CLIENT_KEY');
var SECRET_KEY = pm.environment.get('SECRET_KEY');
var AUTH_TYPE = 'CEA algorithm=HmacSHA256';

function getPath(url) {
          var pathRegex = /.+?\:\/\/.+?(\/.+?)(?:#|\?|$)/;
          var result = url.match(pathRegex);
          return result && result.length > 1 ? result[1] : '';
}

function getQueryString(url) {
          var arrSplit = url.split('?');
          return arrSplit.length > 1 ? url.substring(url.indexOf('?')+1) : '';
}

function getAuthHeader(httpMethod, requestUrl, requestBody) {

          var requestPath = getPath(requestUrl);
          var queryString = getQueryString(requestUrl);

          var timestamp = new Date().toISOString().split('.')[0]+"Z";
          timestamp = timestamp.replace(/:/gi, "").replace(/-/gi, "").substring(2);

          var requestData = [timestamp, httpMethod, requestPath, queryString].join("");
          requestData = replaceVariables(requestData);
          var hash = CryptoJS.HmacSHA256(requestData, SECRET_KEY);
          var hmacDigest = CryptoJS.enc.Hex.stringify(hash);
          var authHeader = AUTH_TYPE + ", access-key=" + CLIENT_KEY + ', signed-date=' + timestamp + ', signature=' + hmacDigest;
          return authHeader;
}

function replaceVariables(templateString) {
          let tokens = _.uniq(templateString.match(/{{\w*}}/g))

    _.forEach(tokens, t => {
       let variable = t.replace(/[{}]/g, '')
       let value = environment[variable] || globals[variable]
       templateString = templateString.replace(new RegExp(t,'g'), value)
    });

    return templateString
}

pm.globals.set('signature', getAuthHeader(request['method'], request['url'], request['data']));

复制好上面的内容，如下图所示，粘贴到Pre-request script tab中即可

4-5. 输入message body

当API请求Method为'POST'或'PUT’时，有时需要将参数写到信息正文中。这种参数叫做信息正文。我们以商品注册API为例看一看。

选择Body tab后，信息格式为‘raw’，content类型选择`JSON(aplication/json)`，参考开发者入口的API详情，输入信息正文（Message body）。

4-6. 调用API

输入所有调用API所需的URI, Method, Header, Parameter, Message后，点击Send按钮就会发送API请求。然后会收到响应的结果信息值，我们来看一下成功、失败时接收的响应信息是什么样的。

响应正常时，下方response框中将出现响应信息，接到HTTP 200的响应代码。

如果出现错误，将收到错误信息与错误代码。

5. API调用时的故障排除

API服务开发的过程中，最重要的不是了解Postman如何使用，而是在调用API时，要很好地理解响应的信息。

5-1. FAQ的使用

酷澎开发者入口是通过FAQ的形式，帮助并指导理解响应信息。

您可以使用搜索功能确认常见问题，因此咨询前，建议使用FAQ搜索功能。

5-2. 确认错误代码及信息

4XX 错误:

400相关的错误大部分都是API请求格式方面的错误。
此时请确认错误信息，看看信息是否输入正确，可立刻解决。
首先查看调用时使用的数据和开发者入口API详情中说的是否一致，如果问题依然没解决，附上“调用信息”和“响应信息”进行咨询，我们会尽快帮您解决。

5XX 错误:

500相关的错误大部分是API响应的处理过程中发生的内部错误。

为掌握准确的原因，请附上“调用信息”和“响应信息”进行咨询，我们会尽快帮您解决。

6.如何查看POSTMAN 调用及响应信息

在咨询调用酷澎OPEN API过程中发生的问题时，请参考以下内容，附上“调用信息”和“响应信息”，我们会更快地为您解决。

6-1. 提供调用信息

点击发送窗右上方的code按钮。

您可以弹窗中的所有调用信息。

调用信息可能会有多种格式，推荐使用‘cURL’ 。

6-2. 提供响应信息

点击下载按钮，下载json格式的信息，您还可以使用剪贴板的复制按钮，将其复制到正文中。同时还可将http响应代码一同发送。

OPENAPI 관련 안내

此组别内的文章

0. OPEN API调用开发流程

4. API Test

6-2. 提供响应信息

OPENAPI 관련 안내

此组别内的文章

0. OPEN API调用开发流程

4. API Test

6-2. 提供响应信息

相关文章