開始する前に
アップロード、ファイルチェック、見積もりは、ゲストセッションを通じてアカウントなしで利用できます。注文にはアカウントが必要です。下の「見積もりから注文へ」を参照してください。API は、サイト自体のアドレス配下の /api にあります。最初に一度設定してください。
API=https://uliketechnology.com/api
F=board.zip
board.zip は、ガーバーファイルとドリルファイルをフラットにまとめた zip です。含める内容については、製造と実装に必要なファイル を参照してください。例では curl と jq が必要です。
ゲストセッション以降の API へのすべてのリクエストには、Authorization: Bearer <token> を付けます。API キーも、ゲストトークンの代わりに同じヘッダーに入れます。すべてのエラーは同じ形式です。
{ "error": { "code": "VALIDATION_FAILED", "message": "…", "details": {}, "requestId": "…" } }
code で分岐してください。message は開発者向けです。
- ゲストセッション: トークンは一度だけ表示されます。
- アップロード: API が示すアドレスへ、API が示すヘッダーとともに zip を
PUTしてください。 - 完了させ、 解析が終わるまでポーリングしてください。
- レポート: 指摘事項、実行されたチェックと実行されなかったチェックです。
- 見積もりプレビュー。
curl でのフロー
注文できる内容を確認してください。トークンは不要です。
curl -s $API/v1/capabilities | jq '.options[].id'
ゲストセッションを開いてください。トークンは一度だけ表示され、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 に同じ body を送信してください。
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 です。エラーは status と code を持つ ApiClientError としてスローされます。
注文に対するチェック
アップロード後に得られるレポートは、ファイルのみに基づいて作成されます。ファイルを注文と照合するには、order に quantities と selection を入れて POST /v1/designs/{designId}/validations(validateDesign)を呼び出してください。応答は状態です:running、failed、done のいずれかです。running の間は、done になるまで1〜2秒ごとに GET /v1/validations/{reportId}(getValidation)を読んでください。
- アップロード 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 | アカウントなしの1日の利用枠を使い切りました。details.resetsOn がその日付です。 |
停止してください。その人に伝えてください。ログインするか、その日付まで待てます。 |
REVISION_CONFLICT |
409 | リビジョンが指定したベースが、見積もりの最新版ではなくなりました。details に両方のヘッドが含まれます。 |
GET /v1/quotes/{quoteId} でヘッドを読み、その上に変更を再適用して再送信してください。 |
他にも、DESIGN_REJECTED(アップロードが拒否されました。details.reason を参照してください)、トークンがないか間違っている場合の UNAUTHENTICATED(間違ったトークンは公開ルートでも拒否されます)、キーまたはゲストトークンで呼び出せないルートに対する FORBIDDEN、無効化されているルートに対する FEATURE_DISABLED があります。
アカウントなしの1日の利用枠
ゲストセッションには、計算の1日の利用枠があります。アップロードと開始されたチェックは、通常の読み取りより多く消費します。1つのネットワークアドレスから多くのゲストセッションを開くこともカウントされます。新しい選択のためにサイトが自動で開始するチェックも、同じ利用枠に課金されます。使い切ると、リセット日付とともに ANONYMOUS_BUDGET_SPENT が返されます。ログインした呼び出し元はこのようにはカウントされません。
見積もりから注文へ
注文は、アカウントに属する保存した見積もりから発注します。ゲストトークンは注文ルートで拒否されます。プログラムがアカウントのために動作する方法は2つあり、どちらも 開発者とアシスタント向け で説明しています。
- API キー。 その人がアカウントの API キーで作成し、できることを選びます。
Authorization: Bearer ulk_…として送信してください。そのキーで作成した見積もりは、そのアカウントに属します。テストキー(ulk_test_…)はサンプルデータでのみ使えます。 - プログラム向けログイン。 アシスタントが自身を登録し、その人がサイトのページで求めている操作を確認して許可するを押し、アシスタントはその権限に限定されたトークンを受け取ります。
保存した配送先は GET /v1/addresses で読んでください。配送先の追加や変更は、その人がブラウザで行います。配送先は、見積もりの destinationCountry の範囲内である必要があります。
注文は POST /v1/orders で発注してください。このルートには Idempotency-Key ヘッダーが必要です。意図する注文ごとに、8〜80文字の表示可能文字からなる新しいキーを1つ用い、再試行時には同じキーを再度使ってください。
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 キーでも、ログインしたアシスタントのトークンでも、回答は APPROVAL_REQUIRED(422)と details.approvalUrl です。そのリンクをその人に渡してください。その人がリンクを開き、ログインし、注文内容と合計を確認して、承認または拒否します。リンクは1回だけ有効で、24時間で期限が切れ、見積もりまたは合計が変わると使えなくなります。
承認後、注文が存在します。GET /v1/orders でアカウントの注文を一覧し、GET /v1/orders/{orderId} で1件を読んでください。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 とは何か、エージェントはどのように発注するか を参照してください。