Voordat u begint
Uploaden, bestandscontrole en offerte werken zonder account via een gastsessie. Een bestelling heeft een account nodig: zie „Van offerte naar bestelling“ hieronder. De API staat op het eigen adres van de site onder /api. Stel dit eenmaal in:
API=https://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>. Een API-sleutel gaat in dezelfde header in plaats van het gasttoken. Elke fout heeft dezelfde vorm:
{ "error": { "code": "VALIDATION_FAILED", "message": "…", "details": {}, "requestId": "…" } }
Vertak op code. De message is voor ontwikkelaars.
- Gastsessie: het token wordt eenmaal getoond.
- Uploaden:
PUThet zip-archief naar het adres dat de API noemt, met de headers die zij noemt. - Voltooien, daarna pollen tot de analyse klaar is.
- Het rapport: bevindingen, welke controles liepen en welke niet.
- 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 de client van onze eigen site en is geen openbaar pakket; 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://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, reviseQuote, listAddresses, placeOrder, getOrder, listOrders en cancelOrder. 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.
- Upload het zip-archief.
- Lees het rapport.
- Corrigeer en upload als nieuw ontwerp. Stop en vraag de persoon wanneer een correctie de functie, de prijs of de levertijd verandert.
- 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
| Code | Status | Wat het betekent | Wat te doen |
|---|---|---|---|
DESIGN_NOT_READY |
422 | Het ontwerp wordt nog gelezen (details.status zegt in welke toestand) of heeft nog geen rapport. |
Lees het ontwerp tot de status niet meer analysing is en vraag daarna opnieuw. |
VALIDATION_FAILED |
400 | De aanvraag heeft niet de verwachte vorm of noemt een optie of waarde die de catalogus niet heeft. details somt de punten of problemen op. |
Corrigeer het in details genoemde veld en stuur opnieuw. Neem optie-id's en waarden uit GET /v1/capabilities. |
NOT_MANUFACTURABLE |
422 | De selectie is iets wat wij niet maken. details.because draagt de redenen. |
Wijzig de selectie; probeer dezelfde niet opnieuw. Vraag de persoon als de wijziging de print zou veranderen. |
ANONYMOUS_BUDGET_SPENT |
429 | Het dagbudget zonder account is opgebruikt. details.resetsOn is de datum. |
Stop. Zeg het de persoon; deze kan inloggen of tot die datum wachten. |
REVISION_CONFLICT |
409 | Een revisie noemde een basis die niet meer de kop van de offerte is. details draagt beide koppen. |
Lees de kop met GET /v1/quotes/{quoteId}, pas uw wijziging daarop toe en stuur opnieuw. |
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), FORBIDDEN als een sleutel of een gasttoken de route niet mag aanroepen, en FEATURE_DISABLED voor een route die is uitgeschakeld.
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.
Van offerte naar bestelling
Een bestelling wordt geplaatst uit een bewaarde offerte die bij een account hoort. Een gasttoken wordt op de bestelroutes geweigerd. Een programma werkt op een van twee manieren voor een account, beide beschreven op Voor ontwikkelaars en assistenten:
- Een API-sleutel. De persoon maakt deze in zijn account onder API-sleutels en kiest wat deze mag doen. Stuur deze als
Authorization: Bearer ulk_…. Een offerte die met de sleutel wordt gemaakt, hoort bij het account. Een testsleutel (ulk_test_…) werkt alleen op voorbeelddata. - Inloggen voor programma's. Een assistent registreert zichzelf, de persoon ziet op een pagina van de site wat hij vraagt te doen en drukt op Toestaan, en de assistent krijgt een token dat tot die machtigingen is beperkt.
Lees de bewaarde adressen met GET /v1/addresses. Een adres wordt door de persoon in de browser toegevoegd of gewijzigd. Het verzendadres moet in het destinationCountry van de offerte liggen.
Plaats de bestelling met POST /v1/orders. De route heeft een Idempotency-Key-header nodig: een nieuwe sleutel van 8 tot 80 zichtbare tekens per bedoelde bestelling, en dezelfde sleutel opnieuw als u het opnieuw probeert:
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 is de totalMinor van de offerte waarmee de persoon instemde. termsVersion noemt de versie van de verkoopvoorwaarden die de persoon accepteerde. dangerousGoods zegt of de zending batterijen of andere gevaarlijke goederen bevat.
Er wordt met deze aanroep niets geplaatst. Het antwoord is APPROVAL_REQUIRED (422) met details.approvalUrl, zowel voor een API-sleutel als voor het token van een assistent die inlogde. Geef die link aan de persoon. Deze opent hem, logt in, ziet de bestelling en het totaalbedrag en keurt goed of wijst af. De link werkt eenmaal, verloopt na 24 uur en stopt met werken als de offerte of het totaalbedrag verandert.
Na de goedkeuring bestaat de bestelling: haal de bestellingen van het account op met GET /v1/orders en lees er een met GET /v1/orders/{orderId}. Deze draagt order.number, het pro-formafactuurnummer in proFormaNumber, de rekening om op te betalen in sellerBank en, onder payments, de bankReference om op de overschrijving te schrijven.
Betaling gebeurt per bankoverschrijving, gedaan door de persoon. Geen sleutel en geen assistent kan betalen. Volg de bestelling met GET /v1/orders/{orderId}. Een ingenieur bevestigt elke bestelling voor productie.
| Code | Status | Wat het betekent | Wat te doen |
|---|---|---|---|
APPROVAL_REQUIRED |
422 | Een ingelogde persoon moet eerst goedkeuren. details.approvalUrl is de pagina. |
Geef de link aan de persoon. Zoek geen weg eromheen. |
TOTAL_MISMATCH |
422 | expectedTotalMinor is niet het totaalbedrag van de offerte. details.totalMinor is het totaalbedrag. |
Lees de offerte opnieuw en toon de persoon de prijs voordat u opnieuw vraagt. |
QUOTE_EXPIRED |
410 | De offerte is voorbij haar geldigheid. | Herzie de offerte voor een nieuwe prijs en toon deze aan de persoon. |
CONFLICT |
409 | details.reason is quote_ordered of quote_not_priced (een ingenieur moet eerst een prijs geven). |
Probeer niet opnieuw. Vertel het de persoon. |
INTAKE_CLOSED |
503 | Er worden op dit moment geen bestellingen aangenomen. details.reopensOn is de datum, als er een is. |
Stop. Vertel het de persoon. |
Dezelfde dienst wordt aan assistenten aangeboden als benoemde tools via een MCP-server: zie Wat MCP is en hoe agenten bestellen.