API:
如何连接
系统

用简单语言理解 API

API 是应用程序编程接口，即一个软件组件与另一个组件交互时遵循的规则。规则说明可以执行哪些操作、需要传递什么数据，以及可能收到什么响应。API 是 Application Programming Interface 的缩写。用户点击应用中的按钮后，程序可以调用 API 来完成相应操作。

假设一个网站接收设备采购咨询。访客填写表单后，网站服务器验证数据，并向 CRM 发出请求：“按这些字段创建一条咨询记录。”CRM 返回记录标识符或错误消息。销售人员不再需要逐条手动录入。但这种数据交换必须经过配置才能工作：CRM 提供 API，并不代表网站已经与它连接。

库、操作系统、浏览器和外部服务都可以提供 API。并非每次 API 调用都通过互联网进行。例如，浏览器会提供操作页面元素的接口。本文主要讨论用于连接网站、CRM、业务管理系统及其他服务的 Web API。浏览器接口与第三方接口的区别，详见MDN 入门指南。

API 请求如何工作

典型的 HTTP 交互包含客户端和服务器：客户端是请求数据或操作的程序，服务器负责接收请求。这里的客户端可能是网站服务器，而非访客的浏览器。同一个系统在不同场景下可以扮演这两种角色。

请求通常包含地址、方法、请求头，以及在需要时包含数据的请求体。某项操作的地址称为端点，即 endpoint。方法用于表明操作类型；请求头可说明数据格式和访问凭据；请求体包含待传输的对象，例如咨询记录的字段。具体需要哪些部分，应以该 API 的文档为准。

地址example.com在这里是占位示例：这只是用于说明原理的结构，不是连接您的 CRM 的命令。即使操作含义相同，不同服务的字段和规则也可能不同。

无需编程，查看真实 API 响应

入门时，可以读取 GitHub 演示仓库的公开信息。这个示例不会创建或修改任何内容。准备本文时，该请求返回了成功响应。服务设有请求频率限制，因此再次请求的结果也取决于当时的访问条件。

1. 在浏览器中打开示例的公开地址。
2. 找到字段full_name：它表示仓库所有者及仓库名称。
3. 查看private：布尔值false表示该仓库不是私有仓库。
4. 比较 API 地址与html_url：后者指向供人浏览的普通网页。

{
  "name": "Hello-World",
  "full_name": "octocat/Hello-World",
  "private": false,
  "html_url": "https://github.com/octocat/Hello-World"
}

这里展示的是精简后的响应片段，而非完整文档。花括号、字段名和值构成 JSON 格式的数据。程序读取指定字段，不需要网页的视觉排版。不要赋予字段排列顺序额外的含义。

如何在 Postman 中查看状态码

在Postman的英文界面中，点击以下按钮新建 HTTP 请求标签页：Add，选择GET，粘贴同一个 URL，然后点击Send。在下方区域检查状态码和响应体。这个公开示例不需要添加公司的密钥等机密信息。按钮和面板位置可能随应用版本变化。

如需进一步使用 GitHub，请阅读官方 REST API 指南：其中介绍了方法、参数、请求头和访问方式。本文示例仅演示读取公开对象，并不证明您的 CRM 或支付系统集成已经配置完成。

REST、JSON、Webhook 与 SDK：哪些概念可以比较

这些术语描述的是方案中的不同部分。JSON 是数据格式，REST 是架构风格，Webhook 是向另一个系统通知事件的机制，SDK 则是可以简化 API 使用的开发工具包。它们并不是互相排斥的选项。

Web API 可以使用 HTTP 和 JSON，但不一定完全遵循 REST 原则。此外还有 SOAP、远程过程调用等方式。对于委托开发的客户，是否提供所需操作、文档和支持，比技术名称是否新潮更重要。相关概览可参阅AWS 的 API 介绍。

定时轮询与事件通知

轮询模式下，集成程序定期询问：“上次检查之后发生了什么变化？”Webhook 模式下，来源系统主动向约定地址发送通知，例如“订单已更新”。这能减少等待和无结果请求，但并不能省去错误处理。

Webhook 可能重复到达，也可能以非预期顺序到达。各服务商的重试投递规则不同。需要验证通知真实性、识别已处理事件，并核对遗漏的变更。例如，GitHub 建议使用 HTTPS、Webhook 密钥并检查投递标识符，具体规则见其官方文档。不要把一个服务的响应时限直接套用到另一个服务。

网站和企业为什么需要 API

先从一项具体的手工操作或数据丢失问题入手。“连接所有系统”并没有定义项目成果。更有效的要求是：“网站上每条已确认的咨询都进入 CRM 中正确的销售流程，包含来源和负责人；未成功传输的咨询可在日志中查看。”

这些只是应用场景，并不保证所选服务支持所有字段。有些产品只在特定套餐中开放 API，或仅通过 API 提供界面的部分功能。前期调研属于以下服务的工作内容：CRM 实施，网站开发以及AI 智能体开发。

文档与需求中需要确认什么

请开发人员展示所需操作的文档，并提供一个小型验证场景。需求中只写“通过 API 集成”，会留下过多解释空间。建议明确以下内容：

• 系统与对象。使用哪个 CRM、哪个网站版本，以及如何定义咨询、订单和客户。
• 传输方向。仅从网站传到 CRM，还是也要反向同步状态。双向交换必须定义冲突处理规则。
• 权威数据源。在哪里修改价格，数据不一致时以哪个系统为准。
• 字段与参考数据。名称映射、必填要求、类型、允许值、币种和时区。
• 交换时机。事件发生后立即执行、定时执行或手动执行，以及允许的延迟。
• 数据量。日常负载、峰值流量及存量记录的首次导出。
• 错误。哪些操作自动重试，哪些错误交由负责人处理，以及如何恢复队列。
• 运行维护。上线后谁负责访问凭据、文档和技术支持。

对于列表响应，要检查分页机制，即将结果拆成多页。成功获取前 100 条记录，并不意味着已导出全部 8000 条。增量同步需要检查点，以及重新获取遗漏时间段的明确方法。具体参数应查阅服务商文档。

API 错误意味着什么

HTTP 状态码描述请求在协议层面的结果。响应正文中的消息与集成日志有助于查明原因。任何状态码都不能单独证明业务流程已正确完成。常见状态码的含义见MDN HTTP 参考文档。

联系技术支持时，请保留带时区的时间、操作、请求标识符、状态码、匿名化示例及预期结果。不要附上正在使用的访问密钥。缺少这些信息时，仅说“偶尔不能用”会延长排查时间。

另一种情况是浏览器因 CORS 而阻止读取响应。这属于跨源访问限制，并不证明所有客户端都无法访问 API。开发人员应检查连接方式。要求访客关闭浏览器保护并不能修复集成。

为什么单次请求成功远远不够

看一个教学示例：CRM 已创建咨询记录，但响应在传输途中丢失。网站检测到超时，再次发送同一条咨询。如果集成程序无法识别重复，销售人员就会看到两条记录。超时仅表示客户端未及时收到响应，并不保证服务器已取消操作。

针对这类情况，需要设计防重复机制：使用稳定的外部标识符、服务所支持的幂等键，或其他约定机制。幂等性是指重复执行同一操作，不会产生超出首次执行的额外效果。随意添加一个名为幂等键的请求头，并不能让第三方 API 自动支持这一特性。

• 重试次数有限制。设置重试间隔、最大尝试次数，并为不可恢复的错误安排单独处理流程。
• 队列持久化保存。进程重启后，未投递事件仍可查看并继续处理。
• 考虑事件顺序。旧状态不能覆盖较新的已确认状态。
• 定期核对记录。对记录进行校验比对，找出未进入常规错误日志的数据遗漏。
• 明确负责人。故障通知应送达了解恢复流程的负责人。

可靠性应在测试环境中通过受控场景验证。无需为了演示而在人们正在使用的网站上人为制造大量错误。对于耗时较长的数据导出，还要单独检查中断后能否继续，以及已完成部分是否会被重复处理。

如何管理密钥与权限

密钥或令牌是访问凭据，并非装饰性配置。权限应与操作相匹配：读取商品目录不一定需要删除订单的权限。应隔离生产与测试环境，记录账户归属，以及更换访问凭据的流程。

服务器端密钥不能放在公开的 JavaScript、HTML、截图或代码仓库中。部分服务专门提供可公开的浏览器密钥；这类密钥只能按服务商规则使用，并配置规定的限制。不能仅因为网站需要某个密钥，就认为它可以安全公开。

有效令牌不能替代对具体对象的权限检查。用户能查看自己的订单，并不意味着可以修改标识符后获取他人的订单。这类访问控制缺陷已被列入OWASP API Security 风险清单。验收时，应要求使用测试账户检查允许和禁止访问的场景。

日志中保留标识符与故障描述通常有帮助；完整客户联系方式及密钥往往并不需要。应约定传输数据的范围、日志访问权限与保存期限。对于 AI 集成，还需单独明确哪些信息可以发送给所选服务商。

如何验收开发人员交付的集成

要求演示一个测试对象的完整流程。以咨询为例，应包括表单提交、网站保存、数据传输、CRM 记录创建及负责人分配。核对目标系统中的字段值。浏览器提示和 HTTP 200 状态都不能代替这项检查。

在测试报告中记录测试对象的具体标识符、日期、结果与未解决问题。项目应提前约定可接受延迟、数据量及恢复时间等量化要求。不存在适用于所有操作的“API 必须在一秒内响应”这一通用标准。

演示后，应取得数据交换说明、启动与恢复操作指南、日志访问权限及支持流程。项目整体交付流程详见网站验收指南。对于网站与 CRM 的连接，还可以参考CRM 实施方案。

上线前需要确认并记录什么

API 常见问题