破解实控人溯源痛点从多级工商底稿核查到股权图谱数据穿透在一级市场股权投资、Pre-IPO 尽职调查以及券商保荐机构核查拟上市公司股东适格性的业务场景中构建一套“投研机构拟上市公司实控人溯源与多层股权图谱构建引擎”是合规风控与投研工程的核心基础设施。拟上市主体往往存在多层级的有限合伙持股平台、员工持股计划ESOP、契约型基金以及跨区域控股子公司投研团队不仅需要向上溯源认定最终实际控制人UBO并核算其直接与间接合并持股比例还需向下厘清控股子公司的经营存续状态。传统的尽调方式依赖研究员手工检索多份工商底稿并在电子表格中逐层折算持股乘积不仅耗费大量工时且在面对交叉持股、同名自然人股东消歧以及多层嵌套变更时极易出现核算偏差。在取得尽调合规授权的前提下基于天远股权穿透接口构建自动化图谱采集管道能够将离散的工商登记信息转化为标准化的图数据模型。研发团队只需在请求中传入目标主体的ent_code企业编码、flag穿透查询层次最高支持 4 层、dir穿透方向up向上溯源股东或down向下排查对外投资以及股权比例过滤区间min_percent与max_percent。系统直连权威商事底层数据库并解密响应报文后可直接提取图谱节点的核心拓扑属性包括节点唯一标识id、主体名称name、用于区分法人与自然人的对象类型lableCompany、Human、Other、跨企业同名自然人消歧标识pid、统一社会信用代码creditCode、企业当前经营状态regStatus、精确股权占比percent以及标识节点在当前层级之外是否仍可继续向下或向上展开的open字段。这些结构化字段为构建 Neo4j 或 NetworkX 股权知识图谱、自动化折算累计受益股份以及识别非存续异常主体提供了客观的数据依据。将这一加密股权穿透能力无缝嵌入 Python 投研数据工程流水线或准入风控网关中能够使尽调系统在数秒内完成拟上市主体多层级股权树的递归拼装与前置准入校验大幅压缩人工核对底稿的周期让投研与合规团队将精力聚焦于核心商业逻辑与治理结构评估。1. Python 加密通信集成构建高可用审核管道1. 核心参数与加密配置接口地址:https://api.tianyuanapi.com/api/v1/QYGLP0HT(需在 URL 附加?t13位时间戳)请求方式:POST请求头:Access-Id: 账号的 Access-Id (必填)Content-Type:application/json关键入参:ent_code: 企业编码支持统一社会信用代码或工商注册号必填flag: 穿透层次数字类型最大支持 4 层必填dir: 穿透方向可选值up向上穿透查询股东、down向下穿透查询对外投资必填min_percent: 股权穿透比例下限大于等于该比例的节点才会被纳入图谱必填max_percent: 股权穿透比例上限小于等于该比例的节点才会被纳入图谱必填鉴权与加密机制: 使用账户的 16 进制 Access Key 作为密钥采用 AES-128 算法的 CBC 模式。每次请求需动态生成 16 字节的 IV初始化向量并配合 PKCS7 填充最终将 IV 与密文拼接后进行 Base64 编码放入请求体data字段中。2. 标准化调用代码 (Python)以下代码展示了如何在投研股权图谱引擎中封装 AES-128-CBC 加解密通信模块并将解密后的多层股权节点解析为可供图数据库如 Neo4j直接入库的实体节点与待延伸探索队列importosimportjsonimporttimeimportbase64importrequestsfromtypingimportDict,Any,List,OptionalfromCrypto.CipherimportAESfromCrypto.Util.Paddingimportpad,unpad# 投研图谱引擎网关配置生产环境建议通过 KMS 或环境变量注入ACCESS_IDos.getenv(TIANYUAN_ACCESS_ID,您的_Access_Id)ACCESS_KEY_HEXos.getenv(TIANYUAN_ACCESS_KEY_HEX,0123456789abcdef0123456789abcdef)API_ENDPOINThttps://api.tianyuanapi.com/api/v1/QYGLP0HTclassEquityPenetrationGraphEngine:拟上市公司实控人溯源与多层股权图谱构建引擎核心客户端def__init__(self,access_id:str,access_key_hex:str):self.access_idaccess_id# 将 16 进制密钥字符串转换为 16 字节二进制密钥 (AES-128)self.key_bytesbytes.fromhex(access_key_hex)def_encrypt_payload(self,params:Dict[str,Any])-str: 采用 AES-128-CBC 模式与 PKCS7 填充加密股权穿透查询参数 plaintextjson.dumps(params,ensure_asciiFalse).encode(utf-8)# 每次请求动态生成 16 字节安全随机 IVivos.urandom(16)cipherAES.new(self.key_bytes,AES.MODE_CBC,iv)ciphertextcipher.encrypt(pad(plaintext,AES.block_size,stylepkcs7))# 将 16 字节 IV 与密文拼接后执行 Base64 编码returnbase64.b64encode(ivciphertext).decode(utf-8)def_decrypt_response(self,encrypted_base64:str)-Any: 从 Base64 响应密文中剥离前 16 字节 IV执行 AES-128-CBC 解密并还原 JSON 结构 raw_bytesbase64.b64decode(encrypted_base64)ivraw_bytes[:16]ciphertextraw_bytes[16:]cipherAES.new(self.key_bytes,AES.MODE_CBC,iv)decrypted_paddedcipher.decrypt(ciphertext)plaintextunpad(decrypted_padded,AES.block_size,stylepkcs7).decode(utf-8)returnjson.loads(plaintext)deffetch_equity_layer(self,ent_code:str,flag:int4,direction:strup,min_percent:str0.05,max_percent:str1.00,timeout:int10)-Optional[Dict[str,Any]]: 发起多层股权穿透请求并解密返回图谱数据 :param ent_code: 拟上市主体或中间层控股平台的企业编码 :param flag: 穿透层级深度1~4 :param direction: up 向上溯源实控人down 向下梳理控股子公司 :param min_percent: 持股比例下限过滤阈值 :param max_percent: 持股比例上限过滤阈值 ifflag1orflag4:raiseValueError(穿透层次 flag 必须在 1 到 4 之间)ifdirectionnotin(up,down):raiseValueError(穿透方向 dir 仅支持 up 或 down)timestamp_msstr(int(time.time()*1000))request_urlf{API_ENDPOINT}?t{timestamp_ms}business_params{ent_code:ent_code,flag:flag,dir:direction,min_percent:min_percent,max_percent:max_percent}headers{Access-Id:self.access_id,Content-Type:application/json}body{data:self._encrypt_payload(business_params)}try:resprequests.post(request_url,jsonbody,headersheaders,timeouttimeout)resp.raise_for_status()resp_payloadresp.json()# 若响应中包含加密的 data 字符串执行对称解密ifresp_payload.get(data)andisinstance(resp_payload[data],str):resp_payload[data]self._decrypt_response(resp_payload[data])returnresp_payloadexceptrequests.RequestExceptionasreq_err:print(f[GraphEngine] 股权穿透网络通信异常:{req_err})returnNoneexceptExceptionasdec_err:print(f[GraphEngine] 报文加解密或解析异常:{dec_err})returnNonestaticmethoddefparse_graph_entities(nodes:List[Dict[str,Any]])-Dict[str,List[Dict[str,Any]]]: 将穿透返回的节点列表归类为自然人实控人候选池、法人股东节点、以及待继续延伸穿透队列 ubo_candidates[]corporate_nodes[]expandable_queue[]fornodeinnodes:# 注意接口文档中对象类型字段名为 lableentity_typenode.get(lable,Other)share_ratiofloat(node.get(percent)or0.0)is_expandablestr(node.get(open,false)).lower()trueifentity_typeHuman:# 利用 pid 实现跨有限合伙平台的同名自然人消歧ubo_candidates.append({node_id:node.get(id),person_pid:node.get(pid),name:node.get(name),direct_percent:share_ratio})elifentity_typeCompany:corp_item{node_id:node.get(id),name:node.get(name),credit_code:node.get(creditCode),reg_status:node.get(regStatus),percent:share_ratio,can_expand:is_expandable}corporate_nodes.append(corp_item)# 若到达第 4 层边界且 open 为 true则将其 creditCode 加入下一轮递归穿透队列ifis_expandableandnode.get(creditCode):expandable_queue.append(corp_item)return{ubo_candidates:ubo_candidates,corporate_nodes:corporate_nodes,expandable_queue:expandable_queue}if__name____main__:engineEquityPenetrationGraphEngine(ACCESS_ID,ACCESS_KEY_HEX)# 示例针对某拟科创板上市主体执行向上 4 层股权溯源过滤持股 5% 以上的核心股东raw_responseengine.fetch_equity_layer(ent_code91310000XXXXXXXXXX,flag4,directionup,min_percent0.05,max_percent1.00)print(json.dumps(raw_response,ensure_asciiFalse,indent2))3. 终端快捷验证 (cURL)在接入图谱构建流水线前研发人员可通过以下 cURL 命令在终端快速验证网关连通性与签名配置curl-XPOSThttps://api.tianyuanapi.com/api/v1/QYGLP0HT?t1727512000000\-HAccess-Id: your_access_id_here\-HContent-Type: application/json\-d{ data: 5rWL6KVSVZfMTZCeXRlc19BbmRfYUVTX0NCQ19DaXBoZXJ0ZXh0X0Jhc2U2NA }2. 核心股权图谱数据解析与业务映射在构建拟上市公司多层股权图谱时解密后的节点属性直接决定了图数据库Vertex Edge的建模精度与实控人认定的准确性。以下为接口核心返回字段与投研图谱引擎的业务映射关系字段名称字段类型核心字段描述投研实控人溯源与股权图谱业务映射nameString公司或人名 (varchar(255))图谱节点展示标签主体名称用于生成股权穿透树节点名称及投研尽调报告披露名称idNumber公司或人 id图谱内部实体主键用于在同一批次穿透结果中构建“股东 - 被投资企业”的有向边Edge关联pidString自然人 pid (varchar(100))实控人合并核算核心字段当同一自然人通过多个员工持股平台或家族控股公司间接持股时利用pid进行跨路径身份对齐与同名自然人消歧lableString对象类型 (varchar(20))区分节点性质Company公司法人、Human自然人、Other其他组织/基金等。注意对接时需严格匹配字段名拼写lablecreditCodeString统一社会信用代码 (varchar(50))法人节点的标准外部工商标识用于关联外部司法涉诉、税务评级库以及作为下一轮递归穿透的ent_code入参regStatusString企业状态 (varchar(50))反映中间控股平台或下属子公司的工商存续状态如存续、迁出、注销等用于识别链条中的非存续异常主体openString延伸状态 (varchar(6))true代表该节点仍有未展开的上层股东或下层投资false代表已穿透至终端叶子节点。用于驱动超 4 层架构的递归拉取percentdouble股权占比直接持股比例。图引擎通过沿有向路径对各层percent求乘积并按同一pid求和自动推算实控人最终受益比例技术提示在将股权穿透图谱落库至投研数据仓库或日志系统时针对lable为Human的自然人节点其关联的pid及外部拓展的个人联系方式如手机号138****0000、证件号等 PII个人敏感信息必须执行掩码脱敏或加盐哈希存储。同时请注意接口返回的实体分类字段拼写为lable而非label在定义 Pydantic 数据校验模型或反序列化结构体时需保持严格一致。3. 场景化应用让核验数据赋能合规闭环拟上市主体向上四层实控人UBO溯源与累计受益权折算在 Pre-IPO 财务与法律尽调阶段系统将拟上市主体的统一社会信用代码作为ent_code传入设定dirup、flag4、min_percent0.01。Python 图引擎解析返回的节点列表后以lableHuman的节点作为穿透终点利用pid归并同一自然人在不同有限合伙企业及控股集团中的持股路径自动计算∑(∏percenti)\sum (\prod \text{percent}_{i})∑(∏percenti​)累计间接持股比例。若单一自然人或一致行动人累计受益比例超过认定阈值系统自动标记其实控人候选地位若发现顶层全部为lableOther或股权高度分散则触发人工复核提醒辅助保荐代表人核查是否存在无实控人情形或代持安排。突破 4 层复杂控股架构的增量递归图谱拼接部分大型产业集团或红筹回归企业的股权架构往往深达 6 至 8 层单次接口调用的最大层次flag4无法一次性触达最顶层自然人。在此场景下图谱构建引擎会扫描第 4 层边界处所有lableCompany的节点若某节点的open字段为true且percent高于核心关注阈值如0.10引擎会自动提取该节点的creditCode作为新的ent_code推入 Celery 异步任务队列再次发起dirup的穿透请求直至所有主干分支节点的open均收敛为false从而在 Neo4j 中完整还原任意深度的全景股权图谱。控股子公司向下穿透与合并报表主体存续合规巡检在评估拟上市公司下属业务板块与关联方交易时投研系统可将参数切换为dirdown、flag3、min_percent0.20快速拉取目标企业直接及间接参控股的子公司网络。系统在构建向下投资图谱的同时自动校验每个Company节点的regStatus字段若全部核心控股子公司均处于“存续”或“在业”状态则自动通过前置准入校验若发现重要参股或控股节点处于注销、吊销等非存续异常主体状态系统立即在尽调工作台高亮该分支链路并生成合规问询清单。4. 生产环境接入的安全与合规边界合规尽调授权与数据最小化采集在启动针对特定非公众企业或关联自然人的深度股权溯源前投研平台需确保已具备合法的尽职调查授权文件或合规业务委托书。对于穿透所得的自然人pid与持股明细应严格限制在投研合规团队内部访问遵循数据最小化与脱敏展示原则。全链路 AES-128-CBC 密文传输股权穿透查询涉及投研机构的重点关注标的与敏感立项信息。每次请求必须严格使用os.urandom(16)生成高熵随机 IV通过 AES-128-CBC 加密请求负载防止中间人通过分析明文报文窥探机构的投研标的池。递归图展开的限流与防环控制在基于opentrue进行跨层级递归穿透时部分复杂集团可能存在交叉持股或环形持股结构。Python 工程侧必须在内存或 Redis 中维护已访问节点的creditCode集合Visited Set以阻断无限递归死循环并结合令牌桶限流器控制并发请求速率保障上游接口与本地图数据库写入通道的平稳运行。