Wyndham-RSVN-0918/docs/project/integrations/ohip-ta-reference-alternatives-20260918.md

TA / Tour Code：扩大范围后的接口候选

日期：2026-09-18。用户授权扩大查证范围，把作用相近的接口也列出供业务确认；尚未批准用其他字段替换 Stay Details → TA Record Locator。本轮只查公开契约和官方说明，没有改业务代码、模拟器、权限或酒店数据，没有创建子智能体。

供业务确认的选择

选择	可以实现的业务作用	Oracle 页面位置 / 与 TA 的关系	当前证据与限制
A. 保留 TA Record Locator	Tour Code 写入指定 TA 输入框并按 TA 查找	用户截图中的原位置	数据字典有类型证据，普通 externalReferences 路径存在；特殊 TA_RECORD_LOCATOR 写读仍未直接证实
B. Custom Reference Number（优先考虑的替代）	保存团号、修改、读回、按团号找预订	Stay Details 的另一个标准字段；不会因使用它就证明原 TA 已填写	customReference 的写/读/搜索路径明确，最长50字符；酒店需确认此字段可用及页面是否已显示
C. External References（普通外部参考号）	按来源系统保存参考号、读回、按来源和编号查询	External References 详情入口；普通类型不等于 TA	使用酒店已有且可用的外部系统类型，不自行编造代码；已证实通用写读结构，酒店配置与重复编号行为待实际验证
D. Reservation UDF / Flex Field（预订自定义字段）	增设明确名为 Tour Code 的字段，存储和查询团号	通过 Page Composer 配置显示位置、标签；不等于原 TA	写读结构明确，官方有界面搜索能力，REST有 flexChar；实际UDF编号及REST搜索字符串格式尚待确定，配置工作更多

选择 B/C/D 会改变业务字段位置与后续查找方式，需用户明确接受后才调整代码和模拟参数。原有 GROUP/FIT TA = Tour Code / Block Name 规则及正式守卫目前保持；有值原样填写，无值不生成、不因更新缺值主动清空旧值。

已核实的公共接口

重新下载 Oracle Property API 26.3 的 RSV、BLK、BLKASYNC，以及平台0.11.0公开OpenAPI。RSV与此前保存的26.3文件逐字节一致。这里“已存在”指公开契约存在，不代表用户应用权限、当前程序已采用该方案或真实酒店验收已通过。

操作	Oracle 原生入口	现有平台入口
postReservation 新建	POST /rsv/v1/hotels/{hotelId}/reservations	POST /api/v1/reservations
putReservation 修改	PUT /rsv/v1/hotels/{hotelId}/reservations/{reservationId}	PUT /api/v1/reservations/{reservationID}
getReservation 详情	GET 同上	GET 同上
searchHotelReservations 搜索	POST /rsv/v1/hotels/{hotelId}/reservations/searches	POST /api/v1/reservations/searches
getHotelReservations 列表搜索	GET /rsv/v1/hotels/{hotelId}/reservations	GET /api/v1/reservations
getReservationByExtId 按外部编号取详情	GET /rsv/v1/hotels/{hotelId}/externalSystems/{externalSystemCode}/reservations/{reservationExternalId}	GET /api/v1/external-systems/{externalSystemCode}/reservations/{reservationExternalID}

B/C/D 的基本存储、修改、详情和搜索均有现有入口，暂不需新增封装。平台 getHotelReservations 查询白名单包含 customReference、externalReferenceIds、externalSystemCodes、taRecordLocatorList、flexChar。POST搜索接收对应Oracle JSON对象。写入需使用既有 ConfirmedWriteRequest，原生请求置于 payload，不能省略确认上下文和幂等信息。

B：Custom Reference 的参数已对清

官方 RSV 对 customReference 的定义是用于识别预订的自定义参考号，字符串，最多50字符。新建/修改和详情的容器不同：

用途	Oracle JSON 位置
新建	/reservations/reservation/0/customReference
修改	/reservations/0/customReference
详情读回	/reservations/reservation/0/customReference
POST搜索	/customReference
GET列表搜索	查询参数 customReference

以下仅为相关字段片段，不是完整预订请求，也未执行：

{"customReference":"LT260517B"}

若用户接受此位置，可把员工确认的 Tour Code 写到该字段，并用相同值搜索，再按实际 Reservation ID、住期等条件核对；不能假定同一团号只对应一间房或一笔预订。历史 TA 数据不会因此自动出现在 Custom Reference 中，切换时需明确历史查询兼容方式，不能批量迁移或覆盖。

Oracle Updating Reservations 的 Stay Details 部分明确列出 Custom Reference Number，并说明可用它搜索预订。页面可见性受酒店定制影响。它可能已有用途：官方渠道控制说明中，SET_RECORD_LOCATOR_CUSTOM_REFERENCE 可将GDS/ADS编号填入Custom Reference。因此选择前需由酒店确认该字段没有被其他业务占用，不操作这些渠道开关来试探TA。

C：普通 External References 的参数

新建、修改、详情分别在上述 B 容器下，将末尾字段换为 externalReferences；每项包含 id、idContext，可选 idExtension。RSV预订父类型说明限制 id 最多50字符、idContext 最多20字符。

{
  "externalReferences": [
    {"idContext":"<酒店确认的现有类型>","id":"LT260517B"}
  ]
}

搜索使用 externalReferenceIds 和 externalSystemCodes 数组。详情按类型选择对应项，保留其他来源的参考号。idContext 不应直接填团号，也不自行创建外部系统类型。Oracle External References 操作说明明确其Type/ID/Leg及搜索用途；外部系统配置说明解释来源系统配置。

getReservationByExtId 是另一种预订寻址方式，不是新TA字段。同一Tour Code可能涉及多个实际预订，优先用列表搜索，再按内部Reservation ID操作；不能未经验证就把团号当成这个单笔详情路径的唯一编号。Oracle另有 putReservationByExtId，当前平台未发布该Operation ID，但普通 putReservation 已能按内部ID修改，不构成本方案的必补接口。

原TA候选 idContext="TA_RECORD_LOCATOR" 与普通类型分开判断，仍以原TA专项证据中的限制为准。

D：预订 UDF / Flex Field 的参数

新建、修改、详情分别在B的对应容器下使用：

userDefinedFields.characterUDFs[].name
userDefinedFields.characterUDFs[].value

characterUDFType 推荐名称为 UDFC01 至 UDFC40；必须选择酒店确认可用的槽位，不直接占用第一个。Schema中的 name 最多20字符，value 最多2000字符；这不是酒店实际输入控件限制的保证。alternateName 不能代替酒店Page Composer配置，也不能认定写入它就会新增页面字段。

Oracle Page Composer说明允许在预订Stay Details增加Flex Field、调整标签；Flex搜索说明说明到店、在住、离店高级搜索与结果列的配置。

RSV GET/POST搜索有 flexChar 字符串数组，平台已承载；但当前schema描述及两份官方Postman集合没有给出“字段名与值”如何编码在字符串中的明确示例。本方案不能将REST搜索格式标为已完全对清，也不编造 UDFC01=... 等格式。

其他相近接口：用途与封装状态

对象 / 接口	官方用途和参数	对本任务的判断
Block TA：postBlock / putBlock / getBlock	reservationDetails.taRecordLocator，最多50字符；新建/读回 /blocks/blockInfo/0/block/reservationDetails/taRecordLocator，修改 /blocks/0/reservationDetails/taRecordLocator	真实明确的团队字段，平台已有；不能把Block头字段直接当作独立FIT的Stay Details字段
postRoomingList / putBlockReservations	POST /blk/v1/blocks/{blockId}/roomingList；PUT /blk/v1/blocks/{blockId}/reservations	团队下批量创建/修改。平台本次目录未发布这两项；schema仍使用通用预订对象，未发现可绕过TA映射缺口的专用预订TA属性。不能为填写FIT团号而引入Block关系和房量扣减
Guest Locator：getReservationLocators / postReservationLocators / changeReservationLocators / deleteReservationLocators	/rsv/v1/hotels/{hotelId}/reservations/{reservationId}/guestLocators，修改/删除追加 /{locatorId}；核心 locatorText、起止日期/时间	记录客人在会议室等位置，供前台转接电话/递送；不是预订团号。平台仅有专用查询入口，不建议为本需求补包写入口
GDS Record Locator	RSV搜索属性 recordLocator 明确描述为GDS编号	不等于TA或任意Tour Code；渠道控制可投影到Custom Reference或External Reference，不构成直接TA写入证明
Reservation Notes / Comments	预订备注可存团号说明，接口已有	可辅助员工查看，但不是结构化编号搜索的等价替代，不建议单独承载身份匹配
Business Event / GraphQL TA 字段	事件/报表中的TA值	只能补充读取或事件观察证据，不提供当前FIT写入闭环

Guest Locator用途依据Oracle26.3官方说明，并由当前RSV26.3的Guest Locator类型与操作说明交叉核实。首次浏览工具取该页面失败；用户再次提供链接后，通过直接公开HTTPS取得HTTP200和完整正文，确认现行26.3仍是客人临时位置用途，原始HTML已保存在本轮忽略证据目录。团队房表约束及TA页面列依据26.3 Rooming Lists说明，页面有TA列不能单独证明REST有同名写入属性。未要求或执行文件上传。

用户指定的 Locators 与 Notes 两页复核

用户提供的Managing Reservation Notes明确允许一笔预订记录多条备注，在各预订状态下新增，并设置类型、内部标记、标题和通知区域。Notes可存放Tour Code供员工查看，属于另一显示位置；未取得通过备注内容直接按团号搜索预订的契约证据，不能因此替换TA匹配逻辑。

Notes通过现有 postReservation / putReservation 写入；通过 getReservation?fetchInstructions=Comments 读回。Oracle层新建数组路径为 /reservations/reservation/0/comments，修改为 /reservations/0/comments，详情返回为 /reservations/reservation/0/comments。条目内参数对应如下：

Notes页面项	Oracle条目参数	说明
Type	comment.type	使用酒店实际备注类型代码
Internal	comment.internal	内部备注标记；手册说明一般不输出到信函/报表，具体报表例外另看其配置
Title	comment.commentTitle	备注标题
Notification Area	comment.notificationLocation	预订、在住、收银或通用区域；具体代码值需酒店目录/已证样例，不把页面显示词直接猜成代码
Comment	comment.text.value	备注正文
修改已有备注的身份	id	数组条目上的备注ID，不是 comment 内的ID

本机FIT新建Converter已发送 comments[].comment.text.value，修改Converter还携带已有备注 id。这证明本地正文映射已实现，不证明类型、标题、Internal和通知区域都已显式配置，也不等于真实酒店已验收。页面说明正文最多2000个单字节字符；当前本地预订验证允许最多16000字符，RSV formattedTextTextType.value 没有对应maxLength。记录此差异供备注长度验收核对，不能把界面限制直接断言成已证实的REST硬限制，也不能用本地16000上限保证Oracle接受。本轮未改这些业务代码。

Locators的实际输入是起止日期、起止时间和Location文本，对应 dateSpan、timeSpan、locatorText；包含位置的文字虽然可自由填写，官方用途仍是电话/递送的临时位置指引。其独立增改查删接口与当前平台查询入口见上表，不为Tour Code用途补包或启用写入。

证据与下一步

官方Schema：RSV、BLK。平台：公开OpenAPI。本机原始文件、SHA256、结构化路径、平台入口对照保存于忽略目录 .planning/fit-ta-alternatives-20260918/。异步规范首次尝试了错误的 /property/async/ 公开路径并得到404，随后按官方仓库树定位 /property/v1/blkasync.json，已成功取得26.3规范；不将404记作接口不存在。

待用户确认的产品选择是：必须写回原TA输入框，还是接受B/C/D的另一显示位置。优先请用户判断B是否符合酒店操作习惯、字段是否已被占用。确认后再编写相应映射、历史查询兼容和模拟；真实系统操作继续由用户执行。此轮没有实际预订调用，没有改变原守卫，也没有把公共契约检查当作真实字段验收。