京诚凭证系统开放文档

Appearance

认证说明 ​

概述（推荐方式：Basic 认证） ​

京诚凭证系统采用 AppId + 密钥 的认证方式。推荐做法：不需要先请求 token，直接在每一个接口的请求头里用 AppId 和密钥拼出 Authorization，即可调用所有接口。

推荐接入方式

  • 将 appId 和 密钥（secret） 按 appId:密钥 拼成一行，再做 Base64 编码，请求头设为：Authorization: Basic {Base64结果}
  • 无需调用「获取 token」接口，所有业务接口都带这一个请求头即可。

一、Authorization 怎么拼（必会） ​

所有接口（包括合同生成、征信查询、征信上报、大数据查询）都在请求头里带同一个东西：Basic + 空格 + Base64(appId:密钥)。

拼凑规则（三步） ​

  1. 拼成一行字符串（中间是英文冒号，不要有空格）

    text
    appId:密钥

    例如 appId 为 my_app_001，密钥为 my_secret_123，则拼成：

    text
    my_app_001:my_secret_123

  2. 对上面这一整串做 Base64 编码
    得到类似：bXlfYXBwXzAwMTpteV9zZWNyZXRfMTIz

  3. 请求头里写

    http
    Authorization: Basic bXlfYXBwXzAwMTpteV9zZWNyZXRfMTIz

    注意：Basic 后面有一个空格，再跟 Base64 结果。

完整请求示例 ​

http
POST /api/contract/create HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Basic bXlfYXBwXzAwMTpteV9zZWNyZXRfMTIz

{
  "templateId": "TPL001",
  "title": "业务合作框架协议",
  "parties": [...]
}

也就是说：不传 token，不先调获取 token 接口，直接用 AppId 和密钥拼出 Authorization 即可。

二、各语言生成 Authorization 示例 ​

Java ​

java
import java.util.Base64;

String appId = "my_app_001";
String secret = "my_secret_123";
String credentials = appId + ":" + secret;
String base64 = Base64.getEncoder().encodeToString(credentials.getBytes(StandardCharsets.UTF_8));
String authorization = "Basic " + base64;
// 请求头：Authorization: authorization

Node.js ​

javascript
const appId = 'my_app_001';
const secret = 'my_secret_123';
const credentials = appId + ':' + secret;
const base64 = Buffer.from(credentials, 'utf-8').toString('base64');
const authorization = 'Basic ' + base64;
// 请求头：Authorization

Python ​

python
import base64

app_id = "my_app_001"
secret = "my_secret_123"
credentials = f"{app_id}:{secret}"
base64_str = base64.b64encode(credentials.encode("utf-8")).decode("utf-8")
authorization = f"Basic {base64_str}"
# 请求头：Authorization

cURL ​

bash
# 先拼 appId:密钥，再 Base64，再带在请求里
curl -X POST "https://api.example.com/api/contract/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'my_app_001:my_secret_123' | base64)" \
  -d '{"templateId":"TPL001",...}'

三、若需调用「获取 token」接口：grant_type 必传说明 ​

有的环境会要求先调一个「获取 token」的接口（例如 OAuth2 风格），接口里会报错：grant_type 必传。

grant_type 是什么意思？ ​

  • grant_type 是 OAuth2 协议里的参数，表示授权类型（用哪种方式换 token）。
  • 用 AppId + 密钥 这种方式换 token 时，类型叫客户端凭证模式，固定传：client_credentials。
  • 所以：报错说 grant_type 必传时，在请求里加上 grant_type=client_credentials 即可。

常见写法有两种（以接口实际要求为准）：

方式 A：表单（application/x-www-form-urlencoded）

http
POST /api/auth/token HTTP/1.1
Host: api.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&appId=your_app_id&secret=your_secret_key

方式 B：JSON（application/json）

http
POST /api/auth/token HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "appId": "your_app_id",
  "secret": "your_secret_key"
}
参数必填说明
grant_type是固定填 client_credentials，表示用 appId+密钥换 token
appId是应用唯一标识
secret是应用密钥

四、AppId 与密钥说明 ​

参数说明
appId应用唯一标识，由澄心科技分配
密钥（secret）与 appId 对应，用于鉴权，严禁泄露或写在前端
  • 推荐：所有接口统一带 Authorization: Basic base64(appId:密钥)，无需先要 token。
  • 若必须走 token 接口：请求里除了 appId、secret，还要带上 grant_type=client_credentials（必传）。

五、请求头与参数说明（grant_type / scope / Content-Type / Authorization） ​

下面把这些参数是什么、放在哪、怎么来的、啥含义统一说明，方便对接时对照。

5.1 总览表 ​

参数名放在哪必填怎么来的含义
Authorization请求头（Header）是用 appId 和密钥按规则拼出来身份凭证，服务端靠它识别你是谁、是否允许访问
Content-Type请求头（Header）是（有 body 时）调用方自己按请求体格式写告诉服务端「我这次请求体是什么格式」
grant_type请求体（Body）或 URL 参数仅「获取 token」接口必填固定写死一个值，见下表表示用哪种方式换 token（OAuth2 协议要求）
scope请求体（Body）或 URL 参数按接口要求，多数可选按接口文档或分配的范围填表示要申请的权限范围，可选

5.2 Authorization（请求头） ​

  • 是什么：HTTP 标准请求头，用来带「身份凭证」。
  • 放在哪：请求头，例如：Authorization: Basic xxxxx。
  • 怎么来的：
    • 本系统推荐：不传 token，用 appId 和密钥 拼出来。
    • 拼法：先把 appId 和 密钥 拼成 appId:密钥，做 Base64 编码，前面加 Basic （注意空格），得到：Authorization: Basic {Base64(appId:密钥)}。
    • 若你们走「先换 token」：则用换到的 access_token，请求头写 Authorization: Bearer {access_token}。
  • 含义：服务端根据这个头识别调用方身份、判断是否有权访问，所以每个请求都要带。

5.3 Content-Type（请求头） ​

  • 是什么：HTTP 标准请求头，表示请求体（Body）的格式。
  • 放在哪：请求头，例如：Content-Type: application/json。
  • 怎么来的：调用方自己写。你发什么格式的 body，就写对应的 Content-Type，不是服务端返回的。
  • 含义：服务端根据它来解析你传的 body。写错会导致 body 解析失败、报错。
  • 常见取值：
取值含义何时用
application/json请求体是 JSON大部分业务接口（合同、征信、大数据等）
application/x-www-form-urlencoded请求体是表单：key1=value1&key2=value2很多「获取 token」接口要求这种格式

示例：

http
POST /api/contract/create HTTP/1.1
Content-Type: application/json
Authorization: Basic xxx

{"templateId":"TPL001", ...}
http
POST /api/auth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
（无需 Authorization，因为就是来要凭证的）

grant_type=client_credentials&appId=xxx&secret=xxx

5.4 grant_type（仅「获取 token」接口） ​

  • 是什么：OAuth2 协议里的参数，表示授权类型（用哪种方式换 token）。
  • 放在哪：请求体（Body） 或 URL 查询参数，具体以接口文档为准。
    • 若 Body 是表单（application/x-www-form-urlencoded），就放在表单里：grant_type=client_credentials。
    • 若 Body 是 JSON（application/json），就放在 JSON 里："grant_type": "client_credentials"。
  • 怎么来的：调用方写死。用 AppId + 密钥换 token 时，固定填 client_credentials（客户端凭证模式），不是服务端下发的。
  • 含义：服务端根据 grant_type 决定「按哪种规则校验你的请求、怎么发 token」。不传或传错会报「grant_type 必传」或参数错误。
  • 本系统常用取值：
取值含义
client_credentials用 appId + 密钥直接换 token，无用户登录，适合服务端调接口

5.5 scope（按需，多数可选） ​

  • 是什么：OAuth2 里表示申请的权限范围（例如能访问哪些接口、哪些数据）。
  • 放在哪：和 grant_type 一样，在获取 token 的请求里：请求体或 URL 参数（以接口文档为准）。
  • 怎么来的：
    • 若接口文档或澄心科技约定了「可填的 scope」，就按约定填（如 contract credit_query）。
    • 若文档写「不传则默认全部」或未要求，可以不传。
  • 含义：限制换到的 token 能干啥；服务端可能根据 scope 限制接口或数据范围。是否必传、可选值以接口文档/约定为准。

示例（表单方式获取 token，带 scope）：

http
POST /api/auth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&appId=xxx&secret=xxx&scope=contract%20credit_query

六、安全与传输 ​

  • 所有接口必须使用 HTTPS，保证 AppId、密钥在传输过程中被加密。
  • 密钥仅在后端使用，不要在前端或公开代码里暴露。

Copyright © 2024 澄心科技