Rychlý start API: nahrání, kontrola, nabídka

Než začnete

API funguje bez účtu prostřednictvím hostovské relace. API je na vlastní adrese webu pod /api. Nastavte ji jednou:

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

board.zip je plochý zip archiv s Vašimi soubory Gerber a vrtacími soubory. Co do něj patří, čtěte v Soubory pro výrobu a osazování. Příklady potřebují curl a jq.

Každý požadavek na API po hostovské relaci nese Authorization: Bearer <token>. Každá chyba má stejný tvar:

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

Větvěte podle code. message je pro vývojáře.

1. Hostovská relace: token se zobrazí jednou.
2. Nahrání: PUT zip archivu na adresu, kterou API jmenuje, se záhlavími, která jmenuje.
3. Dokončení, poté dotazování, dokud není analýza hotová.
4. Zpráva: zjištění, které kontroly běžely a které ne.
5. Náhled ceny.

Tok s curl

Přečtěte, co lze objednat. K tomu není token potřeba:

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

Otevřete hostovskou relaci. Token se zobrazí jednou a platí 30 dní:

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

Ohlaste soubor. Odpověď obsahuje uploadId, designId, uploadUrl a 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\"}")

Pošlete soubor na adresu, kterou odpověď jmenuje, s každým záhlavím v requiredHeaders (typ obsahu, délka a kontrolní součet; bez nich je nahrání odmítnuto s 403). Poté nahrání dokončete:

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

Stav je nejprve analysing. Čtěte návrh, dokud se nezmění. Když je ready, zpráva je v odpovědi:

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

Nadpis je no_problems_in_checks_run, problems_found nebo could_not_check. Čtěte také checksRun a checksNotRun: kontrola, která neběžela, není splněná. Další stavy jsou needs_mapping (nastavte vrstvy pomocí PUT /v1/designs/{designId}/layer-mapping), needs_engineer a rejected.

Požádejte o náhled ceny. selection a destinationCountry jsou povinné; prázdná selection vezme výchozí hodnoty:

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 je instant (cena platí, jak je zobrazena) nebo review (inženýr ji potvrdí); reviewReasons říká proč. totalMinor je v minoritních jednotkách měny odpovědi currency a chybí, když inženýr musí zakázku ocenit. K uložení nabídky POST /v1/quotes bere stejné tělo.

Stejný tok s JavaScript klientem

Klient @ulike/sdk tyto trasy obaluje. Ještě není publikován jako balíček; toto je jeho tvar, abyste stejná volání mohli psát s fetch. Názvy metod:

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

Další metody jsou createUpload, completeUpload, getDesign, setLayerMapping, validateDesign, getValidation, waitForValidation, createQuote, getQuote a reviseQuote. Chyby se vyhazují jako ApiClientError se status a code.

Kontrola pro objednávku

Zpráva, kterou dostanete po nahrání, je vytvořena jen ze souborů. Ke kontrole souborů vůči objednávce volejte POST /v1/designs/{designId}/validations (validateDesign) s order obsahujícím quantities a selection. Odpověď je stav: running, failed nebo done. Zatímco je running, čtěte GET /v1/validations/{reportId} (getValidation) každou sekundu nebo dvě, dokud není done.

1. Nahrajte zip archiv.
2. Přečtěte zprávu.
3. Opravte a nahrajte jako nový návrh. Zastavte a zeptejte se osoby, když oprava mění funkci, cenu nebo dodací lhůtu.
4. Čisté soubory: spusťte kontrolu pro objednávku.

Nabídka nebo náhled s volbami, které přinášejí jiné limity (silnější měď, jiná tloušťka), potřebuje kontrolu pro tento výběr. Pokud žádná není, jedna se spustí a náhled nese důvod technické kontroly file_check_pending a check s jeho reportId. Cena se zobrazí ihned, ale nabídka zůstane v review, dokud tato kontrola není hotová. Čtěte kontrolu jako výše a poté požádejte o náhled znovu.

Chyby, které potkáte

Možné jsou také DESIGN_REJECTED (nahrání bylo odmítnuto; viz details.reason), UNAUTHENTICATED pro chybějící nebo špatný token (špatný token je odmítnut i na veřejných trasách) a FEATURE_DISABLED pro trasu, která ještě není otevřená.

Denní příděl bez účtu

Hostovská relace má denní příděl výpočtu. Nahrání a spuštěné kontroly stojí více než prosté čtení a otevírání mnoha hostovských relací z jedné síťové adresy se také počítá. Kontrola, kterou web sám spustí pro nový výběr, se účtuje na stejný příděl. Když je vyčerpán, dostanete ANONYMOUS_BUDGET_SPENT s datem, kdy se resetuje. Přihlášení volající se takto nepočítají.

Co API dnes neumí: objednávání, platba, klíče API a přihlášení pro agenty jsou plánované a nedostupné. Plánovaný server MCP je popsán v Co je MCP a jak agenti objednávají.