---
title: 快速开始与接入流程
description: 说明从试调到上线的接入步骤、验收要点与推荐阅读顺序。
sidebar_position: 1
---


# 快速开始与接入流程

本页用于说明接入准备项、最小试调路径和标准推进流程，适合首次接入开放平台的产品经理、技术负责人和实施人员。

如已确定具体能力范围，建议先完成本页最小试调，再进入对应接口目录开展批量联调。

## 当前版本与主路径

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

本页中的调用示例和验收建议均基于 `2.0`。

调用主路径：

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

## 接入前准备

建议在联调前完成以下准备：

1. 明确业务目标和优先接口
2. 确认待开通接口范围和配额预期
3. 准备服务端调用环境，不直接由前端页面发起平台请求
4. 获取接入凭证，包括 `appid`、`token` 和开通结果说明

## 最小试调流程

建议先以单接口完成一次最小流程验证，再进入批量联调。

### 1. 选择基础接口

优先选择入参较少、返回结构稳定的接口，例如药品详情或基础查询接口。

本步骤的目标是验证网络连通、签名正确性、权限状态和返回结构解析能力。

### 2. 生成公共 Header

所有接口都需要在 Header 中携带以下参数：

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

签名算法：

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

注意事项：

- Header 字段名使用 `appid`，不要写成 `app_id`
- 参与签名计算的 `timestamp` 必须与请求头中的 `timestamp` 完全一致
- 每次发起请求都应重新生成 `timestamp` 和 `sign`

可直接执行的签名生成示例：

```bash
APP_ID='REPLACE_YOUR_APP_ID'
TOKEN='REPLACE_YOUR_TOKEN'
TIMESTAMP=$(python -c 'import time; print(int(time.time()*1000))')
SIGN=$(python - <<'PY'
import hashlib, os
print(hashlib.md5(f"{os.environ['APP_ID']}{os.environ['TOKEN']}{os.environ['TIMESTAMP']}".encode()).hexdigest())
PY
)
```

建议同时传入：

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

### 3. 发起最小请求

```bash
curl -X GET \
  'https://medical.nocode.com/open/v2/nc.ms.drug.package.detail?drug_package_id=REPLACE_DRUG_PACKAGE_ID' \
  -H 'appid: REPLACE_WITH_YOUR_APPID' \
  -H 'sign: REPLACE_YOUR_SIGN' \
  -H 'timestamp: REPLACE_YOUR_TIMESTAMP' \
  -H 'X-Request-ID: REPLACE_YOUR_UUID'
```

其中 `REPLACE_YOUR_SIGN` 对应上一步脚本生成的 `SIGN` 变量值。

如需优先联调智能接口，可替换为 `POST /v2/nc.ms.smart.department.recommend`。

### 4. 判定结果并定位问题

成功响应通常返回：

```json
{
  "data": {}
}
```

若调用失败，通常会返回类似下面的结构。  
不同接口或历史版本中，`message` 可能是英文或中文：

```json
{
  "error": {
    "code": 400110,
    "message": "No API permission"
  }
}
```

接入初期常见错误：

- `400101 Signature verification failed / 签名校验未通过`
- `400102 Timestamp expired / 时间戳已过期`，`400105 Invalid timestamp / 时间戳格式无效`
- `400110 No API permission / 当前无接口调用权限`
- `400112 Daily call quota exceeded / 已超过当日调用上限`，`400113 Request rate limit exceeded / 请求过于频繁，请稍后再试`
- `400115 Insufficient balance / 账户余额不足`
- `400116 Outside authorization validity period / 授权未生效或已过期`

## 标准接入流程

最小试调通过后，建议按以下顺序推进。

### 1. 需求确认

确认接口范围、调用量预期、回调需求、批量处理需求和验收口径。

### 2. 开通与权限配置

根据合作范围完成接口权限开通。

如涉及药品对码、异步任务或高调用量，通常需要额外配置。

### 3. 联调

联调阶段建议重点核对以下事项：

- 请求头和签名规则是否统一
- 分页、批量和限流逻辑是否符合预期
- 错误码处理是否完整
- 回调、重试和幂等策略是否满足业务要求

### 4. 验收

上线前建议完成以下验收项：

- 核心接口有效响应率达到预期
- 关键字段完成映射与落库
- 主要错误码具备明确处理逻辑
- 数据口径与字段含义已完成业务确认
- 日志可追踪 `X-Request-ID` 或内部请求流水

### 5. 上线

建议先采用受控流量发布，并持续观察：

- 有效响应率
- 配额消耗
- 关键接口延迟
- 字段解析异常

## 按阶段继续阅读

- 了解平台整体能力：阅读 [平台介绍](/doc/intro)
- 核对认证与调用规则：阅读 [认证与调用约定](/doc/getting-started/authentication-and-calling-conventions)
- 开始联调与调试：阅读 [请求示例与调试](/doc/getting-started/request-examples-and-debugging)
- 确认权限、配额和边界：阅读 [平台规则总览](/doc/platform-rules/platform-rules-overview)
- 评估版本升级影响：阅读 [版本与变更策略](/doc/platform-rules/version-and-change-policy)