自建前台 API
你自己架官網的首頁、行程頁與日誌頁,toko 供應資料。客人按報名時,連回平台完成結帳與付款。
什麼時候用
- 公司已有自己設計的官網,想直接顯示 toko 裡的行程、梯次與日誌。
- 不想自己處理報名、付款與會員:這些仍由平台提供。
只想讓平台的網站使用公司網址,不需要自建前台,改用自有網域。三種方式的比較見模組與串接選擇。
| 由你的官網負責 | 由平台負責 |
|---|---|
| 首頁、行程頁、日誌頁 | 報名、結帳、付款、會員中心、訂單頁 |
開通與切換
需要進階套組的「自建前台」模組,由平台開通。到後台 →「公司設定」→「方案模組」確認狀態。開通能力、建立金鑰或綁定網域,都不會自動切換正式網站。
在後台 →「內容與行銷」→「網站」的「網址與網域」卡片設定:
- 「網站模式」選「使用自建前台」。這只切換下方的設定,不會改變正式網站。
- 填「官網網址」(只接受 HTTPS,例如
https://www.example.com),按「儲存官網網址」。 - 選填「報名與結帳網域」。不填就使用平台提供的網址。
- 確認官網已可正常運作後,按「啟用/套用自建前台」。
啟用後:
- 平台首頁導向你的官網。
- 報名與會員頁改用簡化的品牌導覽,客人可由 Logo 或「返回官網」回到你的網站。
- 平台的內容頁退出搜尋索引。
日後修改官網網址,也要再按一次「啟用/套用自建前台」才會生效。按「切回平台官網」會恢復平台模板與索引,並保留官網網址、內容與金鑰。
兩種模式都能在「內容」分頁預覽模板。預覽只有獲授權的瀏覽器看得到,使用已儲存內容,不改正式模式。
誰可以操作
| 操作 | 需要的權限 |
|---|---|
| 切換網站模式、改官網網址與網域 | 管理網站模式與網域 |
| 編輯內容、關於頁與 SEO | 編輯內容與 SEO |
| 建立與撤銷前台金鑰 | 建立與撤銷 API 金鑰 |
申請前台金鑰
- 到後台 →「內容與行銷」→「網站」→「開發者」分頁,按「建立前台金鑰」。
- 重新驗證身分。
- 填「名稱(用途)」,例如「正式站」「測試站」。
- 複製完整金鑰,交給官網的後端。完整金鑰只顯示這一次。
前台金鑰屬於公司,不屬於某位員工:建立者離職後照常有效,也不會到期。它只能讀公開資料,不能讀訂單或個資。
- 可以同時有多把有效金鑰。輪替方式:先建新的、換到官網、再撤銷舊的。
- 清單顯示每把金鑰的最後使用時間。
- 不再使用或外洩時,在同一頁按「撤銷」。
金鑰只放在官網的後端伺服器,不放進瀏覽器程式碼。API 不允許瀏覽器直接呼叫。
前台金鑰與員工的 API 金鑰不能互換。
›網站設定的 API 與 CLI 對應
- 讀取與修改:
GET /api/v1/settings/storefront、PATCH /api/v1/settings/storefront。網站模式欄位websiteMode為platform或headless;官網網址欄位customStorefrontUrl傳null清除準備資料,正式入口維持到再次啟用或切回。行程頁路徑欄位customStorefrontTripPath填/shop/{slug}這類路徑,傳null時行程連結用平台的行程頁。 - 權限:網站模式與網址需要
website.manage;內容、關於頁與 SEO 需要website.edit;前台金鑰需要api_key.manage。
toko settings storefront-update --data '{"customStorefrontUrl":"https://www.example.com"}'
toko settings storefront-update --data '{"websiteMode":"headless"}'
toko settings storefront-update --data '{"websiteMode":"platform"}'以下各節寫給架官網的工程師。
呼叫方式
官網後端對「網站」頁顯示的報名網址發出請求,每個請求都帶前台金鑰。可使用平台網址,或你綁定的報名網域。
›請求範例與處理順序
curl https://shop.example.com/api/storefront/v1/site \
-H "Authorization: Bearer $TOKO_STOREFRONT_KEY" \
-H "X-Toko-Buyer-IP: 203.0.113.7"前台金鑰以 toko_sfk_ 開頭,只能呼叫 /api/storefront/v1。員工 API token 不能呼叫前台 API。
伺服器依序處理:
- 以網域解析租戶。查無站台回
404 not_found,平台暫時故障回503 service_unavailable。 - 驗證金鑰。缺少、格式錯誤、已撤銷或屬於別的租戶都回
401 unauthorized,不區分原因。 - 扣限速額度。超過時回
429 rate_limited。 - 檢查模組。未開通回
403 module_disabled;重新開通後,未撤銷的金鑰恢復可用。 - 驗證參數,組出回應。
沒有有效金鑰時,不揭露路徑或參數錯誤。限速服務無法使用時回 503 rate_limit_unavailable。
端點
每種頁面要呼叫的端點是固定的。行程頁呼叫兩支:行程內容可以快取,梯次名額不可以快取。
| 頁面 | 呼叫 |
|---|---|
| 頁首頁尾 | GET /site |
| 行程列表 | GET /trips |
| 行程頁 | GET /trips/{slug} + GET /trips/{slug}/departures |
| 日誌列表 | GET /journal |
| 日誌頁 | GET /journal/{slug} |
| 首頁清單 | GET /banners、GET /categories、GET /faqs |
| 近期梯次 | GET /departures |
行程端點另需開通行程模組。關閉時,GET /trips、GET /trips/{slug}、GET /trips/{slug}/departures 與 GET /departures 都回 403 module_disabled。其他前台端點仍可使用。
草稿、封存與不存在的頁面都回同一個「找不到」。
›欄位說明
- 圖片與網址一律是絕對網址,以報名網域為 base。
- 正文
bodyHtml是平台渲染並清理過的 HTML,可以直接放進頁面。後台標記的文字顏色與底色以<span data-color data-bg style>輸出,已帶 inline 色碼;要改用自己的配色,以[data-color]、[data-bg]選擇器覆寫。 difficultyLevel是對客難度:1 輕鬆、2 入門、3 中等、4 進階、5 挑戰;null表示未分級。它與內部資格審核分數分開,不自動換算。tags是自由標籤陣列,例如['百岳', '親子健行', '日本']。標籤沒有固定分類,也不決定難度、模組或報名資格。前台可收齊列表分頁後自行篩選。員工 API 與 CLI 用字串陣列維護:省略保留原值,傳[]清空。- 行程與日誌詳情另有
seoTitle、seoDescription、ogImageUrl,來自後台的 SEO 設定。值為null時,依序改用標題、摘要與封面圖。ogImageUrl是絕對網址,不支援的協定回null。列表不含這些欄位。 isClimbing是後台的「登山」行程旗標。租戶沒開登山模組時一律false。- 草稿、封存與不存在的 slug 都回
404 not_found。
首頁行程分類,依後台排序,最多 8 個
/api/storefront/v1/categories回應欄位 · data
itemsname分類名稱。
tag分類對應的行程標籤,與 `/trips` 回傳的 `tags` 其中一個完全相同。
imageUrl分類圖片的絕對網址;沒有圖片為 null。
curl -X GET "https://shop.example.com/api/storefront/v1/categories" \
-H "Authorization: Bearer $TOKO_STOREFRONT_KEY" \
-H "X-Toko-Buyer-IP: <客人 IP>"{
"ok": true,
"data": {
"items": [
{
"name": "…",
"tag": "…",
"imageUrl": "…"
}
]
}
}所有行程近期出團的價格、名額與報名狀態
/api/storefront/v1/departures參數
days選填回應欄位 · data
departurestripSlug所屬行程的 slug;以它呼叫 `trips/{slug}`。
minGroupSize所屬行程的最低成團人數;未設定為 null。還差幾位成團,讀 `availability.seatsToMinGroupSize`。
id出團 id(`dep_` 前綴)。
departureDate出發日(`YYYY-MM-DD`)。
returnDate回程日(`YYYY-MM-DD`)。
priceTwd每人直客價(TWD)。與結帳計價同一個函式,促銷中的出團是促銷價。
capacity名額上限(人數)。
remainingSeats剩餘名額(人數),不小於 0。
bookingStateavailability公開可報名度:狀態、剩餘名額、一張單的人數上限、成團差額。與平台的行程頁同一個判準。
status可報名度:`open` 有名額;`low` 有名額但快額滿(剩 1 或 2 位);`soldout` 額滿且不收候補; `waitlist` 額滿但收候補;`lottery` 抽籤制、有名額;`lottery_full` 抽籤制、額滿; `closed` 不開放報名。之後可能新增值,不認得的值請當成不可報名。
remainingSeats剩餘名額(人數),不小於 0。
maxPartySize一張單最多可報幾位。額滿收候補時是名額上限;不可報名時是 0。
seatsToMinGroupSize還差幾位達到行程的最低成團人數:0 是已成團;行程未設定最低成團人數為 null。
bookingUrl報名網址:`https://<交易鏈網域>/checkout?departure_id=<出團 id>`,直接進結帳流程第一步。
lotteryLeadDays抽籤日在出發日前幾天(後台的「抽籤前幾天」)。梯次有設定用梯次的值,否則用行程的值; 都沒設定為 null。抽籤時程表有這一天時,實際抽籤日以時程表為準。
deposit訂金。沒設訂金、或一位旅客的訂金就是全額時為 null(只能付全額)。
basis計算單位:`per_person` 每位旅客一份訂金;`per_order` 每張訂單一筆,不看人數。 比例訂金一律是 `per_person`。
amountTwd一位旅客報名時的訂金(TWD)。`per_person` 的固定金額訂金是這個金額乘人數; 比例訂金按結帳的總額取整,不要自己乘。
percent比例訂金的百分比(1–100);固定金額為 null。比例訂金以折扣後的總額計算。
requiredtrue:租戶只收訂金,結帳不提供付全額。false:客人可選付全額或付訂金。
balanceDue尾款期限:`before_date` 是不抽籤的出團,於 `date`(`YYYY-MM-DD`)前繳; `after_lottery_win` 是抽籤出團,中籤後 `days` 天內繳。之後可能新增 `kind`。
curl -X GET "https://shop.example.com/api/storefront/v1/departures" \
-H "Authorization: Bearer $TOKO_STOREFRONT_KEY" \
-H "X-Toko-Buyer-IP: <客人 IP>"{
"ok": true,
"data": {
"departures": [
{
"tripSlug": "…",
"minGroupSize": 0,
"id": "…",
"departureDate": "…",
"returnDate": "…",
"priceTwd": 0,
"capacity": 0,
"remainingSeats": 0,
"bookingState": "lottery",
"availability": {
"status": "closed",
"remainingSeats": 0,
"maxPartySize": 0,
"seatsToMinGroupSize": 0
},
"bookingUrl": "…",
"lotteryLeadDays": 0,
"deposit": null
}
]
}
}首頁常見問題,依後台排序,最多 20 題
/api/storefront/v1/faqs回應欄位 · data
itemsquestion問題。
answer答案,純文字,可含換行。
curl -X GET "https://shop.example.com/api/storefront/v1/faqs" \
-H "Authorization: Bearer $TOKO_STOREFRONT_KEY" \
-H "X-Toko-Buyer-IP: <客人 IP>"{
"ok": true,
"data": {
"items": [
{
"question": "…",
"answer": "…"
}
]
}
}已發布日誌的卡片,cursor 分頁
/api/storefront/v1/journal參數
limit選填cursor選填上一頁回應的 nextCursor;第一頁不帶
回應欄位 · data
itemsslug日誌網址 slug;以它呼叫 `journal/{slug}`。
title標題。
excerpt摘要;未設定為 null。
coverImageUrl封面圖的絕對網址;未設定為 null。
publishedAt發布時間(ISO 8601,UTC)。
authorName作者(嚮導)名稱;未設定為 null。
updatedAtLast edit time (ISO 8601, UTC). Use it for `dateModified` and sitemap `lastmod`.
nextCursorcurl -X GET "https://shop.example.com/api/storefront/v1/journal" \
-H "Authorization: Bearer $TOKO_STOREFRONT_KEY" \
-H "X-Toko-Buyer-IP: <客人 IP>"{
"ok": true,
"data": {
"items": [
{
"slug": "…",
"title": "…",
"excerpt": "…",
"coverImageUrl": "…",
"publishedAt": "…",
"authorName": "…",
"updatedAt": "…"
}
],
"nextCursor": "…"
}
}一篇日誌的完整內容
/api/storefront/v1/journal/{slug}參數
slug路徑日誌 slug(路徑參數)
回應欄位 · data
bodyHtmltitle標題。
slug日誌網址 slug;以它呼叫 `journal/{slug}`。
excerpt摘要;未設定為 null。
coverImageUrl封面圖的絕對網址;未設定為 null。
seoTitleSEO title override; null uses the post title.
seoDescriptionSEO description override; null uses the excerpt.
ogImageUrlAbsolute sharing image URL; null uses the cover image.
updatedAtLast edit time (ISO 8601, UTC). Use it for `dateModified` and sitemap `lastmod`.
publishedAt發布時間(ISO 8601,UTC)。
authorName作者(嚮導)名稱;未設定為 null。
curl -X GET "https://shop.example.com/api/storefront/v1/journal/<slug>" \
-H "Authorization: Bearer $TOKO_STOREFRONT_KEY" \
-H "X-Toko-Buyer-IP: <客人 IP>"{
"ok": true,
"data": {
"bodyHtml": "…",
"title": "…",
"slug": "…",
"excerpt": "…",
"coverImageUrl": "…",
"seoTitle": "…",
"seoDescription": "…",
"ogImageUrl": "…",
"updatedAt": "…",
"publishedAt": "…",
"authorName": "…"
}
}站台資訊:品牌名、首頁標題、logo、聯絡方式、交易鏈網址
/api/storefront/v1/site回應欄位 · data
name品牌名(`tenant_settings.company_name`)。
homeTitle首頁標題整句(含品牌段,後台「網站 → SEO → 首頁標題」);未設定為 null,由前台自訂預設。
ogImageUrl預設分享圖的絕對網址(後台「網站 → SEO → 預設分享圖」);未設定為 null,由前台自訂預設。
logoUrlLogo 的絕對網址;未設定為 null。
phone聯絡電話;未設定為 null。
email對外聯絡信箱(`tenant_settings.company_email`);未設定為 null,不退回系統信的回覆信箱。
lineOfficialUrlLINE 官方帳號加好友網址;未設定為 null。
facebookUrlFacebook 粉專網址;未設定為 null。
instagramUrlInstagram 網址;未設定為 null。
youtubeUrlYouTube 頻道網址;未設定為 null。
shopUrl交易鏈網址(平台供應的結帳、會員、訂單頁所在的 origin)。
memberUrl會員中心網址。
curl -X GET "https://shop.example.com/api/storefront/v1/site" \
-H "Authorization: Bearer $TOKO_STOREFRONT_KEY" \
-H "X-Toko-Buyer-IP: <客人 IP>"{
"ok": true,
"data": {
"name": "…",
"homeTitle": "…",
"ogImageUrl": "…",
"logoUrl": "…",
"phone": "…",
"email": "…",
"lineOfficialUrl": "…",
"facebookUrl": "…",
"instagramUrl": "…",
"youtubeUrl": "…",
"shopUrl": "…",
"memberUrl": "…"
}
}上架行程的卡片,cursor 分頁
/api/storefront/v1/trips參數
limit選填cursor選填上一頁回應的 nextCursor;第一頁不帶
回應欄位 · data
itemstagsFree-form trip tags. The website defines its own filters.
difficultyLevelPublic difficulty, from 1 (easy) to 5 (challenging). Null means unrated.
slug行程網址 slug;以它呼叫 `trips/{slug}`。
title行程標題。
summary一句話摘要;未設定為 null。
destination目的地名稱。
isOverseasTrue when the trip goes outside Taiwan (the admin "海外" trip flag).
isClimbing登山行程(後台的「登山」行程旗標)。租戶沒開登山模組時一律 false。
durationDays天數。
hasPreTripNightTrue when the trip starts with a gathering night before departure (Day 0). The night adds one night to the trip length.
priceFromTwd「NT$ X 起」的起價(TWD 整數)。
depositFromTwd「訂金 NT$ X 起」:可報名出團中,一位旅客的最低訂金(TWD)。沒有訂金、訂金就是全額, 或訂金是每張訂單一筆時為 null。各出團的訂金細節讀 `trips/{slug}/departures` 的 `deposit`。
coverImageUrl封面圖的絕對網址;未設定為 null。
nextDepartureDate最近一個前台可報名出團的出發日(`YYYY-MM-DD`);沒有為 null。
updatedAtLast edit time of the trip (ISO 8601, UTC). Use it for the sitemap `lastmod`. Gallery image changes move it forward. Departure seats, status, and prices do not change it.
nextCursorcurl -X GET "https://shop.example.com/api/storefront/v1/trips" \
-H "Authorization: Bearer $TOKO_STOREFRONT_KEY" \
-H "X-Toko-Buyer-IP: <客人 IP>"{
"ok": true,
"data": {
"items": [
{
"tags": [
"…"
],
"difficultyLevel": 0,
"slug": "…",
"title": "…",
"summary": "…",
"destination": "…",
"isOverseas": true,
"isClimbing": true,
"durationDays": 0,
"hasPreTripNight": true,
"priceFromTwd": 0,
"depositFromTwd": 0,
"coverImageUrl": "…",
"nextDepartureDate": "…",
"updatedAt": "…"
}
],
"nextCursor": "…"
}
}行程內容
/api/storefront/v1/trips/{slug}參數
slug路徑行程 slug(路徑參數)
回應欄位 · data
bodyHtmllodging住宿配套;沒有配套或住宿模組未開通時為空陣列。
namelocationdescriptionnights本行程在此據點住幾晚。
facilitieskeylabelimageUrls據點相簿的絕對網址;沒有相簿時退回封面圖。
roomTypesnamedescriptioncapacityPerUnit每間最多人數。
beds床型與床數。
labelcountfloorSizeSqm坪數;未設定為 null。
facilitieskeylabelimageUrls房型照片的絕對網址。
titleslugcoverImageUrl封面圖的絕對網址;未設定為 null。
seoTitleSEO title override; null uses the trip title.
seoDescriptionSEO description override; null uses the summary.
ogImageUrlAbsolute sharing image URL; null uses the cover image.
isOverseasTrue when the trip goes outside Taiwan (the admin "海外" trip flag).
updatedAtLast edit time of the trip (ISO 8601, UTC). Use it for `dateModified` and the sitemap `lastmod`. Gallery image changes move it forward. Departure seats, status, and prices do not change it.
tagsFree-form trip tags. The website defines its own filters.
summarydestinationdurationDaysdifficultyLevelPublic difficulty, from 1 (easy) to 5 (challenging). Null means unrated.
priceFromTwdnotices注意事項。
suggestedFlights建議航班;沒填或資料有錯時為 null。結構見 `StorefrontSuggestedFlightsDto`: `plans[]`(推薦方案在第一個)→ `segments[]`(搭飛機)或 `airports[]`/`route`(車站集合)。
updated最後核對班表的年月 YYYY-MM。
ticket機票:不含/可代訂(不含但可代訂)/含。
plans推薦方案在第一個。
nameprimary推薦方案;陣列第一個一定是推薦方案。
modeflight=搭飛機到機場集合(看 `segments`);station=自行前往車站集合(看 `airports`、`route`)。
meetDay集合在行程第幾天。
meetTime集合時間 HH:MM;null=抵達後。
meetPlacesegments航班;station 方案為空陣列。
dirout=去程、ret=回程、dom=當地國內線。同一方向依陣列順序是第 1、2、3 段。
flight完整班號,例如 `CI118`。
airline航空公司名稱,例如「中華航空」。
from出發機場 IATA 三碼。
fromName出發機場短名,例如「桃園」。
to抵達機場 IATA 三碼。
toName抵達機場短名。
depDaydep起飛時間 HH:MM。
arrDayarr抵達時間 HH:MM。
airports建議抵達機場,第一個最推薦;flight 方案為空陣列。
codeIATA 三碼。
name短名,例如「名古屋中部」。
route接駁路線;flight 方案為 null。
duration接駁所需時間與方式;flight 方案為 null。
arriveDayBefore建議前一天抵達。
cancellationFeeTiers生效的退改費階梯(行程覆寫,否則租戶預設),依 `daysBefore` 降序。
daysBefore距出發日 ≥ 此天數時適用本列。0 是出發當天。
feePercent扣款百分比(0–100);定額扣款的列為 null。
feeFixedTwd每人定額扣款(TWD 整數);百分比扣款的列為 null。
isClimbing登山行程(後台的「登山」行程旗標)。租戶沒開登山模組時一律 false。
isLinkOnlyTrue when the trip is link-only: the trip list leaves it out, and only people with the trip URL can book it. Mark the trip page noindex and leave out structured data (JSON-LD).
hasPreTripNightTrue when the trip starts with a gathering night before departure (Day 0). The night adds one night to the trip length.
foreignTravelersOnlyTrue when the trip takes foreign travelers only (the admin "限外籍旅客" trip flag). Checkout rejects a traveler whose nationality is blank or Taiwan. Show a notice on the trip page.
images行程相簿(依顯示順序)。
url圖片的絕對網址。
caption圖說;未設定為 null。
feeIncludes費用包含。
feeExcludes費用不包含。
curl -X GET "https://shop.example.com/api/storefront/v1/trips/<slug>" \
-H "Authorization: Bearer $TOKO_STOREFRONT_KEY" \
-H "X-Toko-Buyer-IP: <客人 IP>"{
"ok": true,
"data": {
"bodyHtml": "…",
"lodging": [
{
"name": "…",
"location": "…",
"description": "…",
"nights": 0,
"facilities": [
{
"key": "…",
"label": "…"
}
],
"imageUrls": [
"…"
],
"roomTypes": [
{
"name": "…",
"description": "…",
"capacityPerUnit": 0,
"beds": [
{
"label": "…",
"count": 0
}
],
"floorSizeSqm": 0,
"facilities": [
{
"key": "…",
"label": "…"
}
],
"imageUrls": [
"…"
]
}
]
}
],
"title": "…",
"slug": "…",
"coverImageUrl": "…",
"seoTitle": "…",
"seoDescription": "…",
"ogImageUrl": "…",
"isOverseas": true,
"updatedAt": "…",
"tags": [
"…"
],
"summary": "…",
"destination": "…",
"durationDays": 0,
"difficultyLevel": 0,
"priceFromTwd": 0,
"notices": [
"…"
],
"suggestedFlights": {
"updated": "2026-11",
"ticket": "可代訂",
"plans": [
{
"name": "中華航空",
"primary": true,
"mode": "flight",
"meetDay": 1,
"meetTime": null,
"meetPlace": "鹿兒島機場",
"segments": [
{
"dir": "out",
"flight": "CI118",
"airline": "中華航空",
"from": "TPE",
"fromName": "桃園",
"to": "KOJ",
"toName": "鹿兒島",
"depDay": 1,
"dep": "08:25",
"arrDay": 1,
"arr": "11:15"
}
],
"airports": [],
"route": null,
"duration": null,
"arriveDayBefore": false
}
]
},
"cancellationFeeTiers": [
{
"daysBefore": 0,
"feePercent": 0,
"feeFixedTwd": 0
}
],
"isClimbing": true,
"isLinkOnly": true,
"hasPreTripNight": true,
"foreignTravelersOnly": true,
"images": [
{
"url": "…",
"caption": "…"
}
],
"feeIncludes": [
"…"
],
"feeExcludes": [
"…"
]
}
}行程的出團、價格、名額與報名狀態
/api/storefront/v1/trips/{slug}/departures參數
slug路徑路徑參數
回應欄位 · data
departuresid出團 id(`dep_` 前綴)。
departureDate出發日(`YYYY-MM-DD`)。
returnDate回程日(`YYYY-MM-DD`)。
priceTwd每人直客價(TWD)。與結帳計價同一個函式,促銷中的出團是促銷價。
capacity名額上限(人數)。
remainingSeats剩餘名額(人數),不小於 0。
bookingStateavailability公開可報名度:狀態、剩餘名額、一張單的人數上限、成團差額。與平台的行程頁同一個判準。
status可報名度:`open` 有名額;`low` 有名額但快額滿(剩 1 或 2 位);`soldout` 額滿且不收候補; `waitlist` 額滿但收候補;`lottery` 抽籤制、有名額;`lottery_full` 抽籤制、額滿; `closed` 不開放報名。之後可能新增值,不認得的值請當成不可報名。
remainingSeats剩餘名額(人數),不小於 0。
maxPartySize一張單最多可報幾位。額滿收候補時是名額上限;不可報名時是 0。
seatsToMinGroupSize還差幾位達到行程的最低成團人數:0 是已成團;行程未設定最低成團人數為 null。
bookingUrl報名網址:`https://<交易鏈網域>/checkout?departure_id=<出團 id>`,直接進結帳流程第一步。
lotteryLeadDays抽籤日在出發日前幾天(後台的「抽籤前幾天」)。梯次有設定用梯次的值,否則用行程的值; 都沒設定為 null。抽籤時程表有這一天時,實際抽籤日以時程表為準。
deposit訂金。沒設訂金、或一位旅客的訂金就是全額時為 null(只能付全額)。
basis計算單位:`per_person` 每位旅客一份訂金;`per_order` 每張訂單一筆,不看人數。 比例訂金一律是 `per_person`。
amountTwd一位旅客報名時的訂金(TWD)。`per_person` 的固定金額訂金是這個金額乘人數; 比例訂金按結帳的總額取整,不要自己乘。
percent比例訂金的百分比(1–100);固定金額為 null。比例訂金以折扣後的總額計算。
requiredtrue:租戶只收訂金,結帳不提供付全額。false:客人可選付全額或付訂金。
balanceDue尾款期限:`before_date` 是不抽籤的出團,於 `date`(`YYYY-MM-DD`)前繳; `after_lottery_win` 是抽籤出團,中籤後 `days` 天內繳。之後可能新增 `kind`。
curl -X GET "https://shop.example.com/api/storefront/v1/trips/<slug>/departures" \
-H "Authorization: Bearer $TOKO_STOREFRONT_KEY" \
-H "X-Toko-Buyer-IP: <客人 IP>"{
"ok": true,
"data": {
"departures": [
{
"id": "…",
"departureDate": "…",
"returnDate": "…",
"priceTwd": 0,
"capacity": 0,
"remainingSeats": 0,
"bookingState": "lottery",
"availability": {
"status": "closed",
"remainingSeats": 0,
"maxPartySize": 0,
"seatsToMinGroupSize": 0
},
"bookingUrl": "…",
"lotteryLeadDays": 0,
"deposit": null
}
]
}
}分頁
行程列表與日誌列表分頁回傳。照回應給的下一頁標記一路取完,不會遺漏或重複。行程依建立時間新到舊,日誌依發布時間新到舊。
›分頁參數
limit是每頁筆數,預設 20,上限 50。超過上限回422 validation,不會靜默截斷。- 回應的
nextCursor原樣帶在下一次請求的cursor。nextCursor為null時沒有下一頁。 - cursor 是不透明字串,不要自己組,也不要解析。日誌的 cursor 解不開時回
422 validation。
梯次與報名狀態
梯次清單只列還沒出發、前台可報名的梯次。每個梯次告訴你目前能不能報名,以及每人直客價(與結帳時的計價相同,促銷中回促銷價)。
每個梯次另帶 lotteryLeadDays:抽籤日在出發日前幾天。梯次有設定用梯次的值,否則用行程的值,都沒設定是 null。用它標示「30 天前抽籤」這類入園資訊,不必解析行程正文。
›報名狀態值
bookingState 是下列其中一個值:
bookingState | 意義 |
|---|---|
open | 有名額,可報名。 |
soldout | 額滿,且不收候補。 |
waitlist | 額滿,但收候補。客人送單後成為候補單。 |
lottery | 抽籤制梯次,在報名期間。 |
抽籤制梯次額滿時,bookingState 仍是 lottery,不會變成 soldout,所以 lottery 不保證可報名。要分辨額滿的抽籤梯次,讀 availability.status。
›可報名度
availability 是平台算好的可報名度。平台自己的行程頁與結帳頁用同一個判準,所以不用自己由名額推導。
| 欄位 | 意義 |
|---|---|
status | 可報名度,值見下表。 |
remainingSeats | 剩餘名額(人數),不小於 0。 |
maxPartySize | 一張單最多可報幾位。額滿收候補時是名額上限;不可報名時是 0。 |
seatsToMinGroupSize | 還差幾位達到最低成團人數。0 是已成團;行程未設定最低成團人數為 null。 |
status | 意義 |
|---|---|
open | 有名額,可報名。 |
low | 有名額,但快額滿(剩 1 或 2 位)。 |
soldout | 額滿,且不收候補。 |
waitlist | 額滿,但收候補。客人送單後成為候補單。 |
lottery | 抽籤制梯次,有名額。 |
lottery_full | 抽籤制梯次,額滿。 |
closed | 不開放報名。 |
之後可能新增 status 的值。不認得的值,請當成不可報名。
priceTwd 是每人直客價。
›訂金
有訂金的梯次帶 deposit,讓客人在報名前就知道現在只需先付多少。沒設訂金,或一位旅客的訂金就是全額時,deposit 是 null,客人只能付全額。金額與結帳用同一個計算。
| 欄位 | 意義 |
|---|---|
basis | per_person 每位旅客一份訂金;per_order 每張訂單一筆,不看人數。 |
amountTwd | 一位旅客報名時的訂金。per_person 的固定金額訂金是這個金額乘人數;比例訂金按結帳的總額取整,不要自己乘。 |
percent | 比例訂金的百分比;固定金額是 null。比例訂金以折扣後的總額計算,畫面上請註明以結帳為準。 |
required | true 時租戶只收訂金,結帳不提供付全額。可寫「報名只需先付訂金」。 |
balanceDue | 尾款期限,見下表。 |
balanceDue.kind | 意義 |
|---|---|
before_date | 不抽籤的梯次。尾款於 date 前繳。 |
after_lottery_win | 抽籤梯次。中籤時才訂期限,尾款於中籤後 days 天內繳。 |
尾款期限照這個欄位寫。不要寫「成團後補尾款」:尾款期限不看成團。之後可能新增 kind 的值,不認得時只顯示訂金。
行程列表的卡片帶 depositFromTwd:可報名梯次中,一位旅客的最低訂金,用來顯示「訂金 NT$ X 起」。訂金是每張訂單一筆的行程,這個欄位是 null。
報名網址
每個梯次都附一個報名網址。把客人連到這個網址,客人會直接進入結帳流程,第一步已選好該梯次,再選人數。
https://<報名網域>/checkout?departure_id=<梯次 id>這個格式是平台的承諾。你可以直接存網址,也可以自己照格式組。平台改格式時,會保留舊網址的轉址。自建前台模式下,舊格式 /tour/<行程 slug>?departure=<梯次 id> 會轉進結帳流程。
廣告追蹤
客人按下報名之後,報名、付款與訂單頁都在報名網域上。要在自己的 GA4 與 Meta 帳號看到成交,照下面四步做:
- 在後台「網站」的「追蹤」分頁填入 GA4 Measurement ID 與 Meta Pixel ID。報名、付款與訂單頁會載入追蹤碼。
- 在同一頁貼上 GA4 Measurement Protocol API secret 與 Meta Conversions API access token。第一筆款項入帳時,平台送出
purchase,帶訂單編號、金額與行程。 - 在官網的 gtag 設定跨網域,把報名網域加進
linker.domains。平台端已經接受官網帶來的_gl。 - 在 GA4 後台「設定網域」加入官網與報名網域,並把報名網域與金流商網域加進「排除不適用的參照連結網址」。
ATM 這類隔幾天才入帳的單,GA4 可能把成交的工作階段來源記成「(not set)」或直接流量。
行程頁路徑
平台有些連結要帶客人回到「這條行程的介紹」,例如後台複製的行程連結、會員訂單裡的行程名稱。自建前台模式下,這些連結指向你的官網。
在後台「網站」設定填入行程頁路徑,用 {slug} 代表行程代碼,例如 /shop/{slug}。平台會把它接在官網網址後面。沒有填時,這些連結用平台的行程頁 /tour/<slug>。
快取
平台已在邊緣快取回應,你的後端不必自行快取。每次頁面需要資料時直接呼叫 API。後台存檔後,內容最晚約 20 秒更新。梯次名額最多晚 1 秒。
›快取標頭
成功回應帶 Cache-Control: no-cache:你的後端每次都向平台取資料。平台邊緣的保存時間列在上方「端點」的標籤上:
- 內容類回應(站台、行程、日誌、輪播、分類、常見問題):保存 10 秒,過期後 10 秒內先回舊內容再更新。
- 梯次回應:保存 1 秒。
- 錯誤回應一律
no-store,邊緣不保存。
成功回應都帶 Vary: Authorization, Toko-Version。邊緣以金鑰與 API 版本區分快取,沒有金鑰的請求命中不到有金鑰的回應。
金鑰改釘選版本後,邊緣保存期間內仍可能回舊版本的格式。要立即換版本,每個請求都帶 Toko-Version。
限速
平台依來源、客人、金鑰與公司四層計算呼叫額度。一個爬蟲用光自己的額度,不會擋到其他客人;正式站與測試站各用一把金鑰,也不會互相擋。
| 層 | 計數對象 | 何時扣額 | 上限 |
|---|---|---|---|
source | 連線來源 IP | 只在金鑰驗證失敗時扣 | 60 次/60 秒 |
buyer | 金鑰+客人 IP | 金鑰有效且帶了合法的客人 IP 時扣 | 150 次/60 秒 |
key | 一把金鑰 | 金鑰有效時扣 | 300 次/60 秒 |
tenant | 整個租戶(所有金鑰合計) | 金鑰有效時扣 | 600 次/60 秒 |
›扣額規則
- 金鑰驗證失敗的請求只扣
source層,以連線來源 IP 計算。合法流量都從你的後端出口 IP 進來,所以source層不扣有效金鑰的請求。 - 金鑰有效的請求由窄到寬扣
buyer→key→tenant。被窄層擋下的請求不再扣寬層。 - 沒帶
X-Toko-Buyer-IP,或值不是合法 IP 時,不套用buyer層。 - IPv6 位址以 /64 網段計算,同一網段共用額度。
key層比tenant層小,所以兩把金鑰可以並存,一把用光不會擋住另一把。
超過任一層時回 429 rate_limited,並帶 Retry-After(秒)。等這段時間後再重試。
X-Toko-Buyer-IP
這個標頭告訴平台,這次請求是替哪一位客人發出的。平台只用它分配每位客人的額度,不寫進稽核,也不做安全判斷。
你的後端必須以自己驗證過的客人連線位址覆寫這個 header,不要原樣轉送客人送來的同名 header。否則客人每次換一個值,客人層的額度就失效,一個爬蟲可以用光整把金鑰的額度。
後端在 CDN 或反向代理之後時,只採信你自己的代理寫入的位址。
API 版本
前台 API 與員工 API 共用同一條 API 版本線,規則見 API 參考 的「API 版本」。請求帶 Toko-Version header 時用它;沒帶時用金鑰的釘選版本。每個回應都帶 Toko-Version,值是實際使用的版本。金鑰驗證失敗、限速與版本錯誤的回應不帶它。
錯誤碼
錯誤回應的格式與員工 API 相同。程式請判斷錯誤碼,不要比對說明文字。
›錯誤格式與錯誤碼
{
"ok": false,
"error": { "code": "unauthorized", "message": "前台金鑰無效" }
}參數錯誤(422 validation)另外帶 error.issues,列出每個欄位的錯誤。
| HTTP | code |
|---|---|
| 400 | version_invalid |
| 400 | version_required |
| 400 | version_unsupported |
| 401 | unauthorized |
| 403 | module_disabled |
| 404 | not_found |
| 422 | validation |
| 429 | rate_limited |
| 500 | internal |
| 503 | rate_limit_unavailable |
| 503 | service_unavailable |
| 503 | transaction_domain_not_configured |
/api/storefront/v1/ 底下不存在的路徑,在驗證金鑰之後回 404 not_found。
不是 JSON 信封的回應
下列回應不經過前台 API 處理,不是 JSON 信封,也不驗證金鑰。你的程式要先檢查 Content-Type,再解析 body:
- 沒有實作的方法:對既有端點送沒有實作的方法(例如
POST /trips),由框架回405,body 不是 JSON 信封。 - 裸路徑:
/api/storefront/v1(結尾沒有斜線與路徑)不屬於前台 API。它可能回 HTML 的404,或被入口驗證擋下。 - 入口驗證:平台在入口擋下的請求回純文字
Forbidden(403)。