API 快速入門：上傳、檔案檢查、報價

開始前

API 可透過訪客工作階段在無帳戶的情況下使用。API 位於網站自身的位址下，路徑為 /api。請設定一次：

API=https://dev.uliketechnology.com/api
F=board.zip

board.zip 是包含您的 Gerber 與鑽孔檔案的平面 zip 檔。其內容請參閱 製造與組裝所需檔案。這些範例需要 curl 與 jq。

訪客工作階段之後，對 API 的每個請求都帶有 Authorization: Bearer <token>。每個錯誤的格式都相同：

{ "error": { "code": "VALIDATION_FAILED", "message": "…", "details": {}, "requestId": "…" } }

請依 code 判斷。message 是給開發人員看的。

1. 訪客工作階段： token 只顯示一次。
2. 上傳： 使用 API 指定的標頭，將 zip 以 PUT 送至 API 指定的位址。
3. 完成上傳， 然後輪詢，直到分析完成。
4. 報告： 檢查發現、已執行的檢查，以及未執行的檢查。
5. 報價預覽。

使用 curl 的流程

讀取可訂購的內容。此呼叫不需要 token：

curl -s $API/v1/capabilities | jq '.options[].id'

開啟訪客工作階段。token 只顯示一次，有效期為 30 天：

T=$(curl -s -X POST $API/v1/guest-sessions | jq -r .token)

宣告檔案。回應包含 uploadId、designId、uploadUrl 與 requiredHeaders：

J=$(curl -s -X POST $API/v1/uploads -H "authorization: Bearer $T" -H 'content-type: application/json' \
  -d "{\"fileName\":\"board.zip\",\"sizeBytes\":$(stat -c %s $F),\"sha256\":\"$(sha256sum $F | cut -d' ' -f1)\",\"purpose\":\"design\"}")

將檔案送至回應指定的位址，並帶上 requiredHeaders 中的每個標頭（內容類型、長度與總和檢查碼；缺少這些標頭時，上傳會以 403 拒絕）。然後完成上傳：

curl -s -X PUT --data-binary @$F \
  $(echo $J | jq -r '.requiredHeaders | to_entries[] | "-H \(.key):\(.value)"') \
  "$(echo $J | jq -r .uploadUrl)"
curl -s -X POST $API/v1/uploads/$(echo $J | jq -r .uploadId)/complete -H "authorization: Bearer $T" | jq .design.status

狀態起初為 analysing。請讀取設計，直到狀態改變。當狀態為 ready 時，報告就在回應中：

D=$(echo $J | jq -r .designId)
curl -s $API/v1/designs/$D -H "authorization: Bearer $T" | jq '.design.status, .report.headline, .report.counts'

標題為 no_problems_in_checks_run、problems_found 或 could_not_check。也請讀取 checksRun 與 checksNotRun：未執行的檢查不算通過。其他狀態為 needs_mapping（使用 PUT /v1/designs/{designId}/layer-mapping 設定層）、needs_engineer 與 rejected。

要求價格預覽。selection 與 destinationCountry 為必填；空的 selection 會採用預設值：

curl -s -X POST $API/v1/quote-previews -H "authorization: Bearer $T" -H 'content-type: application/json' \
  -d "{\"designId\":\"$D\",\"quantities\":{\"boardsFabricated\":10,\"boardsAssembled\":0},\"selection\":{},\"destinationCountry\":\"DE\"}" \
  | jq '.mode, .reviewReasons, .totalMinor'

mode 為 instant（價格如顯示所示成立）或 review（由工程師確認）；reviewReasons 說明原因。totalMinor 以回應中 currency 的最小單位表示；當工作須由工程師定價時，此欄位不存在。若要儲存報價，POST /v1/quotes 接受相同的請求主體。

使用 JavaScript 用戶端的相同流程

@ulike/sdk 用戶端封裝了這些路由。它尚未以套件形式發布；以下是其形式，讓您可以用 fetch 撰寫相同的呼叫。方法名稱：

import { createClient } from '@ulike/sdk';

let token;
const api = createClient({ baseUrl: 'https://dev.uliketechnology.com/api', token: () => token });

const caps = await api.capabilities();
token = (await api.createGuestSession()).token;
const started = await api.uploadDesign({ name: 'board.zip', bytes }); // announce, PUT, complete
const view = await api.waitForDesign(started.design.id); // polls getDesign
const preview = await api.previewQuote({
  designId: view.design.id,
  quantities: { boardsFabricated: 10, boardsAssembled: 0 },
  selection: {},
  destinationCountry: 'DE',
});

其他方法為 createUpload、completeUpload、getDesign、setLayerMapping、validateDesign、getValidation、waitForValidation、createQuote、getQuote 與 reviseQuote。錯誤會以 ApiClientError 擲出，並帶有 status 與 code。

針對訂單的檢查

您在上傳後取得的報告僅根據檔案本身產生。若要針對訂單檢查檔案，請呼叫 POST /v1/designs/{designId}/validations（validateDesign），並在 order 中放入 quantities 與 selection。回應是一個狀態：running、failed 或 done。當狀態為 running 時，每一至兩秒讀取一次 GET /v1/validations/{reportId}（getValidation），直到狀態為 done。

1. 上傳 zip 檔。
2. 讀取報告。
3. 修正並以新設計上傳。 當修正會改變功能、價格或交貨時間時，請停止並詢問對方。
4. 檔案無問題： 執行針對訂單的檢查。

帶有會引入其他限制之選項（較厚的銅、不同的厚度）的報價或預覽，需要針對該選擇進行檢查。若不存在這類檢查，系統會啟動一項檢查，預覽會帶有審查原因 file_check_pending，以及帶有其 reportId 的 check。價格會立即顯示，但報價會保持在 review 狀態，直到該檢查完成。請依上述方式讀取該檢查，然後再次要求預覽。

您會遇到的錯誤

另外也可能出現 DESIGN_REJECTED（上傳被拒絕；請參閱 details.reason）、用於 token 缺失或錯誤的 UNAUTHENTICATED（錯誤的 token 即使在公開路由上也會被拒絕），以及用於尚未開放路由的 FEATURE_DISABLED。

無帳戶時的每日額度

訪客工作階段有每日的運算額度。上傳與已啟動的檢查比一般讀取消耗更多額度，從同一個網路位址開啟許多訪客工作階段也會列入計算。網站為新選擇自行啟動的檢查會扣同一額度。額度用完時，您會收到 ANONYMOUS_BUDGET_SPENT 以及重置日期。已登入的呼叫者不以此方式計算。

API 目前無法做的事：訂購、付款、API 金鑰，以及供代理程式使用的登入功能，都在規劃中，尚不可用。規劃中的 MCP 伺服器請參閱 什麼是 MCP 以及代理程式如何訂購。