即時追蹤

即時追蹤會在你已發佈的地圖上顯示車輛現在在哪裡、今天在哪裡停靠：例如餐車的路線、接駁車環線、行動診所。訪客會看到每輛在班車輛在地圖上移動，今天的站點帶有就在這裡、營業中或今日休息，以及距下一站還要多久的預估。訪客看到的內容請參閱即時版面。

它由三個部分組成，都在 Kaleidr Studio 中：

部分	是什麼
一個站點集合	時刻表：每個站點、其地址及每週的服務時段。它和其他地點資料庫集合一樣。
一個車隊	你的車輛、它們的班次，以及訪客看到它們的精確度。在資料、車隊下管理。
位置	每輛車的位置，來自以下四種來源之一：司機的報到連結、司機模式下的手機、你自己的追蹤器，或連接你車載資訊服務供應商的連接器。

只有車輛在班時才會顯示其位置。 在該車輛所有班次之外記錄的位置會在送達時被捨棄：從不儲存、從不顯示，只計數。參閱班次。

車隊

在資料下選擇車隊分頁，然後選擇新增車隊。為它命名並設定時區，若有站點集合，則選擇其站點集合。Studio 會建立一個同名的車輛集合：這個集合就是你地圖上的車隊，你可以像加入任何集合一樣把它加入地圖。它不包含匯入的地點；其中的車輛就是車隊的車輛。

車隊頁面上的新增車輛可新增一輛：

欄位	訪客可見	用途
名稱	是	車輛在地圖和面板中的標籤，例如「1 號餐車」。在車隊內唯一。
類型	是	卡車、廂型車、轎車、公車、接駁車、船、推車或自行車。
顏色	是	車輛在地圖上的顏色。
描述	是	卡片上的一行簡短說明，最多 200 個字元。
外部 ID	否	你自己的 ID，供連接器以及站點的車輛欄位比對使用。
班次時間	否	依排定時間營運的車隊中，班次所遵循的每週時間。參閱班次。

停用的車輛從不顯示，其位置也會被捨棄。車隊頁面會以完整精確度繪製車隊的即時地圖，只有你看得到。

擁有者、管理員和成員管理車隊和車輛；檢視者可以檢視。只有擁有者和管理員可以刪除車隊、清除車輛的歷史以及管理連接器。刪除車隊會刪除車隊及其車輛、裝置、連結、班次、歷史和連接器，然後刪除其車輛集合。

站點時刻表

時刻表是一個站點集合。每個站點都是一個帶有名稱以及地址或座標的地點，以下欄位決定它何時提供服務：

欄位	含義
營業時間	站點每週的服務時段，寫法與營業時間相同：每天最多四個時段。時段可以跨越午夜，並歸屬於其開始的那一天。
時區	時段所用的時區。空白時使用集合的時區。
狀態	`paused` 會讓站點每天都停止。任何其他值或空白則保留。
車輛	服務該站點的車輛名稱或外部 ID。空白時為車隊中的任何車輛。
服務日期	`YYYY-MM-DD` 格式的日期，以逗號或空格分隔。存在時，站點只在這些日期營運。

在某個日期，站點的時段為：

狀態為 paused，或時區無效時：無；
有服務日期但該日期不在其中時：無；
沒有營業時間時：若服務日期列出該日期則為全天，否則為無；
其他情況：當天是星期幾就用哪天的營業時間。

當今天的某個時段包含當地時間，或昨天某個跨越午夜的時段包含當地時間時，站點即為營業中。「今天」是車隊時區中的日期。

站點	查詢時間	時段	營業
營業時間週一 11:00–14:00	週一 12:00	11:00–14:00	是
同上	週一 15:00	11:00–14:00	否
同上，加上服務日期 `2026-11-02`	週一 2026-11-09，12:00	無	否
服務日期 `2026-11-02`，無營業時間	2026-11-02，09:00	全天	是
營業時間週一 11:00–14:00，狀態 `Paused`	週一 12:00	無	否
營業時間週五 22:00–02:00	週六 01:00	週五的 22:00–02:00	是
營業時間週一 11:00–14:00，時區無效	週一 12:00	無	未知
服務日期 `2026-11-02, 2026-11-03 2026-11-04`，營業時間週一 11:00–14:00	週二 2026-11-03	週二的營業時間：無	否

範本建立工具中的 Location 範本和下載範例試算表可讓你從一個已填好的站點集合開始。

報到連結

報到連結讓司機不需要應用程式、不需要帳戶，就能用任何手機瀏覽器標示車輛已抵達某個站點。

在車隊頁面上建立一個：選擇車輛，報到連結，建立連結。Studio 只會顯示一次該連結，並提供複製連結和可掃描的 QR 碼。連結看起來像 https://map-embed.kaleidr.com/checkin.html#…。

每輛車一個連結， 有效期 180 天。取代連結會產生新連結並立即讓舊連結失效；在手機遺失或司機離職時使用。撤銷連結會讓它失效。之後，Studio 只顯示連結的最後四個字元、到期時間和上次使用時間。
連結就是鑰匙。 任何持有它的人在站點附近都能替車輛報到。只與司機分享。
請在瀏覽器中開啟。 此頁面在其他頁面的框架中無法運作。

司機頁面顯示車輛、今天的站點及其狀態：

我已抵達會讀取一次手機位置，並在可及範圍內的站點報到：範圍為 250 公尺加上該讀數的精確度，且精確度必須在 100 公尺以內。範圍內有多個站點或沒有站點時，頁面會列出今天的站點，由司機選擇一個，該站點必須在 2,000 公尺以內。開啟了允許在站點以外報到的車隊還會提供非排定站點。
今日收工會把該車輛今天剩餘的站點標示為今日休息並結束其班次。今日恢復營業可在當天清除這些標示，但不會開始班次。

報到會開啟一個班次，持續到站點時段結束後 30 分鐘，並在站點本身的位置顯示車輛，而不是手機的位置。手機位置只用來尋找站點，之後即被捨棄。在站點以外報到時，車輛會在手機位置（四捨五入到約 10 公尺）顯示四個小時；如果車隊的公開精確度更粗，則依該精確度取整。

司機模式下的手機

裝有 Kaleidr 應用程式的司機手機會在司機班次期間分享車輛位置。在車隊頁面上選擇車輛的配對手機，再選擇顯示配對碼，會顯示一個 QR 碼和一個八碼代碼，有效期 10 分鐘，且只能使用一次。司機用手機相機掃描 QR 碼，或在應用程式中輸入代碼。司機這一側的操作請參閱司機模式。

裝置列出每輛車的手機和追蹤器。取消配對會立即移除一個裝置：它的下一次呼叫會遭拒，由它開始的班次也會結束。

追蹤器和位置 API

追蹤器是你自己的任何傳送位置的裝置或系統：帶 HTTP 用戶端的 GPS 裝置，或你自己的派車軟體。在車隊頁面上選擇車輛的新增定位器並為其命名，Studio 只會顯示一次它的金鑰。該金鑰屬於這輛車。

curl https://api.kaleidr.com/live-api/v1/positions \
  -H "Authorization: Bearer YOUR_DEVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "positions": [
      { "lat": 40.74110, "lng": -73.98970, "heading": 90, "speed": 8.3, "accuracy": 12,
        "recorded_at": "2026-10-22T15:04:05Z" }
    ],
    "sent_at": "2026-10-22T15:04:06Z"
  }'

欄位	規則
`positions`	1 到 100 個點，順序不拘。本文最大 64 KiB。
`lat`, `lng`	必填。在有效範圍內，且不能同時為 0。
`heading`	以正北為起點的角度。
`speed`	公尺每秒。
`accuracy`	公尺。精確度差於 100 公尺的點會被捨棄。
`recorded_at`	必填。測量位置的時間：RFC 3339，或自 1970 年起的毫秒數。
`sent_at`	依裝置時鐘記錄的批次傳送時間。若與 Kaleidr 的時鐘相差超過 5 秒但不到一天，每個 `recorded_at` 都會依差值校正；相差一天以上時，該批次會遭拒。

回應：

{
  "accepted": 1,
  "dropped": { "off_shift": 0, "stale": 0, "future": 0, "inaccurate": 0, "rate": 0, "duplicate": 0 },
  "shift": { "id": "…", "state": "on", "ends_at": "2026-10-23T03:04:05Z" },
  "min_interval_s": 10
}

捨棄原因	說明
`off_shift`	記錄時間不在該車輛的任何班次內，或車輛已停用。從不儲存。
`stale`	記錄於 12 小時以前。
`future`	記錄時間比 Kaleidr 的時鐘超前 30 秒以上。
`inaccurate`	精確度差於 100 公尺，或速度、精確度為負值。
`rate`	與該車輛上一個點的時間間隔短於你方案的更新間隔。
`duplicate`	已保留一個具有相同 `recorded_at` 的點。

GET /live-api/v1/device 傳回裝置、其車輛、車隊和進行中的班次。POST /live-api/v1/device/shift 搭配 { "action": "start" } 或 { "action": "end" }，可從裝置開始或結束車輛的班次。

狀態	`error`	含義
400	`invalid_request`	本文格式錯誤；`field` 指出出錯的部分。
400	`clock_invalid`	`sent_at` 與 Kaleidr 的時鐘相差一天以上。
401	`unauthorized`	沒有金鑰，或金鑰不明。
401	`device_revoked`	裝置已在 Studio 中被移除。請停止傳送。
409	`off_shift`	批次中有點，但沒有一個落在班次內，且沒有進行中的班次。在班次開始前停止傳送。
413	`batch_too_large`	超過 100 個點，或超過 64 KiB。
429	`rate_limited`	此裝置每分鐘的請求超過 12 次。等待 `Retry-After` 指定的秒數。

錯誤的格式為 { "error": <code>, "message": <sentence> }。行駛中請每 10 到 30 秒傳送一次：一批多個點比每個點一個請求更好。

連接器

連接器從你的車輛已在回報的車載資訊服務系統取得位置。擁有者和管理員可在車隊頁面的連接器、新增連接器中加入。連接器適用於 Pro 和 Enterprise。

連接器	你需要提供	位置如何送達
Samsara	一個對車輛位置有讀取權限的 API 權杖	Kaleidr 依擷取間隔向 Samsara 要求新位置。
Geotab	伺服器（一個 `geotab.com` 主機）、資料庫、使用者名稱、密碼	Kaleidr 依擷取間隔向 Geotab 要求新的記錄。
Traccar	不需提供：Studio 會顯示接收 URL 和密鑰	你的 Traccar 伺服器轉送每個位置。
Webhook	不需提供：Studio 會顯示接收 URL 和密鑰	你的系統傳送已簽署的批次。

憑證只寫不讀。 Studio 在儲存 Samsara 或 Geotab 憑證前會呼叫一次進行檢查，之後不再顯示。取代憑證可更換它。
接收密鑰只顯示一次。 更換密鑰會產生新密鑰；舊密鑰會繼續有效 24 小時。
比對方式決定供應商的車輛如何對應你的車輛：外部 ID（預設）或名稱。沒有對應的供應商車輛會列在未比對車輛下，並提供新增為車輛；其位置會被捨棄。
擷取間隔至少 30 秒，且不短於你方案的更新間隔。
狀態：正常；已暫停，由你暫停或因你的方案允許的連接器較少；發生錯誤，連續五次輪詢失敗後進入，仍會重試；無效，供應商拒絕憑證時進入，直到你更換憑證。已暫停或無效的 Traccar 或 webhook 連接器會拒絕傳給它的資料。

來自連接器的位置同樣要經過班次規則。

Traccar

使用 Studio 顯示的 URL 和密鑰，將以下幾行加入 Traccar 伺服器的設定檔 traccar.xml，然後重新啟動 Traccar：

<entry key='forward.enable'>true</entry>
<entry key='forward.url'>https://api.kaleidr.com/live-api/v1/ingest/YOUR_CONNECTOR_ID/traccar</entry>
<entry key='forward.json'>true</entry>
<entry key='forward.header'>X-Kaleidr-Connector-Secret: YOUR_CONNECTOR_SECRET</entry>

Traccar 裝置透過其唯一 ID（外部 ID）或名稱與車輛比對。Traccar 標示為無效的位置會被捨棄。

Webhook

每個請求最多向接收 URL 傳送 100 個點，並以連接器的密鑰簽署：

import { createHmac } from 'node:crypto';

const body = JSON.stringify({
  positions: [
    { vehicle: 'TRUCK-1', lat: 40.7411, lng: -73.9897, heading: 90, speed: 8.3, accuracy: 12,
      recorded_at: '2026-10-22T15:04:05Z' },
  ],
});
const t = Math.floor(Date.now() / 1000);
const v1 = createHmac('sha256', process.env.KALEIDR_CONNECTOR_SECRET).update(`${t}.${body}`).digest('hex');

await fetch('https://api.kaleidr.com/live-api/v1/ingest/YOUR_CONNECTOR_ID/webhook', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Kaleidr-Signature': `t=${t},v1=${v1}` },
  body,
});

Kaleidr-Signature 為 t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>，即預訂 webhook 的方案，只是方向相反。t 必須在 Kaleidr 時鐘的 5 分鐘以內，簽章必須涵蓋你傳送的確切位元組。
vehicle 是車輛的外部 ID 或名稱，取決於比對方式。speed 以公尺每秒為單位，accuracy 以公尺為單位，recorded_at 為 RFC 3339 或自 1970 年起的毫秒數。
簽章錯誤會以 401 signature_invalid 遭拒。

班次

班次是車輛可以被顯示的時間。每輛車最多只有一個進行中的班次，最長持續 16 小時。班次透過以下四種方式之一開始和結束：

由誰開始	何時結束
司機模式中的開始值勤	結束值勤，或 16 小時後
一次報到	站點時段結束後 30 分鐘、今日收工，或 16 小時後
Studio 中車輛的開始值勤	Studio 中的結束值勤，或 16 小時後
值勤模式為預定時間的車隊中，車輛的班次時間	這些時間結束時

不在班時，不發佈也不保留任何內容。 在所有班次之外記錄的位置會在送達時被捨棄。只保留被捨棄位置的數量，用於用量區段。
結束班次會讓車輛從你的地圖上消失， 在地圖下一次重新整理時生效。
連接器和追蹤器一直在回報，因此由班次決定。 在手動車隊中，只有在由司機、報到或 Studio 開啟的班次進行期間，它們的位置才會通過。在預定時間車隊中，車輛的班次時間會開啟和結束其班次。
移除裝置會結束由它開始的班次。

公開精確度

車隊頁面上的隱私與顯示設定訪客看到你車輛的精確度：

公開精確度	訪客看到	方向和速度
精確	精確到約 1 公尺的位置	顯示
街道，約 100 公尺（預設）	四捨五入到約 100 公尺的位置	顯示
區域，約 1 公里	四捨五入到約 1 公里的位置	不顯示

在站點報到的車輛顯示在站點本身的位置。
標示為過時的時間（30 到 900 秒；預設 120）：超過這段時間未回報的車輛會顯示 5 分鐘前出現。
隱藏的時間（60 到 3,600 秒；預設 900）：超過這段時間未回報的車輛不再顯示。
訪客只看得到每輛車的名稱、類型、顏色、描述、狀態、四捨五入後的位置和距上次回報的時間；精確度不是區域，約 1 公里時，還看得到方向和速度。裝置、外部 ID 和歷史從不公開。

歷史與保留

你可以在歷史下以完整精確度查看每輛車某一天的軌跡。歷史最多每 30 秒保留一個點（若你方案的更新間隔更長，則依該間隔），另外還會保留距上一個保留點 200 公尺以上的任何點。超過你方案的歷史天數後，點會被刪除，最長不超過 90 天。

清除歷史（擁有者和管理員）會一次刪除車輛的所有位置和已結束的班次。
刪除車輛或車隊會一併刪除其歷史。取消裝置配對不會刪除車輛的歷史。
歷史天數較少的方案會在下一次每日清理時刪除多出的歷史。

司機不是 Kaleidr 帳戶。這裡除了你輸入的裝置名稱外，沒有任何能識別某個人的資訊。

到達時間預估

即時版面會顯示車輛到達下一站需要多久，或到達詢問到我這裡要多久？的訪客需要多久。每一個這樣的時間都是估計：

它依道路距離和一般速度計算。不包含交通狀況， 車輛的實際路線也可能不同。
它從訪客看到的位置出發，即車隊公開精確度下的位置。
它以時長顯示，例如 約 12 分鐘，絕不顯示為到達時刻。沒有道路路線時顯示 無法估計。
訪客自己的位置只用於這次預估，從不儲存或記錄。

預估的次數限制為每位訪客每分鐘 20 次、每張地圖每天 2,000 次。它們不計入你的 Kaleidr AI 用量。

僅限 Kaleidr 地圖

即時車輛會繪製在使用 Kaleidr 自有底圖的地圖上：所有嵌入的 viewer 以及 Studio。Kaleidr Map 在顯示其他供應商的地圖時，不會繪製車隊的車輛。任何車輛位置都不會傳送給第三方地圖供應商。

限制

限制	Free	Pro	Enterprise
整個組織的啟用車輛	2	25	依你的協議設定
位置歷史天數	1	30	90
車輛相鄰兩點的最短間隔	30 秒	10 秒	5 秒
連接器	無	3	依你的協議設定

一個車隊最多 500 輛車。限制只會阻止新的操作：超出限制的組織會保留已有內容，但超出方案天數的歷史會被刪除，超出方案的連接器會被暫停。

車隊頁面上的用量顯示今天的計數：已接受的位置、被捨棄的位置及原因、訪客讀取次數和預估次數。

車隊​

站點時刻表​

報到連結​

司機模式下的手機​

追蹤器和位置 API​

連接器​

Traccar​

Webhook​

班次​

公開精確度​

歷史與保留​

到達時間預估​

僅限 Kaleidr 地圖​

限制​

相關內容​

車隊