新核云 Open API 基于当前新核云服务基础设施搭建的对外开放平台。我们致力于给客户和开发者提供稳定可靠的新核云数据访问能力。

1. 流程概述

创建应用：用户可根据业务需要，创建集成应用，并获取该应用的身份证（ APP Key & APP Secret ），注意：APP Key & APP Secret 与应用是一对一关系。
获取访问凭证：用户通过新核云提供的 APP Key 与 APP Secret，获取 API 的访问凭证（ access_token），该凭证在 API 调用过程中用于对调用者身份进行鉴权。
调整 API 权限：不同的 API 有不同的接口权限和字段权限要求，可根据应用的需要调整对应系统用户的权限细节。
调用 API ：根据实际需要完成以上配置步骤后，即可开始调用 API，API 的具体介绍与参数说明可以参考 API 列表。

1.1 创建应用

1.1.1 授权商品：OpenAPI

用户需要先确认已开通以下商品：OpenAPI，查看路径：右上角 → 新核云产品目录 → 已购商品
授权该商品给当前用户

1.1.2 创建应用：获取 APP Key & APP Secret

商品授权成功后，可访问导航菜单：设置 → 开放平台 → 应用，点击新建按钮来创建应用。
输入应用名称，并根据需求维护 webhook 和添加事件，保存后系统会自动生成 APP Key & APP Secret。

1.2 获取访问凭证

1.2.1 访问凭证介绍

为了提升 API 调用的安全性，新核云开放平台设计了访问凭证（access_token）机制。访问凭证是将应用获得的所有数据访问和接口调用权限绑定在一起，在权限范围内允许应用对相关数据进行读写操作。
调用 API 获取应用资源时，需要通过 access_token 对调用者身份进行鉴权，即告知新核云当前是谁、以什么身份获取什么租户的什么数据。调用 API 时，必须在 HTTP Header 中携带该访问凭证，以便获取权限范围内的资源信息。
access_token 在下发的时候，会有一个过期时间（accessTokenExpireIn），过期后 access_token 即失效。在下发 access_token 的同时，新核云会提供 refresh_token，用于在 access_token 失效后，重新获得 access_token。注意 refresh_token也有过期时间（refreshTokenExpireIn），如果 refresh_token 也过期了，需要通过 APP Key 和 APP Secret 重新获取。

1.2.2 访问凭证获取方式

登录新核云系统，查看应用信息，获取系统自动生成的 APP Key 和 APP Secret
- APP Key & APP Secret 是由新核云开放平台提供，使第三方得以访问新核云数据的凭证。APP Key 针对单一租户空间，暂不支持一个 APP Key 对多个租户空间。租户空间表示新核云 SAAS 平台单一组织数据集合。
使用用 APP Key和 APP Secret 调用新核云认证 API 的相关接口，可以获取调用其他接口的 access_token 和 refresh_token。
- access_token 是从新核云获取数据的重要凭证，所有接口访问过程中都需要携带此信息用于验证接口的访问权限。
- refresh_token 是在 access_token 过期之后，重新获取 access_token 的凭证。

1.3 调整 API 权限

不同的 API 有不同的接口权限和字段权限要求，在创建应用的时候，系统会初始化一个与应用名称相同的系统账号，默认分配管理员角色。具体权限细节可以在员工管理详情查看和修改分配角色，在角色管理详情修改功能及数据权限细节。

查看该系统账号详情，确认分配的角色，可根据需要修改分配的角色，路径：设置 → 空间管理 → 成员管理
查看修改角色对应的功能及数据权限，可以根据需要进行修改调整，路径：设置 → 空间管理 → 角色管理

1.4 调用 API

完成创建应用、获取访问凭证、调整完 API 权限之后，才能调用 API。

调用 API 时，需要将访问凭证 access_token 放入请求 Header 中（Authorization:Bearer <access_token>），并申明『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.eyJ0ZW5hbnRJZCI6ImE5NGRlYmUyLTlkNmEtNDkwNS1iZWQyLTQwMDg0OGJkMzM0OCIsImlzcyI6Im9wZW4tYXBpIiwiZXhwIjoxNTk5NDUzODk0LCJpYXQiOjE1OTk0NDY2OTQsInN0YWZmSWQiOiIxMDAwMTQ2NSJ9.a-ZAfOpIDSFx45UR3x2TfLQmCYZvGkeq9-iBP8ZvBO8'
  --data-binary '{"name":"","start":0,"length":10000}' \\
  --compressed \\
  --insecure

调用服务端 API 时，需要使用 HTTPS 协议、UTF-8 编码。
注意：生成 Token 和刷新 Token 的接口有访问频率限制，如果调用频繁，会被禁用掉。所以这里开发者要根据 Token 的过期时间来控制好 Token 的生成或者刷新机制。
查看 API 调用日志

2. API 列表

左侧导航下不同域下的 API 信息可以帮助你获取和修改新核云相关模块下的业务数据。

导航	说明
认证 API	用户获取访问凭证 access_token和 refresh_token
制造域 MFR	主要包括生产制造相关信息的 API 接口，包括：生产单、BOM、标准工序、工艺路线、生产小组、工作中心、生产领料申请、生产备料任务、生产还料任务、生产报工单、生产报废入库任务等
质量域 QLTY	主要包括质量管理相关信息的 API 接口，包括：生产检验方案、生产检验规范、生产检验单、生产检验任务、生产不合格品处理单、采购检验方案、采购检验规范、收料检验单、收料不合格品处理单、收料放行单等
供应链域 SC	主要包括销售、采购相关信息的 API 接口，包括：客户、客户分类、供应商、供应商分类、企业(即客户&供应商)地址、销售订单、发货单、销售退货单、销售出库任务、销售退货入库任务、采购申请、采购订单、采购收料单、采购入库任务、采购退料出库任务、销售价目表、采购价目表等
厂内物流域 LOG	主要包括库存管理相关信息的 API 接口，包括：物料、物料分类、单位、规格、仓库、库位、出库申请单、入库申请单、移库申请单、盘点单、组装拆卸单、申请出库任务、申请入库任务、申请移库任务等
设备域 EQUIP	主要包括设备管理相关信息的 API 接口，包括：设备、设备维修单、设备保养单等
用户与租户域 USER	主要包括用户中心和空间管理相关信息的 API 接口，包括：空间、员工、部门、角色、用户等

3. 频控策略

待更新，包括频控策略登记、触发限制后的响应、建议处理方式等。

4. 通用错误码

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

API 调用指南

1. 流程概述

1.1 创建应用

1.1.1 授权商品：OpenAPI

1.1.2 创建应用：获取 APP Key & APP Secret

1.2 获取访问凭证

1.2.1 访问凭证介绍

1.2.2 访问凭证获取方式

1.3 调整 API 权限

1.4 调用 API

2. API 列表

3. 频控策略

4. 通用错误码