toko

旅客與個資

旅客是一張訂單上實際出行的人,不是登入帳號。證件號碼加密保存,畫面只顯示遮罩,要看完整號碼得另外申請並留紀錄。

旅客與會員的差別

概念是什麼在哪裡看
會員登入帳號,也是訂單的訂購人後台 →「客戶」→「旅客會員」
旅客某張訂單上要出行的人訂單頁「旅客」分頁

同一個人可以出現在很多張訂單上,每次都是一筆旅客資料。訂購人本人也是一位旅客,標示為「主要聯絡人」。不要把旅客資料當成客戶主檔。會員的管理見會員與會員中心。

旅客資料

在訂單頁「旅客」分頁的「旅客本團資訊」卡管理名單:

  • 新增旅客:選「只補名單(席次已買)」或「加一席(多收一人團費)」。
  • 編輯、移除,或把旅客拆出成另一張訂單。
  • 列印旅客名冊。

每位旅客的資料:姓名、身分證、護照、生日、性別、電話、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,請重新讀取後再試。修改不會部分提交。
bash
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。

題型答案欄位規則
singleoptionIds剛好一個選項
multioptionIds選項集合,重複值會去除
quantityquantities選項 ID 對應 0–999 整數;0 視為未選
texttext去掉頭尾空白後最多 500 字
json
{
  "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。

護照自動辨識與核對

行程模組已開通、訂單包含海外行程時,系統會辨識護照影本,帶出英文姓名、護照號碼、生日、效期、國籍與性別的建議值。辨識結果只是建議,要有人核對確認後才寫入正式資料。

客人在結帳時:

  1. 拍照或選圖上傳,系統自動辨識一次。
  2. 檢查核對區的建議值與檢查碼警示,修正後按「確認並帶入這位旅客」。
  3. 換照片會取消原本的確認,已填的表單值保留。

客人在訂單頁: 可上傳、換檔,按「載入原值並核對」比對正式資料與辨識建議,修正後按「核對無誤,確認護照資料」。客人拿不到影像原檔。

後台承辦:

  1. 在旅客資料按「載入原值並核對護照」。畫面並列正式原值、辨識建議與差異。
  2. 修正六項資料,按「確認並更新旅客資料」。狀態變成「已確認」。
  3. 適用但缺影本時,名單顯示「補傳護照影本」入口。

規則:

  • 辨識失敗、檢查碼不符或額度用完時,仍可手填後確認。
  • 確認表示有人核對過資料,不證明護照真偽,也不代表身分認領。
  • 六項護照資料改變、換檔或轉單後,要重新確認。改電話等其他欄位不影響確認。
  • 純換梯且資料與影本沒變時,保留確認,但會依新日期檢查效期。
  • 確認也受修改期限限制(出發前第 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。

相關指南

Command Palette

Search for a command to run...