Gli ordini apriranno a breve. Fino ad allora scriva a support@uliketechnology.com: un ingegnere risponde.

Tutte le guide

Assistenti AI

Guida rapida API: caricamento, controllo, preventivo

Le chiamate che portano un file di scheda al rapporto di controllo, a un prezzo e a un ordine, con curl e il client JavaScript, e gli errori che incontrerà.

Per gli assistenti AIAggiornato il 2026-11-178 min di letturaMarkdown grezzo per assistenti AI

L'API e il server MCP qui descritti apriranno insieme agli ordini.

Prima di iniziare

Il caricamento, il controllo dei file e il preventivo funzionano senza un account tramite una sessione ospite. Un ordine richiede un account: veda «Da un preventivo a un ordine» sotto. L'API si trova all'indirizzo del sito sotto /api. Lo imposti una volta:

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

board.zip è uno zip piatto dei Suoi file Gerber e di foratura. Per cosa contiene, veda File per fabbricazione e montaggio. Gli esempi richiedono curl e jq.

Ogni richiesta all'API dopo la sessione ospite richiede Authorization: Bearer <token>. Una chiave API va nello stesso header al posto del token ospite. Ogni errore ha la stessa forma:

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

Scelga in base a code. Il message è per gli sviluppatori.

Cinque piccole immagini in ordine: una chiave, un file che va a un indirizzo di caricamento, una clessidra, una pagina di rapporto con segnalazioni e un'etichetta del prezzo
  1. Sessione ospite: il token è mostrato una volta.
  2. Caricamento: invii con PUT lo zip all'indirizzo che l'API indica, con gli header che essa indica.
  3. Completamento, poi interroghi fino a quando l'analisi è terminata.
  4. Il rapporto: segnalazioni, quali controlli sono stati eseguiti e quali no.
  5. L'anteprima del preventivo.

Il flusso con curl

Legga cosa può essere ordinato. Questo non richiede token:

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

Apra una sessione ospite. Il token è mostrato una volta e dura 30 giorni:

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

Annunci il file. La risposta contiene uploadId, designId, uploadUrl e 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\"}")

Invii il file all'indirizzo che la risposta indica, con ogni header in requiredHeaders (tipo di contenuto, lunghezza e checksum; senza di essi il caricamento è rifiutato con 403). Poi completi il caricamento:

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

All'inizio lo stato è analysing. Legga il progetto fino a quando cambia. Quando è ready, il rapporto è nella risposta:

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

Il titolo è no_problems_in_checks_run, problems_found o could_not_check. Legga anche checksRun e checksNotRun: un controllo che non è stato eseguito non è un superamento. Gli altri stati sono needs_mapping (imposti gli strati con PUT /v1/designs/{designId}/layer-mapping), needs_engineer e rejected.

Richieda un'anteprima del prezzo. selection e destinationCountry sono obbligatori; un selection vuoto prende i valori predefiniti:

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 (il prezzo resta come mostrato) o review (un ingegnere lo conferma); reviewReasons indica perché. totalMinor è in unità minori della currency della risposta ed è assente quando un ingegnere deve prezzare il lavoro. Per salvare un preventivo, POST /v1/quotes accetta lo stesso body.

Lo stesso flusso con il client JavaScript

Il client @ulike/sdk incapsula queste route. È il client del nostro sito e non è un pacchetto pubblico; questa è la sua forma, in modo che Lei possa scrivere le stesse chiamate con fetch. Nomi dei metodi:

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

Tra gli altri metodi vi sono createUpload, completeUpload, getDesign, setLayerMapping, validateDesign, getValidation, waitForValidation, createQuote, getQuote, reviseQuote, listAddresses, placeOrder, getOrder, listOrders e cancelOrder. Gli errori sono lanciati come ApiClientError con uno status e un code.

Il controllo per un ordine

Il rapporto che Lei ottiene dopo il caricamento è realizzato sui soli file. Per controllare i file rispetto a un ordine, chiami POST /v1/designs/{designId}/validations (validateDesign) con order che contiene quantities e selection. La risposta è uno stato: running, failed o done. Mentre è running, legga GET /v1/validations/{reportId} (getValidation) ogni secondo o due fino a quando è done.

Un ciclo di tre fasi: caricare i file, leggere il rapporto, correggere e caricare di nuovo; una freccia lascia il ciclo verso un segno di spunta quando i file sono puliti
  1. Carichi lo zip.
  2. Legga il rapporto.
  3. Corregga e carichi come nuovo progetto. Si fermi e chieda alla persona quando una correzione cambia la funzione, il prezzo o il tempo di consegna.
  4. File puliti: esegua il controllo per l'ordine.

Un preventivo o un'anteprima con opzioni che comportano altri limiti (rame più spesso, un altro spessore) necessita di un controllo per quella selezione. Se non ne esiste uno, ne viene avviato uno e l'anteprima riporta il motivo di verifica file_check_pending e un check con il suo reportId. Il prezzo è mostrato subito, ma il preventivo resta in review fino a quando quel controllo è terminato. Legga il controllo come sopra, poi richieda di nuovo l'anteprima.

Errori che Lei incontrerà

Codice Stato Cosa significa Cosa fare
DESIGN_NOT_READY 422 Il progetto è ancora in lettura (details.status indica quale stato), o non ha ancora un rapporto. Legga il progetto fino a quando lo stato non è analysing, poi chieda di nuovo.
VALIDATION_FAILED 400 La richiesta non ha la forma attesa, o indica un'opzione o un valore che il catalogo non ha. details elenca le questioni o i problemi. Corregga il campo indicato in details e invii di nuovo. Prenda id e valori delle opzioni da GET /v1/capabilities.
NOT_MANUFACTURABLE 422 La selezione è qualcosa che non produciamo. details.because riporta i motivi. Cambi la selezione; non riprovi la stessa. Chieda alla persona se la modifica altererebbe la scheda.
ANONYMOUS_BUDGET_SPENT 429 La quota giornaliera senza account è esaurita. details.resetsOn è la data. Si fermi. Lo dica alla persona; essa può accedere o attendere fino a quella data.
REVISION_CONFLICT 409 Una revisione ha indicato una base che non è più la testa del preventivo. details riporta entrambe le teste. Legga la testa con GET /v1/quotes/{quoteId}, riapplichi la Sua modifica su di essa e invii di nuovo.

Sono possibili anche DESIGN_REJECTED (il caricamento è stato rifiutato; veda details.reason), UNAUTHENTICATED per un token mancante o errato (un token errato è rifiutato anche sulle route pubbliche), FORBIDDEN per una chiave o un token ospite che non può chiamare la route, e FEATURE_DISABLED per una route disattivata.

La quota giornaliera senza account

Una sessione ospite ha una quota giornaliera di calcolo. I caricamenti e i controlli avviati costano più di una semplice lettura e anche l'apertura di molte sessioni ospite da un solo indirizzo di rete viene conteggiata. Un controllo che il sito avvia da solo per una nuova selezione è addebitato alla stessa quota. Quando è esaurita, Lei riceve ANONYMOUS_BUDGET_SPENT con la data di reimpostazione. I chiamanti che hanno effettuato l'accesso non sono conteggiati in questo modo.

Da un preventivo a un ordine

Un ordine viene effettuato a partire da un preventivo salvato che appartiene a un account. Un token ospite viene rifiutato sulle route degli ordini. Un programma lavora per un account in uno di due modi, entrambi descritti in Per sviluppatori e assistenti:

  • Una chiave API. La persona la crea nel suo account in Chiavi API e sceglie cosa può fare. La invii come Authorization: Bearer ulk_…. Un preventivo creato con la chiave appartiene all'account. Una chiave di test (ulk_test_…) funziona solo con dati di esempio.
  • Accesso per i programmi. Un assistente si registra da solo, la persona vede cosa chiede di fare in una pagina del sito e preme Consenti, e l'assistente riceve un token limitato a tali autorizzazioni.

Legga gli indirizzi salvati con GET /v1/addresses. Un indirizzo viene aggiunto o modificato dalla persona nel browser. L'indirizzo di spedizione deve trovarsi nel destinationCountry del preventivo.

Effettui l'ordine con POST /v1/orders. La route richiede un header Idempotency-Key: una chiave nuova da 8 a 80 caratteri visibili per ogni ordine previsto, e la stessa chiave di nuovo quando Lei riprova:

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 è il totalMinor del preventivo che la persona ha accettato. termsVersion indica la versione delle condizioni di vendita che la persona ha accettato. dangerousGoods indica se la spedizione contiene batterie o altre merci pericolose.

Con questa chiamata non viene effettuato nulla. La risposta è APPROVAL_REQUIRED (422) con details.approvalUrl, sia per una chiave API sia per il token di un assistente che ha effettuato l'accesso. Consegni tale link alla persona. Essa lo apre, accede, vede l'ordine e il totale, e approva o rifiuta. Il link funziona una volta, scade dopo 24 ore e smette di funzionare se il preventivo o il totale cambia.

Dopo l'approvazione l'ordine esiste: elenchi gli ordini dell'account con GET /v1/orders e ne legga uno con GET /v1/orders/{orderId}. Riporta order.number, il numero di fattura proforma in proFormaNumber, il conto su cui pagare in sellerBank e, in payments, il bankReference da scrivere sul bonifico.

Il pagamento avviene tramite bonifico bancario, effettuato dalla persona. Nessuna chiave e nessun assistente possono pagare. Segua l'ordine con GET /v1/orders/{orderId}. Un ingegnere conferma ogni ordine prima della produzione.

Codice Stato Cosa significa Cosa fare
APPROVAL_REQUIRED 422 Una persona che ha effettuato l'accesso deve prima approvare. details.approvalUrl è la pagina. Consegni il link alla persona. Non cerchi un modo per aggirarlo.
TOTAL_MISMATCH 422 expectedTotalMinor non è il totale del preventivo. details.totalMinor è il totale. Legga di nuovo il preventivo e mostri il prezzo alla persona prima di chiedere di nuovo.
QUOTE_EXPIRED 410 Il preventivo ha superato la sua validità. Riveda il preventivo per un prezzo nuovo e lo mostri alla persona.
CONFLICT 409 details.reason è quote_ordered o quote_not_priced (un ingegnere deve prima indicare un prezzo). Non riprovi. Lo dica alla persona.
INTAKE_CLOSED 503 Al momento non si accettano ordini. details.reopensOn è la data, quando ve ne è una. Si fermi. Lo dica alla persona.

Lo stesso servizio viene offerto agli assistenti come strumenti nominati tramite un server MCP: veda Cos'è MCP e come ordinano gli agenti.