变更指令在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？

龟仔妈妈（数字化智能工作站·旗舰版） 本身就是一台“扫描+上传+回调”一体机。用户把纸质文件放进龟仔妈妈，选择扫描，设备会自动：

1. 生成双层PDF（可OCR检索）；
2. 将文件上传到会博通服务器；
3. 会博通服务器按照配置的 CallBlackUrl 推送元数据（含条码识别结果，例如变更单号）；
4. 第三方系统收到元数据后，根据条码匹配已有的变更指令条目，再调用下载接口把扫描件拉回来，自动挂接。

整个过程无需人工干预，纸质文件扫完即归档。

六、官方API文档与资源

本文所有接口细节均依据 《会博通龟仔系列产品文件同步API接口文档》 撰写。你可以在会博通官网开发者中心获取完整文档（包括RSA公钥、接口完整参数表、错误码说明）。

• 官方开发者中心：https://www.hbotong.com/developer
• 本文配套Python示例代码（模拟回调接收、Token管理、下载重试）已上传GitHub：
  https://github.com/huibotong/railway-archive-etl

七、写在最后：别再手动导数据了

很多开发团队一听到“异构系统对接”就头大，以为要写无数个适配器。但会博通这套开放API的设计哲学非常务实：推送轻量元数据，回调确认，主动拉取内容。你只需要实现一个很薄的回调接口，剩下的全是标准HTTP调用。

铁路基建项目的档案验收，不应该成为通宵加班的理由。花一天时间把这条自动化管道搭好，以后每个月的归档工作就是点一下“重试”按钮。

—— 会博通·代码搬运工，基于官方API文档编写