Pemesanan segera dibuka. Sampai saat itu, tulis ke support@uliketechnology.com dan insinyur akan menjawab.

Semua panduan

Asisten AI

Panduan cepat API: unggah, periksa, penawaran

Panggilan yang membawa file papan ke laporan pemeriksaan file, harga dan pesanan, dengan curl dan klien JavaScript, serta kesalahan yang akan ditemui.

Untuk asisten AIDiperbarui 2026-11-17Baca 7 menitMarkdown mentah untuk asisten AI

API dan server MCP yang dijelaskan di sini dibuka bersamaan dengan pemesanan.

Sebelum Anda mulai

Unggah, pemeriksaan file, dan penawaran bekerja tanpa akun, melalui sesi tamu. Pesanan memerlukan akun: lihat "Dari penawaran ke pesanan" di bawah. API berada di alamat situs itu sendiri di bawah /api. Atur satu kali:

API=https://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>. Kunci API dimasukkan dalam header yang sama sebagai pengganti token tamu. Setiap kesalahan memiliki bentuk yang sama:

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

Ambil cabang berdasarkan code. message diperuntukkan bagi pengembang.

Lima gambar kecil berurutan: kunci, file yang menuju alamat unggah, jam pasir, halaman laporan berisi temuan, dan label harga
  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 adalah klien situs kami sendiri dan bukan paket publik; 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://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, reviseQuote, listAddresses, placeOrder, getOrder, listOrders dan cancelOrder. 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.

Lingkaran tiga langkah: unggah file, baca laporan, perbaiki dan unggah lagi; sebuah panah keluar dari lingkaran menuju tanda centang ketika file bersih
  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

Kode Status Artinya Yang harus dilakukan
DESIGN_NOT_READY 422 Desain masih dibaca (details.status menyebutkan keadaannya), atau belum memiliki laporan. Baca desain hingga statusnya bukan analysing, lalu minta lagi.
VALIDATION_FAILED 400 Permintaan tidak memiliki bentuk yang diharapkan, atau menyebutkan opsi atau nilai yang tidak ada dalam katalog. details mencantumkan masalahnya. Perbaiki bidang yang disebutkan dalam details dan kirim lagi. Ambil id dan nilai opsi dari GET /v1/capabilities.
NOT_MANUFACTURABLE 422 Pilihan tersebut adalah sesuatu yang tidak kami buat. details.because membawa alasannya. Ubah pilihan; jangan coba lagi pilihan yang sama. Tanyakan kepada orang tersebut jika perubahan itu akan mengubah papan.
ANONYMOUS_BUDGET_SPENT 429 Kuota harian tanpa akun sudah habis. details.resetsOn adalah tanggalnya. Berhenti. Beri tahu orang tersebut; mereka dapat masuk atau menunggu hingga tanggal tersebut.
REVISION_CONFLICT 409 Sebuah revisi menyebutkan basis yang tidak lagi menjadi kepala penawaran. details membawa kedua kepala. Baca kepala dengan GET /v1/quotes/{quoteId}, terapkan kembali perubahan Anda padanya, dan kirim lagi.

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), FORBIDDEN untuk kunci atau token tamu yang tidak boleh memanggil rute, dan FEATURE_DISABLED untuk rute yang dimatikan.

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.

Dari penawaran ke pesanan

Pesanan ditempatkan dari penawaran yang disimpan yang dimiliki akun. Token tamu ditolak pada rute pesanan. Program bekerja untuk akun dengan salah satu dari dua cara, keduanya dijelaskan di Untuk pengembang dan asisten:

  • Kunci API. Orang tersebut membuatnya di akunnya di bagian Kunci API dan memilih apa yang boleh dilakukan kunci. Kirim kunci sebagai Authorization: Bearer ulk_…. Penawaran yang dibuat dengan kunci dimiliki akun. Kunci uji (ulk_test_…) hanya bekerja pada data contoh.
  • Masuk untuk program. Asisten mendaftarkan dirinya, orang tersebut melihat apa yang diminta untuk dilakukan pada halaman situs dan menekan Izinkan, dan asisten mendapatkan token yang terbatas pada izin tersebut.

Baca alamat yang disimpan dengan GET /v1/addresses. Alamat ditambah atau diubah oleh orang tersebut di peramban. Alamat pengiriman harus berada di destinationCountry penawaran.

Tempatkan pesanan dengan POST /v1/orders. Rute memerlukan header Idempotency-Key: satu kunci baru berisi 8 sampai 80 karakter yang terlihat per pesanan yang dimaksud, dan kunci yang sama lagi ketika Anda mencoba lagi:

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 adalah totalMinor penawaran yang disetujui orang tersebut. termsVersion menyebutkan versi syarat penjualan yang diterima orang tersebut. dangerousGoods menyatakan apakah kiriman berisi baterai atau barang berbahaya lainnya.

Tidak ada yang ditempatkan oleh panggilan ini. Jawabannya adalah APPROVAL_REQUIRED (422) dengan details.approvalUrl, baik untuk kunci API maupun untuk token asisten yang Masuk. Berikan tautan tersebut kepada orang tersebut. Orang tersebut membuka tautan, Masuk, melihat pesanan dan total, lalu menyetujui atau menolak. Tautan berfungsi satu kali, kedaluwarsa setelah 24 jam, dan berhenti berfungsi jika penawaran atau total berubah.

Setelah persetujuan, pesanan ada: ambil daftar pesanan akun dengan GET /v1/orders dan baca satu pesanan dengan GET /v1/orders/{orderId}. Pesanan membawa order.number, nomor faktur pro-forma dalam proFormaNumber, rekening tujuan pembayaran dalam sellerBank dan, di bawah payments, bankReference yang ditulis pada transfer.

Pembayaran melalui transfer bank, yang dilakukan oleh orang tersebut. Tidak ada kunci dan tidak ada asisten yang dapat membayar. Ikuti pesanan dengan GET /v1/orders/{orderId}. Seorang insinyur mengonfirmasi setiap pesanan sebelum produksi.

Kode Status Artinya Yang harus dilakukan
APPROVAL_REQUIRED 422 Seseorang yang Masuk harus menyetujui terlebih dahulu. details.approvalUrl adalah halamannya. Berikan tautan kepada orang tersebut. Jangan mencari jalan untuk menghindarinya.
TOTAL_MISMATCH 422 expectedTotalMinor bukan total penawaran. details.totalMinor adalah totalnya. Baca penawaran lagi dan tunjukkan harga kepada orang tersebut sebelum Anda meminta lagi.
QUOTE_EXPIRED 410 Penawaran sudah melewati masa berlakunya. Revisi penawaran untuk harga baru, dan tunjukkan kepada orang tersebut.
CONFLICT 409 details.reason adalah quote_ordered atau quote_not_priced (seorang insinyur harus memberikan harga terlebih dahulu). Jangan coba lagi. Beri tahu orang tersebut.
INTAKE_CLOSED 503 Saat ini tidak ada pesanan yang diterima. details.reopensOn adalah tanggalnya, jika ada. Berhenti. Beri tahu orang tersebut.

Layanan yang sama ditawarkan kepada asisten sebagai alat bernama melalui server MCP: lihat Apa itu MCP dan bagaimana agen melakukan pemesanan.