לפני שמתחילים
העלאה, בדיקת קבצים והצעת מחיר עובדים ללא חשבון, דרך הפעלת אורח. הזמנה דורשת חשבון: ראה "מהצעת מחיר להזמנה" למטה. ממשק ה-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 היא למפתחים.
- הפעלת אורח: האסימון מוצג פעם אחת.
- העלאה:
PUTאת ה-zip לכתובת שממשק ה-API קובע, עם הכותרות שהוא קובע. - השלם, אחר כך סקור עד שהניתוח מסתיים.
- הדוח: ממצאים, אילו בדיקות רצו ואילו לא.
- תצוגת הצעת המחיר.
הזרימה עם 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.
- העלה את ה-zip.
- קרא את הדוח.
- תקן והעלה כתכנון חדש. עצור ושאל את האדם כאשר תיקון משנה את התפקוד, המחיר או זמן המסירה.
- קבצים נקיים: הרץ את בדיקת ההזמנה.
הצעת מחיר או תצוגה עם אפשרויות שמביאות מגבלות אחרות (נחושת עבה יותר, עובי אחר) דורשת בדיקה לבחירה זו. אם אין אחת, אחת מתחילה, והתצוגה נושאת את סיבת הסקירה 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 וכיצד סוכנים מזמינים.