版本: v1.0 修改日期: 2026-05-29 文档定位：本手册面向项目经理，只讲”该做什么、向厂家要什么、怎么判断资料齐了”。技术细节由技术团队负责。
完成后你将能够：明确开发边界、向厂家收齐接口资料，通过提资入口提交，技术团队即可开始配置。
阅读路径：确认适用场景（第 1 节）→ 明确开发边界（第 3 节）→ 收资料（第 4 节）→ 自查提交（第 7 节）。
1 确认是否走本手册
1.1 适用场景
满足以下任一条件，走本手册：
- 客户已有自研软件（如能源管理平台、ERP、SCADA 上位机），要把数据共享给我方
- 厂家提供”接口文档”或”API 文档”
- 对方答复”我们提供 RESTful 接口”或”我们有 Web Service”
1.2 不走本手册的情况
| 现场情况 | 应走方式 |
|---|---|
| 直接连接现场硬件设备（PLC、电表、变频器） | S7 / Modbus / OPC UA 对接 |
| 设备主动推送物联数据 | MQTT 对接 |
| 大批量、流式数据 | Kafka 对接 |
2 术语速览
| 术语 | 通俗解释 | 类比 |
|---|---|---|
| HTTP / HTTPS | 网页、App、系统之间最常用的”网络通信方式”；HTTPS 是加密版本 | 普通快递 vs. 加密快递 |
| 接口（API） | 对方系统对外开放的”窗口”，我方按规则去取数据或下指令 | 银行的业务窗口 |
| 接口文档 | 详细说明每个窗口怎么用、要带什么资料、会返回什么 | 业务办理指南 |
| Base Path | 接口的”基础路径”，所有接口共用的前缀（如 /api/v1） | 大楼地址 |
| 请求方法 | GET（取数据）、POST（提交）、PUT（更新）、DELETE（删除） | 业务种类 |
| 鉴权 | 证明”我是合法调用方”的过程 | 进门刷工卡 |
| Token | 鉴权后拿到的”临时通行证”，有有效期，过期要换新 | 临时访客证 |
| Header / 请求头 | 每次请求附带的”信封信息”，鉴权信息常放在这里 | 快递面单 |
| Body / 请求体 | 请求中真正的”内容”，通常是 JSON 格式 | 快递箱里的东西 |
| JSON | 一种通用的数据格式，长得像 {"温度": 25.6} | 通用记录格式 |
| QPS | 每秒最多允许调用几次接口 | 窗口每秒能办几个号 |
| 测试环境 / 生产环境 | 测试环境用于联调验证；生产环境是真实业务环境 | 排练场 vs. 正式演出 |
💡 鉴权常见方式速查
方式 通俗说明 现场常见度 无鉴权 任何人都能调，通常仅限内网 少 Basic 用户名密码 base64 编码 中 Bearer Token 在 Header 里带一个长串令牌 最常见 AppKey + Sign App 标识 + 用密钥算出来的签名 多见于大平台
3 对接前必须明确：开发边界由谁负责
这是 HTTP 对接最容易踩坑的环节。两种模式必选其一，不能含糊：
3.1 模式 A：由我方按对方协议开发（最常见）
- 对方已有平台和接口，我方写程序去”调用”对方接口。
- 对方需提供：完整接口文档 + 鉴权凭证 + 点表。
3.2 模式 B：由对方按我方规范接入
- 对方按我方平台规范向我方接口推送数据。
- 我方需提供：viSCADA 南向 HTTP 规范 + 接口地址 + 凭证。
⚠️ 项目经理须向客户或厂家确认模式后，后期不修改方案或者对接协议。
4 资料清单（可直接发给厂家）
📌 提交命名格式：项目名-HTTP-接口清单
📎 若由对方按我方规范接入（模式 B），请附：viSCADA 南向 HTTP 规范
以下资料均为必填，缺一不可：
- 开发边界（模式 A 还是模式 B，书面确认）
- 接口文档（含版本号）——模式 A 必填
- 协议、域名 / IP、端口、Base Path（测试与生产环境分别提供）
- 鉴权方式与传参规则（类型、位置、字段格式）
- Token 获取方式与刷新规则——有鉴权时必填
- 完整点表（含字段名、数据类型、时间戳字段与时区、读写属性）
- 时间戳字段名与格式（含时区，如
UTC+8） - 接口频率限制（QPS）——超出限制将返回 429 错误，必须提前明确
5 操作步骤
步骤 1：向客户或厂家确认开发边界
参考第 3 节。任何对接细节都要在边界明确之后才能谈，否则双方人员都可能做无效工作。
步骤 2：索要正式接口文档（模式 A）
⚠️ 不接受以下形式：
- 口头描述或微信截图
- 没有版本号的草稿文档
文档必须包含：每个接口的 URL、请求方法、请求参数、返回示例、错误码说明。
步骤 3：把鉴权细节写清楚
鉴权是 HTTP 联调失败率最高的环节。要求厂家逐项书面说明：
- 类型：Bearer / Basic / AppKey+Sign / 其他
- 传递位置：放在 Header / Query / Body 哪一处
- 字段名格式：如
Authorization: Bearer <token>（注意大小写） - Token 获取与刷新：从哪个接口换 Token、有效期多久、过期怎么刷新
步骤 4：核查点表完整性
完整点表必须包含五项，缺一不可：字段名（英文键名）、数据类型、时间戳字段名、时区、读写属性。
步骤 5：测试和生产环境分别索取
测试环境与生产环境通常是完全不同的两套地址、账号、Token。两套都要拿，联调结束切换到生产时不至于卡壳。
6 资料收集表
| 分类 | 字段 | 是否必填 | 填写要求 |
|---|---|---|---|
| 接口资料 | 开发边界 | 必填 | 明确”我方按对方协议开发”或”对方按我方规范接入” |
| 接口资料 | 接口文档 | 模式 A 必填 | 注明版本号、更新时间 |
| 访问地址 | 协议 / 域名或 IP / 端口 / Base Path | 必填 | 区分测试与生产环境，如 https://api.example.com:443/api/v1 |
| 鉴权 | 鉴权类型 | 必填 | Bearer / Basic / AppKey+Sign / 无鉴权 |
| 鉴权 | 传递位置与字段格式 | 必填 | 如 Header: Authorization: Bearer <token> |
| 鉴权 | Token 获取与刷新规则 | 有鉴权时必填 | 含获取接口路径、有效期、刷新方式 |
| 点表 | 完整点表 | 必填 | 优先提供可编辑 Excel，其他格式可接受，但内容须清晰准确；含字段名、数据类型、时间戳字段与时区、读写属性 |
| 性能 | 接口频率限制（QPS） | 必填 | 每秒最多支持多少次请求？ |
7 提交前自查清单
- 已书面确认开发边界（模式 A 或模式 B）
- 模式 A 已获取带版本号的正式接口文档
- 模式 B 已发送 viSCADA 南向 HTTP 规范 给对方
- 已明确鉴权类型、传递位置、字段名格式
- 已确认 Token 的获取接口、有效期、刷新规则
- 已获取完整点表（含字段名、数据类型、时间戳字段与时区）
- 已确认时间戳的字段名、格式、时区
- 已分别获取测试环境与生产环境的地址与凭证
- 已完成 网络连通性 验证
- 已通过 统一提资入口 提交资料
- 已在泛微系统发起技术服务流程
8 常见问题与处置
⚠️ 只给接口地址，不给文档
- 后果：一个 URL 不构成可对接的资料，技术团队无法判断参数、返回值、错误码，无法开始开发。
- 处置：退回要求提供完整接口文档，注明版本号；不接受截图或口头描述。
⚠️ 鉴权信息只说半句
- 后果：比如只说”用 Bearer 鉴权”，不说字段名、不说放哪里、不说 Token 怎么换——联调时每个细节都要来回沟通，严重影响进度。
- 处置：要求厂家填写鉴权四要素：类型、传递位置、字段格式、Token 规则，缺一不可。
⚠️ 时间戳缺时区
- 后果：这是数据”差 8 小时”的头号原因。
2026-04-13 10:30:00到底是北京时间还是 UTC，双方理解不同，数据时序全乱。- 处置：要求时间戳字段必须注明时区（如
UTC+8）；推荐使用带时区的 ISO 8601 格式，如2026-04-13T10:30:00+08:00。
⚠️ 接口文档版本未锁定
- 后果：对方中途修改文档而不通知，我方按旧版本开发完后联调失败，返工代价极大。
- 处置：要求文档必须标注版本号，任何变更必须主动通知我方。
⚠️ 未提前确认频率限制（QPS）
- 后果：采集程序超出接口限流，返回
429 Too Many Requests，数据采集中断。- 处置：提资时明确：“接口每秒最多能调多少次？“并在点表中标注各接口的采集频率。
⚠️ 测试联调通过，生产环境断了
- 后果：两套环境地址变了、鉴权变了、Token 换了，甚至字段名微调，全部按测试环境配置的参数在生产上全部失效。
- 处置：测试环境与生产环境从一开始就分别索取，不能等联调完成后再补。
⚠️ HTTPS 证书校验失败
- 后果：部分客户使用自签名证书，我方调用时因证书不受信任而连接被拒。
- 处置：提资时确认：“贵方接口是否使用受信任 CA 签发的证书？“如使用自签名证书，需提前协商处理方式。
9 遇到问题的三步处置
- 先排查：网络未通、文档不全、鉴权信息不完整——三类问题覆盖 80% 的卡点。
- 对照清单：参考第 4 节资料清单，逐项确认是否到位。
- 同步技术团队：将已收集资料、网络测试结果、接口调用截图（含返回值）、当前卡点整理后一并发送，避免反复沟通。
10 关联资料
- 🔗 viSCADA 南向 HTTP 规范
- 🔗 网络连通性验证指引
- 🔗 统一提资入口（钉钉文档）
Last updated on