Panduan cepat API: unggah, periksa, penawaran

Sebelum Anda mulai

API bekerja tanpa akun melalui sesi tamu. API berada di alamat situs itu sendiri di bawah /api. Atur satu kali:

API=https://dev.uliketechnology.com/api
F=board.zip

board.zip adalah zip datar berisi file Gerber dan file bor Anda. Untuk isi yang perlu ada di dalamnya, lihat File untuk fabrikasi dan perakitan. Contoh ini memerlukan curl dan jq.

Setiap permintaan ke API setelah sesi tamu menggunakan Authorization: Bearer <token>. Setiap kesalahan memiliki bentuk yang sama:

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

Ambil cabang berdasarkan code. message diperuntukkan bagi pengembang.

1. Sesi tamu: token hanya ditampilkan satu kali.
2. Unggah: lakukan PUT zip ke alamat yang disebutkan API, dengan header yang disebutkan API.
3. Selesaikan, lalu lakukan polling hingga analisis selesai.
4. Laporan: temuan, pemeriksaan mana yang dijalankan dan mana yang tidak.
5. Pratinjau penawaran.

Alur dengan curl

Baca apa yang dapat dipesan. Langkah ini tidak memerlukan token:

curl -s $API/v1/capabilities | jq '.options[].id'

Buka sesi tamu. Token hanya ditampilkan satu kali dan berlaku 30 hari:

T=$(curl -s -X POST $API/v1/guest-sessions | jq -r .token)

Umumkan file. Jawabannya berisi uploadId, designId, uploadUrl dan 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\"}")

Kirim file ke alamat yang disebutkan dalam jawaban, dengan setiap header dalam requiredHeaders (jenis konten, panjang dan checksum; tanpa ketiganya unggahan ditolak dengan 403). Lalu selesaikan unggahan:

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

Status pada awalnya adalah analysing. Baca desain hingga statusnya berubah. Ketika statusnya ready, laporan ada dalam jawaban:

D=$(echo $J | jq -r .designId)
curl -s $API/v1/designs/$D -H "authorization: Bearer $T" | jq '.design.status, .report.headline, .report.counts'

Judul utama adalah no_problems_in_checks_run, problems_found atau could_not_check. Baca juga checksRun dan checksNotRun: pemeriksaan yang tidak dijalankan bukanlah lulus. Status lainnya adalah needs_mapping (atur lapisan dengan PUT /v1/designs/{designId}/layer-mapping), needs_engineer dan rejected.

Minta pratinjau harga. selection dan destinationCountry wajib diisi; selection yang kosong menggunakan nilai bawaan:

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 adalah instant (harga berlaku sebagaimana ditampilkan) atau review (seorang insinyur mengonfirmasinya); reviewReasons menjelaskan alasannya. totalMinor dalam satuan minor dari currency pada jawaban, dan tidak ada ketika seorang insinyur harus menentukan harga pekerjaan. Untuk menyimpan penawaran, POST /v1/quotes menggunakan isi yang sama.

Alur yang sama dengan klien JavaScript

Klien @ulike/sdk membungkus rute ini. Klien ini belum diterbitkan sebagai paket; ini adalah bentuknya, sehingga Anda dapat menulis panggilan yang sama dengan fetch. Nama metode:

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',
});

Metode lainnya adalah createUpload, completeUpload, getDesign, setLayerMapping, validateDesign, getValidation, waitForValidation, createQuote, getQuote dan reviseQuote. Kesalahan dilempar sebagai ApiClientError dengan status dan code.

Pemeriksaan untuk sebuah pesanan

Laporan yang Anda terima setelah unggah dibuat dari file saja. Untuk memeriksa file terhadap sebuah pesanan, panggil POST /v1/designs/{designId}/validations (validateDesign) dengan order yang berisi quantities dan selection. Jawabannya berupa keadaan: running, failed atau done. Selama running, baca GET /v1/validations/{reportId} (getValidation) setiap satu atau dua detik hingga keadaannya done.

1. Unggah zip.
2. Baca laporan.
3. Perbaiki dan unggah sebagai desain baru. Berhenti dan tanyakan kepada orang tersebut ketika perbaikan mengubah fungsi, harga atau waktu pengiriman.
4. File bersih: jalankan pemeriksaan untuk pesanan.

Penawaran atau pratinjau dengan opsi yang membawa batasan lain (tembaga lebih tebal, ketebalan lain) memerlukan pemeriksaan untuk pilihan tersebut. Jika belum ada, satu pemeriksaan dimulai, dan pratinjau membawa alasan pemeriksaan file_check_pending dan sebuah check dengan reportId-nya. Harga ditampilkan sekaligus, tetapi penawaran tetap dalam review hingga pemeriksaan tersebut selesai. Baca pemeriksaan seperti di atas, lalu minta pratinjau lagi.

Kesalahan yang akan Anda temui

Kemungkinan lain adalah DESIGN_REJECTED (unggahan ditolak; lihat details.reason), UNAUTHENTICATED untuk token yang hilang atau salah (token yang salah ditolak bahkan pada rute publik), dan FEATURE_DISABLED untuk rute yang belum dibuka.

Kuota harian tanpa akun

Sesi tamu memiliki kuota komputasi harian. Unggahan dan pemeriksaan yang dimulai memerlukan biaya lebih daripada pembacaan biasa, dan membuka banyak sesi tamu dari satu alamat jaringan juga dihitung. Pemeriksaan yang dimulai situs sendiri untuk pilihan baru dibebankan ke kuota yang sama. Ketika kuota habis, Anda menerima ANONYMOUS_BUDGET_SPENT dengan tanggal kuota direset. Pemanggil yang masuk tidak dihitung dengan cara ini.

Yang belum dapat dilakukan API saat ini: pemesanan, pembayaran, kunci API dan masuk untuk agen direncanakan dan belum tersedia. Server MCP yang direncanakan dijelaskan dalam Apa itu MCP dan cara agen memesan.