PHP 调用区块链存证接口前，先确认你真需要链上存证
不少项目团队容易陷入一个误区，以为“数据上链”就等于“法律有效”。其实不然。国内司法体系认可的电子存证，核心是构建一套完整的证据链条，它必须包含「可信时间戳」、「可验证的哈希值」以及「完整的操作日志」。这可不是随便调用一个区块链API就能自动实现的。
2026虚拟币交易平台推荐：
- 欧易（OKX）交易平台（>>>进入官网<<<）（下载OKX的Android安装包）
- 币安（Binance）交易平台（>>>进入官网<<<）（下载币安Android安装包）
目前，真正能被法院采信的，基本是那些已经接入最高人民法院「司法区块链平台」的几家机构，比如蚂蚁链、腾讯至信链、百度超级链。它们提供的才是符合司法要求的存证服务，接口通常是 submitEvidence 这类封装好的功能，而不是让你自己去连接比特币或以太坊的公共节点。
所以，动手写PHP代码之前，关键的第一步是做好准备工作：
- 确认你合作的存证服务商是否具备《电子认证服务许可证》，以及是否拥有司法区块链节点的正式接入资质。
- 仔细阅读他们提供的SDK或REST API文档，重点关注
hashType是否支持sha256——这是目前法院采信的主流算法。 - 检查接口返回的数据结构里，是否包含
evidenceId（存证编号）和timestamp（时间戳）这两个关键字段。如果没有，后续将无法在「人民法院司法区块链平台」官网上进行核验，证据效力会大打折扣。
用 cURL 提交合同哈希到至信链 API 的关键写法
以腾讯至信链的开放平台为例，它的核心要求是传递原始合同文件的 sha256 哈希值（而非文件本身），并且请求必须附带签名。PHP开发在这里翻车的案例可不少。
常见的报错现象包括：401 Unauthorized（签名错误）、400 Bad Request（哈希值长度或格式不对）、或者返回 "code":5001（时间戳超时）。
要避开这些坑，有几个实操要点必须牢记：
- 计算哈希：务必使用
hash_file('sha256', $filePath)函数直接计算文件哈希。切忌使用md5_file，也避免先读取文件内容再用hash('sha256', $content)，因为文件编码、换行符（\n vs \r\n）甚至不可见的BOM头都可能导致最终哈希值不一致。 - 生成签名：签名算法通常要求使用HMAC-SHA256。签名字符串的拼接格式一般为
$method.$uri.$timestamp.$body，其中body是标准的JSON字符串（确保没有多余空格）。签名密钥就是平台分配的secretKey。 - 设置请求头：除了常见的Content-Type，通常还需要携带
X-TX-Nonce（一个随机生成的8位字符串）和X-TX-Timestamp（当前秒级时间戳，与服务器误差不能超过300秒）。 - 发送请求：不要使用
file_get_contents来发送POST数据。正确做法是使用cURL库，并通过curl_setopt($ch, CURLOPT_POSTFIELDS, $json)设置请求体，这样可以避免中文等字符出现乱码问题。
$body = json_encode([
'evidenceHash' => hash_file('sha256', '/path/to/contract.pdf'),
'businessId' => 'CONTRACT_20240520_XXXX',
'fileName' => 'service_agreement_v2.pdf'
], JSON_UNESCAPED_UNICODE);
$signature = base64_encode(hash_hmac('sha256', "POST./v1/evidence/".$timestamp.$body, $secretKey, true));
存证后怎么让合同 PDF 自动带「存证标识」水印？
合同完成存证后，还有一个提升用户体验和法律效力感知的关键步骤：让生成的PDF合同文件本身带上“已区块链存证”的标识。这本质上属于PDF后处理，与区块链调用是两回事。
这里有个常见的误区：试图用PHP的GD库直接在PDF上绘制文字水印。GD库是处理位图图像的，而PDF是矢量格式，强行转换会导致文件失真，放大后模糊不清。
正确的技术路线是：
- 推荐工具库：使用
setasign/fpdi配合tcpdf的组合。FPDI负责导入原始PDF页面，TCPDF则用来生成包含水印文字和二维码的新图层，最后进行叠加。 - 二维码内容：水印中的二维码，其内容必须是可直接跳转的存证查询地址，例如
https://ecourt.gov.cn/chain/verify?eid=xxxxx。直接放哈希值是没用的，用户无法直接验证。 - 水印设计：水印位置建议放在每页的右下角，透明度设置为
0.15左右，既清晰又不遮盖原文。字体最好选择像helvetica这类系统普遍预装或法院文书常用的字体，避免使用某些特殊字体导致在他人电脑上渲染异常。
验证环节 PHP 怎么校验存证结果是否真实有效
这是最不能掉以轻心的一环。后台调用存证API返回了“成功”，并不等同于数据已经牢固地写入了区块链。必须进行主动验证，否则一旦发生纠纷，你将拿不出任何有效的自证依据。
一个完整的验证逻辑应该包含三层，层层递进：
- 接口状态验证：调用存证服务商的查询接口（如至信链的
/v1/evidence/{evidenceId}），检查返回数据中status字段是否为'SUCCESS'，并且blockHeight（区块高度）大于0。如果区块高度为0，意味着交易还未被区块链网络确认。 - 哈希值核验：在本地再次使用
hash_file('sha256', $localFile)计算合同文件的哈希值，并与接口返回的evidenceHash进行严格比对（注意区分大小写）。这一步是验证文件在传输和存储过程中是否被篡改的核心。 - 防篡改存根：将接口返回的关键链上凭证，如
merkleRoot（默克尔树根）和txId（交易ID），存入你自己的业务数据库。当用户未来对存证提出质疑时，你可以直接提供这些值，引导其前往「人民法院司法区块链平台」官网进行独立、公开的验证。
最后必须提醒的是，存证过程并非一劳永逸。有时接口可能返回 status === 'PENDING'（处理中）。这时，后台需要实现一个简单的轮询机制（例如最多重试3次，每次间隔2秒），而不是直接告诉用户“存证已完成”。
说到底，技术实现上的最大挑战，往往在于“哈希一致性”——你本地计算的、提交给链的、最终法院平台比对的，这三处的哈希值必须一字不差。任何一个细微的差别，比如PDF里多了一个空格、换行符格式不同，都会导致整个存证链条失效。这才是关键所在。
