คู่มือเริ่มใช้ 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 ระบุ พร้อมส่วนหัวที่ 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 คืออะไรและตัวแทนสั่งซื้ออย่างไร ครับ