dongli

东犁服务


一. 请求约定

[TOC]

# 接口域名 {{base_url}} 全局映射为
1. 正式 (暂时未出)
https://admin-ly.malldongli.com
2. 测试 (暂时未出)
https://wx-api.malldongli.com

一. 请求约定

  • 本文档中所有被动接口都统一使用 HTTP POST 方法调用.
  • 调用参数统一使用JSON, 放置在HTTP的POST请求体中【raw请求体格式】, 接口服务字符编码统一使用UTF-8
  • 特别声明,HTTP链接中的查询参数会被忽略
  • 认证参数放置在HTTP的Header中, 认证参数说明见【接口鉴权(验签)方案】

> 示例

# url
POST {{base_url}}/api/open_service/ping

# header
version: 1
appid: test_id
timestamp: 1694596594123
sign: 258dbcf088894ae21cf97dc5ea4a7c690aa92ac9f9f693d020e2d3023c0fc6cf

# body [raw]
{"hello":"DongLi"}

二. 响应示例

  • 相应统一为UTF-8编码的JSON内容
  • JSON统一的外层框架结构
字段 类型 说明
code 数字 状态码 0:成功 1:失败 其他:见【响应示例】
message string 结果说明
data 不定 接口响应

三. 响应业务状态码表

状态码 说明
0 成功
1 通用失败状态. 响应见message
1000 请求参数有误.
1001 appid错误/appid禁用
1002 当前请求, 时间参数不合法.
1003 验签失败
1004 版本错误
1005 请求参数需放在POST的body消息体raw格式
1006 完全加密, 请求参数消息体raw参数有误
1007 获取机构信息失败, 请联系管理员.

四. 接口鉴权(验签)方案

> 接口统一使用 hash sign 签名方式进行接口鉴权。

1.鉴权物料说明

> 【1】开发方在对接前, 需要在东犁方获得接口鉴权使用的 version, appid, appkey。 > 【2】接口对接方有义务保护其 appId, appKey 不外泄。 如因对接方泄漏 appid, appkey, 接口被冒名调用导致的数据泄漏、损坏等问题,东犁方有权拒绝承担修复、赔偿责任。

2. 鉴权 sign 签名计算说明

> 使用 SHA256 签名的方式进行接口鉴权。调用方和接口内部使用相同的方法. > 相同的version, appid和appkey进行签名,比较传入签名与计算签名是否一致来确定是否鉴权通过。

3. 鉴权 sign 签名计算方式

a. 物料准备

// 1. 请求链接 : {{base_url}}/api/open_service/ping
// 2. version : 1
// 3. appid   : test_id    (仅作示例,实际通常appid要复杂的多)
// 4. appkey  : test_key   (仅作示例,实际通常appkey要复杂的多)

// 5. 请求调用的消息体 【注意此示例消息体无结尾空白。如果有结尾空白也应计入消息体内容中。】
{"hello":"DongLi"}

b. 通过以下步骤获得签名数据:

> [步骤1] > 获取系统时间戳或从请求 header 中获取传入时间戳(毫秒数),假设为 1694596594123 > (请求时间戳, 必须为当前请求时间的前后1分钟内合法)


> [步骤2] > 将[appid]、[version]、[timestamp]、[appkey]联接成一个字符串。此示例结果为:

// appid : test_id
// version : 1
// timestamp : 1694596594123
// appkey : test_key

test_id11694596594123test_key

> [步骤3] > 将[步骤2]结果按UTF-8编码转换为字符串数据


> [步骤4] > 对[步骤3]得到的数据计算其SHA256摘要值。此示例结果为:

258dbcf088894ae21cf97dc5ea4a7c690aa92ac9f9f693d020e2d3023c0fc6cf

c. 请求方计算完签名, 拼凑指定参数作为请求Header参数

# header参数包含以下参数
# 需要将[appid]、[version]、[timestamp]、[sign]四个参数, 作为header头的请求内容
appid: test_id
version: 1
timestamp: 1694596594123
sign: 258dbcf088894ae21cf97dc5ea4a7c690aa92ac9f9f693d020e2d3023c0fc6cf

d. 请求返回值

// 请求有误的返回示例
{
    "code": 1007,
    "message": "获取机构信息失败, 请联系管理员.",
    "data": []
}
{
    "code": 1003,
    "message": "验签失败",
    "data": []
}

// 请求成功的返回示例 (返回此格式, 表示验签正常.)
{
    "code": 0,
    "message": "成功",
    "data": {
        "headers": {
            "Content-Type": "application/json;charset=UTF-8",
            "Content-Length": "19",
            "appid": "test_id",
            "timestamp": "1694596594123",
            "sign": "258dbcf088894ae21cf97dc5ea4a7c690aa92ac9f9f693d020e2d3023c0fc6cf"
        },
        "params": "",
        "body": {
            "hello": "DongLi"
        }
    }
}

页面列表

ITEM_HTML