API-snelstart: uploaden, controleren, offerte

Voordat u begint

De API werkt zonder account via een gastsessie. De API staat op het eigen adres van de site onder /api. Stel dit eenmaal in:

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

board.zip is een plat zip-archief met uw Gerber- en boorbestanden. Wat erin hoort, leest u in Bestanden voor productie en assemblage. De voorbeelden hebben curl en jq nodig.

Elke aanvraag aan de API na de gastsessie neemt Authorization: Bearer <token>. Elke fout heeft dezelfde vorm:

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

Vertak op code. De message is voor ontwikkelaars.

1. Gastsessie: het token wordt eenmaal getoond.
2. Uploaden: PUT het zip-archief naar het adres dat de API noemt, met de headers die zij noemt.
3. Voltooien, daarna pollen tot de analyse klaar is.
4. Het rapport: bevindingen, welke controles liepen en welke niet.
5. Het prijsvoorbeeld.

De stroom met curl

Lees wat besteld kan worden. Hiervoor is geen token nodig:

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

Open een gastsessie. Het token wordt eenmaal getoond en blijft 30 dagen geldig:

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

Meld het bestand aan. Het antwoord bevat uploadId, designId, uploadUrl en 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\"}")

Stuur het bestand naar het adres dat het antwoord noemt, met elke header in requiredHeaders (content-type, lengte en checksum; zonder deze wordt de upload geweigerd met 403). Voltooi daarna de upload:

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

De status is eerst analysing. Lees het ontwerp tot deze verandert. Als deze ready is, staat het rapport in het antwoord:

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

De kop is no_problems_in_checks_run, problems_found of could_not_check. Lees ook checksRun en checksNotRun: een controle die niet liep, is geen geslaagde controle. De andere statussen zijn needs_mapping (stel de lagen in met PUT /v1/designs/{designId}/layer-mapping), needs_engineer en rejected.

Vraag een prijsvoorbeeld aan. selection en destinationCountry zijn vereist; een lege selection neemt de standaardwaarden:

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 is instant (de prijs geldt zoals getoond) of review (een ingenieur bevestigt deze); reviewReasons zegt waarom. totalMinor staat in mineure eenheden van de currency van het antwoord en ontbreekt wanneer een ingenieur de opdracht moet beprijzen. Om een offerte te bewaren, neemt POST /v1/quotes dezelfde body.

Dezelfde stroom met de JavaScript-client

De client @ulike/sdk wikkelt deze routes. Deze is nog niet als pakket gepubliceerd; dit is de vorm, zodat u dezelfde aanroepen met fetch kunt schrijven. Methodennamen:

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 andere methoden zijn createUpload, completeUpload, getDesign, setLayerMapping, validateDesign, getValidation, waitForValidation, createQuote, getQuote en reviseQuote. Fouten worden geworpen als ApiClientError met een status en een code.

De controle voor een bestelling

Het rapport dat u na het uploaden krijgt, is alleen uit de bestanden gemaakt. Om de bestanden tegen een bestelling te controleren, roept u POST /v1/designs/{designId}/validations (validateDesign) aan met order dat quantities en selection bevat. Het antwoord is een toestand: running, failed of done. Terwijl deze running is, leest u GET /v1/validations/{reportId} (getValidation) elke seconde of twee tot deze done is.

1. Upload het zip-archief.
2. Lees het rapport.
3. Corrigeer en upload als nieuw ontwerp. Stop en vraag de persoon wanneer een correctie de functie, de prijs of de levertijd verandert.
4. Schone bestanden: voer de controle voor de bestelling uit.

Een offerte of voorbeeld met opties die andere grenswaarden meebrengen (dikker koper, andere dikte) heeft een controle voor die selectie nodig. Als er geen is, wordt er een gestart en draagt het voorbeeld de controlereden file_check_pending en een check met diens reportId. De prijs wordt meteen getoond, maar de offerte blijft in review tot die controle klaar is. Lees de controle als hierboven en vraag daarna het voorbeeld opnieuw aan.

Fouten die u zult tegenkomen

Mogelijk zijn ook DESIGN_REJECTED (de upload is geweigerd; zie details.reason), UNAUTHENTICATED voor een ontbrekend of fout token (een fout token wordt ook op openbare routes geweigerd) en FEATURE_DISABLED voor een route die nog niet open is.

Het dagbudget zonder account

Een gastsessie heeft een dagbudget aan rekentijd. Uploads en gestarte controles kosten meer dan een gewone lezing, en het openen van veel gastsessies vanaf een netwerkadres wordt ook geteld. Een controle die de site zelf start voor een nieuwe selectie wordt op hetzelfde budget verrekend. Als het op is, krijgt u ANONYMOUS_BUDGET_SPENT met de datum waarop het wordt gereset. Ingelogde aanroepers worden niet zo geteld.

Wat de API vandaag niet kan: bestellen, betalen, API-sleutels en inloggen voor agenten zijn gepland en niet beschikbaar. De geplande MCP-server wordt beschreven in Wat MCP is en hoe agenten bestellen.