線上下單即將開放。在此之前,請寫信至 support@uliketechnology.com,工程師會回覆您。

全部指南

AI 助理

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

將電路板檔案送至檔案檢查報告、價格與訂單的呼叫,包含 curl 與 JavaScript 用戶端,以及您會遇到的錯誤。

給 AI 助理更新於 2026-11-172 分鐘閱讀供 AI 助理使用的原始 Markdown

本文所述的 API 與 MCP 伺服器將與線上下單同時開放。

開始前

上傳、檔案檢查與報價可透過訪客工作階段在無帳戶的情況下使用。訂購需要帳戶:請參閱下文「從報價到訂單」。API 位於網站自身的位址下,路徑為 /api。請設定一次:

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

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

訪客工作階段之後,對 API 的每個請求都帶有 Authorization: Bearer <token>。API 金鑰放在同一個標頭中,代替訪客 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://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、listAddresses、placeOrder、getOrder、listOrders 與 cancelOrder。錯誤會以 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_NOT_READY 422 設計仍在讀取中(details.status 會說明目前狀態),或尚無報告。 讀取設計,直到狀態不再是 analysing,然後再次要求。
VALIDATION_FAILED 400 請求不符合預期格式,或指定了目錄中沒有的選項或值。details 列出問題。 修正 details 中指出的欄位後重新送出。選項 id 與值請取自 GET /v1/capabilities。
NOT_MANUFACTURABLE 422 該選擇是本廠不生產的項目。details.because 帶有原因。 請更改選擇;不要以相同選擇重試。若更改會改變電路板,請詢問對方。
ANONYMOUS_BUDGET_SPENT 429 無帳戶時的每日額度已用完。details.resetsOn 是重置日期。 停止。告知對方;對方可以登入,或等到該日期。
REVISION_CONFLICT 409 修訂版指定的基底已不再是報價的最新版。details 帶有兩者的最新版資訊。 使用 GET /v1/quotes/{quoteId} 讀取最新版,在其上重新套用您的更改,然後再次送出。

另外也可能出現 DESIGN_REJECTED(上傳被拒絕;請參閱 details.reason)、用於 token 缺失或錯誤的 UNAUTHENTICATED(錯誤的 token 即使在公開路由上也會被拒絕)、金鑰或訪客 token 無權呼叫該路由時的 FORBIDDEN,以及用於已關閉路由的 FEATURE_DISABLED。

無帳戶時的每日額度

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

從報價到訂單

訂單從屬於某個帳戶的一份已儲存報價下單。訪客 token 在訂單路由上會被拒絕。程式透過兩種方式之一為帳戶工作,兩種方式都在 給開發人員與助理 中說明:

  • API 金鑰。 對方在其帳戶的 API 金鑰下建立它,並選擇它可以執行的操作。將其作為 Authorization: Bearer ulk_… 送出。用該金鑰建立的報價屬於該帳戶。測試金鑰(ulk_test_…)只能用於範例資料。
  • 供程式使用的登入。 助理自行註冊,對方在本站的一個頁面上看到它請求執行的操作並按下允許,助理隨即獲得一個僅限於這些權限的 token。

使用 GET /v1/addresses 讀取已儲存的地址。地址由對方在瀏覽器中新增或變更。收貨地址必須位於報價的 destinationCountry 內。

使用 POST /v1/orders 下單。該路由需要 Idempotency-Key 標頭:每個預期訂單使用一個由 8 到 80 個可見字元組成的新金鑰,重試時再次使用同一金鑰:

curl -s -X POST $API/v1/orders -H "authorization: Bearer $KEY" -H 'content-type: application/json' \
  -H "idempotency-key: $(uuidgen)" \
  -d "{\"quoteId\":\"$Q\",\"expectedTotalMinor\":$TOTAL,\"shipToAddressId\":\"$SHIP\",\"billToAddressId\":\"$BILL\",\"paymentMethod\":\"bank_transfer\",\"termsVersion\":\"$TERMS\",\"dangerousGoods\":false}"

expectedTotalMinor 是對方同意的報價的 totalMinor。termsVersion 指明對方接受的銷售條款版本。dangerousGoods 說明貨物中是否含有電池或其他危險品。

此呼叫不會下單。無論使用 API 金鑰,還是使用已登入助理的 token,回覆都是 APPROVAL_REQUIRED(422)與 details.approvalUrl。將該連結交給對方。對方開啟它,登入,查看訂單與總計,然後核准或拒絕。該連結只能使用一次,24 小時後到期,當報價或總計變更時即失效。

核准後,訂單即存在:使用 GET /v1/orders 列出帳戶的訂單,使用 GET /v1/orders/{orderId} 讀取其中一份。其中 order.number 為訂單編號,形式發票編號位於 proFormaNumber 中,收款帳戶位於 sellerBank 中,payments 下的 bankReference 為轉帳時填寫的參考編號。

付款透過銀行轉帳進行,由對方完成。任何金鑰和任何助理都不能付款。使用 GET /v1/orders/{orderId} 追蹤訂單。工程師在生產前確認每份訂單。

代碼 狀態 含義 處理方式
APPROVAL_REQUIRED 422 需要已登入的人先核准。details.approvalUrl 為該頁面。 將連結交給對方。不要尋找繞過的方法。
TOTAL_MISMATCH 422 expectedTotalMinor 不是報價的總計。details.totalMinor 為總計。 再次讀取報價,在再次詢問前向對方顯示價格。
QUOTE_EXPIRED 410 報價已超過有效期。 修訂報價以取得新價格,並向對方顯示。
CONFLICT 409 details.reason 為 quote_ordered 或 quote_not_priced(需要工程師先給出價格)。 不要重試。告知對方。
INTAKE_CLOSED 503 目前不接受訂單。details.reopensOn 為恢復日期(如有)。 停止。告知對方。

同一項服務也透過 MCP 伺服器以具名工具的形式提供給助理:請參閱什麼是 MCP 以及代理程式如何訂購。