Phygitals申领订单为何停在partially_submitted？核权限、结算legs与物流
链小知 · 进阶 · 核验 · 依官方文档整理
用已有脱敏Vault记录区分报价、预订、分腿结算和finalized，避免把列表缺单或局部成功当申领失败/全部完成。
开始前准备
- 准备已有申领材料：API key公开id（不包含secret）、权限范围、owner_wallet、quote_id/session_id、报价时间与费用、已有proof元数据、order_id、各leg fingerprint与结果、订单及每卡状态。地址/联系方式脱敏，不额外取得个人数据。
- 按2026-10-14公开正文核已有脱敏记录，verification=documentation；不登录、创建key、连接钱包、请求业务API/RPC、构造或签名交易、付款、提现、生成证明或申请寄送。
1. 确认Vault权限与原订单所属账户
Public API文档列用户范围phy_ key，经X-API-Key或Bearer提供；Vault六个端点都需要vault.claim，不因其他目录端点可公开读就认定订单匿名。每次调用带持卡的on-curve Solana owner_wallet，同一key账户完成后续核对；该字段在signed-in web sessions会被拒绝，不能混套登录网页方法。401核key/撤销/权限，404可能是订单不存在或不属于该账户，不直接当资产没有。
检查结果：key公开id、vault.claim、持卡wallet与原订单双方范围一致；secret不进入核对表。
2. 报价是15分钟窗口，金额与卡/地址绑定
price-estimate接受1至100项{type,address,slug}和shippingDetails；items或地址变化须重新报价。记录quote_id、session_id与withdrawal_fees、shipping_cost、total_cost，文档示例的金额不是固定费率。报价有效15分钟；过期仅在重新定价后总额不变时仍可能接受，不能保证可用。此API申领用链上USDC付费，不支持卡/Pack Credits；quote阶段尚未预订或扣费。
检查结果：卡牌、地址版本、时点与USDC total_cost明确；过期/缺费用只记待核，不套示例报价。
3. 仅比对已有holder proof，不创建签名
claim-init要求wallet_proof={tx_signature,timestamp}。已有proof交易须由owner_wallet作fee payer，恰有一个SPL Memo且文本为phygitals:claim:<key id>:<quote_id>:<timestamp>，timestamp为Unix秒；交易确认后提供，至多5分钟旧。key id是公开标识，不能拿API secret代替。没有这些已有元数据只确认文档条件，不构造、提交或生成proof；其他Vault端点不需要新proof。
检查结果：wallet、公开key id、quote及秒单位相符，确认时点/唯一Memo缺证据即保留未知。
4. 预订订单与链上结算分开
claim-init消费报价，创建运费/费用一leg加每卡一leg，初始均pending，order_id对应报价session_id；重复已预订quote返回同order_id，不在此阶段移动链上资产。USDC不足或卡已转走/冻结/进入escrow/存在进行中申领时拒绝，quote仍可复用但需核当前条件。transaction_init订单隐藏于列表却可按id看；列表无单不能替代按原id与原key账户的记录。
检查结果：order_id/session_id与所有pending legs对应；预订和扣费/转卡各有独立结果。
5. 按leg fingerprint核局部成功与续接
claim-request-txs的mode=transactions返回费用USDC转移与卡转移，每笔至多两张卡、每次至多20个legs，不能把20读成卡数或交易数。已有finish材料按order_id、owner_wallet及原返回type/fingerprint/addresses对照，已签tx字段也须对应；该路径文档称平台付网络费。success=false是已确认但出错，重新取新交易才是官方恢复方法；同leg最多重建3次后retry=true，已settled腿从不重建，不能重发旧blockhash字节或盲重全部订单。
检查结果：每leg结果、fingerprint、费用腿与卡腿分清；局部成功未写全部完成，重试未重复已settled腿。
6. 最后finish后仍需finalized收口
partially_submitted表示只完成部分legs，永远不会自行推进，应从request-txs阶段续接。最后一笔finish之后还要再取一次request-txs，直到mode=finalized；该返回才写tracking并推进订单，带每项状态、bundle id和fee paid。processing表示所有legs settled、进入履约；failed看error_message，cancelled是终态，不能仅凭一个success=true断言所有卡已寄出。
检查结果：记录mode=finalized与各leg/每卡状态；没有finalized则保留未收口。
7. 订单、每卡与分仓物流分别验收
order接口只返回原key账户的订单及公开字段，不暴露内部员工字段。分别核order status、item_statuses中的received/pending/failed、tracking_ids和vault_statuses；transit为承运途中、tracking_available为已寄且有单号、delivered为送达。多仓可分多个包裹，不能一个tracking覆盖所有卡。官方申领确认开始processing不可取消；成功处理并寄出后数字卡退役，不能在预订时就认定销毁。仓储/保险声明与实际交付证据分开，没有收货材料只确认公开状态含义。
检查结果：每卡、分仓tracking与整体状态有独立记录；不可逆处理及数字退役时点准确，未将报价估值当赔付/送达保证。
怎样确认完成
- 得到quote→预订→逐leg→finalized→逐卡/逐仓物流的有界状态记录。
- 记录缺证据或所属账户不明的分支；文档核验不表示本人申领、履约或保险赔付已成功。
常见错误与边界
- API holder-wallet申领路径与网页支付/签名会话不同；权限与原订单账户必须一起核。
- 429可能涉及请求窗口或提现日额度，不能统一按一分钟重试；具体额度未明不补数字。
- 数字所有权、实物保管、合作方保险和物流完成需要不同证据。