Înainte să începeți
Încărcarea, verificarea fișierelor și oferta funcționează fără cont, printr-o sesiune de vizitator. O comandă are nevoie de un cont: vedeți „De la o ofertă la o comandă” mai jos. API-ul este la adresa proprie a site-ului, sub /api. Setați-l o dată:
API=https://uliketechnology.com/api
F=board.zip
board.zip este un fișier zip plat cu fișierele Gerber și fișierul de găurire. Ce intră în el vedeți la Fișiere pentru fabricație și asamblare. Exemplele au nevoie de curl și jq.
Fiecare cerere spre API după sesiunea de vizitator ia antetul Authorization: Bearer <token>. O cheie API intră în același antet în locul tokenului de vizitator. Fiecare eroare are aceeași formă:
{ "error": { "code": "VALIDATION_FAILED", "message": "…", "details": {}, "requestId": "…" } }
Ramificați după code. Câmpul message este pentru dezvoltatori.
- Sesiunea de vizitator: tokenul este arătat o dată.
- Încărcarea: trimiteți fișierul zip cu
PUTla adresa pe care o numește API-ul, cu anteturile pe care le numește. - Finalizarea, apoi interogarea până când analiza este gata.
- Raportul: observații, ce verificări au rulat și ce verificări nu au rulat.
- Previzualizarea ofertei.
Fluxul cu curl
Citiți ce se poate comanda. Pentru aceasta nu este nevoie de token:
curl -s $API/v1/capabilities | jq '.options[].id'
Deschideți o sesiune de vizitator. Tokenul este arătat o dată și durează 30 de zile:
T=$(curl -s -X POST $API/v1/guest-sessions | jq -r .token)
Anunțați fișierul. Răspunsul are uploadId, designId, uploadUrl și 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\"}")
Trimiteți fișierul la adresa pe care o numește răspunsul, cu fiecare antet din requiredHeaders (tipul de conținut, lungimea și suma de control; fără ele încărcarea este refuzată cu 403). Apoi finalizați încărcarea:
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
Starea este la început analysing. Citiți proiectarea până se schimbă. Când este ready, raportul este în răspuns:
D=$(echo $J | jq -r .designId)
curl -s $API/v1/designs/$D -H "authorization: Bearer $T" | jq '.design.status, .report.headline, .report.counts'
Titlul este no_problems_in_checks_run, problems_found sau could_not_check. Citiți și checksRun și checksNotRun: o verificare care nu a rulat nu este un succes. Celelalte stări sunt needs_mapping (setați straturile cu PUT /v1/designs/{designId}/layer-mapping), needs_engineer și rejected.
Cereți o previzualizare de preț. Câmpurile selection și destinationCountry sunt obligatorii; un selection gol ia valorile implicite:
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'
Câmpul mode este instant (prețul rămâne cum este arătat) sau review (un inginer îl confirmă); câmpul reviewReasons spune de ce. Câmpul totalMinor este în unități minore ale monedei currency din răspuns și lipsește când un inginer trebuie să stabilească prețul lucrării. Pentru a păstra o ofertă, POST /v1/quotes ia același corp.
Același flux cu clientul JavaScript
Clientul @ulike/sdk încapsulează aceste rute. Este clientul propriului nostru site și nu este un pachet public; aceasta este forma lui, ca să puteți scrie aceleași apeluri cu fetch. Numele metodelor:
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',
});
Celelalte metode sunt createUpload, completeUpload, getDesign, setLayerMapping, validateDesign, getValidation, waitForValidation, createQuote, getQuote, reviseQuote, listAddresses, placeOrder, getOrder, listOrders și cancelOrder. Erorile sunt aruncate ca ApiClientError cu status și code.
Verificarea pentru o comandă
Raportul primit după încărcare este făcut numai pe fișiere. Pentru a verifica fișierele față de o comandă, apelați POST /v1/designs/{designId}/validations (validateDesign) cu order care conține quantities și selection. Răspunsul este o stare: running, failed sau done. Cât timp este running, citiți GET /v1/validations/{reportId} (getValidation) la fiecare secundă sau două până când este done.
- Încărcarea fișierului zip.
- Citirea raportului.
- Corectarea și încărcarea ca proiectare nouă. Opriți-vă și întrebați persoana când o corecție schimbă funcția, prețul sau timpul de livrare.
- Fișiere curate: rulați verificarea pentru comandă.
O ofertă sau o previzualizare cu opțiuni care aduc alte limite (cupru mai gros, altă grosime) are nevoie de o verificare pentru acea selecție. Dacă nu există niciuna, una este pornită, iar previzualizarea poartă motivul de verificare file_check_pending și un câmp check cu reportId al lui. Prețul este arătat imediat, dar oferta rămâne în review până când verificarea este gata. Citiți verificarea ca mai sus, apoi cereți din nou previzualizarea.
Erorile pe care le veți întâlni
| Cod | Stare | Ce înseamnă | Ce faceți |
|---|---|---|---|
DESIGN_NOT_READY |
422 | Proiectarea este încă citită (details.status spune care stare), sau nu are încă raport. |
Citiți proiectarea până când starea nu mai este analysing, apoi cereți din nou. |
VALIDATION_FAILED |
400 | Cererea nu are forma așteptată sau numește o opțiune ori o valoare pe care catalogul nu o are. Câmpul details enumeră problemele. |
Corectați câmpul numit în details și trimiteți din nou. Luați identificatorii și valorile opțiunilor din GET /v1/capabilities. |
NOT_MANUFACTURABLE |
422 | Selecția este ceva ce nu fabricăm. Câmpul details.because poartă motivele. |
Schimbați selecția; nu reîncercați aceeași. Întrebați persoana dacă schimbarea ar modifica placa. |
ANONYMOUS_BUDGET_SPENT |
429 | Alocația zilnică fără cont este epuizată. Câmpul details.resetsOn este data. |
Opriți-vă. Spuneți persoanei; se poate autentifica sau aștepta până la acea dată. |
REVISION_CONFLICT |
409 | O revizie a numit o bază care nu mai este capul ofertei. Câmpul details poartă ambele capete. |
Citiți capul cu GET /v1/quotes/{quoteId}, reaplicați modificarea pe el și trimiteți din nou. |
Sunt posibile și codurile DESIGN_REJECTED (încărcarea a fost refuzată; vedeți details.reason), UNAUTHENTICATED pentru un token lipsă sau greșit (un token greșit este refuzat chiar și pe rutele publice), FORBIDDEN pentru o cheie sau un token de vizitator care nu poate apela ruta și FEATURE_DISABLED pentru o rută care este dezactivată.
Alocația zilnică fără cont
O sesiune de vizitator are o alocație zilnică de calcul. Încărcările și verificările pornite costă mai mult decât o citire simplă, iar deschiderea multor sesiuni de vizitator de la aceeași adresă de rețea este și ea contorizată. O verificare pe care site-ul o pornește singur pentru o selecție nouă este taxată din aceeași alocație. Când este epuizată, primiți ANONYMOUS_BUDGET_SPENT cu data la care se resetează. Apelanții autentificați nu sunt contorizați astfel.
De la o ofertă la o comandă
O comandă este plasată dintr-o ofertă păstrată care aparține unui cont. Un token de vizitator este refuzat pe rutele de comandă. Un program lucrează pentru un cont în unul din două moduri, ambele descrise la Pentru dezvoltatori și asistenți:
- O cheie API. Persoana o creează în contul ei la Chei API și alege ce poate face. Trimiteți-o ca
Authorization: Bearer ulk_…. O ofertă creată cu cheia aparține contului. O cheie de test (ulk_test_…) funcționează numai pe date de exemplu. - Autentificarea pentru programe. Un asistent se înregistrează singur, persoana vede pe o pagină a site-ului ce solicită să facă și apasă Permiteți, iar asistentul primește un token limitat la acele permisiuni.
Citiți adresele salvate cu GET /v1/addresses. O adresă este adăugată sau schimbată de persoană în browser. Adresa de expediere trebuie să fie în destinationCountry al ofertei.
Plasați comanda cu POST /v1/orders. Ruta are nevoie de un antet Idempotency-Key: o cheie nouă de 8 până la 80 de caractere vizibile pentru fiecare comandă intenționată și aceeași cheie din nou când reîncercați:
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}"
Câmpul expectedTotalMinor este totalMinor al ofertei cu care persoana a fost de acord. Câmpul termsVersion numește versiunea condițiilor de vânzare pe care persoana le-a acceptat. Câmpul dangerousGoods spune dacă expedierea conține baterii sau alte mărfuri periculoase.
Prin acest apel nu se plasează nimic. Răspunsul este APPROVAL_REQUIRED (422) cu details.approvalUrl, la fel pentru o cheie API și pentru tokenul unui asistent care s-a autentificat. Dați acel link persoanei. Îl deschide, se autentifică, vede comanda și totalul și aprobă sau refuză. Linkul funcționează o dată, expiră după 24 de ore și nu mai funcționează dacă se schimbă oferta sau totalul.
După aprobare comanda există: listați comenzile contului cu GET /v1/orders și citiți una cu GET /v1/orders/{orderId}. Aceasta are order.number, numărul facturii pro forma în proFormaNumber, contul în care se plătește în sellerBank și, sub payments, bankReference de scris pe transfer.
Plata se face prin transfer bancar, făcut de persoană. Nicio cheie și niciun asistent nu poate plăti. Urmăriți comanda cu GET /v1/orders/{orderId}. Un inginer confirmă fiecare comandă înainte de producție.
| Cod | Stare | Ce înseamnă | Ce faceți |
|---|---|---|---|
APPROVAL_REQUIRED |
422 | O persoană autentificată trebuie să aprobe mai întâi. Câmpul details.approvalUrl este pagina. |
Dați linkul persoanei. Nu căutați o cale de ocolire. |
TOTAL_MISMATCH |
422 | Câmpul expectedTotalMinor nu este totalul ofertei. Câmpul details.totalMinor este totalul. |
Citiți din nou oferta și arătați persoanei prețul înainte să cereți din nou. |
QUOTE_EXPIRED |
410 | Oferta a trecut de valabilitate. | Revizuiți oferta pentru un preț nou și arătați-o persoanei. |
CONFLICT |
409 | Câmpul details.reason este quote_ordered sau quote_not_priced (un inginer trebuie să dea mai întâi un preț). |
Nu reîncercați. Spuneți persoanei. |
INTAKE_CLOSED |
503 | În acest moment nu se primesc comenzi. Câmpul details.reopensOn este data, când există una. |
Opriți-vă. Spuneți persoanei. |
Același serviciu este oferit asistenților ca instrumente numite printr-un server MCP: vedeți Ce este MCP și cum comandă agenții.