---
id: "zh/developer-api-overview"
title: "开发 API 概览"
language: "zh"
description: "介绍企业开发账号、认证方式、API 目录、调用规范和开发者索引。"
canonical_url: "https://www.babel.cc/public/babelwiki/zh/developer-api-overview.html"
markdown_url: "https://www.babel.cc/public/babelwiki/ai/zh/developer-api-overview.md"
alternates: {"en": "https://www.babel.cc/public/babelwiki/ai/en/developer-api-overview.md", "zh": "https://www.babel.cc/public/babelwiki/ai/zh/developer-api-overview.md"}
reading_note: "文档记录不等于当前部署能力；以实际版本、授权模块与配置为准。保留原文的可选、限制及待确认说明，勿补猜接口。 / Documentation is not a guarantee for every deployment. Preserve optional-module requirements, limitations and unresolved API contracts."
---

# 开发 API 概览

巴别鸟开发 API 用于把企业网盘的认证、文件、分享、组织、消息和登录能力接入第三方业务系统。左侧栏按接口作用分组，组内直接列出可调用端点。

## 调用总览

- 企业管理员在私有云企业管理后台创建开发者账号，获得 `client_id`、`client_secret` 和 JWT 相关密钥。
- OAuth 回调方式使用 `/api/authorize.do` 获取授权码，再用 `/api/token.do` 获取 `access_token`。
- JWT 免登录方式使用 `/api/authorizeByJWT.do` 或 `/account/tokenLogin.do`，私有化部署需开启对应配置。
- 文件访问 API 请求需要在 HTTP Header 中携带 `Authorization: Bearer <access_token>`。
- POST、PUT、DELETE 请求通常使用 `Content-Type: application/json`。

### JWT 声明结构与有效期 {#jwt-contract-status}

已确认两类用途：`/account/tokenLogin.do` 使用携带用户 `email`、`phone` 或 `babelId` 信息的 `userToken` 建立网页会话，支持用 `fileId` 打开指定文件，用 `onlyFileList=1` 仅显示文件列表；`/api/authorizeByJWT.do` 使用携带开发者 `client_id` 信息的 `jwt_token`，并通过查询参数指定用户，取得 `code` 后再经 `/api/token.do` 换取访问及刷新凭证。两种 JWT 不能混用。

以下结构已确认适用于当前部署：`time`、`duration`、`payload` 都是顶层 claims。`time` 为生成 JWT 时的 Unix 毫秒时间戳，`duration` 为该 JWT 的有效时长（秒），`payload` 为业务对象。网页登录的邮箱放在 `payload.email`；开发者授权的 ID 放在 `payload.client_id`，当前提供的样例中该 ID 为数字。

网页登录 `userToken` 解码后的结构（身份及时间为示例值）：

```json
{
  "duration": 60,
  "payload": {"email": "user@example.com"},
  "time": 1790000000000
}
```

授权 `jwt_token` 解码后的结构（应用 ID 及时间为示例值）：

```json
{
  "duration": 60,
  "payload": {"client_id": 1000000000001},
  "time": 1790000000000
}
```

`60` 表示这两个样例的 JWT 有效 60 秒，不是已确认的固定值或默认值；`time` 在每次生成时取当前时间，不能复制样例时间使用。这里的有效期属于提交给登录／授权接口的 JWT，不等于网页会话或之后换取的 `access_token` 的有效期。本次确认范围为当前部署，不据此宣称所有历史版本都相同。

### Java JWT 对接样例

以下示例根据巴别鸟 API 对接样例整理，用于演示如何生成 JWT 字符串。实际项目中请把密钥、企业域名、用户邮箱、手机号、工号和 `client_id` 替换为当前企业管理后台提供的值，不要在前端页面、客户端安装包或公开代码仓库中暴露 JWT 密钥。

JWT 载荷结构包含三个核心字段：

| 字段 | 说明 |
| --- | --- |
| `time` | 生成 token 的时间戳，单位为毫秒 |
| `duration` | token 有效时长，单位为秒 |
| `payload` | 业务对象：当前邮箱登录样例为 `{"email":"user@example.com"}`；开发者授权样例为 `{"client_id":1000000000001}`。 |

常见用法：

- 用户免登录：生成 `userToken` 后访问 `/account/tokenLogin.do?userToken=<JWT_TOKEN>`。
- OAuth/JWT 授权：生成 `jwt_token` 后访问 `/api/authorizeByJWT.do?response_type=code&client_id=<CLIENT_ID>&jwt_token=<JWT_TOKEN>&email=<USER_EMAIL>`，再用返回的 `code` 换取 `access_token`。
- 文件 API 调用：获取 `access_token` 后，在后续文件、分享、企业等 API 请求 Header 中携带 `Authorization: Bearer <access_token>`。

最小实现步骤：先构造 `payload`，邮箱登录使用 `{email: "user@example.com"}`，开发者授权按当前样例使用数值型 `{client_id: 1000000000001}`（替换为实际应用 ID，Java 中可用 `long`）；再构造 JWT claims：`{time: 当前毫秒时间戳, duration: 60, payload: payload}`；然后使用企业后台配置的 JWT 密钥按 HS256 / HmacSHA256 签名，得到 JWT 字符串；最后把该字符串作为 `userToken` 或 `jwt_token` 放入对应 URL。URL 查询参数中的 `client_id` 使用同一实际应用 ID。

```java
import java.nio.charset.StandardCharsets;
import java.util.HashMap;
import java.util.Map;
import javax.crypto.SecretKey;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.security.Keys;

public final class BabelJwtExample {
    public static String createToken(Map<String, Object> payload) {
        String secret = System.getenv("BABEL_JWT_SECRET");
        if (secret == null || secret.isEmpty()) {
            throw new IllegalStateException("BABEL_JWT_SECRET is required");
        }
        SecretKey key = Keys.hmacShaKeyFor(secret.getBytes(StandardCharsets.UTF_8));
        Map<String, Object> claims = new HashMap<>();
        claims.put("time", System.currentTimeMillis());
        claims.put("duration", 60);
        claims.put("payload", payload);
        return Jwts.builder().claims(claims).signWith(key, Jwts.SIG.HS256).compact();
    }
}
```

示例采用 JJWT 0.12.x 的调用方式，`jjwt-api`、`jjwt-impl` 与 `jjwt-jackson` 应使用一致的版本，依赖配置参见 [JJWT 官方说明](https://github.com/jwtk/jjwt)。按巴别鸟对接样例使用密钥的 UTF-8 字节；若交付约定不同编码，先与实施方确认，勿自行截断、填充或变换密钥。HS256 密钥不足 256 位时库会拒绝签名，应由管理员提供合适的密钥。

本例只生成签名，不是登录服务或完整的 JWT 验证器。`time`、`duration` 是巴别鸟自定义字段，不等同于标准 `exp`。用户身份必须由可信服务端根据已认证会话确定，生成的 Token 不应写入日志；实际授权与失效行为需在目标部署中联调。

## API 分组

| 分组 | 主要用途 | 典型入口 |
| --- | --- | --- |
| 认证 API | 开发者账号、OAuth 回调、JWT 免登录、Token 获取和刷新 | [获取 token](https://www.babel.cc/public/babelwiki/zh/api-post-api-token-do.html) |
| 文件 API | 文件列表、文件信息、上传下载、版本、移动复制、回收站、素材库分类 | [获取文件列表](https://www.babel.cc/public/babelwiki/zh/api-get-nd-api-file-list-dir.html) |
| 分享 API | 分享链接、分享权限、参与人、关注提醒 | [获取文件的分享 url](https://www.babel.cc/public/babelwiki/zh/api-get-nd-api-share-shareurl.html) |
| 企业 API | 企业信息、部门、成员、企业日志 | [获取当前企业信息](https://www.babel.cc/public/babelwiki/zh/api-get-nd-api-enterprise-current.html) |
| 消息与登录 API | 公告、部门讨论、JWT token 登录、通用状态码 | [JWT token 登录](https://www.babel.cc/public/babelwiki/zh/api-get-account-tokenlogin-do.html) |

## 单接口页面

每个 API 条目均有独立页面，便于开发者按接口查阅路径、方法、参数和返回信息。

- [GET 认证接口一（登录回调方式）](https://www.babel.cc/public/babelwiki/zh/api-get-api-authorize-do.html)：`/api/authorize.do`
- [GET 认证接口二（免登录 JWT token 方式）](https://www.babel.cc/public/babelwiki/zh/api-get-api-authorizebyjwt-do.html)：`/api/authorizeByJWT.do`
- [POST 获取 token](https://www.babel.cc/public/babelwiki/zh/api-post-api-token-do.html)：`/api/token.do`
- [POST 刷新 token](https://www.babel.cc/public/babelwiki/zh/api-post-api-refreshtoken-do.html)：`/api/refreshToken.do`
- [GET 获取文件列表](https://www.babel.cc/public/babelwiki/zh/api-get-nd-api-file-list-dir.html)：`/nd/api/file/list_dir` — **请求 page 从 0 开始；返回 pages 为总页数**
- [GET 获取文件信息](https://www.babel.cc/public/babelwiki/zh/api-get-nd-api-file-fileinfo.html)：`/nd/api/file/fileinfo`
- [POST 创建文件夹](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-file-create-folder.html)：`/nd/api/file/create_folder`
- [GET 预上传文件](https://www.babel.cc/public/babelwiki/zh/api-get-api-file-preuploadfile-do.html)：`/api/file/preUploadFile.do`
- [GET 获取下载文件地址](https://www.babel.cc/public/babelwiki/zh/api-get-api-file-getfiledownloadurl-do.html)：`/api/file/getFileDownloadUrl.do`
- [GET 获取下载多文件地址](https://www.babel.cc/public/babelwiki/zh/api-get-api-file-downloadmultifiles-do.html)：`/api/file/downloadMultiFiles.do`
- [GET 获取下载文件缩略图地址](https://www.babel.cc/public/babelwiki/zh/api-get-api-file-downloadthumbnail-do.html)：`/api/file/downloadThumbnail.do`
- [POST 修改文件信息](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-file-update-file.html)：`/nd/api/file/update_file`
- [POST 修改文件名](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-file-rename.html)：`/nd/api/file/rename`
- [POST 删除文件(到回收站）](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-file-remove-file.html)：`/nd/api/file/remove_file`
- [POST 删除文件（从回收站）](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-file-remove-from-trash.html)：`/nd/api/file/remove_from_trash`
- [POST 清空回收站](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-file-empty-trash.html)：`/nd/api/file/empty_trash`
- [POST 恢复文件（从回收站）](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-file-restore-file.html)：`/nd/api/file/restore_file`
- [GET 获取文件的所有版本信息](https://www.babel.cc/public/babelwiki/zh/api-get-nd-api-file-versions.html)：`/nd/api/file/versions`
- [POST 设置文件当前版本](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-file-version.html)：`/nd/api/file/version`
- [POST 移动文件](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-file-move.html)：`/nd/api/file/move`
- [POST 拷贝文件](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-file-copy.html)：`/nd/api/file/copy`
- [POST 拷贝文件进度](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-file-copy-progress.html)：`/nd/api/file/copy_progress`
- [GET 文件日志](https://www.babel.cc/public/babelwiki/zh/api-get-nd-api-file-file-logs.html)：`/nd/api/file/file_logs`
- [POST 设置用户是否有权访问素材库](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-file-set-user-access-material-library.html)：`/nd/api/file/set_user_access_material_library`
- [POST 创建素材库分类](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-file-create-material-class.html)：`/nd/api/file/create_material_class`
- [POST 创建子素材库](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-file-create-material-folder.html)：`/nd/api/file/create_material_folder`
- [GET 获取文件的分享 url](https://www.babel.cc/public/babelwiki/zh/api-get-nd-api-share-shareurl.html)：`/nd/api/share/shareurl`
- [GET 获取分享的权限列表](https://www.babel.cc/public/babelwiki/zh/api-get-nd-api-share-share-roles.html)：`/nd/api/share/share_roles`
- [GET 获取用户对于单个文件有权设置的分享角色](https://www.babel.cc/public/babelwiki/zh/api-get-nd-api-share-share-role-forfile.html)：`/nd/api/share/share_role_forfile`
- [POST 创建链接分享](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-share-open-link-share.html)：`/nd/api/share/open_link_share`
- [POST 关闭链接分享](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-share-close-link-share.html)：`/nd/api/share/close_link_share`
- [POST 设置链接分享密码](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-share-set-share-password.html)：`/nd/api/share/set_share_password`
- [POST 邀请人员参与分享](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-share-invite-share.html)：`/nd/api/share/invite_share`
- [GET 获取所有分享参与人](https://www.babel.cc/public/babelwiki/zh/api-get-nd-api-share-share-participants.html)：`/nd/api/share/share_participants` — **已补非空 users 样例及字段类型**
- [POST 设置分享参与人的权限角色](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-share-set-participant-role.html)：`/nd/api/file/set_participant_role` — **role_id 取 roles[].id 整数；babelshare_id 取 users[].babelshareId 字符串**
- [POST 删除分享参与人](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-file-remove-share-participant.html)：`/nd/api/file/remove_share_participant`
- [POST 提醒关注](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-file-focus-file.html)：`/nd/api/file/focus_file`
- [POST 移除某人的关注](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-file-unfocus-file.html)：`/nd/api/file/unfocus_file`
- [GET 获取关注文件的用户列表](https://www.babel.cc/public/babelwiki/zh/api-get-nd-api-file-user-focusfile.html)：`/nd/api/file/user_focusfile`
- [GET 获取可以关注文件的用户列表，并且标记已关注文件的用户](https://www.babel.cc/public/babelwiki/zh/api-get-nd-api-file-user-can-focusfile.html)：`/nd/api/file/user_can_focusfile` — **isFocusFile：0 未关注，1 已关注**
- [GET 获取当前企业信息](https://www.babel.cc/public/babelwiki/zh/api-get-nd-api-enterprise-current.html)：`/nd/api/enterprise/current`
- [GET 获取企业所有部门信息](https://www.babel.cc/public/babelwiki/zh/api-get-nd-api-enterprise-departments.html)：`/nd/api/enterprise/departments`
- [POST 创建企业部门](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-enterprise-create-department.html)：`/nd/api/enterprise/create_department`
- [GET 获取部门角色列表](https://www.babel.cc/public/babelwiki/zh/api-get-nd-api-enterprise-dep-role.html)：`/nd/api/enterprise/dep_role`
- [POST 添加部门人员](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-enterprise-add-dep-mem.html)：`/api/add_dep_mem.do` — **结果标记已确认**
- [POST 删除部门人员](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-enterprise-remove-dep-mem.html)：`/nd/api/enterprise/remove_dep_mem` — **结果标记已确认**
- [GET 获取自己所在部门信息](https://www.babel.cc/public/babelwiki/zh/api-get-nd-api-enterprise-mydeparments.html)：`/nd/api/enterprise/mydeparments`
- [GET 获取部门人员](https://www.babel.cc/public/babelwiki/zh/api-get-nd-api-enterprise-departmentmembers.html)：`/nd/api/enterprise/departmentmembers`
- [POST 添加企业成员](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-enterprise-add-ent-mem.html)：`/api/add_ent_mem.do` — **结果标记已确认**
- [POST 更新成员信息](https://www.babel.cc/public/babelwiki/zh/api-post-api-updateuserinfo-do.html)：`/api/updateUserInfo.do`
- [GET 获取企业成员信息](https://www.babel.cc/public/babelwiki/zh/api-get-api-getenterprisemember-do.html)：`/api/getEnterpriseMember.do`
- [POST 获取企业所有成员](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-enterprise-enterprise-members.html)：`/nd/api/enterprise/enterprise_members`
- [POST 获取企业日志](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-enterprise-enterprise-logs.html)：`/nd/api/enterprise/enterprise_logs`
- [POST 发布公告](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-enterprise-broadcast.html)：`/nd/api/enterprise/broadcast`
- [GET 获取发布的公告](https://www.babel.cc/public/babelwiki/zh/api-get-nd-api-enterprise-broadcast.html)：`/nd/api/enterprise/broadcast`
- [POST 发送部门讨论](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-file-send-dep-discussion.html)：`/nd/api/file/send_dep_discussion`
- [POST 获取部门讨论](https://www.babel.cc/public/babelwiki/zh/api-post-nd-api-file-dep-discussion.html)：`/nd/api/file/dep_discussion`
- [GET 获取企业日志](https://www.babel.cc/public/babelwiki/zh/api-get-nd-api-enterprise-enterprise-logs.html)：`/nd/api/enterprise/enterprise_logs`
- [GET JWT token 登录](https://www.babel.cc/public/babelwiki/zh/api-get-account-tokenlogin-do.html)：`/account/tokenLogin.do`

## JWT 身份与保密提示

`/api/authorizeByJWT.do` 应明确传入目标用户的 `email`、`phone` 或 `babelId`。源 API 说明不指定用户时可能使用管理员身份，业务集成不应省略身份字段或直接信任外部传入的用户标识。JWT 签名不加密载荷，不要放入敏感明文；生产环境不要输出 Token 到控制台日志。