1. 基本概念

1.1 API 概述

📌

API 调用适用于按需获取数据、执行特定操作和主动查询系统状态的场景。例如：

某业务系统需要定期同步新核云中的生产计划用料数据，则可以调用查询计划用料 API。

某生产企业需要拉取最新的物料出入库记录，确保与企业ERP系统的基础数据一致，则可以调用查询生产备料出库任务 API、查询生产还料入库任务 API 等。

某外部审核流程需要在特定节点更新生产单状态，则可以调用更新生产单 API，主动将状态修改为“已审核”或“已驳回”，从而驱动业务流程向下流转。

同时，新核云开放平台提供了基于生产单创建信息的实时同步与自动化记录的业务场景的快速搭建教程，让您快速上手事件订阅、API调用与飞书工作流集成，实时更新生产单数据并生成数据看板，丝滑对接多个系统。

1.2 APP Key & APP Secret

💡

APP Key & APP Secret 是由新核云开放平台提供，使第三方得以访问新核云数据的凭证。可以把 APP Key & APP Secret 简单理解为你的应用在新核云平台的 “身份证” 和 “密码”。

APP Key

你的应用在新核云平台的唯一身份标识，相当于你的用户名或账号。

公开的：可以配置在代码或配置文件中，用于标识是哪个应用在调用API。

不变的：创建应用后生成，通常不会改变。

APP Secret

用来验证你应用身份的密码。APP Key 针对单一租户空间，暂不支持一个 APP Key 对多个租户空间。租户空间表示新核云 SAAS 平台单一组织数据集合。

高度保密的：必须像保护密码一样保护它，避免泄露或公开到前端代码、GitHub等公开地方。

核心作用：它与APP Key一起，通过平台的认证API来换取每次调用API时必须使用的访问凭证（Access Token）。

APP Secret 代表了你的应用的所有权限，一旦泄露，他人就可以冒充你的应用访问或操作数据。建议将其存储在服务器端等安全环境，避免在前端网页、移动App等客户端直接使用。

1.3 访问凭证（Access Token）

🧷

为了提升 API 调用的安全性，新核云开放平台设计了访问凭证（Access Token）机制。

访问凭证是将应用获得的所有数据访问和接口调用权限绑定在一起，在权限范围内允许应用对相关数据进行读写操作。

调用 API 获取应用资源时，需要通过访问凭证（Access Token）对调用者身份进行鉴权，即告知新核云当前是谁、以什么身份获取什么租户的什么数据。调用 API 时，必须在 HTTP Header 的Authorization 字段中携带该访问凭证，以便获取权限范围内的资源信息。

🚪

新核云平台提供两种类型的 Access Token，以满足不同的集成场景需求：

标准 Access Token（推荐）
这是最常用且安全性更高的方式。通过调用新核云认证 API，使用 APP Key 和 APP Secret 换取。

特性：具有较短的有效期，到期后需使用 Refresh Token 重新获取。

优点：遵循 OAuth 2.0 最佳实践，即使 Token 意外泄露，其风险窗口期也较短。

适用场景：适用于由服务器端发起的、有稳定后端服务的常规集成项目。

永久 Access Token
一种简化集成的凭证，可在开放平台控制台中手动创建。

特性：有效期极长或永久（除非手动撤销），无需通过 API 定期刷新。

优点：配置简单，无需实现复杂的 Token 生命周期管理代码。

注意事项：一旦泄露，风险极大，因为攻击者可能长期持有该凭证进行非法操作。必须像保护 APP Secret 一样严格保管。

适用场景：主要用于内部、高度可信的环境，或用于调试、测试以及某些无法实现 Token 刷新流程的特定 Legacy 系统。不建议在生产环境中轻易使用。

选择建议：
出于安全考虑，强烈建议优先使用标准的、有有效期的 Access Token。仅在充分评估安全风险后，且确有必要时才考虑使用永久 Token。无论使用哪种 Token，都必须通过 HTTPS 发起请求，并确保凭证的存储安全。

永久 Access Token 代表了您应用的所有权限。请勿将其嵌入前端代码、客户端应用程序或公开的仓库中。建议将其存储在安全的服务器环境或配置管理系统中，并定期审计其使用情况。

1.4 刷新凭证（Refresh Token）

📌

使用 APP Key & APP Secret 调用新核云认证 API 的相关接口，可以获取调用其他接口的访问凭证（Access Token）和刷新凭证（Refresh Token）。

访问凭证（Access Token）在下发的时候，会有一个过期时间，过期后访问凭证即失效。

在下发访问凭证（Access Token）的同时，新核云会提供刷新凭证（Refresh Token），用于在访问凭证失效后重新获得。注意刷新凭证（Refresh Token）也有过期时间，如果刷新凭证也过期了，需要通过 APP Key & APP Secret 重新获取。

1.5 流程图

2. API 调用规范与参数

2.1 获取访问凭证（认证 API）

2.1.1 请求示例

{
    "body": {
        "appKey": "123344sasdasd",
        "appSecret": "!asdDAsdsdFj7aaa]PX@"
    }
}

2.1.2 响应示例

{
  "code": 0,
  "message": "",
  "data": {
    "entity": {
      "accessToken":"eyJhbGciOiJIUzI1NiJ9.eyJ0ZW5hbnRJZCI6ImE5AAAAmUyLTlkNmEtNDkwNS1iZWQyLTQwMDg0OGJkMzM0OCIsImlzcyI6Im9wZW4tYXBpIiwiZXhwIjoxNzE5NDUzODk0LCJpYXQiOjE3MTk0NDY2OTQsInN0YWZmSWQiOiIxMDAwMTQ2NSJ9.a-ZAfOpIDSFx45UR3x2TfLQmCYZvGkeq9-iBP8ZvBO8",
      "accessTokenExpireIn": 7200,
      "refreshToken": "eyJhbGciOiJIUzI1NiJ9.eyJ0ZW5hbnRJZCI6ImE5NGRlYmUyAcsbadaNDkwNS1iZWQyLTQwMDg0OGJkMzM0OCIsImlzcyI6Im9wZW4tYXBpIiwiZXhwIjoxNzIyMDM1Mjk0LCJpYXQiOjE3MTk0NDY2OTR9.xyz789abc456def123ghi0",
      "refreshTokenExpireIn": 2592000
    }
  }
}

生成 Token 和刷新 Token 的接口有访问频率限制，如果调用频繁，会被禁用掉。所以这里开发者要根据 Token 的过期时间来控制好 Token 的生成或者刷新机制。

2.2 API请求规范

2.2.1 基础URL

新核云开放平台提供的 API 遵循 RESTful 风格，请求 URL 的格式如下：

2.2.2 通用 HTTP Headers 结构

🔖 Authorization（必需）: Bearer<access_token>

调用 API 时，需要将访问凭证（Access Token）放入请求 Header 中，并申明『Bearer』类型。参考用法：

curl '<http://c2.xinheyun.com/api/open/v2/items/query>' \\
  -H 'Connection: keep-alive' \\
  -H 'Accept: application/json, text/plain, */*' \\
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJ0ZW5hbnRJZCI6ImE5AAAABBccddLTlkNmEtNDkwNS1iZWQyLTQwMDg0OGJkMzM0OCIsImlzcyI6Im9wZW4tYXBpIiwiZXhwIjoxNTk5NDUzODk0LCJpYXQiOjE1OTk0NDY2OTQsInN0YWZmSWQillIxMDAwMTQ2NSJ9.a-ZAfOpIDSFx45UR3x2TfLQmCYZvGkeq9-iBP8ZvBO8'
  --data-binary '{"name":"","start":0,"length":10000}' \\
  --compressed \\
  --insecure

🔖 Content-Type（必需）：

2.2.3 通用请求体结构

2.2.4 请求代码示例 (查询生产单工序 API)

2.2.5 频控策略 (Rate Limiting)

为确保平台稳定性和资源公平使用，新核云开放平台对 API 调用实施以下频次控制策略：

控制维度	限制阈值	等效频率	规则说明
日调用总量	86,400 次/24小时	平均每秒 1 次	24小时滚动窗口计算
分钟级并发	600 次/分钟	平均每秒 10 次	1分钟滚动窗口计算

📌

规则关系说明：上述两项限制为同时生效（逻辑与关系）。即使未超过日调用总量限制，但分钟级并发超限同样会触发流控。

分钟级限流触发：当某分钟内调用次数超过 600 次时，服务将暂时受限。

恢复条件：等待最近一分钟内的调用次数回落至 600 次以下（滚动计算）。

日调用量限流触发：当 24 小时内累计调用次数超过 86,400 次时，服务将暂停。

恢复条件：等待最近 24 小时内的调用次数回落至限额以下（滚动计算）。

💡

最佳实践建议：

实施请求队列和指数退避重试机制，避免瞬时高峰触发限流。

针对非实时需求的数据获取，可采用批量查询接口减少调用次数。

重要业务功能建议实现本地缓存机制，降低重复 API 调用。

请注意：限流计数采用滚动窗口算法，不会在固定整点（如每日零点或每分钟开始时）重置。请根据实际业务需求合理规划 API 调用节奏。

2.2.6 IP白名单

🔒

为了进一步增强 API 调用的安全性，新核云开放平台提供了 IP 白名单功能。此功能允许您限制只有来自特定 IP 地址的请求才能访问您的应用 API，有效防止未经授权的访问和潜在的攻击。

📌

功能特点

访问控制：仅允许预设 IP 地址或地址段发起 API 请求。

灵活配置：支持 IPv4/IPv6 地址，可使用 CIDR 表示法配置 IP 段（如：192.168.1.0/24）。

多地址支持：可同时配置多个 IP 地址或网段，满足复杂网络环境需求。

配置方法

登录新核云开放平台，进入应用列表，查看路径：开放平台 → API → OAuth 客户端。

配置 IP 白名单

您可以在新建应用时找到 IP 白名单设置项，也可以为应用列表中的已有应用编辑配置。

添加 IP 地址

添加需要允许访问的 IP 地址或网段，格式示例：192.168.1.1,192.168.1.2，中间用逗号分隔。

保存配置后立即生效

📍

注意事项

启用 IP 白名单后，只有列表中的 IP 地址可以调用 API

如果配置为空，则允许所有 IP 地址访问（不推荐）

建议将您的工作服务器、内部网络段以及可信的第三方服务 IP 加入白名单

配置变更后，现有访问凭证不会立即失效，但来自非白名单 IP 的请求将被拒绝

错误响应

当请求来自未授权的 IP 地址时，API 将返回 401 Forbidden 错误：

{
  "code": 401,
  "message": "IP address not in whitelist",
  "data": null
}

重要： 在启用 IP 白名单前，请确保已将您自己的服务器 IP 地址添加到白名单中，否则可能导致服务中断。建议先在测试环境验证配置，再应用到生产环境。

对于动态 IP 或云服务器环境，可以考虑使用域名而非固定 IP，但需确保域名解析的 IP 范围在可控范围内，或使用网络代理层进行集中访问控制。

3. 错误处理与调试

3.1 通用HTTP错误码

错误码	含义	注意事项
200	请求成功，服务器正常返回数据	需检查响应具体内容是否符合预期（如数据完整性、格式正确性); 部分 API 可能返回 200 但附带警告信息（如部分字段缺失）
401	权限不足，请求被拒绝	常见原因：认证信息无效（如过期 Token、错误 API Secret）；用户角色无权限访问目标资源; IP 白名单限制。处理建议：检查访问凭据状态; 认用户权限范围（如是否为管理员）; 请联系新核云技术人员。
403	禁止访问，请求被服务器拒绝	常见原因：应用权限不足（如未授权访问该API）；资源操作越权（如普通用户尝试管理员操作）； APP Key/Secret 验证失败；访问频率超限。处理建议：检查应用权限配置；确认请求参数和身份凭证正确性；降低调用频率或申请更高配额；联系管理员调整权限范围。
404	请求的资源不存在	常见原因： URL 路径拼写错误资源已被删除；未正确初始化资源（如未创建对应 ID 的记录）。处理建议：检查请求的 URL 路径和参数；确认资源 ID 是否存在（如先调用 GET /users 获取列表）；对客户端输入进行校验（如 UUID 格式）。
500	服务器内部错误（非客户端责任）	常见原因：服务端代码异常（如空指针、数据库死锁）；依赖服务不可用（如支付网关故障）；超时或资源耗尽。处理建议：请联系新核云技术人员。

3.2 调试技巧：查看API调用日志

查看路径：开放平台 → API → OAuth 客户端，找到需要查看的API应用，点击详情按钮查看API调用日志

4. 获取帮助

访问新核云社区——开放平台提问

API 参考

1. 基本概念#

1.1 API 概述#

1.2 APP Key & APP Secret #

APP Key#

APP Secret#

1.3 访问凭证（Access Token）#

1.4 刷新凭证（Refresh Token）#

1.5 流程图#

2. API 调用规范与参数#

2.1 获取访问凭证（认证 API）#

2.1.1 请求示例#

2.1.2 响应示例#

2.2 API请求规范#

2.2.1 基础URL#

2.2.2 通用 HTTP Headers 结构#

2.2.3 通用请求体结构#

2.2.4 请求代码示例 (查询生产单工序 API)#

2.2.5 频控策略 (Rate Limiting)#

2.2.6 IP白名单#

功能特点#

配置方法#

注意事项#

错误响应#

3. 错误处理与调试#

3.1 通用HTTP错误码#

3.2 调试技巧：查看API调用日志#

4. 获取帮助#