APIクイックスタート：アップロード、チェック、見積もり

開始する前に

API は、ゲストセッションを通じてアカウントなしで利用できます。API は、サイト自体のアドレス配下の /api にあります。最初に一度設定してください。

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

board.zip は、ガーバーファイルとドリルファイルをフラットにまとめた zip です。含める内容については、製造と実装に必要なファイル を参照してください。例では curl と jq が必要です。

ゲストセッション以降の API へのすべてのリクエストには、Authorization: Bearer <token> を付けます。すべてのエラーは同じ形式です。

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

code で分岐してください。message は開発者向けです。

1. ゲストセッション： トークンは一度だけ表示されます。
2. アップロード： API が示すアドレスへ、API が示すヘッダーとともに zip を PUT してください。
3. 完了させ、 解析が終わるまでポーリングしてください。
4. レポート： 指摘事項、実行されたチェックと実行されなかったチェックです。
5. 見積もりプレビュー。

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://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 です。エラーは status と code を持つ ApiClientError としてスローされます。

注文に対するチェック

アップロード後に得られるレポートは、ファイルのみに基づいて作成されます。ファイルを注文と照合するには、order に quantities と selection を入れて POST /v1/designs/{designId}/validations（validateDesign）を呼び出してください。応答は状態です：running、failed、done のいずれかです。running の間は、done になるまで1〜2秒ごとに GET /v1/validations/{reportId}（getValidation）を読んでください。

1. アップロード zip をアップロードしてください。
2. レポートを読んでください。
3. 修正して、新しい設計としてアップロードしてください。 修正によって機能、価格、納期が変わる場合は、停止して、その人に確認してください。
4. クリーンなファイル： 注文に対するチェックを実行してください。

他の制限（銅箔がより厚い、別の板厚など）を伴うオプションを持つ見積もりまたはプレビューには、その選択に対するチェックが必要です。チェックが存在しない場合は開始され、プレビューには技術確認の理由 file_check_pending と、その reportId を持つ check が含まれます。価格はすぐに表示されますが、そのチェックが終わるまで見積もりは review のままです。上記のようにチェックを読み、その後プレビューを再リクエストしてください。

発生するエラー

他にも、DESIGN_REJECTED（アップロードが拒否されました。details.reason を参照してください）、トークンがないか間違っている場合の UNAUTHENTICATED（間違ったトークンは公開ルートでも拒否されます）、まだ公開されていないルートに対する FEATURE_DISABLED があります。

アカウントなしの1日の利用枠

ゲストセッションには、計算の1日の利用枠があります。アップロードと開始されたチェックは、通常の読み取りより多く消費します。1つのネットワークアドレスから多くのゲストセッションを開くこともカウントされます。新しい選択のためにサイトが自動で開始するチェックも、同じ利用枠に課金されます。使い切ると、リセット日付とともに ANONYMOUS_BUDGET_SPENT が返されます。ログインした呼び出し元はこのようにはカウントされません。

今日の API でできないこと：注文、支払い、API キー、エージェント向けログインは計画中であり、利用できません。計画中の MCP サーバーについては、MCP とは何か、エージェントはどのように注文するか で説明しています。