API 文档 ¶

开放平台服务器地址: https://macromap.cxkjedu.com/api/open/

API 文档约定格式 ¶

宏图开放平台 API 文档格式主要如下：

请求：
    基本信息
    请求头
    路径参数
    查询参数
    请求体
    请求体示例
响应：
    响应体
    响应体示例
    错误码

基本信息 ¶

介绍调用 API 所需要的请求方式、路径、访问凭证和权限等信息。

HTTP URL：服务端 API 的 URL。
HTTP Method：服务端 API 仅支持 HTTPS 协议和标准 HTTP 方法，如 GET、POST 等。
权限要求：调用 API 所需要权限，多个权限的关系为或，申请其中任一权限即可。
字段权限要求：请求返回结果中如需使用部分字段，需要特别申请权限。一般敏感字段的读取需要申请这类权限。

请求参数 ¶

调用 API 的详细入参说明，参数使用风格遵循 RESTFul，请注意不同参数在调用时的位置。

请求头：这部分参数需要放在 HTTP 请求的 Header 中，主要包含调用 API 所需要使用的访问凭证（API Token）以及 HTTP Content-Type。
路径参数：这部分参数需要放置在 URL 中，在文档中一般以:开头。
查询参数：这部分参数需要在 URL 后使用?进行连接，多个查询参数间以&分隔。
请求体：这部分参数需要放在 HTTP 请求的 Body 中，一般为 JSON 格式。
请求体示例：对应 API 的成功请求参数的样例。

响应 ¶

调用 API 的返回值。

响应体：一次 API 调用后，HTTP 响应中 Body 部分的内容。
响应体示例：API 成功请求结果的样例。
错误码：调用该 API 可能返回的错误码解释以及排查建议。

API 调用流程 ¶

如下图所示，在调用服务端接口前，需要完成以下准备工作：

apis_index_img001

开放平台的 API 都需要带上访问凭证 API Token 进行请求，否则系统会返回 401 应用未认证错误，每个商户都可以在控制中心生成应用授权密钥和公钥。应用服务商需要通过商户提供的密钥和公钥通过开放平台访问凭证获取接口获得访问凭证 API Token，并在每个请求的 Header 中携带访问凭证。

商户获取应用密钥 ¶

1、打开商户管理平台 https://macromap.cxkjedu.com/ 登录商户账号，选择应用管理

2、在商户管理平台应用管理中点击添加应用，输入应用名称点击保存

3、保存应用成功后，获取应用公钥和密钥。开发者即可使用应用公钥密钥调用访问凭证获取接口取得接口访问凭证（API Token）

访问凭证获取接口 ¶

请求

基本
HTTP URL	https://macromap.cxkjedu.com/api/open/auth
HTTP Method	GET

请求头

名称	类型	必填	描述
Content-Type	string	是	固定值："application/json; charset=utf-8"

查询参数

名称	类型	必填	描述
secret	string	是	应用程序公钥
key	string	是	应用程序密钥

请求体

该请求无请求体

请求体示例

$ curl --location --request GET 'https://macromap.cxkjedu.com/api/open/auth?secret=obxxxxxxx&key=wexxxxxxxx'

响应体

名称	类型	描述
status	string	接口状态 SUCCESS 表示成功
code	int	响应代码 200 表示成功
msg	string	错误描述
data	data	-
∟ app_name	string	应用程序名称
∟ app_secret	string	应用程序公钥
∟ app_key	string	应用程序密钥
∟ app_token	string	应用程序访问凭证（API Token）
∟ merchant	string	商户信息
∟ id	int	商户 id
∟ name	string	商户名称
∟ email	string	商户邮箱
∟ merchant_id	string	商户账号
∟ created_at	string	商户创建时间
∟ updated_at	string	商户修改时间

响应体示例

{
    "status": "SUCCESS",
    "code": 200,
    "data": {
        "app_name": "收银驱动",
        "app_secret": "obxxxxxxx",
        "app_key": "wexxxxxxxx",
        "app_token": "aoexxxxxxxxxxxxxxiO",
        "merchant": {
            "id": 2,
            "name": "宏图系统",
            "email": "htbots@pbk6.cn",
            "phone": null,
            "merchant_id": "cxexxxxxxxx",
            "email_verified_at": null,
            "created_at": "2021-03-27T04:10:59.000000Z",
            "updated_at": "2021-09-28T13:04:55.000000Z"
        }
    }
}

API 调用方式 ¶

调用服务端接口时，需要使用 HTTPS 协议、JSON 数据格式、UTF8 编码。请求需要把访问凭证 API Token 放到 Header 的 open-token 字段中。

示例 (curl) ：

该示例请求获取商户信息。

$ curl -X GET 'https://macromap.cxkjedu.com/api/open/merchant' \
-H 'open-token: <这里替换为对应的 API Token>' \
-H 'content-type:application/json; charset=utf-8'

响应体：

{
    "status": "SUCCESS",
    "code": 200,
    "data": {
        "id": 2,
        "name": "宏图系统",
        "email": "htbots@pbk6.cn",
        "phone": null,
        "merchant_id": "cxexxxxxxxx",
        "email_verified_at": null,
        "created_at": "2021-03-27T04:10:59.000000Z",
        "updated_at": "2021-09-28T13:04:55.000000Z"
    }
}

API 常见错误码 ¶

code	描述	备注
400	参数异常或其他错误
401	应用认证错误或商户已禁用该应用
404	接口错误
500	系统异常