शुरू करने से पहले
अपलोड, फ़ाइल जांच और कोटेशन अतिथि सत्र द्वारा बिना खाते काम करते हैं। ऑर्डर को खाता चाहिए: नीचे "कोटेशन से ऑर्डर तक" देखें। API साइट के अपने पते पर /api के अधीन है। उसे एक बार सेट करें:
API=https://uliketechnology.com/api
F=board.zip
board.zip आपकी Gerber और ड्रिल फ़ाइलों का सपाट zip है। उसमें क्या जाता है, इसके लिए निर्माण और असेंबली के लिए फ़ाइलें देखें। उदाहरणों को curl और jq चाहिए।
अतिथि सत्र के बाद API के प्रत्येक अनुरोध में Authorization: Bearer <token> लगता है। API कुंजी अतिथि टोकन के स्थान पर समान हेडर में जाती है। प्रत्येक त्रुटि का समान आकार है:
{ "error": { "code": "VALIDATION_FAILED", "message": "…", "details": {}, "requestId": "…" } }
code पर शाखा करें। message डेवलपर के लिए है।
- अतिथि सत्र: टोकन एक बार दिखाया जाता है।
- अपलोड: zip को API द्वारा नामित पते पर, उसके द्वारा नामित हेडर के साथ
PUTकरें। - पूर्ण करें, फिर विश्लेषण होने तक पोल करें।
- रिपोर्ट: अवलोकन, कौन सी जांचें चलीं और कौन सी नहीं।
- कोटेशन पूर्वावलोकन।
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 हैं। त्रुटियां status और code के साथ ApiClientError के रूप में फेंकी जाती हैं।
ऑर्डर की जांच
अपलोड के बाद आपको मिलने वाली रिपोर्ट केवल फ़ाइलों पर बनी है। फ़ाइलों को ऑर्डर के विरुद्ध जांचने के लिए, quantities और selection रखने वाले order के साथ POST /v1/designs/{designId}/validations (validateDesign) कॉल करें। उत्तर स्थिति है: running, failed या done। running के दौरान, done होने तक प्रत्येक सेकंड या दो में GET /v1/validations/{reportId} (getValidation) पढ़ें।
- zip अपलोड करें।
- रिपोर्ट पढ़ें।
- ठीक करें और नए डिज़ाइन के रूप में अपलोड करें। जब सुधार कार्य, कीमत या वितरण समय बदले तो रुकें और व्यक्ति से पूछें।
- साफ़ फ़ाइलें: ऑर्डर की जांच चलाएं।
ऐसे विकल्पों वाला कोटेशन या पूर्वावलोकन जो अन्य सीमाएं लाते हैं (मोटा कॉपर, अन्य मोटाई) उसे उस चयन के लिए जांच चाहिए। यदि कोई नहीं है, एक शुरू होता है, और पूर्वावलोकन समीक्षा कारण file_check_pending और उसके reportId के साथ check रखता है। कीमत तुरंत दिखाई जाती है, पर कोटेशन जांच होने तक 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 क्या है और एजेंट कैसे ऑर्डर करते हैं देखें।