---
title: 认证与调用约定
description: 说明开放平台的主路径、公共 Header、签名算法、协议约定与安全要求。
sidebar_position: 2
---


# 认证与调用约定

本页聚焦开放平台的通用技术约定。

如已拿到 `appid` 和 `token`，并准备正式发起接口调用，建议先完整阅读本页。

## 当前版本说明

当前对外稳定开放版本为 `2.0`。

本页中的调用主路径、签名规则和 Header 约定，均以 `2.0` 为默认前提。

## 调用方式概览

平台基于 HTTP 协议提供接口服务，基础调用流程为：

1. 根据接口文档准备参数
2. 生成签名
3. 拼装 HTTP 请求
4. 发起请求
5. 接收并解析 JSON 响应

调用主路径：

```text
https://medical.nocode.com/open/
```

## 公共 Header

调用任何一个 API 时，都必须在 HTTP Header 中传入以下参数：

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `appid` | string | 是 | 平台分配的应用标识 |
| `sign` | string | 是 | 请求签名结果 |
| `timestamp` | string | 是 | 毫秒级 Unix 时间戳，请求时间戳与服务端当前时间的偏差不得超过 1 分钟 |

建议同时带上：

| 参数 | 是否必填 | 说明 |
| --- | --- | --- |
| `Content-Type: application/json` | 视接口而定 | `POST` 接口通常需要 |
| `X-Request-ID` | 否 | 建议传入 UUID，便于双方排查问题 |

## 签名算法

平台采用 `appid + token + timestamp` 的组合签名方式。

签名算法：

```text
sign = lowercase(MD5(appid + token + timestamp))
```

示例：

```text
appid: ENHmKoxq97i4eRHn
token: LUZa2HfaxoLkAbgVc3BfNMzG6EaGJHvr
timestamp: 1561952337000
sign: 323fa1f3c22ea7e0fb4886513205dd87
```

## 协议约定

- 协议：`HTTPS`
- 返回格式：`JSON`
- 鉴权信息通过 HTTP Header 传递
- 建议在服务端统一封装签名逻辑，不要散落在多个调用点

调用失败时，平台通常返回 HTTP `400` 和结构化错误对象。  
不同接口或历史版本中，`message` 可能返回英文或中文提示，建议结合错误码一起处理：

```json
{
  "error": {
    "code": 400108,
    "message": "Invalid request parameters"
  }
}
```

## 安全要求

1. 不要将 `appid`、`token` 和签名逻辑直接暴露给前端页面
2. 应通过服务端或受控中间层发起平台请求
3. 应始终使用 `HTTPS`
4. 建议保留请求日志、错误码和 `X-Request-ID` 便于排查

## 常见错误码

接入初期最常见的是下面几类：

| 错误码 | 英文提示 | 中文说明 |
| --- | --- | --- |
| `400101` | Signature verification failed | 签名校验未通过 |
| `400102` | Timestamp expired | 时间戳已过期 |
| `400103` | Missing timestamp | 未提供时间戳 |
| `400104` | Invalid appid | appid 无效 |
| `400105` | Invalid timestamp | 时间戳格式无效 |
| `400108` | Invalid request parameters | 请求参数有误 |
| `400109` | Internal system error | 系统异常 |
| `400110` | No API permission | 当前无接口调用权限 |
| `400111` | Data not found | 未找到对应数据 |
| `400112` | Daily call quota exceeded | 已超过当日调用上限 |
| `400113` | Request rate limit exceeded | 请求过于频繁，请稍后再试 |
| `400114` | Invalid request source | 调用来源校验未通过 |
| `400115` | Insufficient balance | 账户余额不足 |
| `400116` | Outside authorization validity period | 授权未生效或已过期 |

如需完整理解授权、配额和上线边界，建议继续阅读 [平台规则总览](/doc/platform-rules/platform-rules-overview)。

## 下一步建议

- 还没有完成整体接入规划：阅读 [快速开始与接入流程](/doc/getting-started/quick-start-and-integration-flow)
- 准备直接发起请求：阅读 [请求示例与调试](/doc/getting-started/request-examples-and-debugging)