toko

自建前台 API

你自己架官網的首頁、行程頁與日誌頁,toko 供應資料。客人按報名時,連回平台完成結帳與付款。

什麼時候用

  • 公司已有自己設計的官網,想直接顯示 toko 裡的行程、梯次與日誌。
  • 不想自己處理報名、付款與會員:這些仍由平台提供。

只想讓平台的網站使用公司網址,不需要自建前台,改用自有網域。三種方式的比較見模組與串接選擇。

由你的官網負責由平台負責
首頁、行程頁、日誌頁報名、結帳、付款、會員中心、訂單頁

開通與切換

需要進階套組的「自建前台」模組,由平台開通。到後台 →「公司設定」→「方案模組」確認狀態。開通能力、建立金鑰或綁定網域,都不會自動切換正式網站。

在後台 →「內容與行銷」→「網站」的「網址與網域」卡片設定:

  1. 「網站模式」選「使用自建前台」。這只切換下方的設定,不會改變正式網站。
  2. 填「官網網址」(只接受 HTTPS,例如 https://www.example.com),按「儲存官網網址」。
  3. 選填「報名與結帳網域」。不填就使用平台提供的網址。
  4. 確認官網已可正常運作後,按「啟用/套用自建前台」。

啟用後:

  • 平台首頁導向你的官網。
  • 報名與會員頁改用簡化的品牌導覽,客人可由 Logo 或「返回官網」回到你的網站。
  • 平台的內容頁退出搜尋索引。

日後修改官網網址,也要再按一次「啟用/套用自建前台」才會生效。按「切回平台官網」會恢復平台模板與索引,並保留官網網址、內容與金鑰。

兩種模式都能在「內容」分頁預覽模板。預覽只有獲授權的瀏覽器看得到,使用已儲存內容,不改正式模式。

誰可以操作

操作需要的權限
切換網站模式、改官網網址與網域管理網站模式與網域
編輯內容、關於頁與 SEO編輯內容與 SEO
建立與撤銷前台金鑰建立與撤銷 API 金鑰

申請前台金鑰

  1. 到後台 →「內容與行銷」→「網站」→「開發者」分頁,按「建立前台金鑰」。
  2. 重新驗證身分。
  3. 填「名稱(用途)」,例如「正式站」「測試站」。
  4. 複製完整金鑰,交給官網的後端。完整金鑰只顯示這一次。

前台金鑰屬於公司,不屬於某位員工:建立者離職後照常有效,也不會到期。它只能讀公開資料,不能讀訂單或個資。

  • 可以同時有多把有效金鑰。輪替方式:先建新的、換到官網、再撤銷舊的。
  • 清單顯示每把金鑰的最後使用時間。
  • 不再使用或外洩時,在同一頁按「撤銷」。

前台金鑰與員工的 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。
bash
toko settings storefront-update --data '{"customStorefrontUrl":"https://www.example.com"}'
toko settings storefront-update --data '{"websiteMode":"headless"}'
toko settings storefront-update --data '{"websiteMode":"platform"}'

以下各節寫給架官網的工程師。

呼叫方式

官網後端對「網站」頁顯示的報名網址發出請求,每個請求都帶前台金鑰。可使用平台網址,或你綁定的報名網域。

›請求範例與處理順序
bash
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。

伺服器依序處理:

  1. 以網域解析租戶。查無站台回 404 not_found,平台暫時故障回 503 service_unavailable。
  2. 驗證金鑰。缺少、格式錯誤、已撤銷或屬於別的租戶都回 401 unauthorized,不區分原因。
  3. 扣限速額度。超過時回 429 rate_limited。
  4. 檢查模組。未開通回 403 module_disabled;重新開通後,未撤銷的金鑰恢復可用。
  5. 驗證參數,組出回應。

沒有有效金鑰時,不揭露路徑或參數錯誤。限速服務無法使用時回 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。

首頁輪播,依後台排序,最多 5 張

GET/api/storefront/v1/banners
前台金鑰Cache-Control: no-cache平台邊緣快取: public, s-maxage=10, stale-while-revalidate=10

回應欄位 · data

items
object[]
imageUrl
string

圖片的絕對網址。

alt
string

圖片替代文字。

linkUrl
string | null

點擊後的連結:站內路徑或 http(s) 網址;沒有連結為 null。站內路徑原樣輸出, 相對於顯示輪播的官網,不是交易鏈網域。

請求
curl -X GET "https://shop.example.com/api/storefront/v1/banners" \
  -H "Authorization: Bearer $TOKO_STOREFRONT_KEY" \
  -H "X-Toko-Buyer-IP: <客人 IP>"
回應
{
  "ok": true,
  "data": {
    "items": [
      {
        "imageUrl": "…",
        "alt": "…",
        "linkUrl": "…"
      }
    ]
  }
}

首頁行程分類,依後台排序,最多 8 個

GET/api/storefront/v1/categories
前台金鑰Cache-Control: no-cache平台邊緣快取: public, s-maxage=10, stale-while-revalidate=10

回應欄位 · data

items
object[]
name
string

分類名稱。

tag
string

分類對應的行程標籤,與 `/trips` 回傳的 `tags` 其中一個完全相同。

imageUrl
string | null

分類圖片的絕對網址;沒有圖片為 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": "…"
      }
    ]
  }
}

所有行程近期出團的價格、名額與報名狀態

GET/api/storefront/v1/departures
前台金鑰Cache-Control: no-cache平台邊緣快取: public, s-maxage=1模組:tour

參數

days選填
integer· min 1

回應欄位 · data

departures
object[]
tripSlug
string

所屬行程的 slug;以它呼叫 `trips/{slug}`。

minGroupSize
number | null

所屬行程的最低成團人數;未設定為 null。還差幾位成團,讀 `availability.seatsToMinGroupSize`。

id
string

出團 id(`dep_` 前綴)。

departureDate
string

出發日(`YYYY-MM-DD`)。

returnDate
string

回程日(`YYYY-MM-DD`)。

priceTwd
number

每人直客價(TWD)。與結帳計價同一個函式,促銷中的出團是促銷價。

capacity
number

名額上限(人數)。

remainingSeats
number

剩餘名額(人數),不小於 0。

bookingState
"lottery" | "open" | "soldout" | "waitlist"
availability
object

公開可報名度:狀態、剩餘名額、一張單的人數上限、成團差額。與平台的行程頁同一個判準。

status
"closed" | "lottery" | "lottery_full" | "low" | "open" | "soldout" | "waitlist"

可報名度:`open` 有名額;`low` 有名額但快額滿(剩 1 或 2 位);`soldout` 額滿且不收候補; `waitlist` 額滿但收候補;`lottery` 抽籤制、有名額;`lottery_full` 抽籤制、額滿; `closed` 不開放報名。之後可能新增值,不認得的值請當成不可報名。

remainingSeats
number

剩餘名額(人數),不小於 0。

maxPartySize
number

一張單最多可報幾位。額滿收候補時是名額上限;不可報名時是 0。

seatsToMinGroupSize
number | null

還差幾位達到行程的最低成團人數:0 是已成團;行程未設定最低成團人數為 null。

bookingUrl
string

報名網址:`https://<交易鏈網域>/checkout?departure_id=<出團 id>`,直接進結帳流程第一步。

lotteryLeadDays
number | null

抽籤日在出發日前幾天(後台的「抽籤前幾天」)。梯次有設定用梯次的值,否則用行程的值; 都沒設定為 null。抽籤時程表有這一天時,實際抽籤日以時程表為準。

deposit
StorefrontDepositDto | null

訂金。沒設訂金、或一位旅客的訂金就是全額時為 null(只能付全額)。

basis
"per_order" | "per_person"

計算單位:`per_person` 每位旅客一份訂金;`per_order` 每張訂單一筆,不看人數。 比例訂金一律是 `per_person`。

amountTwd
number

一位旅客報名時的訂金(TWD)。`per_person` 的固定金額訂金是這個金額乘人數; 比例訂金按結帳的總額取整,不要自己乘。

percent
number | null

比例訂金的百分比(1–100);固定金額為 null。比例訂金以折扣後的總額計算。

required
boolean

true:租戶只收訂金,結帳不提供付全額。false:客人可選付全額或付訂金。

balanceDue
BalanceDueRule

尾款期限:`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 題

GET/api/storefront/v1/faqs
前台金鑰Cache-Control: no-cache平台邊緣快取: public, s-maxage=10, stale-while-revalidate=10

回應欄位 · data

items
object[]
question
string

問題。

answer
string

答案,純文字,可含換行。

請求
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 分頁

GET/api/storefront/v1/journal
前台金鑰Cache-Control: no-cache平台邊緣快取: public, s-maxage=10, stale-while-revalidate=10

參數

limit選填
integer· min 1
cursor選填
string· max 128 · min 1

上一頁回應的 nextCursor;第一頁不帶

回應欄位 · data

items
object[]
slug
string

日誌網址 slug;以它呼叫 `journal/{slug}`。

title
string

標題。

excerpt
string | null

摘要;未設定為 null。

coverImageUrl
string | null

封面圖的絕對網址;未設定為 null。

publishedAt
string

發布時間(ISO 8601,UTC)。

authorName
string | null

作者(嚮導)名稱;未設定為 null。

updatedAt
string

Last edit time (ISO 8601, UTC). Use it for `dateModified` and sitemap `lastmod`.

nextCursor
string | null
請求
curl -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": "…"
  }
}

一篇日誌的完整內容

GET/api/storefront/v1/journal/{slug}
前台金鑰Cache-Control: no-cache平台邊緣快取: public, s-maxage=10, stale-while-revalidate=10

參數

slug路徑
string· min 1

日誌 slug(路徑參數)

回應欄位 · data

bodyHtml
string | null
title
string

標題。

slug
string

日誌網址 slug;以它呼叫 `journal/{slug}`。

excerpt
string | null

摘要;未設定為 null。

coverImageUrl
string | null

封面圖的絕對網址;未設定為 null。

seoTitle
string | null

SEO title override; null uses the post title.

seoDescription
string | null

SEO description override; null uses the excerpt.

ogImageUrl
string | null

Absolute sharing image URL; null uses the cover image.

updatedAt
string

Last edit time (ISO 8601, UTC). Use it for `dateModified` and sitemap `lastmod`.

publishedAt
string

發布時間(ISO 8601,UTC)。

authorName
string | null

作者(嚮導)名稱;未設定為 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、聯絡方式、交易鏈網址

GET/api/storefront/v1/site
前台金鑰Cache-Control: no-cache平台邊緣快取: public, s-maxage=10, stale-while-revalidate=10

回應欄位 · data

name
string

品牌名(`tenant_settings.company_name`)。

homeTitle
string | null

首頁標題整句(含品牌段,後台「網站 → SEO → 首頁標題」);未設定為 null,由前台自訂預設。

ogImageUrl
string | null

預設分享圖的絕對網址(後台「網站 → SEO → 預設分享圖」);未設定為 null,由前台自訂預設。

logoUrl
string | null

Logo 的絕對網址;未設定為 null。

phone
string | null

聯絡電話;未設定為 null。

email
string | null

對外聯絡信箱(`tenant_settings.company_email`);未設定為 null,不退回系統信的回覆信箱。

lineOfficialUrl
string | null

LINE 官方帳號加好友網址;未設定為 null。

facebookUrl
string | null

Facebook 粉專網址;未設定為 null。

instagramUrl
string | null

Instagram 網址;未設定為 null。

youtubeUrl
string | null

YouTube 頻道網址;未設定為 null。

shopUrl
string

交易鏈網址(平台供應的結帳、會員、訂單頁所在的 origin)。

memberUrl
string

會員中心網址。

請求
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 分頁

GET/api/storefront/v1/trips
前台金鑰Cache-Control: no-cache平台邊緣快取: public, s-maxage=10, stale-while-revalidate=10模組:tour

參數

limit選填
integer· min 1
cursor選填
string· max 64 · min 1

上一頁回應的 nextCursor;第一頁不帶

回應欄位 · data

items
object[]
tags
string[]

Free-form trip tags. The website defines its own filters.

difficultyLevel
number | null

Public difficulty, from 1 (easy) to 5 (challenging). Null means unrated.

slug
string

行程網址 slug;以它呼叫 `trips/{slug}`。

title
string

行程標題。

summary
string | null

一句話摘要;未設定為 null。

destination
string

目的地名稱。

isOverseas
boolean

True when the trip goes outside Taiwan (the admin "海外" trip flag).

isClimbing
boolean

登山行程(後台的「登山」行程旗標)。租戶沒開登山模組時一律 false。

durationDays
number

天數。

hasPreTripNight
boolean

True when the trip starts with a gathering night before departure (Day 0). The night adds one night to the trip length.

priceFromTwd
number

「NT$ X 起」的起價(TWD 整數)。

depositFromTwd
number | null

「訂金 NT$ X 起」:可報名出團中,一位旅客的最低訂金(TWD)。沒有訂金、訂金就是全額, 或訂金是每張訂單一筆時為 null。各出團的訂金細節讀 `trips/{slug}/departures` 的 `deposit`。

coverImageUrl
string | null

封面圖的絕對網址;未設定為 null。

nextDepartureDate
string | null

最近一個前台可報名出團的出發日(`YYYY-MM-DD`);沒有為 null。

updatedAt
string

Last 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.

nextCursor
string | null
請求
curl -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": "…"
  }
}

行程內容

GET/api/storefront/v1/trips/{slug}
前台金鑰Cache-Control: no-cache平台邊緣快取: public, s-maxage=10, stale-while-revalidate=10模組:tour

參數

slug路徑
string· min 1

行程 slug(路徑參數)

回應欄位 · data

bodyHtml
string | null
lodging
object[]

住宿配套;沒有配套或住宿模組未開通時為空陣列。

name
string
location
string | null
description
string | null
nights
number

本行程在此據點住幾晚。

facilities
object[]
key
string
label
string
imageUrls
string[]

據點相簿的絕對網址;沒有相簿時退回封面圖。

roomTypes
object[]
name
string
description
string | null
capacityPerUnit
number

每間最多人數。

beds
object[]

床型與床數。

label
string
count
number
floorSizeSqm
number | null

坪數;未設定為 null。

facilities
object[]
key
string
label
string
imageUrls
string[]

房型照片的絕對網址。

title
string
slug
string
coverImageUrl
string | null

封面圖的絕對網址;未設定為 null。

seoTitle
string | null

SEO title override; null uses the trip title.

seoDescription
string | null

SEO description override; null uses the summary.

ogImageUrl
string | null

Absolute sharing image URL; null uses the cover image.

isOverseas
boolean

True when the trip goes outside Taiwan (the admin "海外" trip flag).

updatedAt
string

Last 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.

tags
string[]

Free-form trip tags. The website defines its own filters.

summary
string | null
destination
string
durationDays
number
difficultyLevel
number | null

Public difficulty, from 1 (easy) to 5 (challenging). Null means unrated.

priceFromTwd
number
notices
string[]

注意事項。

suggestedFlights
StorefrontSuggestedFlightsDto | null

建議航班;沒填或資料有錯時為 null。結構見 `StorefrontSuggestedFlightsDto`: `plans[]`(推薦方案在第一個)→ `segments[]`(搭飛機)或 `airports[]`/`route`(車站集合)。

updated
string

最後核對班表的年月 YYYY-MM。

ticket
"不含" | "可代訂" | "含"

機票:不含/可代訂(不含但可代訂)/含。

plans
object[]

推薦方案在第一個。

name
string
primary
boolean

推薦方案;陣列第一個一定是推薦方案。

mode
"flight" | "station"

flight=搭飛機到機場集合(看 `segments`);station=自行前往車站集合(看 `airports`、`route`)。

meetDay
number

集合在行程第幾天。

meetTime
string | null

集合時間 HH:MM;null=抵達後。

meetPlace
string
segments
object[]

航班;station 方案為空陣列。

dir
"dom" | "out" | "ret"

out=去程、ret=回程、dom=當地國內線。同一方向依陣列順序是第 1、2、3 段。

flight
string

完整班號,例如 `CI118`。

airline
string

航空公司名稱,例如「中華航空」。

from
string

出發機場 IATA 三碼。

fromName
string

出發機場短名,例如「桃園」。

to
string

抵達機場 IATA 三碼。

toName
string

抵達機場短名。

depDay
number
dep
string

起飛時間 HH:MM。

arrDay
number
arr
string

抵達時間 HH:MM。

airports
object[]

建議抵達機場,第一個最推薦;flight 方案為空陣列。

code
string

IATA 三碼。

name
string

短名,例如「名古屋中部」。

route
string | null

接駁路線;flight 方案為 null。

duration
string | null

接駁所需時間與方式;flight 方案為 null。

arriveDayBefore
boolean

建議前一天抵達。

cancellationFeeTiers
object[]

生效的退改費階梯(行程覆寫,否則租戶預設),依 `daysBefore` 降序。

daysBefore
number

距出發日 ≥ 此天數時適用本列。0 是出發當天。

feePercent
number | null

扣款百分比(0–100);定額扣款的列為 null。

feeFixedTwd
number | null

每人定額扣款(TWD 整數);百分比扣款的列為 null。

isClimbing
boolean

登山行程(後台的「登山」行程旗標)。租戶沒開登山模組時一律 false。

isLinkOnly
boolean

True 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).

hasPreTripNight
boolean

True when the trip starts with a gathering night before departure (Day 0). The night adds one night to the trip length.

foreignTravelersOnly
boolean

True 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
object[]

行程相簿(依顯示順序)。

url
string

圖片的絕對網址。

caption
string | null

圖說;未設定為 null。

feeIncludes
string[]

費用包含。

feeExcludes
string[]

費用不包含。

請求
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": [
      "…"
    ]
  }
}

行程的出團、價格、名額與報名狀態

GET/api/storefront/v1/trips/{slug}/departures
前台金鑰Cache-Control: no-cache平台邊緣快取: public, s-maxage=1模組:tour

參數

slug路徑
string

路徑參數

回應欄位 · data

departures
object[]
id
string

出團 id(`dep_` 前綴)。

departureDate
string

出發日(`YYYY-MM-DD`)。

returnDate
string

回程日(`YYYY-MM-DD`)。

priceTwd
number

每人直客價(TWD)。與結帳計價同一個函式,促銷中的出團是促銷價。

capacity
number

名額上限(人數)。

remainingSeats
number

剩餘名額(人數),不小於 0。

bookingState
"lottery" | "open" | "soldout" | "waitlist"
availability
object

公開可報名度:狀態、剩餘名額、一張單的人數上限、成團差額。與平台的行程頁同一個判準。

status
"closed" | "lottery" | "lottery_full" | "low" | "open" | "soldout" | "waitlist"

可報名度:`open` 有名額;`low` 有名額但快額滿(剩 1 或 2 位);`soldout` 額滿且不收候補; `waitlist` 額滿但收候補;`lottery` 抽籤制、有名額;`lottery_full` 抽籤制、額滿; `closed` 不開放報名。之後可能新增值,不認得的值請當成不可報名。

remainingSeats
number

剩餘名額(人數),不小於 0。

maxPartySize
number

一張單最多可報幾位。額滿收候補時是名額上限;不可報名時是 0。

seatsToMinGroupSize
number | null

還差幾位達到行程的最低成團人數:0 是已成團;行程未設定最低成團人數為 null。

bookingUrl
string

報名網址:`https://<交易鏈網域>/checkout?departure_id=<出團 id>`,直接進結帳流程第一步。

lotteryLeadDays
number | null

抽籤日在出發日前幾天(後台的「抽籤前幾天」)。梯次有設定用梯次的值,否則用行程的值; 都沒設定為 null。抽籤時程表有這一天時,實際抽籤日以時程表為準。

deposit
StorefrontDepositDto | null

訂金。沒設訂金、或一位旅客的訂金就是全額時為 null(只能付全額)。

basis
"per_order" | "per_person"

計算單位:`per_person` 每位旅客一份訂金;`per_order` 每張訂單一筆,不看人數。 比例訂金一律是 `per_person`。

amountTwd
number

一位旅客報名時的訂金(TWD)。`per_person` 的固定金額訂金是這個金額乘人數; 比例訂金按結帳的總額取整,不要自己乘。

percent
number | null

比例訂金的百分比(1–100);固定金額為 null。比例訂金以折扣後的總額計算。

required
boolean

true:租戶只收訂金,結帳不提供付全額。false:客人可選付全額或付訂金。

balanceDue
BalanceDueRule

尾款期限:`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,客人只能付全額。金額與結帳用同一個計算。

欄位意義
basisper_person 每位旅客一份訂金;per_order 每張訂單一筆,不看人數。
amountTwd一位旅客報名時的訂金。per_person 的固定金額訂金是這個金額乘人數;比例訂金按結帳的總額取整,不要自己乘。
percent比例訂金的百分比;固定金額是 null。比例訂金以折扣後的總額計算,畫面上請註明以結帳為準。
requiredtrue 時租戶只收訂金,結帳不提供付全額。可寫「報名只需先付訂金」。
balanceDue尾款期限,見下表。
balanceDue.kind意義
before_date不抽籤的梯次。尾款於 date 前繳。
after_lottery_win抽籤梯次。中籤時才訂期限,尾款於中籤後 days 天內繳。

尾款期限照這個欄位寫。不要寫「成團後補尾款」:尾款期限不看成團。之後可能新增 kind 的值,不認得時只顯示訂金。

行程列表的卡片帶 depositFromTwd:可報名梯次中,一位旅客的最低訂金,用來顯示「訂金 NT$ X 起」。訂金是每張訂單一筆的行程,這個欄位是 null。

報名網址

每個梯次都附一個報名網址。把客人連到這個網址,客人會直接進入結帳流程,第一步已選好該梯次,再選人數。

shell
https://<報名網域>/checkout?departure_id=<梯次 id>

這個格式是平台的承諾。你可以直接存網址,也可以自己照格式組。平台改格式時,會保留舊網址的轉址。自建前台模式下,舊格式 /tour/<行程 slug>?departure=<梯次 id> 會轉進結帳流程。

廣告追蹤

客人按下報名之後,報名、付款與訂單頁都在報名網域上。要在自己的 GA4 與 Meta 帳號看到成交,照下面四步做:

  1. 在後台「網站」的「追蹤」分頁填入 GA4 Measurement ID 與 Meta Pixel ID。報名、付款與訂單頁會載入追蹤碼。
  2. 在同一頁貼上 GA4 Measurement Protocol API secret 與 Meta Conversions API access token。第一筆款項入帳時,平台送出 purchase,帶訂單編號、金額與行程。
  3. 在官網的 gtag 設定跨網域,把報名網域加進 linker.domains。平台端已經接受官網帶來的 _gl。
  4. 在 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

這個標頭告訴平台,這次請求是替哪一位客人發出的。平台只用它分配每位客人的額度,不寫進稽核,也不做安全判斷。

後端在 CDN 或反向代理之後時,只採信你自己的代理寫入的位址。

API 版本

前台 API 與員工 API 共用同一條 API 版本線,規則見 API 參考 的「API 版本」。請求帶 Toko-Version header 時用它;沒帶時用金鑰的釘選版本。每個回應都帶 Toko-Version,值是實際使用的版本。金鑰驗證失敗、限速與版本錯誤的回應不帶它。

錯誤碼

錯誤回應的格式與員工 API 相同。程式請判斷錯誤碼,不要比對說明文字。

›錯誤格式與錯誤碼
json
{
  "ok": false,
  "error": { "code": "unauthorized", "message": "前台金鑰無效" }
}

參數錯誤(422 validation)另外帶 error.issues,列出每個欄位的錯誤。

HTTPcode
400version_invalid
400version_required
400version_unsupported
401unauthorized
403module_disabled
404not_found
422validation
429rate_limited
500internal
503rate_limit_unavailable
503service_unavailable
503transaction_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)。

相關指南

Command Palette

Search for a command to run...