API-snabbstart: ladda upp, kontrollera, offert

Innan du börjar

API:t fungerar utan konto via en gästsession. API:t finns på webbplatsens egen adress under /api. Ställ in det en gång:

API=https://dev.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>. Varje fel har samma form:

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

Grena på code. message är för utvecklare.

1. Gästsession: token visas en gång.
2. Uppladdning: PUT zip-arkivet till adressen som API:t anger, med de headers det anger.
3. Slutför, polla sedan tills analysen är klar.
4. Rapporten: observationer, vilka kontroller som kördes och vilka som inte gjorde det.
5. 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 ännu inte publicerad som 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://dev.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 och reviseQuote. 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.

1. Ladda upp zip-arkivet.
2. Läs rapporten.
3. Rätta och ladda upp som ny konstruktion. Stanna och fråga personen när en rättning ändrar funktionen, priset eller ledtiden.
4. 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

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) och FEATURE_DISABLED för en rutt som ännu inte är öppen.

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å.

Vad API:t inte kan idag: beställning, betalning, API-nycklar och inloggning för agenter är planerade och inte tillgängliga. Den planerade MCP-servern beskrivs i Vad MCP är och hur agenter beställer.