Başlamadan önce
Yükleme, dosya kontrolü ve teklif, bir misafir oturumu aracılığıyla hesap olmadan çalışır. Bir sipariş bir hesap gerektirir: aşağıda "Bir tekliften siparişe" bölümüne bakın. API, sitenin kendi adresinde /api altındadır. Bir kez ayarlayın:
API=https://uliketechnology.com/api
F=board.zip
board.zip, Gerber ve delik dosyalarınızın düz bir zip'idir. İçine neyin girdiğine dair Üretim ve montaj için dosyalar bölümüne bakın. Örneklerin curl ve jq'ya ihtiyacı vardır.
Misafir oturumundan sonra API'ye yapılan her istek Authorization: Bearer <token> alır. Bir API anahtarı, misafir belirteci yerine aynı başlıkta gider. Her hatanın aynı şekli vardır:
{ "error": { "code": "VALIDATION_FAILED", "message": "…", "details": {}, "requestId": "…" } }
code üzerinde dallanın. message geliştiriciler içindir.
- Misafir oturumu: belirteç bir kez gösterilir.
- Yükleme: zip'i API'nin adlandırdığı adrese, adlandırdığı başlıklarla
PUTyapın. - Tamamlayın, sonra analiz bitene kadar yoklayın.
- Rapor: bulgular, hangi kontrollerin çalıştığı ve hangilerinin çalışmadığı.
- Teklif önizlemesi.
Curl ile akış
Neyin sipariş edilebileceğini okuyun. Bunun için belirteç gerekmez:
curl -s $API/v1/capabilities | jq '.options[].id'
Bir misafir oturumu açın. Belirteç bir kez gösterilir ve 30 gün sürer:
T=$(curl -s -X POST $API/v1/guest-sessions | jq -r .token)
Dosyayı duyurun. Yanıt uploadId, designId, uploadUrl ve requiredHeaders içerir:
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\"}")
Dosyayı, requiredHeaders içindeki her başlıkla (içerik türü, uzunluk ve sağlama toplamı; bunlar olmadan yükleme 403 ile reddedilir) yanıtın adlandırdığı adrese gönderin. Sonra yüklemeyi tamamlayın:
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
Durum ilk başta analysing'dir. Değişene kadar tasarımı okuyun. ready olduğunda, rapor yanıttadır:
D=$(echo $J | jq -r .designId)
curl -s $API/v1/designs/$D -H "authorization: Bearer $T" | jq '.design.status, .report.headline, .report.counts'
Başlık no_problems_in_checks_run, problems_found veya could_not_check'tir. checksRun ve checksNotRun'ı da okuyun: çalışmayan bir kontrol bir geçme değildir. Diğer durumlar needs_mapping (katmanları PUT /v1/designs/{designId}/layer-mapping ile ayarlayın), needs_engineer ve rejected'tir.
Bir fiyat önizlemesi isteyin. selection ve destinationCountry gereklidir; boş bir selection varsayılanları alır:
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 (fiyat gösterildiği gibi geçerlidir) veya review'dur (bir mühendis onaylar); reviewReasons nedenini söyler. totalMinor, yanıtın currency'sinin küçük birimlerindedir ve bir mühendisin işi fiyatlandırması gerektiğinde yoktur. Bir teklifi saklamak için POST /v1/quotes aynı gövdeyi alır.
JavaScript istemcisiyle aynı akış
@ulike/sdk istemcisi bu yolları sarar. Kendi sitemizin istemcisidir ve genel bir paket değildir; bu onun şeklidir, böylece aynı çağrıları fetch ile yazabilirsiniz. Yöntem adları:
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',
});
Diğer yöntemler arasında createUpload, completeUpload, getDesign, setLayerMapping, validateDesign, getValidation, waitForValidation, createQuote, getQuote, reviseQuote, listAddresses, placeOrder, getOrder, listOrders ve cancelOrder vardır. Hatalar, status ve code ile ApiClientError olarak atılır.
Sipariş kontrolü
Yüklemeden sonra aldığınız rapor yalnızca dosyalar üzerinde yapılır. Dosyaları bir siparişe karşı kontrol etmek için, quantities ve selection tutan order ile POST /v1/designs/{designId}/validations (validateDesign) çağrısı yapın. Yanıt bir durumdur: running, failed veya done. running iken, done olana kadar her bir veya iki saniyede bir GET /v1/validations/{reportId} (getValidation) okuyun.
- Zip'i yükleyin.
- Raporu okuyun.
- Düzeltin ve yeni bir tasarım olarak yükleyin. Bir düzeltme işlevi, fiyatı veya teslim süresini değiştirdiğinde durun ve kişiye sorun.
- Temiz dosyalar: sipariş kontrolünü çalıştırın.
Başka sınırlar getiren seçeneklere (daha kalın bakır, başka bir kalınlık) sahip bir teklif veya önizleme, bu seçim için bir kontrole ihtiyaç duyar. Hiçbiri yoksa biri başlatılır ve önizleme, file_check_pending inceleme nedenini ve reportId'siyle bir check taşır. Fiyat hemen gösterilir, ancak teklif bu kontrol bitene kadar review'da kalır. Yukarıdaki gibi kontrolü okuyun, sonra önizlemeyi tekrar isteyin.
Karşılaşacağınız hatalar
| Kod | Durum | Ne anlama gelir | Ne yapmalı |
|---|---|---|---|
DESIGN_NOT_READY |
422 | Tasarım hâlâ okunuyor (details.status hangi durumda olduğunu söyler) veya henüz bir raporu yok. |
Durum analysing olmayana kadar tasarımı okuyun, sonra tekrar isteyin. |
VALIDATION_FAILED |
400 | İsteğin beklenen şekli yok veya katalogda olmayan bir seçenek veya değer adlandırıyor. details sorunları veya konuları listeler. |
details içinde adlandırılan alanı düzeltin ve tekrar gönderin. Seçenek kimliklerini ve değerlerini GET /v1/capabilities adresinden alın. |
NOT_MANUFACTURABLE |
422 | Seçim üretmediğimiz bir şey. details.because nedenleri taşır. |
Seçimi değiştirin; aynısını tekrar denemeyin. Değişikliğin kartı değiştirip değiştirmeyeceğini kişiye sorun. |
ANONYMOUS_BUDGET_SPENT |
429 | Hesapsız günlük ödenek kullanıldı. details.resetsOn tarihtir. |
Durun. Kişiye söyleyin; oturum açabilir veya bu tarihe kadar bekleyebilir. |
REVISION_CONFLICT |
409 | Bir revizyon, artık teklifin başı olmayan bir taban adlandırdı. details her iki başı da taşır. |
Başı GET /v1/quotes/{quoteId} ile okuyun, değişikliğinizi onun üzerinde tekrar uygulayın ve tekrar gönderin. |
Ayrıca DESIGN_REJECTED (yükleme reddedildi; bkz. details.reason), eksik veya yanlış bir belirteç için UNAUTHENTICATED (yanlış bir belirteç herkese açık yollarda bile reddedilir), yolu çağıramayan bir anahtar veya misafir belirteci için FORBIDDEN ve kapatılmış bir yol için FEATURE_DISABLED mümkündür.
Hesapsız günlük ödenek
Bir misafir oturumunun günlük bir bilgi işlem ödeneği vardır. Yüklemeler ve başlatılan kontroller, sade bir okumadan daha pahalıdır ve tek bir ağ adresinden birçok misafir oturumu açmak da sayılır. Sitenin yeni bir seçim için kendi başına başlattığı bir kontrol, aynı ödeneğe ücretlendirilir. Tükendiğinde, sıfırlandığı tarihle ANONYMOUS_BUDGET_SPENT alırsınız. Oturum açmış arayanlar bu şekilde sayılmaz.
Bir tekliften siparişe
Bir sipariş, bir hesaba ait saklanan bir tekliften verilir. Bir misafir belirteci sipariş yollarında reddedilir. Bir program, ikisi de Geliştiriciler ve asistanlar için bölümünde anlatılan iki yoldan biriyle bir hesap için çalışır:
- Bir API anahtarı. Kişi onu hesabında API anahtarları altında oluşturur ve ne yapabileceğini seçer. Onu
Authorization: Bearer ulk_…olarak gönderin. Anahtarla oluşturulan bir teklif hesaba aittir. Bir test anahtarı (ulk_test_…) yalnızca örnek veriler üzerinde çalışır. - Programlar için oturum açma. Bir asistan kendini kaydeder, kişi sitenin bir sayfasında ne yapmayı istediğini görür ve İzin verin düğmesine basar ve asistan bu izinlerle sınırlı bir belirteç alır.
Kayıtlı adresleri GET /v1/addresses ile okuyun. Bir adres, kişi tarafından tarayıcıda eklenir veya değiştirilir. Gönderim adresi, teklifin destinationCountry değerinde olmalıdır.
Siparişi POST /v1/orders ile verin. Yol bir Idempotency-Key başlığı gerektirir: amaçlanan sipariş başına 8 ila 80 görünür karakterlik yeni bir anahtar ve tekrar denediğinizde yine aynı anahtar:
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, kişinin kabul ettiği teklifin totalMinor değeridir. termsVersion, kişinin kabul ettiği satış koşullarının sürümünü adlandırır. dangerousGoods, gönderimin pil veya diğer tehlikeli mallar içerip içermediğini söyler.
Bu çağrıyla hiçbir şey verilmez. Yanıt, bir API anahtarı ve oturum açmış bir asistanın belirteci için aynı şekilde APPROVAL_REQUIRED (422) ve details.approvalUrl değeridir. Bu bağlantıyı kişiye verin. Onu açar, oturum açar, siparişi ve toplamı görür ve onaylar veya reddeder. Bağlantı bir kez çalışır, 24 saat sonra süresi dolar ve teklif veya toplam değişirse çalışmayı durdurur.
Onaydan sonra sipariş mevcuttur: hesabın siparişlerini GET /v1/orders ile listeleyin ve birini GET /v1/orders/{orderId} ile okuyun. order.number değerini, proFormaNumber içindeki proforma fatura numarasını, sellerBank içinde ödenecek hesabı ve payments altında havaleye yazılacak bankReference değerini taşır.
Ödeme, kişi tarafından yapılan banka havalesiyladır. Hiçbir anahtar ve hiçbir asistan ödeme yapamaz. Siparişi GET /v1/orders/{orderId} ile izleyin. Bir mühendis üretimden önce her siparişi onaylar.
| Kod | Durum | Ne anlama gelir | Ne yapmalı |
|---|---|---|---|
APPROVAL_REQUIRED |
422 | Önce oturum açmış bir kişinin onaylaması gerekir. details.approvalUrl sayfadır. |
Bağlantıyı kişiye verin. Bunun etrafından bir yol aramayın. |
TOTAL_MISMATCH |
422 | expectedTotalMinor, teklifin toplamı değildir. details.totalMinor toplamdır. |
Teklifi tekrar okuyun ve tekrar istemeden önce kişiye fiyatı gösterin. |
QUOTE_EXPIRED |
410 | Teklif geçerliliğini geçmiştir. | Teklifi yeni bir fiyat için gözden geçirin ve kişiye gösterin. |
CONFLICT |
409 | details.reason, quote_ordered veya quote_not_priced değeridir (önce bir mühendisin fiyat vermesi gerekir). |
Tekrar denemeyin. Kişiye söyleyin. |
INTAKE_CLOSED |
503 | Şu anda sipariş alınmıyor. details.reopensOn, olduğunda tarihtir. |
Durun. Kişiye söyleyin. |
Aynı hizmet, asistanlara bir MCP sunucusu aracılığıyla adlandırılmış araçlar olarak sunulur: bkz. MCP nedir ve aracılar nasıl sipariş verir.