התחלה מהירה ל-API: העלאה, בדיקה, הצעת מחיר

לפני שמתחילים

ממשק ה-API עובד ללא חשבון דרך הפעלת אורח. ממשק ה-API נמצא בכתובת האתר עצמו תחת /api. הגדר אותו פעם אחת:

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

board.zip הוא zip שטוח של קובצי ה-Gerber והקידוח שלך. למה שנכנס לתוכו, ראה קבצים לייצור ולהרכבה. הדוגמאות דורשות curl ו-jq.

כל בקשה לממשק ה-API לאחר הפעלת האורח לוקחת Authorization: Bearer <token>. לכל שגיאה יש אותה צורה:

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

הסתעף על code. ה-message היא למפתחים.

1. הפעלת אורח: האסימון מוצג פעם אחת.
2. העלאה: PUT את ה-zip לכתובת שממשק ה-API קובע, עם הכותרות שהוא קובע.
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 לוקח את אותו גוף.

אותה זרימה עם לקוח 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 ו-check עם ה-reportId שלו. המחיר מוצג מיד, אך הצעת המחיר נשארת ב-review עד שבדיקה זו מסתיימת. קרא את הבדיקה כנ"ל, אחר כך בקש את התצוגה שוב.

שגיאות שתפגוש

אפשריים גם DESIGN_REJECTED (ההעלאה נדחתה; ראה details.reason), UNAUTHENTICATED לאסימון חסר או שגוי (אסימון שגוי נדחה גם בנתיבים ציבוריים), ו-FEATURE_DISABLED לנתיב שעדיין לא פתוח.

הקצבה היומית ללא חשבון

להפעלת אורח יש קצבת מחשוב יומית. העלאות ובדיקות שהתחילו עולות יותר מקריאה פשוטה, ופתיחת הפעלות אורח רבות מכתובת רשת אחת נספרת גם. בדיקה שהאתר מתחיל בעצמו לבחירה חדשה מחויבת לאותה קצבה. כאשר היא נוצלה, אתה מקבל ANONYMOUS_BUDGET_SPENT עם התאריך שהיא מתאפסת. מתקשרים מחוברים אינם נספרים כך.

מה ממשק ה-API אינו יכול לעשות היום: הזמנה, תשלום, מפתחות API וכניסה לסוכנים מתוכננים ולא זמינים. שרת ה-MCP המתוכנן מתואר במהו MCP וכיצד סוכנים מזמינים.