千夜网

千夜网 · 公网文档

集成与对接

本栏目用于 OpenAPI、鉴权、回调与环境说明，帮助开发者快速集成千夜科技的产品和服务。

OpenAPI 文档

API 基础信息

API 域名https://api.1001n.net/v1
请求方法GET, POST, PUT, DELETE
数据格式JSON
认证方式X-Tenant-Id + 角色头

示例请求

{
  "method": "GET",
  "url": "https://api.1001n.net/v1/qx/knowledge/categories",
  "headers": {
    "X-Tenant-Id": "your-tenant-id",
    "X-Qx-Role": "PARENT",
    "X-Qx-User-Id": "your-user-id"
  }
}

智游讲解（文旅域）专项

接口分组、识别对接与账号边界

`/api/v1/tour/*`、`/api/v1/vision/*`、`/api/v1/explain/*` 的对接约定；第三方识别 provider 规范；游客端账号独立与 RuoYi 总后台的边界。

研学 + 教育（线下为主）专项

任务/进度/复盘的数据回传与幂等

研学前/中/后任务闭环的接口边界；离线缓存与补传；幂等键与对账口径；与讲解/识别能力的联动。

鉴权说明

X-Tenant-Id + 角色头认证

所有 API 请求都需要在请求头中包含租户 ID 和角色信息，以确保请求的安全性和权限控制。

  • X-Tenant-Id：租户 ID，用于标识不同的租户
  • X-Qx-Role：角色类型，可选值：PARENT、COACH、ADMIN
  • X-Qx-User-Id：用户 ID，用于标识具体的用户

请求头示例

// 家长角色示例
{
  "X-Tenant-Id": "your-tenant-id",
  "X-Qx-Role": "PARENT",
  "X-Qx-User-Id": "your-user-id"
}

// 教练角色示例
{
  "X-Tenant-Id": "your-tenant-id",
  "X-Qx-Role": "COACH",
  "X-Qx-User-Id": "your-coach-id"
}

// 管理员角色示例
{
  "X-Tenant-Id": "your-tenant-id",
  "X-Qx-Role": "ADMIN",
  "X-Qx-User-Id": "your-admin-id"
}

环境说明

生产环境

  • API 域名：https://api.1001n.cn
  • 状态：正式上线
  • 稳定性：高
  • 适用场景：生产应用

测试环境

  • API 域名：https://api-test.1001n.cn
  • 状态：可用
  • 稳定性：中
  • 适用场景：开发测试

错误码说明

错误码含义解决方案
400请求参数错误检查请求参数是否正确
401未授权检查租户 ID 和角色头是否正确
403禁止访问检查权限是否足够
404资源不存在检查请求路径是否正确
500服务器内部错误联系技术支持