API调用协议 - 蔬东坡开放平台V2版本

一、API调用方法详解

开发平台的API是基于HTTP协议来调用的，开发者可以根据（OPENAPI）的协议来封装HTTP请求进行调用

使用获得的appid与secret通过获取access_token接口，来获取access_token， access_token有效期为24小时，超时后可通过该接口重新获取；

使用获取的access_token访问开放平台业务接口。

二、调用入口

调用API的服务URL地址，开放平台目前提供了2个环境给开发者使用：正式环境，测试环境。

1、测试环境：开发者软件测试接口时的测试环境，通过测试地址获取测试数据，并调试代码。

2、正式环境：客户蔬东坡生鲜供应链系统的正式环境，通过正式环境可以获取到客户的正式数据。

调用环境	服务地址	说明
测试环境	http://scm.sdongpo.com/cc_thirdparty	蔬东坡的内部测试系统
正式环境	http://scm.sdongpo.com/cc_xxx	xxx代表客户的正式环境的项目code

三、公共参数

调用任何一个API都必须传入的参数，目前支持的公共参数有：

参数名称	参数类型	是否必须	参数说明
Authorization	string	是	访问令牌，通过接口获取access_token获取，如: Bearer token
Content-Type	string	是	指定请求体的格式（如 application/json）
X-Request-Id	string	是	请求id，主要用来做接口幂等，随机字符串，md5加密32位小写如：921e69818917335cebcd1da7ecb8d863

💡

注意：所有公共参数都是以header的方式入参。

四、业务参数

API调用除了必须包含公共参数外，如果API本身有业务级的参数也必须传入，每个API的业务级参数请考对应API列表说明。

五、调用示例
以openApiV2/Commodity/AddCategory调用为例，具体步骤如下：

1、获取 Access Token
使用 appid 和 secret 获取 Access Token。
具体参考获取access_token

2、修改请求头
在请求头中添加 Authorization

"Authorization": "Bearer <Your Access Token>",

3、组装HTTP请求
java示例

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = HttpResponse<String> response = Unirest.post("/openApi/Commodity/AddCategory")
.header("Authorization", "Bearer Kgggkldcfqtq9Ng4SZtEYK_EEvR3rWIUVCYnJcSYDOYKJfLkdHpdrtZItTumHyQMSnrZKJw0jJbmG78ePwX5wDXo-iO6ZPdULJ9vMdkF2NHdBvP3WEhZJR9oO_elN7QF")
.header("X-REQUEST-ID", "921e69818917335cebcd1da7ecb8d863")
.header("User-Agent", "Apifox/1.0.0 (https://apifox.com)")
.header("Content-Type", "application/json")
.body("{\"name\":\"黄瓜\",\"code\":\"hg111\",\"pid\":0,\"site_id\":6}")
.asString();

php示例

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
   CURLOPT_URL => '/openApi/Commodity/AddCategory',
   CURLOPT_RETURNTRANSFER => true,
   CURLOPT_ENCODING => '',
   CURLOPT_MAXREDIRS => 10,
   CURLOPT_TIMEOUT => 0,
   CURLOPT_FOLLOWLOCATION => true,
   CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
   CURLOPT_CUSTOMREQUEST => 'POST',
   CURLOPT_POSTFIELDS =>'{"name":"黄瓜","code":"hg111","pid":0,"site_id":6}',
   CURLOPT_HTTPHEADER => array(
      'Authorization: Bearer Kgggkldcfqtq9Ng4SZtEYK_EEvR3rWIUVCYnJcSYDOYKJfLkdHpdrtZItTumHyQMSnrZKJw0jJbmG78ePwX5wDXo-iO6ZPdULJ9vMdkF2NHdBvP3WEhZJR9oO_elN7QF',
      'X-REQUEST-ID: 921e69818917335cebcd1da7ecb8d863',
      'User-Agent: Apifox/1.0.0 (https://apifox.com)',
      'Content-Type: application/json'
   ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

go示例

package main

import (
   "fmt"
   "strings"
   "net/http"
   "io/ioutil"
)

func main() {

   url := "/openApi/Commodity/AddCategory"
   method := "POST"

   payload := strings.NewReader(`{"name":"黄瓜","code":"hg111","pid":0,"site_id":6}`)

   client := &http.Client {
   }
   req, err := http.NewRequest(method, url, payload)

   if err != nil {
      fmt.Println(err)
      return
   }
   req.Header.Add("Authorization", "Bearer Kgggkldcfqtq9Ng4SZtEYK_EEvR3rWIUVCYnJcSYDOYKJfLkdHpdrtZItTumHyQMSnrZKJw0jJbmG78ePwX5wDXo-iO6ZPdULJ9vMdkF2NHdBvP3WEhZJR9oO_elN7QF")
   req.Header.Add("X-REQUEST-ID", "921e69818917335cebcd1da7ecb8d863")
   req.Header.Add("User-Agent", "Apifox/1.0.0 (https://apifox.com)")
   req.Header.Add("Content-Type", "application/json")

   res, err := client.Do(req)
   if err != nil {
      fmt.Println(err)
      return
   }
   defer res.Body.Close()

   body, err := ioutil.ReadAll(res.Body)
   if err != nil {
      fmt.Println(err)
      return
   }
   fmt.Println(string(body))
}

六、注意事项

1、所有的GET接口：请求参数通常是通过URL的查询字符串（Query String）传递的。查询字符串是URL中?后面的部分，参数以键值对的形式出现，多个参数之间用&分隔。

GET请求参数的结构

http://scm.sdongpo.com/cc_thirdparty//superAdmin/Traceability/editEntity?param1=value1&param2=value2&param3=value3

? 后面是查询字符串的开始。

param1=value1 是一个键值对，param1 是参数名，value1 是参数值。

多个参数之间用 & 分隔。

2、所有的POST接口：业务参数需要以JSON对象的形式传递。

请求头示例:

Content-Type: application/json

请求体示例:

{
  "username": "john",
  "password": "123456"
}

七、HTTP状态码

状态码	错误信息	错误原因	解决方案
200	成功	---	---
400	请求参数错误	缺少必填参数	检查接口参数
401	令牌已过期	访问令牌已过期	重新获取访问令牌
403	身份验证不通过	appid、secret错误	---
405	请求方式错误	接口请求方式错误	---
429	访问受限	qps或访问量达到限制	---