档案管理软件与金蝶财务系统集成实操落地技术指南

集成前核心准备工作

1. 必装工具与环境

需提前安装以下工具，均提供官方固定下载地址：

• Python 3.8+：官方下载地址https://www.python.org/ftp/python/3.10.11/python-3.10.11-amd64.exe
• 金蝶云星空系统账号（需具备开放平台权限）
• 你的档案管理系统（需开启REST API接口，若为开源系统需提前部署完成）

安装Python时需勾选Add Python to PATH，否则后续命令行无法调用。

2. 权限与账号准备

需提前获取两类权限凭证，禁止使用他人账号：

• 金蝶侧：登录金蝶云星空→【系统管理】→【开放平台】→【应用管理】，新建应用命名为「档案集成工具」，勾选档案管理全量API权限，保存后复制应用ID与AppSecret；再登录金蝶开发者平台https://developer.kingdee.com/，下载对应版本的「档案管理API手册」，记录新增档案接口地址。
• 档案系统侧：登录你的档案管理系统→【系统设置】→【开发者中心】，开启REST API，生成长期有效API Token，复制Token与档案列表查询接口地址。

字段映射规则确认

集成核心是双方字段一一对应，需提前明确：

金蝶侧必填字段：档案编码、档案名称、档案分类、启用状态
你的档案系统对应字段：需确保字段名与上述一致，若字段名不同，需在集成脚本中做转换（例如将你方「分类ID」转换为金蝶「档案分类」名称）；映射关系需写入后续配置文件。

集成代码实操（Python）

1. 安装依赖库

打开Windows CMD或Linux终端，切换至工作目录，执行以下命令：

pip install requests python-dotenv

命令说明：requests用于调用外部API，python-dotenv用于管理敏感配置，避免硬编码泄露。

2. 编写配置文件（.env）

在工作目录新建文件，命名为「.env」，内容完整复制如下，替换所有占位符：

``` 金蝶配置 KINGDEE_APP_ID=你的金蝶应用ID KINGDEE_APP_SECRET=你的金蝶应用密钥 KINGDEE_API_URL=https://api.kingdee.com/cloud/v1 档案系统配置 ARCHIVE_API_URL=你的档案系统API地址（例如https://192.168.1.100/api/archives/） ARCHIVE_API_TOKEN=你的档案系统API Token 字段映射 FIELD_MAPPING={ "doc_code": "档案编码", "doc_name": "档案名称", "category": "档案分类", "is_active": "启用状态" } ```

注意：.env文件禁止提交至代码仓库，仅本地存储，权限设为仅当前用户可读写。

3. 编写核心集成脚本（integration.py）

在工作目录新建文件，命名为「integration.py」，完整内容如下：

``` import os import requests from dotenv import load_dotenv 加载.env配置文件 load_dotenv() 加载所有配置项 KINGDEE_API_URL = os.getenv("KINGDEE_API_URL") KINGDEE_APP_ID = os.getenv("KINGDEE_APP_ID") KINGDEE_APP_SECRET = os.getenv("KINGDEE_APP_SECRET") ARCHIVE_API_URL = os.getenv("ARCHIVE_API_URL") ARCHIVE_API_TOKEN = os.getenv("ARCHIVE_API_TOKEN") FIELD_MAPPING = os.getenv("FIELD_MAPPING") 1. 获取金蝶访问token（有效期2小时） def get_kingdee_access_token(): auth_url = f"{KINGDEE_API_URL}/auth/token" payload = { "appId": KINGDEE_APP_ID, "appSecret": KINGDEE_APP_SECRET } resp = requests.post(auth_url, json=payload) return resp.json().get("accessToken") 2. 拉取档案系统全量档案数据 def fetch_archives_from_archive_system(): headers = {"Authorization": f"Bearer {ARCHIVE_API_TOKEN}"} resp = requests.get(ARCHIVE_API_URL, headers=headers) return resp.json().get("data", []) 3. 将档案数据同步至金蝶 def sync_to_kingdee(access_token, archive_data): kingdee_url = f"{KINGDEE_API_URL}/archive/add" headers = { "Authorization": f"Bearer {access_token}", "Content-Type": "application/json" } 转换字段为金蝶格式 kingdee_data = {v: archive_data.get(k) for k, v in FIELD_MAPPING.items()} 调用金蝶接口 resp = requests.post(kingdee_url, json=kingdee_data, headers=headers) return resp.json() 主执行流程 if __name__ == "__main__": try: kingdee_token = get_kingdee_access_token() archives = fetch_archives_from_archive_system() for item in archives: result = sync_to_kingdee(kingdee_token, item) if result.get("code") == "200": print(f"[SUCCESS] 档案同步：{item.get('doc_name')}") else: print(f"[FAIL] 档案同步失败：{item.get('doc_name')}，错误：{result.get('message')}") except Exception as e: print(f"[ERROR] 全局异常：{str(e)}") ```

脚本说明：主流程依次完成「获取金蝶token→拉取档案→转换字段→同步至金蝶」，异常会被捕获并输出日志。

测试与上线部署

1. 测试环境验证

执行以下步骤：

1. 在你的档案系统中新建1条测试档案（编码：TEST001，名称：测试档案，分类：内部档案，启用状态：是）；
2. 打开命令行，切换至工作目录，执行python integration.py；
3. 查看日志，若显示「[SUCCESS] 档案同步：测试档案」，则登录金蝶云星空→【档案管理】→【档案列表】，搜索「TEST001」，确认档案存在且字段正确，验证通过。

2. 定时自动同步配置

需设置定时任务，避免手动触发：

• Windows系统：打开「任务计划程序」→「创建基本任务」→名称设为「档案金蝶自动同步」→触发器设为每天凌晨2点→动作设为「启动程序」→程序路径选Python安装目录下的python.exe（例：C:\Python310\python.exe）→参数填写「你的工作目录\integration.py」→完成保存。
• Linux系统：编辑crontab，执行命令crontab -e，添加行：0 2 /usr/bin/python3 /你的工作目录/integration.py，保存退出。

常见问题排查

1. 金蝶接口返回「权限不足」：检查金蝶应用是否勾选「档案管理全量API权限」；
2. 档案系统返回「401未授权」：检查API Token是否过期，需重新生成；
3. 同步失败「字段缺失」：核对字段映射是否与双方系统实际字段一致。