旅客與個資
旅客是一張訂單上實際出行的人,不是登入帳號。證件號碼加密保存,畫面只顯示遮罩,要看完整號碼得另外申請並留紀錄。
旅客與會員的差別
| 概念 | 是什麼 | 在哪裡看 |
|---|---|---|
| 會員 | 登入帳號,也是訂單的訂購人 | 後台 →「客戶」→「旅客會員」 |
| 旅客 | 某張訂單上要出行的人 | 訂單頁「旅客」分頁 |
同一個人可以出現在很多張訂單上,每次都是一筆旅客資料。訂購人本人也是一位旅客,標示為「主要聯絡人」。不要把旅客資料當成客戶主檔。會員的管理見會員與會員中心。
旅客資料
在訂單頁「旅客」分頁的「旅客本團資訊」卡管理名單:
- 新增旅客:選「只補名單(席次已買)」或「加一席(多收一人團費)」。
- 編輯、移除,或把旅客拆出成另一張訂單。
- 列印旅客名冊。
每位旅客的資料:姓名、身分證、護照、生日、性別、電話、Email、LINE、國籍、英文姓名(同護照)、護照效期、護照影本、通訊地址、緊急聯絡人、飲食、過敏/病史、分房偏好。
修改期限: 出發前第 7 天(含)仍可修改;第 6 天起名單凍結,畫面顯示「出發前 7 天內,名單已凍結」。一張訂單有多個梯次時,以最早出發的梯次計算。已取消或已完成的訂單不能修改。分房偏好不受這個期限限制。
名單凍結後還要改: 凍結期內,員工在旅客分頁仍可以編輯、新增、移除、拆出旅客。編輯與新增前會跳確認視窗;移除與拆到別梯在原本的確認對話框顯示同一段提醒。提醒內容:名單可能已經送入山證、投保,改完請同步修改送件與保險。
- 每次修改都記在訂單「紀錄」分頁,標示「凍結期修改名單」。飲食、醫療備註等欄位記舊值與新值;姓名、證號、生日等個資欄位只記欄位名稱。
- 改到姓名、英文姓名、身分證號、護照號、生日、國籍,或名單多一人、少一人時,梯次的出團準備出現「重新送件與投保」待辦。見出團準備。
- 客人在前台仍不能修改,也不能上傳或確認護照。
國籍: 從固定的國家清單選,畫面顯示中文國名。國籍留空視為本國旅客。舊資料存了對不到的國名時,畫面顯示「國籍待確認」。
›API 對應
旅客沒有獨立資源,隨訂單讀寫。讀取 GET /orders/{id} 的 travelers[]。寫入需 order.update:
| 操作 | 端點 |
|---|---|
| 新增 | POST /orders/{id}/travelers(回傳 travelerId) |
| 修改 | PATCH /orders/{id}/travelers/{travelerId} |
| 移除 | DELETE /orders/{id}/travelers/{travelerId} |
| 只改分房偏好 | PATCH /orders/{id}/travelers/{travelerId}/rooming |
主要欄位:fullName、idNumber/passportNo(寫入即加密;讀取只回 idNumberMask/passportNoMask)、birthDate、gender、phone、email、lineId、lineDisplayName、englishName、nationality、passportExpiryDate、address、emergencyContactName、emergencyContactPhone、diet、medicalNotes、roomPreference、roommatePref、surveyAnswers。回傳另有 isPrimary(主要聯絡人)與 roomLabel(已配的房間)。
birthDate、passportExpiryDate要是真實存在的YYYY-MM-DD,否則回422 validation。新增與修改時傳null或空字串表示未填;代客建單POST /orders不填就省略。englishName只收大寫英文、空白、連字號、逗號。nationality存 ISO 3166-1 alpha-2 代碼(也接受 alpha-3,例JPN)。新增時省略會存TW;傳空字串或null表示未知。無法辨識的國名回422。修改其他欄位時省略nationality,可保留待確認的舊值。- 資料版本過期或被並行操作鎖住時回
409 conflict,請重新讀取後再試。修改不會部分提交。
curl -X POST "https://your-tenant.example.com/api/v1/orders/$ORDER_ID/travelers" \
-H "Authorization: Bearer $TOKO_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "fullName": "王小明", "birthDate": "1990-05-30", "idNumber": "A123456789" }'資料完整度
系統逐欄檢查旅客資料,把問題標出來。缺漏只做標示、不擋存檔,你可以分次補齊。訂單會顯示「N 位資料不完整」或「N 位資料待補」,並列進出團前待辦。
每位旅客都要有: 電話、生日、通訊地址、緊急聯絡人姓名與電話、Email、LINE ID。
證件看國籍:
- 本國旅客(國籍留空或台灣)一定要有身分證。國家公園入山入園申請不收護照。
- 外國旅客一定要有護照。
- 國籍留空又只有護照時,分不出本國或外國,系統提示「國籍未填」,請補國籍或身分證。
本國旅客另外檢查格式: 電話須包含完整區碼或國碼,國際號碼接受 +國碼 或國碼開頭。少碼、區碼缺漏仍為錯誤。台灣地址要對得到縣市與鄉鎮市區,身分證檢查碼要正確。手機與緊急聯絡人電話相同、性別不是男或女、生日早於 1900 年、緊急聯絡人是同團隊員,也會標出來。同一電話的國內與國際寫法視為同號。
有效國際電話與海外地址只列提醒: 不算資料有誤或缺件,也不要求送籤匯出確認。承辦可在訂單旅客卡逐項按「確認沒問題」。系統記錄確認人與時間,確認後移除提醒。電話、緊急電話、地址、國籍或所屬訂單改變後,須重新確認;改回原值也一樣。
GET /departures/{depId}/validation-summary 的錯誤、待補與缺件人數,都排除這些聯絡資料提醒。提醒確認從後台旅客卡操作,API 與 CLI 沒有新增確認命令。
例外:會擋下的情況:
- 客人在前台自助報名時,必填欄位要一次填齊(格式問題不擋)。
- 行程啟用抽籤實名制的抽籤梯次,以及受限名額的行程,每位旅客都要有身分證或護照號碼。缺件或清空最後一個證件號會被拒絕。
- 必填的調查題沒答。
- 送籤匯出時,有問題的旅客要先確認才能匯出,見入山入園申請與送籤。
報名調查項
行程設定的調查題(餐點、上車點、裝備意願等)由每位旅客各自回答。客人在前台報名時填寫;後台代客建單或新增旅客時也能填。
- 必填題沒答、選了已停用的選項、或答了不屬於這個行程的題目,整筆操作會被拒絕。
- 選擇題的選項全部停用時,該題不必填。
- 已停用的題目或選項,舊答案保留。
題目設定見行程與梯次。
›API:答案格式
建單前先讀 GET /departures/{depId}/survey(trip.read),取得題目 id、kind、required 與選項 id、disabled。用這些 ID 填每位旅客的 surveyAnswers,不要用題目文字當 ID。
| 題型 | 答案欄位 | 規則 |
|---|---|---|
single | optionIds | 剛好一個選項 |
multi | optionIds | 選項集合,重複值會去除 |
quantity | quantities | 選項 ID 對應 0–999 整數;0 視為未選 |
text | text | 去掉頭尾空白後最多 500 字 |
{
"surveyAnswers": [
{ "questionId": "tsq_meal", "optionIds": ["tso_vegetarian"] },
{ "questionId": "tsq_equipment", "quantities": { "tso_pole": 2 } },
{ "questionId": "tsq_notes", "text": "不吃花生" }
]
}- 建單與新增旅客時,省略答案視為未答。不合規則回
422 validation。 - 修改旅客時,省略
surveyAnswers表示不改;傳陣列表示整份取代;[]清除可編輯的答案,仍檢查必填。 - 遇到「設定已變更」的錯誤,重新讀取題目並請使用者確認,不要直接重試。
同意書與旅遊契約
| 文件 | 誰簽 | 怎麼簽 |
|---|---|---|
| 個人資料保護同意書 | 訂購人 | 登入後在訂單頁按「前往簽署同意書」。 |
| 自訂同意書 | 訂購人,可代每位旅客確認 | 訂單頁「前往簽署」。承辦不能代簽。 |
| 旅遊契約 | 每位旅客(無 Email 時寄給訂購人) | 收到第一筆款項後,系統寄出免登入的簽署連結,旅客手寫簽名。 |
- 同意書只認最新版。發布新版會要求重簽。
- 客人交紙本同意書,或已在舊系統簽過(只限搬來的舊單)時,承辦在訂單「文件」分頁的同意書卡標記已簽,可上傳掃描檔。標記綁訂單,換梯與發布新版都不影響。標了的單不算待簽,也不再催簽。這不是代簽,系統不留簽署紀錄。
- 「成團後才要求」的自訂同意書,只在梯次已成團且未取消時才需要簽;抽籤訂單還要已中籤。
- 旅遊契約的簽署連結在出發後 7 天失效。可開「審閱期硬擋 24 小時」與「允許法定代理人代簽」。
- 後台在訂單頁「文件」分頁看契約狀態,按「產生/補發簽署連結」補發。已簽署的契約不能撤銷。
契約流程在後台 →「公司設定」→「旅遊契約」啟用,詳見旅遊契約。同意書範本在後台 →「範本」→「同意書範本」維護,見同意書與罐頭訊息範本。
›API 對應
- 同意書種類與適用行程:
GET /consent-kinds、POST /consent-kinds、PUT /consent-kinds/{id}、DELETE /consent-kinds/{id}。營運 API 不能替客人簽署。 - 旅遊契約:
GET /orders/{id}/agreements、POST /orders/{id}/agreements/generate、POST /orders/{id}/agreements/{agreementId}/sign-link、POST /orders/{id}/agreements/{agreementId}/reissue、POST /orders/{id}/agreements/{agreementId}/revoke、POST /orders/{id}/agreements/{agreementId}/resend-copy、POST /orders/{id}/agreements/{agreementId}/resign。需tour_agreement.manage。
分房偏好
客人報名時可選自動配房、指定房友或加價單人房;後台也能在旅客的「分房需求」修改。性別是分房的硬性條件。實際排房在梯次頁的「分房」分頁進行,見出團準備與線控。
查看完整證件號
身分證與護照號加密保存,畫面一律只顯示遮罩。需要完整號碼時,按遮罩號碼旁的「顯示全碼」圖示。
- 只能查看你看得到的訂單上的旅客。
- 每次查看都留稽核紀錄。需要時才看,不要逐筆查看來拼湊整份名單。
- 需要整梯名單(送籤、投保)時,用「匯出送籤資料」,見入山入園申請與送籤。
›API 與權限
POST /orders/{id}/travelers/{travelerId}/reveal,帶 field(idNumber 或 passportNo),回 { field, value }。需 order.reveal_pii 與 order.read,並受訂單可見範圍限制。
護照影本
部分國家公園的外籍入園申請要每位外籍隊員的護照影本。
誰可以存影本:
- 外籍旅客都可以。
- 本國旅客:要開通行程模組,且行程是海外行程。
怎麼上傳:
- 客人在前台報名時上傳,或之後在訂單頁補傳、換檔。沒上傳也能完成報名,只會多一條送籤提醒。
- 後台在旅客資料按「代傳」或「換檔」,也可以「檢視」「下載」。
檔案規則:
- 收 JPG、PNG、WebP、HEIC,8MB 以內。不收 PDF。
- 系統轉成 JPEG,並去掉拍攝位置等資訊。
- 解析度上限約 2,500 萬像素。用手機最高畫質(例:48MP)拍的照片會被拒收,請改用一般畫質或截圖。
- 影本加密保存,出發日後 180 天自動銷毀;會員終止時一併銷毀。
›權限
檢視與下載需 order.read 與 order.reveal_pii,每次檢視都留稽核;代傳與換檔需 order.update。
護照自動辨識與核對
行程模組已開通、訂單包含海外行程時,系統會辨識護照影本,帶出英文姓名、護照號碼、生日、效期、國籍與性別的建議值。辨識結果只是建議,要有人核對確認後才寫入正式資料。
客人在結帳時:
- 拍照或選圖上傳,系統自動辨識一次。
- 檢查核對區的建議值與檢查碼警示,修正後按「確認並帶入這位旅客」。
- 換照片會取消原本的確認,已填的表單值保留。
客人在訂單頁: 可上傳、換檔,按「載入原值並核對」比對正式資料與辨識建議,修正後按「核對無誤,確認護照資料」。客人拿不到影像原檔。
後台承辦:
- 在旅客資料按「載入原值並核對護照」。畫面並列正式原值、辨識建議與差異。
- 修正六項資料,按「確認並更新旅客資料」。狀態變成「已確認」。
- 適用但缺影本時,名單顯示「補傳護照影本」入口。
規則:
- 辨識失敗、檢查碼不符或額度用完時,仍可手填後確認。
- 確認表示有人核對過資料,不證明護照真偽,也不代表身分認領。
- 六項護照資料改變、換檔或轉單後,要重新確認。改電話等其他欄位不影響確認。
- 純換梯且資料與影本沒變時,保留確認,但會依新日期檢查效期。
- 確認也受修改期限限制(出發前第 6 天起凍結)。期限過了,請客人在訂單對話聯絡承辦。
- 每個帳號 24 小時內最多辨識 24 次,結帳與訂單頁共用,服務失敗也計次。同一影本再次辨識至少間隔 30 秒。
- 上傳前會顯示旅行社聯絡方式與用途。影像送到 Google Cloud Vision 的全球端點辨識,不保證在特定地區處理。
›權限
後台核對需 order.read、order.update、order.reveal_pii 與該訂單的存取範圍。載入正式原值與辨識建議會留下揭露稽核。模組停用時不銷毀影本,但停用辨識與確認。
證件效期提醒
多數國家要求入境時護照效期還有半年以上。行程是海外團時,系統用旅客的護照效期比對出發日,標出「效期不足」或「出發前已過期」。
- 門檻:預設 180 天。在後台 →「公司設定」→「出團作業」→「警示門檻」的「護照效期提醒天數」調整。
- 在哪裡看:
- 後台工作台的「證件效期提醒」卡:未來 90 天出團中效期不足的旅客。
- 海外梯次的「出團準備」分頁:「護照效期提醒」卡。
- 旅客會員列表:紅色「護照效期」標示。
- 寄信:系統每天早上 9 點寄提醒信給訂單的負責業務(沒有時寄給建單者),不寄給旅客。
- 沒填效期就沒有提醒,但出團準備會列為「未填效期」待補。效期可由客人在海外團結帳時填寫,或由承辦在旅客資料、K 單填寫。
行程模組停用時,系統略過證件效期通知。
›API 對應
- 旅客欄位
passportExpiryDate(CLI--passport-expiry)。 - 從一批會員中找出名下有即將出團、且效期有問題的人:
GET /members/expiry-warnings,以ids帶逗號分隔的會員 id(最多 200 個),回傳需提醒的userIds。
登山審核
登山模組開啟、行程是登山團且設了難度時,建單會自動審核每位旅客的資格:以旅客自填的路線對照貴公司的登山路線分級表,加上過去完成訂單的紀錄,算出能力分,再和行程難度比較。
審核不擋下單,也不擋收款。 能力不足只會標成待審核,由團隊在出團前處理。
客人填什麼: 爬過的路線、完成日期、完成時間(例:8 小時、2 天,選填),以及是否有高山經驗。路線選到分級表上已設定高海拔的路線時,高山經驗依分級表帶入,客人不能改;其他路線由客人自己勾選。完成時間只給承辦審核時看,不計分。客人看不到難度與能力分。客人可在會員中心的「登山經歷」補登。
後台怎麼處理: 後台 →「訂單」→「派發 / 資格審核」→「資格審核」分頁。
- 依「待審核」「待回覆」「判定可能過期」「已核可」「已駁回」篩選。
- 按「核可放行」,或按「駁回」並選後續處理:補件、換團或退費。兩者都可選罐頭訊息寄給客人,備註代入
{{補充說明}}。核可時,能力分勉強的旅客預選「建議加強體能訓練」版範本,其餘預選一般版。預選規則見罐頭訊息範本。 - 駁回不會取消訂單。選補件或換團時,訂單標為「待客人回覆」;選退費時,請另外在訂單上建立退款。
- 處理完按「標記已解決」。
入門免審: 行程編輯頁「登山難度評鑑」區塊勾「入門免審」後,該行程不比對能力分與難度分,審核結果一律「無須審核」,畫面標「入門免審」。「需具備高山經驗」照判,缺高山經驗仍進待審核。難度分數照真值填,結團時照真值記入旅客的登山經歷。一張訂單含多條行程時,以要審核的行程為準。
判定會過期: 審核結果是建單當下的快照。行程之後改了難度、高山經驗或入門免審,紀錄會標「判定可能過期」。自動判定的紀錄按「重跑本單審核」;已人工核可或駁回的紀錄,按「重新核可」或「重新駁回」重新裁決。
計分規則:
- 路線名稱去掉前後空白後,要和登山路線分級表完全相同才計分。未知路線不計分。
- 客人、業務或 API 自填的分數只供參考,不計分。
- 分級表空白時,只有完成訂單的紀錄計分;兩者都沒有時,能力分為 1。
- 補上分級表後,下次計算就採用。既有訂單的審核結果不會自動更新,要重跑。
- 承辦代填的經歷若影響了分數或高山標記,該旅客一律進待審核。
高山經驗從哪裡來: 行程勾「需具備高山經驗才可報名」時,旅客要有一筆高山經驗紀錄才會自動通過。完成訂單寫入的紀錄,在行程勾了「屬高海拔」時記為有高山經驗。勾「需具備高山經驗」的行程一律屬高海拔。一張訂單含多條行程時,任一條屬高海拔即記上。
- 「屬高海拔」在行程編輯頁的「登山難度評鑑」區塊,API 欄位是
isHighAltitude。 - 自填經歷的高山經驗看登山路線分級表的「高海拔」:路線名稱完全相同、而且該路線已設定時,以分級表為準。請讓分級表與行程的「屬高海拔」依同一份定義填寫,同一條路線兩邊才會一致。
- 系統寫入的紀錄不受代填限制。勾錯會讓完成該團的每位旅客之後都自動通過,所以請依公司定義勾選。
- 行程沒有難度分數時,完成訂單不寫紀錄,也不記高山經驗。
- 事後改勾不會更新已寫入的紀錄。
›API 對應
- 建單時逐位旅客帶
travelers[].climbingRecords:路線名稱必填,完成日、完成時間(durationValue加durationUnit:hour或day,兩個一起給)、hasAlpineExperience選填。路線對到分級表上已設定高海拔的路線時,hasAlpineExperience以分級表為準。gradeScore只為相容保留,不計分。 - 旅客沒填身分證或護照號碼時,那位旅客的
climbingRecords整批不存,訂單照常建立。回應的warnings會帶一則climbing_records_skipped,列出旅客的位置、姓名與沒存的筆數。 - 建單後補登:
GET /orders/{id}/travelers/{travelerId}/climbing-records、POST /orders/{id}/travelers/{travelerId}/climbing-records、DELETE /orders/{id}/travelers/{travelerId}/climbing-records/{recordId}。需order.update與登山模組。 - 建單前試算:
POST /orders/screening-preview。行程勾了入門免審時,result.verdict是not_required。 - 入門免審:建立或更新行程時帶
screeningExempt(POST /trips、PATCH /trips/{id})。 - 人工裁決:
POST /orders/{id}/review-screening(screening.review)。核可與駁回都可帶templateId寄信。駁回必須帶disposition:resupplement(補件)、switch_trip(換團)、refund(退費)。重新裁決帶redecide: true並指定travelerId;紀錄已與行程一致時回409。 - 標記已解決:
POST /orders/{id}/resolve-screening-follow-up。 - 「重跑本單審核」只有後台入口。
- 審核結果值:
not_required(行程未評級)、auto_pass、needs_review、manual_approved、manual_rejected。
相關指南
- 會員與會員中心:訂購帳號、代建會員、認領與 PDPA。
- 入山入園申請與送籤:送籤資料匯出。
- 訂單與金流模型:旅客所屬的訂單、應收與退款。
- orders API:旅客相關端點的完整參數。