ก่อนเริ่มใช้งาน
การอัปโหลด การตรวจสอบไฟล์ และใบเสนอราคาใช้งานได้โดยไม่ต้องมีบัญชี ผ่านเซสชันผู้เยี่ยมชมครับ คำสั่งซื้อต้องใช้บัญชี โปรดดู "จากใบเสนอราคาไปสู่คำสั่งซื้อ" ด้านล่างครับ 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 ระบุ พร้อมส่วนหัวที่ 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 คืออะไรและเอเจนต์สั่งซื้ออย่างไร ครับ