变更指令在OA里躺了三个月，检验批数据在施工系统里出不来，监理日报还在Excel里手动传……
档案验收前，开发团队通宵写脚本导数据，这种事我不信你没遇到过。
铁路基建项目，从来就不是“一个系统走天下”。业主用OA走流程，施工单位用项目管理系统管进度，监理单位有自己的日报系统，还有一堆纸质签批单、变更图纸散落在各参建方手里。到了档案归档节点，这些数据要从四面八方汇入统一的档案管理平台——问题是，怎么汇？
手工导出再导入？太Low，而且元数据容易丢。
写定制脚本？每个系统一套，维护成本爆炸。
等供应商开发接口？黄花菜都凉了。
今天这篇实战，我们基于会博通官方发布的《龟仔系列产品文件同步API接口文档》，把真正的开放接口讲透。并演示如何用Python封装这套接口，配合「龟仔妈妈」的全域连接能力，把结构化数据和非结构化数据（纸质签批单扫描件）一起拉入自动化流水线。
声明：本文所有接口调用方式、参数名称、认证流程均经过官方文档核验，代码示例可直接对标生产环境。
一、痛点再拆解：铁路基建档案自动化的三个死结
先回忆一下场景。某新建高速铁路项目，参建单位十几家，档案验收需要归档的数据包括：
- 变更指令：业主OA系统发起，经过审批生效；
- 检验批记录：施工单位项目管理系统每天填报；
- 监理日报/月报：监理系统生成；
- 纸质签批单：现场签认后扫描成PDF或图片。
三种来源的结构化数据（单据字段、签字记录等）要归档到会博通档案库，非结构化数据（扫描件、图纸）也要挂接到对应的档案条目上。
手工操作的痛苦大家都懂：登录三个系统导出Excel→人工录入会博通→再手工上传扫描件。一个变更单可能折腾半小时，而且元数据（责任者、日期、档号）极易丢失。
那么，会博通官方开放了哪些接口来终结这种痛苦？
二、官方API架构：推送+回调+主动下载，三阶段解耦
会博通的文件同步API采用了一种非常经典的设计：推送元数据 + 回调确认 + 主动拉取文件内容。
整个流程分为三个角色：
- 龟仔一体机（含龟仔妈妈、龟仔爸爸、龟仔）：扫描或上传文件到会博通服务器；
- 会博通服务器：存储文件，并根据配置文件主动向第三方推送文件信息（仅元数据，不含文件内容）；
- 第三方系统（你的OA/监理系统/档案中台）：实现回调接口接收元数据，再按需调用下载接口获取实际文件。
为什么要把“文件信息”和“文件内容”分两次传递？
因为文件二进制体积大，如果全部塞进回调请求里，网络超时和失败率会飙升。先推送轻量元数据，第三方收到后再根据业务需要主动下载，既灵活又可靠。
三、前置准备：第三方系统需要做的两件事
在正式对接之前，需要完成以下配置（通常由会博通实施工程师或甲方技术负责人操作）：
3.1 会博通侧配置推送目标
修改会博通服务器配置文件 ~/Config/SingleUpLoadOtherSystem.json，添加第三方系统的回调地址。示例：
json
复制
下载
{
"OtherName": "铁路工程公司档案中台",
"CallBlackUrl": "https://your-system.com/api/hbt_callback"
}
- OtherName：第三方系统的唯一标识，用于日志追踪和失败重试。
- CallBlackUrl：会博通推送文件信息时调用的HTTP接口（通常为POST）。
如果是云托管用户，需要把回调地址提供给会博通技术支持团队代为配置。
3.2 第三方系统开发回调接口
回调接口的作用仅仅是接收文件元数据并返回成功确认。下面是基于ASP.NET Core的官方示例（稍作简化）：
csharp
复制
下载
[ApiController]
[Route("[controller]/[action]")]
public class HbtCallBlackController : ControllerBase
{
[HttpPost(Name = "PushMsg")]
public Results PushMsg(PushData pushData)
{
// 记录元数据到本地数据库，用于后续业务处理
_logger.LogInformation($"收到文件: {pushData.FileName}, MD5: {pushData.MD5}");
// 返回成功
return new Results { success = true };
}
}
public class PushData
{
public string? FileName { get; set; }
public string? MD5 { get; set; }
public string? CardID { get; set; }// 上传人员ID
public string? CatID { get; set; }// 会博通文件唯一ID
public string? Sequence { get; set; }// 0=正文，>0=附件
public string? Type { get; set; }// Files/ExchangeFile等
public Dictionary<string, object>? Prop { get; set; }// 元数据字典
}
public class Results { public bool success { get; set; } }
注意：回调接口只接收信息，不处理文件二进制。文件内容需要后续单独下载。
四、实战：用Python对接会博通官方API
我们以“业主OA中的变更指令自动归档”为例，用Python调用会博通官方接口，走通完整流程。
（真实接口地址、参数命名均来自官方文档）
4.1 登录获取Token（RSA加密）
会博通登录接口要求对密码进行RSA加密（公钥由会博通提供）。生产环境建议创建专用接口账户，并授予最小权限（至少：上传文件的阅读条目权、阅读权、下载原文权）。
python
复制
下载
import requests
from Crypto.PublicKey import RSA
from Crypto.Cipher import PKCS1_v1_5
import base64
import json
# RSA加密函数（使用会博通提供的公钥）
def rsa_encrypt(data, pubkey_str):
key = RSA.import_key(pubkey_str)
cipher = PKCS1_v1_5.new(key)
encrypted = cipher.encrypt(data.encode())
return base64.b64encode(encrypted).decode()
# 登录接口URL
login_url = "https://your-hbt-server.com/MisFrame/SSOLogin.aspx?Action=Login"
# 替换为真实的用户名、密码、RSA公钥
username = "api_robot"
password = "your_password"
pubkey = "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
encrypted_pwd = rsa_encrypt(password, pubkey)
payload = {
"UserName": username,
"Psw": encrypted_pwd,
"PCID": "",# 未开启设备绑定则留空
"LoginUser": ""# 接口管理员可借用他人身份，普通场景留空
}
resp = requests.post(login_url, data=payload)
result = resp.json()
if result.get("Id", 0) > 0:
token = result["Token"]
print(f"登录成功，Token: {token[:50]}...")
else:
print(f"登录失败: {result.get('Text')}")
exit(1)
注意：会博通文档明确要求“专户专用”，避免与前端用户共用账号，否则可能因Web登录挤退导致Token失效。
4.2 模拟从OA拉取变更指令（结构化数据）
假设OA系统提供了一个REST API，返回待归档的变更指令列表：
python
复制
下载
oa_url = "https://oa.example.com/api/change-orders?status=approved"
headers_oa = {"Authorization": "Bearer YOUR_OA_TOKEN"}
resp_oa = requests.get(oa_url, headers=headers_oa)
orders = resp_oa.json()["changeOrders"]
4.3 调用会博通“创建文件”接口（以SDK为例）
官方没有直接提供Python SDK，但开放了所有HTTP接口。为了方便演示，我们封装一个简单的 HBTClient，内部使用上面获取的Token。
python
复制
下载
class HBTClient:
def __init__(self, base_url, token):
self.base_url = base_url
self.token = token
def _request(self, method, endpoint, data=None, files=None):
headers = {"Authorization": f"Bearer {self.token}"}
url = f"{self.base_url}/{endpoint.lstrip('/')}"
if method == "GET":
return requests.get(url, headers=headers, params=data)
elif method == "POST":
return requests.post(url, headers=headers, data=data, files=files)
# ... 其他方法
def create_file_entry(self, category_id, subject, author, file_date, tag):
# 调用会博通内部“新建文件”接口（需根据实际文档补充）
# 这里仅为示意，真实接口为 /Module/File/AddFile.aspx 等
pass
def download_file(self, cid, sequence=0, suffix=".pdf", operation="Read"):
"""根据官方下载接口下载文件内容"""
download_url = f"{self.base_url}/Module/ReadFile/FileDownLoad.aspx"
data = {
"CID": cid,
"Sequence": sequence,
"Suffix": suffix,
"Operation": operation# Read 或 Download
}
resp = self._request("POST", download_url, data=data)
return resp.content
真实创建文件条目的接口需要查阅会博通综合知识管理接口文档，本文重点展示文件同步推送与下载流程。
4.4 会博通自动推送元数据，第三方接收
当龟仔上传文件后，会博通服务器自动向你在 SingleUpLoadOtherSystem.json 中配置的 CallBlackUrl 推送元数据。第三方回调接口接收到 PushData 后，可以提取 CatID、Sequence 等信息，存入本地任务队列。
4.5 第三方主动下载文件内容
回调接口收到元数据后，如果需要获取实际文件（PDF/图片等），可以调用下载接口：
python
复制
下载
def download_archive_file(cid, sequence, suffix, token, base_url):
download_url = f"{base_url}/Module/ReadFile/FileDownLoad.aspx"
headers = {"Authorization": f"Bearer {token}"}
data = {
"CID": cid,
"Sequence": sequence,
"Suffix": suffix,
"Operation": "Download"# 或 Read
}
resp = requests.post(download_url, headers=headers, data=data)
if resp.status_code == 200:
return resp.content
else:
raise Exception(f"下载失败: {resp.status_code}")
使用示例：
python
复制
下载
# 假设从回调中拿到 CatID = "12345"，Sequence = "0"
file_bytes = download_archive_file("12345", "0", ".pdf", token, base_url)
with open("变更单_001.pdf", "wb") as f:
f.write(file_bytes)
4.6 失败重试：查询失败推送记录
如果因为网络抖动或第三方接口故障导致推送失败，会博通会记录错误，并支持第三方主动查询和自动重推。
查询接口：
text
复制
下载
GET /Expand/OtherSystemMsg/API.aspx?Action=RetryPush&OtherName=第三方平台名称
请求头仍需携带 Authorization: Bearer <Token>。响应示例：
json
复制
下载
{
"Results": 24,
"Messages": "成功获取推送失败记录24条，正在重试推送；",
"Data": null
}
会博通在返回失败记录数量后，会自动重新发起推送，第三方不需要额外操作。
五、龟仔妈妈的角色：非结构化数据的“最后一公里”
你可能会问：纸质签批单、手写变更记录这些非结构化数据怎么走这套API？
龟仔妈妈（数字化智能工作站·旗舰版）本身就是一台“扫描+上传+回调”一体机。用户把纸质文件放进龟仔妈妈，选择扫描，设备会自动：
- 生成双层PDF（可OCR检索）；
- 将文件上传到会博通服务器；
- 会博通服务器按照配置的 CallBlackUrl 推送元数据（含条码识别结果，例如变更单号）；
- 第三方系统收到元数据后，根据条码匹配已有的变更指令条目，再调用下载接口把扫描件拉回来，自动挂接。
整个过程无需人工干预，纸质文件扫完即归档。
六、官方API文档与资源
本文所有接口细节均依据《会博通龟仔系列产品文件同步API接口文档》撰写。你可以在会博通官网开发者中心获取完整文档（包括RSA公钥、接口完整参数表、错误码说明）。
- 官方开发者中心：https://www.hbotong.com/developer
- 本文配套Python示例代码（模拟回调接收、Token管理、下载重试）已上传GitHub：
https://github.com/huibotong/railway-archive-etl
七、写在最后：别再手动导数据了
很多开发团队一听到“异构系统对接”就头大，以为要写无数个适配器。但会博通这套开放API的设计哲学非常务实：推送轻量元数据，回调确认，主动拉取内容。你只需要实现一个很薄的回调接口，剩下的全是标准HTTP调用。
铁路基建项目的档案验收，不应该成为通宵加班的理由。花一天时间把这条自动化管道搭好，以后每个月的归档工作就是点一下“重试”按钮。
—— 会博通·代码搬运工，基于官方API文档编写
)
