ההזמנה נפתחת בקרוב. עד אז, כתוב אל support@uliketechnology.com ומהנדס ישיב לך.

כל המדריכים

עוזרי AI

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

הקריאות שלוקחות קובץ לוח לדוח בדיקת קבצים, למחיר ולהזמנה, עם curl ולקוח JavaScript, ובנוסף השגיאות שתפגוש.

לעוזרי AIעודכן 2026-11-176 דקות קריאהMarkdown גולמי לעוזרי AI

ממשק ה-API ושרת ה-MCP המתוארים כאן ייפתחו יחד עם ההזמנה.

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

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

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

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

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

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

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

קוד סטטוס מה זה אומר מה לעשות
DESIGN_NOT_READY 422 התכנון עדיין נקרא (details.status אומר איזה מצב), או שאין לו דוח עדיין. קרא את התכנון עד שהסטטוס אינו analysing, אחר כך שאל שוב.
VALIDATION_FAILED 400 לבקשה אין את הצורה הצפויה, או שהיא קובעת אפשרות או ערך שאין בקטלוג. details מפרט את הבעיות או הנושאים. תקן את השדה הקבוע ב-details ושלח שוב. קח מזהי אפשרויות וערכים מ-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), UNAUTHENTICATED לאסימון חסר או שגוי (אסימון שגוי נדחה גם בנתיבים ציבוריים), FORBIDDEN למפתח או לאסימון אורח שאינו יכול לקרוא לנתיב, ו-FEATURE_DISABLED לנתיב שמכובה.

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

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

מהצעת מחיר להזמנה

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

  • מפתח API. האדם יוצר אותו בחשבונו תחת מפתחות API ובוחר מה הוא יכול לעשות. שלח אותו כ-Authorization: Bearer ulk_…. הצעת מחיר שנוצרת עם המפתח שייכת לחשבון. מפתח בדיקה (ulk_test_…) עובד על נתוני דוגמה בלבד.
  • כניסה לתוכניות. עוזר רושם את עצמו, האדם רואה מה הוא מבקש לעשות בדף של האתר ולוחץ על אפשר, והעוזר מקבל אסימון שמוגבל להרשאות אלה.

קרא את הכתובות השמורות עם 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 אומר אם המשלוח מחזיק סוללות או סחורות מסוכנות אחרות.

שום דבר אינו מבוצע בקריאה זו. התשובה היא APPROVAL_REQUIRED (422) עם details.approvalUrl, למפתח API ולאסימון של עוזר שנכנס באותה מידה. תן קישור זה לאדם. הוא פותח אותו, נכנס, רואה את ההזמנה ואת הסך הכול, ומאשר או דוחה. הקישור עובד פעם אחת, פג לאחר 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 וכיצד סוכנים מזמינים.