开放平台

快速开始与接入

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

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

当前版本与主路径

当前稳定开放版本为 2.0。

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

调用主路径：

plain.txt
https://medical.nocode.com/open/

接入前准备

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

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

最小试调流程

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

1. 选择基础接口

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

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

2. 生成公共 Header

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

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

签名算法：

plain.txt
sign = lowercase(MD5(appid + token + timestamp))

注意事项：

  • Header 字段名使用 appid，不要写成 app_id
  • 参与签名计算的 timestamp 必须与请求头中的 timestamp 完全一致
  • 每次发起请求都应重新生成 timestamp 和 sign
  • 下方脚本中的 APPID_VALUE 只是本地变量名，用于生成签名和拼装请求头

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

terminal.sh
APPID_VALUE='REPLACE_WITH_YOUR_APPID'
TOKEN='REPLACE_YOUR_TOKEN'
TIMESTAMP=$(python3 -c 'import time; print(int(time.time()*1000))')

SIGN=$(APPID_VALUE="$APPID_VALUE" TOKEN="$TOKEN" TIMESTAMP="$TIMESTAMP" python3 - <<'PY'
import hashlib
import os

raw = f"{os.environ['APPID_VALUE']}{os.environ['TOKEN']}{os.environ['TIMESTAMP']}"
print(hashlib.md5(raw.encode()).hexdigest())
PY
)

echo "timestamp=${TIMESTAMP}"
echo "sign=${SIGN}"

建议同时传入：

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

3. 发起最小请求

下面命令默认沿用上一步已经生成的 APPID_VALUE、TIMESTAMP 和 SIGN。

terminal.sh
DRUG_PACKAGE_ID='REPLACE_DRUG_PACKAGE_ID'
REQUEST_ID=$(uuidgen 2>/dev/null || python3 -c 'import uuid; print(uuid.uuid4())')

curl --request GET \
  --url "https://medical.nocode.com/open/v2/nc.ms.drug.package.detail?drug_package_id=${DRUG_PACKAGE_ID}" \
  --header "appid: ${APPID_VALUE}" \
  --header "sign: ${SIGN}" \
  --header "timestamp: ${TIMESTAMP}" \
  --header "X-Request-ID: ${REQUEST_ID}"

其中 SIGN 对应上一步脚本生成的签名值。

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

4. 判定结果并定位问题

成功响应通常返回：

example.json
{
  "data": {}
}

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

example.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. 上线

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

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

按阶段继续阅读