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.
- Sessione ospite: il token è mostrato una volta.
- Caricamento: invii con
PUTlo zip all'indirizzo che l'API indica, con gli header che essa indica. - Completamento, poi interroghi fino a quando l'analisi è terminata.
- Il rapporto: segnalazioni, quali controlli sono stati eseguiti e quali no.
- 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.
- Carichi lo zip.
- Legga il rapporto.
- 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.
- 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.