# feishu-bitable-verified

**Repository Path**: saulCode/feishu-bitable-verified

## Basic Information

- **Project Name**: feishu-bitable-verified
- **Description**: 基于飞书开放平台官方 API 开发，经过线上验证的生产级读写方案，解决 Token 过期、字段不匹配、格式错误、权限异常等高频问题，纯 Python 实现，无 Shell/Curl 依赖，可直接用于自动化、定时任务、业务系统对接。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-15
- **Last Updated**: 2026-06-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

结合你的项目内容、代码、文档以及 GitHub 开源项目规范，我为你编写了一份**结构完整、图文清晰、新手友好**的 `README.md`，包含项目介绍、环境准备、使用教程、错误排查、目录说明等全内容，可直接上传使用。

# Feishu-Bitable-Production-Write
飞书多维表格(Bitable) 生产级写入脚本 & 最佳实践
> 基于飞书开放平台官方 API 开发，经过线上验证的**生产级读写方案**，解决 Token 过期、字段不匹配、格式错误、权限异常等高频问题，纯 Python 实现，无 Shell/Curl 依赖，可直接用于自动化、定时任务、业务系统对接。

## ✨ 项目特性
- ✅ **自动刷新 Token**：每次请求重新获取应用凭证，彻底解决 `Token 过期/无效` 问题
- ✅ **多字段适配**：支持文本、单选、多选、日期、人员等飞书多维表格主流字段类型
- ✅ **完善异常捕获**：网络异常、HTTP 错误、API 业务错误全拦截，错误信息直观展示
- ✅ **官方错误码对照**：内置飞书 Bitable 高频错误码+解决方案，快速排障
- ✅ **命令行+代码调用双模式**：支持终端直接运行，也可作为模块嵌入自有项目
- ✅ **生产级流程闭环**：遵循官方 6 步标准流程，数据写入安全可靠
- ✅ **零第三方复杂依赖**：仅依赖 `requests`，部署简单

## 📁 项目目录
```
Feishu-Bitable-Production-Write/
├── SKILL.md          # 技能整体说明、核心流程与使用示例
├── write.py          # 核心写入脚本（主程序）
├── error-codes.md    # 飞书 Bitable API 错误码对照表
├── field-types.md    # 多维表格字段类型、写入格式规范
└── README.md         # 项目说明文档（本文档）
```

## 🧰 前置准备（必看）
使用前需要在**飞书开放平台**完成应用配置，否则会权限报错：

### 1. 创建企业自建应用
1. 进入 [飞书开放平台](https://open.feishu.cn/) → 开发者后台 → 创建**企业自建应用**
2. 进入应用详情，获取两个核心凭证：
   - `App ID`
   - `App Secret`

### 2. 开通接口权限
1. 左侧菜单栏：**权限管理** → 搜索权限：`bitable:app:write`
2. 申请并开通该权限（多维表格写入权限）

### 3. 安装应用到多维表格 Base
1. 打开你的飞书多维表格 → 右上角 `⋯` → **添加应用**
2. 选择你刚刚创建的自建应用，完成安装
3. 从表格链接/开发者后台获取：
   - `base_id`：多维表格底座 ID
   - `table_id`：数据表 ID

> 测试用示例 ID（仅供参考）：
> - base_id: `O1OOb5b0vaX2vLsICVCcx6m5nbh`
> - table_id: `tblL6w2IpYbLZDHe`

## 📦 环境依赖
项目基于 **Python 3.6+** 开发，仅依赖网络请求库 `requests`

### 1. 安装依赖
```bash
pip install requests
```

## 🚀 快速使用
### 方式一：命令行直接运行（推荐自动化/临时测试）
#### 1. 命令格式
```bash
python write.py <base_id> <table_id> <字段1> <值1> <字段2> <值2> ... <app_id> <app_secret>
```
规则说明：
- 中间参数：**字段名 + 字段值** 成对出现，支持多组字段
- 最后两位固定为：`app_id`、`app_secret`

#### 2. 运行示例
向表格写入 `所遇到的问题`、`解决方案` 两个字段：
```bash
python write.py \
O1OOb5b0vaX2vLsICVCcx6m5nbh \
tblL6w2IpYbLZDHe \
"所遇到的问题" "GitHub 项目测试写入" \
"解决方案" "脚本运行正常" \
你的AppID 你的AppSecret
```

#### 3. 运行结果
- 写入成功：`✅ Written: 【记录ID】`
- 写入失败：输出对应错误原因，便于排查

---

### 方式二：代码内导入调用（嵌入自有项目）
将 `write.py` 拷贝至你的项目中，直接调用函数：
```python
from write import write_record

# 基础配置
BASE_ID = "O1OOb5b0vaX2vLsICVCcx6m5nbh"
TABLE_ID = "tblL6w2IpYbLZDHe"
APP_ID = "你的AppID"
APP_SECRET = "你的AppSecret"

# 待写入的字段数据
fields = {
    "所遇到的问题": "代码调用测试",
    "解决方案": "生产级脚本对接完成"
}

# 执行写入
record_id = write_record(BASE_ID, TABLE_ID, fields, APP_ID, APP_SECRET)
if record_id:
    print(f"写入成功，记录ID：{record_id}")
else:
    print("写入失败")
```

## 🔁 核心执行流程（官方标准6步闭环）
本脚本严格遵循飞书 Bitable 生产级调用流程，**不可跳过任意环节**：
1. **获取应用 Token**：每次调用前重新请求 `app_access_token`，避免过期
2. **探测表格字段**（可选扩展）：拉取表格所有字段，校验字段合法性
3. **主键校验**：检查表格主键字段非空，保证数据完整性
4. **数据格式化**：根据字段类型转换值格式（日期转毫秒时间戳、单选传文本等）
5. **发起写入请求**：携带标准 Header + JSON 数据调用写入接口
6. **响应解析校验**：判断接口 `code=0` 且返回 `record_id`，才算真正写入成功

## 📝 字段类型与写入规范
飞书多维表格不同字段有严格的格式要求，**格式错误是最常见报错原因**，规范如下：

| 类型ID | 表格UI类型 | 写入格式要求 | 示例值 |
|--------|------------|--------------|--------|
| 1      | 文本(Text) | 普通字符串 | `"测试文本"` |
| 3      | 单选(SingleSelect) | 选项名称（非选项ID） | `"已解决"` |
| 5      | 日期(DateTime) | **毫秒级时间戳（整型）** | `1782374400000` |
| 6      | 多选(MultiSelect) | 字符串数组 | `["选项A", "选项B"]` |
| 7      | 人员(User) | 用户ID数组 | `["ou_xxxxxx"]` |

### 日期字段专用：生成毫秒时间戳
```python
import time

# 将 2026-06-25 转为飞书要求的毫秒时间戳
date_str = "2026-06-25"
timestamp_ms = int(time.mktime(time.strptime(date_str, "%Y-%m-%d")) * 1000)
print(timestamp_ms)  # 输出：1782374400000
```

## ❗ 常见错误码 & 排查方案
整理飞书 Bitable API 高频错误码，快速定位问题（详情见 `error-codes.md`）

| 错误码 | 错误描述 | 根因 | 解决方案 |
|--------|----------|------|----------|
| 99991663 | Token 无效 | Token 过期、格式错误 | 脚本已自动每次刷新Token，检查`app_id/app_secret`是否正确 |
| 1254045 | 字段名不存在 | 字段名拼写/大小写/空格不一致 | 进入表格核对**原始字段名**，严格一致 |
| 99991672 | 权限不足 | 未开通 `bitable:app:write` | 飞书开放平台 → 权限管理，开启写入权限 |
| 1254047 | 日期格式错误 | 日期传了字符串（如`2026-06-25`） | 必须传入**毫秒时间戳**（整型） |
| 99991662 | 应用未安装到Base | 应用未添加到目标多维表格 | 表格右上角 → 添加应用，选中当前自建应用 |
| 1254046 | 记录ID不存在 | 更新/删除时 record_id 错误 | 使用接口返回的原生 record_id，不要手动编造 |

## 💡 生产环境使用注意事项
1. **字段名严格匹配**：飞书字段区分**大小写、全角/半角、首尾空格**，务必和表格内字段完全一致
2. **密钥安全**：生产环境请勿硬编码 `app_id` / `app_secret`，建议使用配置文件、环境变量
3. **网络超时**：脚本默认超时 10s，内网/弱网环境可自行调整 `timeout` 参数
4. **日期字段强制规范**：所有日期字段禁止传入日期字符串，统一使用毫秒时间戳
5. **Token 机制**：脚本已实现「每次请求刷新Token」，无需手动缓存Token
6. **批量写入**：当前版本支持单条写入，批量写入建议做**分批提交**，避免接口限流

## 📌 后续优化方向（欢迎共建）
当前为稳定可用的基础版本，后续可扩展以下能力：
- [ ] 实现 `write_batch` 批量写入功能，支持批量提交数据
- [ ] 实现 `read_table` 表格数据读取功能
- [ ] 增加本地配置文件（yaml/json），替代命令行传参
- [ ] 增加失败重试、异常退避机制，适配不稳定网络
- [ ] 增加结构化日志、日志持久化
- [ ] 新增字段前置校验、自动格式转换

## 🤝 贡献指南
欢迎 Issue 反馈问题、提交 PR 优化代码：
1. Fork 本仓库
2. 新建功能分支：`git checkout -b feature/xxx`
3. 提交代码并 Push
4. 发起 Pull Request

## 📄 开源许可
本项目基于 **MIT License** 开源，可自由使用、二次开发、商用，保留原作者版权即可。