---
title: 天河链官方文档勘误与联调坑
type: experience
permalink: main/projects/d44c219a-0b31-4de1-b160-323eb34a4c6a/天河链官方文档勘误与联调坑
stable_id: 92e5c8d9-c4ef-4ab7-99ac-1b81f3228b59
scope: project
project_id: d44c219a-0b31-4de1-b160-323eb34a4c6a
memory_type: experience
status: active
revision: 1
restored_from_commit: 6a6a895eafcca6052e81a14fca103a42635dd1c2
created_at: '2026-09-23T15:07:46.337350+00:00'
updated_at: '2026-09-23T15:07:46.337422+00:00'
tags:
- blockchain
- tianhe
- pitfall
---

勿被官方文档（语雀版）误导，以 APIFox 在线文档 + 实测为准：
- 交易详情接口（接口5）真实路径 `/api/v2/nfr/transaction/detail`（语雀少 `/nfr`）。
- 确认接口（接口9）是 GET 但参数放 JSON 请求体（query 会报 "request body missing"），需用 `node:http/https` 底层发带 body 的 GET，appKey 不进 URL；`status` 语义 "0x0"=成功否则失败。
- upload 的 multipart 必须手工构造：whatwg FormData+Blob 会被 undici 强加 filename 导致 500；userDto 分段需“无 filename + Content-Type: application/json”。
- publish 的 `operateId` 限 20 字符；name≤42、author≤120、feature≤500。
- 确认接口对纯存证 upload 交易结构性返回 `500 "Index: 3, Size: 1"`（非偶发），仅对 token 交易有效。
- 发行可能返回 tokenId=-1，需确认后回填。
- 接口成功只代表交易已提交，不代表链上最织确认；实测 mint 提交同秒即可查到进块。
- 严格校验 `code===0` 且 publish 必须返回交易哈希，否则走 FAILED，杜绝用本地 dataHash 冒充链上哈希的“假上链”。
- 本地 `/uploads/` 相对路径不能直接写链（feature），发行前以 BASE_URL 转绝对地址。
- 天河请求/响应/异常文本与持久化 raw 必须脱敏 appKey/userKey/newUserKey（先脱敏再截断）。