合同字段从哪里来
签署不是把一段正文和一个邮箱发出去。至少要区分三类数据：俱乐部维护的客户资料、已发布的模板内容、签署过程中产生的填写值和证据。
谁维护，接口取什么
| 数据 | 来源及维护方式 | Partner 接入方的做法 |
|---|---|---|
| 人员 ID | SportsX 创建人员时分配；本地业务 ID 是另一套标识 | 保存 data.contactId；已有人员先查询匹配，始终按字符串传 ID |
| 姓名、电话、生日 | 商户维护的俱乐部人员资料；生日不是每次发送时上传的年龄数字 | 调用 GET /v1/club/contacts/{id} 核对；可用 PATCH /v1/club/contacts/{id} 更新支持的字段 |
| 收信邮箱 | 签署人的联系邮箱，由服务端查找并形成收件记录 | 发送前核对签署人详情。人员 PATCH 只能为尚无邮箱的人设置身份邮箱，已有邮箱不能修改 |
| 家长和孩子关系 | 已维护的家庭及成员关系，不靠姓名猜测 | 调用 GET /v1/club/contacts/{id}/households 核对 relation 与 contactId；维护关系见家庭接口 |
| 俱乐部法定名称、地址、隐私联系信息 | 商户的合规资料；联系邮箱、电话来自组织资料 | 发签署请求时不传这些字段；缺失或不准确时回到后台维护 |
| 课程、排期、价格等合同内容 | 商户编制模板时的 authoringInputs 及发布版本 | 读取模板详情核对；不是在签署 POST 中传价格或排期覆盖 |
| 地区及文档适用规则 | 俱乐部合规配置、模板版本的 jurisdictionProfile 和附加文档规则 | 使用 resolve-waivers 的结果辅助选文档；不要在接入代码中硬编码某个法案的年龄阈值 |
| 字段定义和签署要求 | 模板详情中的 fields、signingRequirements | 核对需要填写、确认、首字母或签名的要求；不自行推断所有模板都相同 |
| 姓名填写值、签名、首字母、同意动作 | 签署人在 SportsX 签署页完成，按文档要求记录 | Partner API 用于发起和查询，不代替用户提交签名 |
| 打开/签署时间、IP、User-Agent、文件证据 | 服务端签署流程记录；部分值可能缺失 | 查询事件、签署详情及文件，不伪造缺失值，也不把 IP 当成身份验证结果 |
完整人员详情需要 club.contacts.read_pii，修改资料需要 club.contacts.write。应最小化本地保存的个人数据，不要将真实资料直接放入工单或调试日志。
同样叫 contactId，含义不一样
| 调用 | contactId 的含义 | 家长为孩子签署的例子 |
|---|---|---|
POST /v1/club/compliance/signing-requests/resolve-waivers | 用于判断文档适用性的参与者 | 孩子 3102 |
POST /v1/club/compliance/signing-requests/preview | 签署人 | 家长 3101，另传 dependentContactId: "3102" |
POST /v1/club/compliance/signing-requests | 接收邀请并签字的人 | 家长 3101，另传 dependentContactId: "3102" |
成年人本人签署时，不传 dependentContactId。普通家长代签也可以是 flowFlavor: "standard"；parental_consent 是专门流程，不是“签署人是不是家长”的通用开关。
家庭关系查不到、存在多个可能签署人、双方资料不一致时，先请商户确认。API 能接收两个 ID，不代表已经替你确认了签署授权。
模板、版本和变量不是一回事
模板详情中的 id 是模板 ID。currentVersion 是版本序号，currentVersionId 才是发送时 items[].templateVersionId 所需的版本 ID。documentKind 从所选模板读取，不根据标题猜测。
fields 说明模板有哪些字段。重点看 fieldKey、fieldType、sourceType、sourceRef、required、editableBySigner：这是对字段的定义，不代表所有值已经在预览里填完。required 与请求中的 items[].required 也不同，后者表示整份文档是否必签。
当前 Partner 的 preview/create 接口没有 variables、fieldValues 或任意 merge-fields 参数。 不能通过添加这些键临时改合同正文、价格或客户生日。资料错误先修资料；合同错误请商户修改并发布合适的模板版本，再预览发送。
年龄和附加文档如何判断
当前附加文档解析读取该俱乐部人员资料中的生日，计算调用时的年龄，并参考俱乐部地区配置判断成年与否。这不是允许客户端直接传入 age: 26 的接口，也不是所有法规都共用一个年龄规则。
服务端在生日缺失时会返回 dobMissing；运动项目的附录无法确定时会返回 appendixMatch。接入方需要把这些不确定性留给商户处理，不能把“没有默认选中”显示成“不需要签署”。
详细的法律文本和规则由模板及地区配置负责。这里解释接口行为，不代替对具体课程、地区或签署人的法律判断。
预览值和最终证据要分开验收
商户预览主要合并模板正文与组织资料。签署人的姓名等字段可能仍是占位符；实际签名、首字母和时间等要到签署阶段才有。
不要将预览 Markdown 当作最终合同存档，也不要因传入正确的 contactId 就认为最终文件一定已完整填好。接入验收必须打开实际签后文件，逐项核对：
- 合同对应的家长和孩子是否正确，姓名、生日、关系是否与确认的资料一致。
- 课程、价格和选中的模板版本是否正确，必签项是否全部处理。
- 签署时间、事件记录、签后文件和完成证明是否能相互对应；缺失数据应保留为空或报告问题，而不是补造。
尤其要单测“生日只在俱乐部资料中维护”以及“standard 流程由家长代签”两种情况。它们能发现仅验证 API 字段类型时看不到的最终文件渲染问题。