API 监控

快速阅读

API 监控用于观察客户系统调用呼叫中心开放接口的健康状态，帮助实施和技术人员判断接口是否可用、调用是否成功、失败原因是什么、是否存在频次限制或响应耗时异常。

本文的核心结论是：

• API 监控回答“外部系统调用平台接口是否正常”。
• 核心关注调用量、成功率、失败率、响应耗时、错误原因、频次限制和调用方信息。
• API 监控不替代接口文档，也不替代业务话单；它是联调、上线值守和异常排查入口。
• 排查接口问题时，应按“鉴权 -> 参数 -> 频次 -> 业务状态 -> 响应结果 -> 日志/话单核对”的顺序处理。

阅读地图

• 如果只想了解 API 监控是什么，重点阅读“二、产品总览”。
• 如果要设计监控字段，重点阅读“六、产品功能说明”和“附录 B：关键字段口径”。
• 如果要做联调或上线保障，重点阅读“七、典型业务场景”和“附录 C：实施检查清单”。

一、文档说明

1.1 文档目的

呼叫中心通常会向客户 CRM、工单、订单、数据中台或业务系统开放接口。客户系统可能通过 API 查询话单、发起外呼、查询监控、获取录音或同步业务结果。

如果没有 API 监控，接口异常时常见问题包括：

1. 客户不知道请求是否到达平台。
2. 实施无法快速判断失败是鉴权、参数、频次还是业务状态问题。
3. 客户系统和呼叫中心平台之间难以对账。
4. 上线联调时缺少统一的问题定位入口。

本文用于统一说明 API 监控的产品口径和交付建议。

1.2 适用对象

• 客户技术负责人：用于观察客户系统调用是否成功。
• 实施顾问：用于联调、上线值守和异常排查。
• 产品经理：用于设计 API 监控字段和错误提示。
• 运营负责人：用于理解接口失败对业务流程的影响。

1.3 文档范围

本文覆盖开放接口调用监控，不覆盖具体接口文档、接口签名算法细节、客户系统代码实现和内部接口链路。

二、产品总览

2.1 API 监控是什么

API 监控是面向外部接口调用的健康监控能力。它记录或汇总客户系统调用平台开放接口的请求时间、接口类型、调用结果、失败原因、响应耗时和调用频次，帮助技术和实施快速判断对接是否正常。

人话总结：

API 监控让客户和实施知道“接口有没有被调用、有没有成功、为什么失败”。

2.2 主要解决的问题

• 客户系统是否成功调用接口。
• 接口失败是鉴权问题、参数问题、频次限制还是业务状态问题。
• 某段时间接口失败是否集中发生。
• 接口响应是否变慢。
• 客户系统是否超频调用。
• 接口调用是否能与话单、任务、录音或业务记录对上。

2.3 页面定位

API 监控属于技术对接健康监控。它适合联调、上线值守和异常排查，不适合作为客户业务结果的唯一依据。

三、核心概念

3.1 开放接口

开放接口是平台面向客户系统提供的标准能力入口，例如查询记录、发起外呼、查询监控、获取录音、同步业务结果等。

3.2 调用结果

调用结果表示请求是否成功处理。失败时应尽量展示客户可理解的失败类型，例如鉴权失败、参数错误、频次限制、资源不存在、业务状态不允许等。

3.3 响应耗时

响应耗时表示接口从接收请求到返回结果的时间。耗时异常可能来自平台处理、客户网络、数据量过大或查询条件不合理。

3.4 频次限制

频次限制用于保护平台稳定性。接口调用超过约定频率时，可能触发限制或失败提示。

3.5 请求标识

请求标识用于定位一次接口调用。实施排障时可通过请求时间、接口名称、调用方、业务标识和请求标识关联日志或业务记录。

四、对象关系与数据流

客户系统发起 API 调用
↓
平台进行鉴权、参数校验、频次校验和业务处理
↓
返回成功或失败结果
↓
API 监控记录调用状态、耗时和错误原因
↓
结合话单、任务、录音、日志或客户系统记录排障

API 监控只说明接口调用过程，不直接代表最终业务一定成功。例如发起外呼接口调用成功，只代表请求被平台受理，后续外呼是否接通仍需看通话记录和话单。

五、能力地图

六、产品功能说明

6.1 概览指标

建议展示：

6.2 明细字段

建议展示：

• 请求时间。
• 接口名称或接口类型。
• 调用方标识。
• 请求结果。
• 失败原因。
• 响应耗时。
• 请求标识。
• 业务标识。
• 通话标识或任务标识。
• 客户侧请求来源。

6.3 筛选条件

常见筛选条件包括：

• 时间范围。
• 接口名称。
• 调用方。
• 请求结果。
• 失败原因。
• 响应耗时范围。
• 业务标识。
• 通话标识。
• 任务标识。

6.4 失败原因分类

建议按客户可理解口径分类：

七、典型业务场景

7.1 客户系统调用失败

实施可按请求时间和接口名称查询 API 监控，先判断请求是否到达平台，再查看失败原因。如果是参数错误，应对照接口文档；如果是频次限制，应调整调用策略。

7.2 发起外呼成功但客户未接到电话

API 监控显示发起外呼请求成功，只代表平台受理请求。后续是否发起、是否接通、失败原因应继续查看外呼记录、话单和通话日志。

7.3 接口响应变慢

技术负责人可按接口名称查看平均耗时和慢请求，判断是否为查询范围过大、请求集中、客户网络或平台处理压力导致。

7.4 上线联调值守

上线初期可持续观察 API 调用量、失败率和错误原因，及时发现客户签名、参数、时间戳和频次配置问题。

八、上线准备与运营建议

8.1 上线准备

1. 确认客户系统要调用哪些开放接口。
2. 确认鉴权方式、时间戳、签名和权限范围。
3. 确认接口调用频率和限流策略。
4. 确认业务标识、通话标识、任务标识等对账字段。
5. 确认异常时客户和实施双方的排查责任。
6. 准备正向、参数错误、鉴权失败、频次限制等验收用例。

8.2 运营建议

• 联调期重点看失败明细。
• 上线初期重点看失败率和响应耗时。
• 稳定期重点关注异常峰值、频次限制和客户系统变更影响。
• API 调用成功不等于业务最终成功，应结合业务记录继续核对。

九、与周边能力的关系

十、FAQ

10.1 API 调用成功是否代表外呼成功？

不一定。接口成功通常表示请求被平台受理，外呼是否接通需查看通话记录和话单。

10.2 API 监控能看到完整请求内容吗？

是否展示完整请求内容取决于产品权限和脱敏策略。涉及客户号码、密钥或敏感信息时应脱敏。

10.3 为什么会触发频次限制？

可能是客户系统短时间内调用过多，或批量任务没有做节流。应按接口约定调整调用频率。

十一、总结

API 监控是客户系统对接排障的重要入口。它关注接口调用是否健康，但业务最终结果仍需结合话单、任务、录音、报表和客户系统记录核对。

附录 A：入口与权限

附录 B：关键字段口径

附录 C：实施检查清单

• 是否确认接口范围。
• 是否确认鉴权和签名方式。
• 是否确认频次限制。
• 是否验证成功调用。
• 是否验证鉴权失败。
• 是否验证参数错误。
• 是否验证频次限制。
• 是否验证业务标识与话单或任务记录关联。

附录 D：常见问题速查

附录 E：术语表