API hızlı başlangıç: yükleme, kontrol, teklif

Başlamadan önce

API, bir misafir oturumu aracılığıyla hesap olmadan çalışır. API, sitenin kendi adresinde /api altındadır. Bir kez ayarlayın:

API=https://dev.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. Her hatanın aynı şekli vardır:

{ "error": { "code": "VALIDATION_FAILED", "message": "…", "details": {}, "requestId": "…" } }

code üzerinde dallanın. message geliştiriciler içindir.

1. Misafir oturumu: belirteç bir kez gösterilir.
2. Yükleme: zip'i API'nin adlandırdığı adrese, adlandırdığı başlıklarla PUT yapın.
3. Tamamlayın, sonra analiz bitene kadar yoklayın.
4. Rapor: bulgular, hangi kontrollerin çalıştığı ve hangilerinin çalışmadığı.
5. 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. Henüz bir paket olarak yayımlanmamıştır; 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://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',
});

Diğer yöntemler createUpload, completeUpload, getDesign, setLayerMapping, validateDesign, getValidation, waitForValidation, createQuote, getQuote ve reviseQuote'tur. 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.

1. Zip'i yükleyin.
2. Raporu okuyun.
3. 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.
4. 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

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) ve henüz açık olmayan 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.

API'nin bugün yapamadığı şeyler: sipariş, ödeme, API anahtarları ve aracılar için oturum açma planlanmıştır ve mevcut değildir. Planlanan MCP sunucusu MCP nedir ve aracılar nasıl sipariş verir bölümünde anlatılır.