OnCallBox 开放 API

1. 概述

openapi是OnCallBox的对外开放API，面向外部系统提供只读查询和少量受控写操作能力。当前开放的资源包括：

工单（Incident）

业务（Service）

团队（Team）

告警（Alert）

事件（Event）

值班表（Schedule）

响应策略（Escalation）

成员（Member）

接口统一挂载在 /api/* 路径下，所有接口都需要进行签名认证。

2. 基本约定

2.1 服务地址

线上地址：https://api.oncallbox.com

请求路径：/api/xxx/query

2.2 数据范围

开放 API 的数据权限由 client_key 绑定的租户决定。调用方不需要显式传租户 ID，服务端会根据 API Client 自动注入租户上下文。

2.3 响应包装

接口统一返回 BaseResponse 风格 JSON，结构可按如下理解：

{
  "code": 0,
  "msg": "OK",
  "data": {}
}

常见含义：

code = 0：成功

code != 0：失败

msg：错误信息或提示信息

data：实际业务返回

签名认证失败时，HTTP 状态码为 401，响应体类似：

{
  "code": 401,
  "msg": "invalid sign",
  "data": null
}

3. 认证与签名

3.1 认证字段

服务端识别以下认证字段：

X-Client-Key

X-Timestamp

X-Sign

统一使用 Header 传递认证字段。

3.2 时间戳

格式：Unix 时间戳，单位秒

有效时间窗：5分钟

3.3 签名算法

签名算法为：

HMAC-SHA256

输出格式：十六进制小写字符串

签名原文：

HTTP_METHOD
REQUEST_PATH
RAW_QUERY
TIMESTAMP
[BODY_SHA256_HEX]

说明：

HTTP_METHOD：如 GET、POST

REQUEST_PATH：如 /api/incident/get

RAW_QUERY：原始查询串，不做自动重排

TIMESTAMP：认证时间戳

BODY_SHA256_HEX：仅 POST/PUT/PATCH 参与；即使请求体为空，也会拼接 body 的 SHA256

3.4 签名示例

签名参考代码如下：

3.5 Header 传参示例

3.6 Query 传参说明

虽然示例脚本演示了 Query 方式，但当前服务端使用 r.URL.RawQuery 直接参与签名计算。为避免 Query 参数顺序、签名参数是否参与签名等歧义，接入时请优先使用 Header 方式。

4. 调用约定

4.1 GET 接口

业务参数放在 Query String

认证参数放 Header

4.2 POST 接口

业务参数放 JSON Body

Header 增加 Content-Type: application/json

Body 原始字节内容参与签名

4.3 分页参数

多数查询接口采用：

page：页码，从 1 开始

size：每页条数

5. 常见错误

5.1 认证错误

missing client_key, timestamp or sign

invalid timestamp

timestamp expired or invalid

invalid client_key

api client disabled

api client expired

invalid sign

5.2 业务错误

业务错误由下游 RPC 返回并透传，常见场景包括：

资源不存在

参数格式错误

当前状态不允许操作

角色数量限制，例如账号管理者最多 3 个

使用指南

OnCallBox 开放 API#

1. 概述#

2. 基本约定#

2.1 服务地址#

2.2 数据范围#

2.3 响应包装#

3. 认证与签名#

3.1 认证字段#

3.2 时间戳#

3.3 签名算法#

3.4 签名示例#

3.5 Header 传参示例#

3.6 Query 传参说明#

4. 调用约定#

4.1 GET 接口#

4.2 POST 接口#

4.3 分页参数#

5. 常见错误#

5.1 认证错误#

5.2 业务错误#