開始前
上傳、檔案檢查與報價可透過訪客工作階段在無帳戶的情況下使用。訂購需要帳戶:請參閱下文「從報價到訂單」。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 是給開發人員看的。
- 訪客工作階段: token 只顯示一次。
- 上傳: 使用 API 指定的標頭,將 zip 以
PUT送至 API 指定的位址。 - 完成上傳, 然後輪詢,直到分析完成。
- 報告: 檢查發現、已執行的檢查,以及未執行的檢查。
- 報價預覽。
使用 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。
- 上傳 zip 檔。
- 讀取報告。
- 修正並以新設計上傳。 當修正會改變功能、價格或交貨時間時,請停止並詢問對方。
- 檔案無問題: 執行針對訂單的檢查。
帶有會引入其他限制之選項(較厚的銅、不同的厚度)的報價或預覽,需要針對該選擇進行檢查。若不存在這類檢查,系統會啟動一項檢查,預覽會帶有審查原因 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 以及代理程式如何訂購。