---
title: 开发 API 概览
description: 介绍企业开发账号、认证方式、API 目录、调用规范和开发者索引。
slug: developer-api-overview
lang: zh
category: API概览
category_order: 8
order: 1
keywords:
  - API
  - 开发者
  - OAuth
  - JWT
  - 文件接口
---

# 开发 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`。

### Java JWT 对接样例

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

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

| 字段 | 说明 |
| --- | --- |
| `time` | 生成 token 的时间戳，单位为毫秒 |
| `duration` | token 有效时长，单位为秒 |
| `payload` | 业务载荷。用于用户免登录时可放入 `email`、`phone` 或 `babelId`；用于 `/api/authorizeByJWT.do` 时可放入 `client_id` |

常见用法：

- 用户免登录：生成 `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>`，再用返回的 `code` 换取 `access_token`。
- 文件 API 调用：获取 `access_token` 后，在后续文件、分享、企业等 API 请求 Header 中携带 `Authorization: Bearer <access_token>`。

最小实现步骤：先构造 `payload`，例如用户免登录使用 `{email: "user@example.com"}`，开发者授权使用 `{client_id: "<CLIENT_ID>"}`；再构造 JWT claims：`{time: 当前毫秒时间戳, duration: 60, payload: payload}`；然后使用企业后台配置的 JWT 密钥按 HS256 / HmacSHA256 签名，得到 JWT 字符串；最后把该字符串作为 `userToken` 或 `jwt_token` 放入对应 URL。

```java
import java.nio.charset.StandardCharsets;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;

import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;

import io.jsonwebtoken.Claims;
import io.jsonwebtoken.JwtBuilder;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;

public class BabelJwtExample {
    // 从企业管理后台或实施交付资料中获取。示例值必须替换，不能直接用于生产环境。
    private static final String JWT_SECRET = "REPLACE_WITH_ENTERPRISE_JWT_SECRET";

    public static void main(String[] args) throws Exception {
        Map<String, Object> user = new HashMap<>();
        user.put("email", "user@example.com");
        // 也可以按企业账号体系改用 phone 或 babelId:
        // user.put("phone", "13800000000");
        // user.put("babelId", "EMP001");

        String userToken = createTokenJWT(user);
        System.out.println("userToken=" + userToken);
        System.out.println("/account/tokenLogin.do?userToken=" + userToken);

        Map<String, Object> clientInfo = new HashMap<>();
        clientInfo.put("client_id", "REPLACE_WITH_CLIENT_ID");
        String jwtToken = createTokenJWT(clientInfo);
        System.out.println("/api/authorizeByJWT.do?response_type=code&client_id=REPLACE_WITH_CLIENT_ID&jwt_token=" + jwtToken);
    }

    public static String createTokenJWT(Map<String, Object> payload) {
        Map<String, Object> claims = new HashMap<>();
        claims.put("time", new Date().getTime());
        claims.put("duration", 60);
        claims.put("payload", payload);

        SecretKey key = generalKey();
        JwtBuilder builder = Jwts.builder()
            .setClaims(claims)
            .signWith(SignatureAlgorithm.HS256, key);
        return builder.compact();
    }

    public static Claims parseTokenJWT(String jwt) {
        SecretKey key = generalKey();
        Claims claims = Jwts.parser()
            .setSigningKey(key)
            .parseClaimsJws(jwt)
            .getBody();

        Long time = ((Number) claims.get("time")).longValue();
        Long duration = ((Number) claims.get("duration")).longValue();
        if (new Date().getTime() - time > 1000L * duration) {
            throw new IllegalStateException("JWT token expired");
        }
        return claims;
    }

    private static SecretKey generalKey() {
        byte[] encodedKey = JWT_SECRET.getBytes(StandardCharsets.UTF_8);
        return new SecretKeySpec(encodedKey, 0, encodedKey.length, "HmacSHA256");
    }
}
```

如果项目使用 `jjwt` 旧版本，代码结构可与上例保持一致；如果使用新版 `jjwt-api`、`jjwt-impl` 和 `jjwt-jackson` 拆分依赖，应按当前库版本调整签名和解析方法。联调时建议先在服务端生成 token 并解析校验，再把 token 放入 `/account/tokenLogin.do` 或 `/api/authorizeByJWT.do` 验证跳转和授权流程。

## API 分组

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

## 单接口页面

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

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