Innan du börjar
Uppladdning, filkontroll och offert fungerar utan konto via en gästsession. En beställning behöver ett konto: se ”Från offert till beställning” nedan. API:t finns på webbplatsens egen adress under /api. Ställ in det en gång:
API=https://uliketechnology.com/api
F=board.zip
board.zip är ett plant zip-arkiv med dina Gerber- och borrfiler. Vad som ska finnas i det läser du i Filer för tillverkning och bestyckning. Exemplen behöver curl och jq.
Varje begäran till API:t efter gästsessionen tar Authorization: Bearer <token>. En API-nyckel går i samma header i stället för gästtoken. Varje fel har samma form:
{ "error": { "code": "VALIDATION_FAILED", "message": "…", "details": {}, "requestId": "…" } }
Grena på code. message är för utvecklare.
- Gästsession: token visas en gång.
- Uppladdning:
PUTzip-arkivet till adressen som API:t anger, med de headers det anger. - Slutför, polla sedan tills analysen är klar.
- Rapporten: observationer, vilka kontroller som kördes och vilka som inte gjorde det.
- Prisförhandsvisningen.
Flödet med curl
Läs vad som kan beställas. Detta behöver ingen token:
curl -s $API/v1/capabilities | jq '.options[].id'
Öppna en gästsession. Token visas en gång och gäller i 30 dagar:
T=$(curl -s -X POST $API/v1/guest-sessions | jq -r .token)
Anmäl filen. Svaret innehåller uploadId, designId, uploadUrl och 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\"}")
Skicka filen till adressen som svaret anger, med varje header i requiredHeaders (content type, längd och checksumma; utan dem avvisas uppladdningen med 403). Slutför sedan uppladdningen:
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
Statusen är först analysing. Läs konstruktionen tills den ändras. När den är ready finns rapporten i svaret:
D=$(echo $J | jq -r .designId)
curl -s $API/v1/designs/$D -H "authorization: Bearer $T" | jq '.design.status, .report.headline, .report.counts'
Rubriken är no_problems_in_checks_run, problems_found eller could_not_check. Läs också checksRun och checksNotRun: en kontroll som inte kördes är inte godkänd. De andra statusarna är needs_mapping (ställ in lagren med PUT /v1/designs/{designId}/layer-mapping), needs_engineer och rejected.
Begär en prisförhandsvisning. selection och destinationCountry krävs; en tom selection tar standardvärdena:
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 är instant (priset gäller som visat) eller review (en ingenjör bekräftar det); reviewReasons säger varför. totalMinor är i mindre enheter av svarets currency och saknas när en ingenjör måste prissätta jobbet. För att spara en offert tar POST /v1/quotes samma body.
Samma flöde med JavaScript-klienten
Klienten @ulike/sdk omsluter dessa rutter. Den är klienten för vår egen webbplats och är inte ett offentligt paket; detta är dess form, så att du kan skriva samma anrop med fetch. Metodnamn:
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',
});
De andra metoderna är createUpload, completeUpload, getDesign, setLayerMapping, validateDesign, getValidation, waitForValidation, createQuote, getQuote, reviseQuote, listAddresses, placeOrder, getOrder, listOrders och cancelOrder. Fel kastas som ApiClientError med en status och en code.
Kontrollen för en beställning
Rapporten du får efter uppladdning görs bara från filerna. För att kontrollera filerna mot en beställning anropar du POST /v1/designs/{designId}/validations (validateDesign) med order som håller quantities och selection. Svaret är ett tillstånd: running, failed eller done. Medan det är running läser du GET /v1/validations/{reportId} (getValidation) varje sekund eller varannan tills det är done.
- Ladda upp zip-arkivet.
- Läs rapporten.
- Rätta och ladda upp som ny konstruktion. Stanna och fråga personen när en rättning ändrar funktionen, priset eller ledtiden.
- Rena filer: kör kontrollen för beställningen.
En offert eller förhandsvisning med alternativ som medför andra gränsvärden (tjockare koppar, annan tjocklek) behöver en kontroll för det valet. Om ingen finns startas en, och förhandsvisningen bär granskningsorsaken file_check_pending och en check med dess reportId. Priset visas genast, men offerten stannar i review tills den kontrollen är klar. Läs kontrollen som ovan och begär sedan förhandsvisningen igen.
Fel du kommer att möta
| Kod | Status | Vad det betyder | Vad du ska göra |
|---|---|---|---|
DESIGN_NOT_READY |
422 | Konstruktionen läses fortfarande (details.status säger i vilket tillstånd), eller har ännu ingen rapport. |
Läs konstruktionen tills statusen inte längre är analysing, fråga sedan igen. |
VALIDATION_FAILED |
400 | Begäran har inte den förväntade formen, eller anger ett alternativ eller värde som katalogen inte har. details listar punkterna eller problemen. |
Rätta fältet som anges i details och skicka igen. Ta alternativ-id:n och värden från GET /v1/capabilities. |
NOT_MANUFACTURABLE |
422 | Valet är något vi inte tillverkar. details.because bär orsakerna. |
Ändra valet; försök inte samma igen. Fråga personen om ändringen skulle ändra kortet. |
ANONYMOUS_BUDGET_SPENT |
429 | Dagskvoten utan konto är förbrukad. details.resetsOn är datumet. |
Stanna. Berätta för personen; hen kan logga in eller vänta till det datumet. |
REVISION_CONFLICT |
409 | En revision angav en bas som inte längre är offertens huvud. details bär båda huvudena. |
Läs huvudet med GET /v1/quotes/{quoteId}, tillämpa din ändring på det och skicka igen. |
Möjliga är också DESIGN_REJECTED (uppladdningen avvisades; se details.reason), UNAUTHENTICATED för en saknad eller fel token (en fel token avvisas även på offentliga rutter), FORBIDDEN för en nyckel eller en gästtoken som inte får anropa rutten, och FEATURE_DISABLED för en rutt som är avstängd.
Dagskvoten utan konto
En gästsession har en dagskvot av beräkning. Uppladdningar och startade kontroller kostar mer än en vanlig läsning, och att öppna många gästsessioner från en nätverksadress räknas också. En kontroll som webbplatsen startar själv för ett nytt val debiteras samma kvot. När den är förbrukad får du ANONYMOUS_BUDGET_SPENT med datumet då den återställs. Inloggade anropare räknas inte så.
Från offert till beställning
En beställning läggs från en sparad offert som hör till ett konto. En gästtoken avvisas på beställningsrutterna. Ett program arbetar för ett konto på ett av två sätt, båda beskrivna på För utvecklare och assistenter:
- En API-nyckel. Personen gör den i sitt konto under API-nycklar och väljer vad den får göra. Skicka den som
Authorization: Bearer ulk_…. En offert som skapas med nyckeln hör till kontot. En testnyckel (ulk_test_…) fungerar bara på exempeldata. - Inloggning för program. En assistent registrerar sig själv, personen ser vad den ber om att göra på en sida på webbplatsen och trycker på Tillåt, och assistenten får en token som är begränsad till de behörigheterna.
Läs de sparade adresserna med GET /v1/addresses. En adress läggs till eller ändras av personen i webbläsaren. Fraktadressen måste ligga i offertens destinationCountry.
Lägg beställningen med POST /v1/orders. Rutten behöver en Idempotency-Key-header: en ny nyckel på 8 till 80 synliga tecken per avsedd beställning, och samma nyckel igen när du försöker på nytt:
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 är offertens totalMinor som personen gick med på. termsVersion namnger versionen av försäljningsvillkoren som personen accepterade. dangerousGoods säger om sändningen innehåller batterier eller annat farligt gods.
Inget läggs med det här anropet. Svaret är APPROVAL_REQUIRED (422) med details.approvalUrl, för en API-nyckel och för token för en assistent som loggade in på samma sätt. Ge den länken till personen. Hen öppnar den, loggar in, ser beställningen och totalsumman och godkänner eller avvisar. Länken fungerar en gång, går ut efter 24 timmar och slutar fungera om offerten eller totalsumman ändras.
Efter godkännandet finns beställningen: lista kontots beställningar med GET /v1/orders och läs en med GET /v1/orders/{orderId}. Den bär order.number, proformafakturanumret i proFormaNumber, kontot att betala till i sellerBank och, under payments, bankReference att skriva på överföringen.
Betalning sker med banköverföring, gjord av personen. Ingen nyckel och ingen assistent kan betala. Följ beställningen med GET /v1/orders/{orderId}. En ingenjör bekräftar varje beställning före produktion.
| Kod | Status | Vad det betyder | Vad du ska göra |
|---|---|---|---|
APPROVAL_REQUIRED |
422 | En inloggad person måste godkänna först. details.approvalUrl är sidan. |
Ge länken till personen. Leta inte efter en väg runt den. |
TOTAL_MISMATCH |
422 | expectedTotalMinor är inte offertens totalsumma. details.totalMinor är totalsumman. |
Läs offerten igen och visa personen priset innan du frågar igen. |
QUOTE_EXPIRED |
410 | Offerten är förbi sin giltighet. | Revidera offerten för ett nytt pris och visa det för personen. |
CONFLICT |
409 | details.reason är quote_ordered eller quote_not_priced (en ingenjör måste ge ett pris först). |
Försök inte igen. Berätta för personen. |
INTAKE_CLOSED |
503 | Inga beställningar tas emot för tillfället. details.reopensOn är datumet, när det finns ett. |
Stanna. Berätta för personen. |
Samma tjänst erbjuds assistenter som namngivna verktyg via en MCP-server: se Vad MCP är och hur agenter beställer.