Bevor Sie beginnen
Hochladen, Dateiprüfung und Angebot funktionieren ohne Benutzerkonto über eine Gast-Sitzung. Eine Bestellung braucht ein Benutzerkonto: siehe „Von einem Angebot zu einer Bestellung“ unten. Die API liegt unter der eigenen Adresse der Website unter /api. Setzen Sie sie einmal:
API=https://uliketechnology.com/api
F=board.zip
board.zip ist ein flaches Zip-Archiv mit Ihren Gerber- und Bohrdateien. Was hineingehört, steht unter Dateien für Fertigung und Bestückung. Die Beispiele brauchen curl und jq.
Jede Anfrage an die API nach der Gast-Sitzung nimmt Authorization: Bearer <token>. Ein API-Schlüssel steht in demselben Header anstelle des Gast-Tokens. Jeder Fehler hat dieselbe Form:
{ "error": { "code": "VALIDATION_FAILED", "message": "…", "details": {}, "requestId": "…" } }
Verzweigen Sie nach code. Die message ist für Entwickler.
- Gast-Sitzung: das Token wird einmal angezeigt.
- Hochladen:
PUTdes Zip-Archivs an die Adresse, die die API nennt, mit den Headern, die sie nennt. - Abschließen, dann abfragen, bis die Analyse fertig ist.
- Der Bericht: Feststellungen, welche Prüfungen liefen und welche nicht.
- Die Preisvorschau.
Der Ablauf mit curl
Lesen Sie, was bestellt werden kann. Dafür ist kein Token nötig:
curl -s $API/v1/capabilities | jq '.options[].id'
Öffnen Sie eine Gast-Sitzung. Das Token wird einmal angezeigt und gilt 30 Tage:
T=$(curl -s -X POST $API/v1/guest-sessions | jq -r .token)
Melden Sie die Datei an. Die Antwort enthält uploadId, designId, uploadUrl und 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\"}")
Senden Sie die Datei an die Adresse, die die Antwort nennt, mit jedem Header in requiredHeaders (Content-Type, Länge und Prüfsumme; ohne sie wird der Upload mit 403 abgelehnt). Schließen Sie den Upload dann ab:
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
Der Status ist zuerst analysing. Lesen Sie das Design, bis er sich ändert. Wenn er ready ist, steht der Bericht in der Antwort:
D=$(echo $J | jq -r .designId)
curl -s $API/v1/designs/$D -H "authorization: Bearer $T" | jq '.design.status, .report.headline, .report.counts'
Die Überschrift ist no_problems_in_checks_run, problems_found oder could_not_check. Lesen Sie auch checksRun und checksNotRun: eine Prüfung, die nicht lief, ist nicht bestanden. Die anderen Status sind needs_mapping (setzen Sie die Lagen mit PUT /v1/designs/{designId}/layer-mapping), needs_engineer und rejected.
Fordern Sie eine Preisvorschau an. selection und destinationCountry sind erforderlich; eine leere selection nimmt die Standardwerte:
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 ist instant (der Preis steht wie angezeigt) oder review (ein Ingenieur bestätigt ihn); reviewReasons sagt warum. totalMinor steht in Nebeneinheiten der currency der Antwort und fehlt, wenn ein Ingenieur den Auftrag bepreisen muss. Um ein Angebot zu speichern, nimmt POST /v1/quotes denselben Body.
Derselbe Ablauf mit dem JavaScript-Client
Der Client @ulike/sdk umhüllt diese Routen. Er ist der Client unserer eigenen Website und kein öffentliches Paket; dies ist seine Form, damit Sie dieselben Aufrufe mit fetch schreiben können. 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',
});
Zu den weiteren Methoden gehören createUpload, completeUpload, getDesign, setLayerMapping, validateDesign, getValidation, waitForValidation, createQuote, getQuote, reviseQuote, listAddresses, placeOrder, getOrder, listOrders und cancelOrder. Fehler werden als ApiClientError mit status und code geworfen.
Die Prüfung für eine Bestellung
Der Bericht, den Sie nach dem Hochladen erhalten, wird nur aus den Dateien erstellt. Um die Dateien gegen eine Bestellung zu prüfen, rufen Sie POST /v1/designs/{designId}/validations (validateDesign) mit order auf, das quantities und selection enthält. Die Antwort ist ein Zustand: running, failed oder done. Während running lesen Sie GET /v1/validations/{reportId} (getValidation) alle ein bis zwei Sekunden, bis er done ist.
- Laden Sie das Zip-Archiv hoch.
- Lesen Sie den Bericht.
- Korrigieren Sie und laden Sie als neues Design hoch. Stoppen Sie und fragen Sie die Person, wenn eine Korrektur die Funktion, den Preis oder die Lieferzeit ändert.
- Saubere Dateien: Führen Sie die Prüfung für die Bestellung aus.
Ein Angebot oder eine Vorschau mit Optionen, die andere Grenzwerte mit sich bringen (dickeres Kupfer, andere Dicke), braucht eine Prüfung für diese Auswahl. Wenn keine vorhanden ist, wird eine gestartet, und die Vorschau trägt den Prüfungsgrund file_check_pending und ein check mit seiner reportId. Der Preis wird sofort angezeigt, aber das Angebot bleibt in review, bis diese Prüfung fertig ist. Lesen Sie die Prüfung wie oben und fordern Sie die Vorschau dann erneut an.
Fehler, denen Sie begegnen werden
| Code | Status | Was es bedeutet | Was zu tun ist |
|---|---|---|---|
DESIGN_NOT_READY |
422 | Das Design wird noch gelesen (details.status sagt, in welchem Zustand), oder es hat noch keinen Bericht. |
Lesen Sie das Design, bis der Status nicht mehr analysing ist, dann fragen Sie erneut. |
VALIDATION_FAILED |
400 | Die Anfrage hat nicht die erwartete Form oder nennt eine Option oder einen Wert, den der Katalog nicht hat. details listet die Punkte oder Probleme. |
Korrigieren Sie das in details genannte Feld und senden Sie erneut. Nehmen Sie Options-IDs und Werte aus GET /v1/capabilities. |
NOT_MANUFACTURABLE |
422 | Die Auswahl ist etwas, das wir nicht fertigen. details.because trägt die Gründe. |
Ändern Sie die Auswahl; versuchen Sie dieselbe nicht erneut. Fragen Sie die Person, wenn die Änderung die Platine verändern würde. |
ANONYMOUS_BUDGET_SPENT |
429 | Das tägliche Kontingent ohne Benutzerkonto ist aufgebraucht. details.resetsOn ist das Datum. |
Stoppen Sie. Sagen Sie es der Person; sie kann sich anmelden oder bis zu diesem Datum warten. |
REVISION_CONFLICT |
409 | Eine Revision nannte eine Basis, die nicht mehr der Kopf des Angebots ist. details trägt beide Köpfe. |
Lesen Sie den Kopf mit GET /v1/quotes/{quoteId}, wenden Sie Ihre Änderung darauf an und senden Sie erneut. |
Möglich sind auch DESIGN_REJECTED (der Upload wurde abgelehnt; siehe details.reason), UNAUTHENTICATED für ein fehlendes oder falsches Token (ein falsches Token wird auch auf öffentlichen Routen abgelehnt), FORBIDDEN, wenn ein Schlüssel oder ein Gast-Token die Route nicht aufrufen darf, und FEATURE_DISABLED für eine Route, die ausgeschaltet ist.
Das tägliche Kontingent ohne Benutzerkonto
Eine Gast-Sitzung hat ein tägliches Kontingent an Rechenzeit. Uploads und gestartete Prüfungen kosten mehr als ein einfaches Lesen, und das Öffnen vieler Gast-Sitzungen von einer Netzwerkadresse wird ebenfalls gezählt. Eine Prüfung, die die Website von sich aus für eine neue Auswahl startet, wird auf dasselbe Kontingent angerechnet. Wenn es aufgebraucht ist, erhalten Sie ANONYMOUS_BUDGET_SPENT mit dem Datum, an dem es zurückgesetzt wird. Angemeldete Aufrufer werden nicht so gezählt.
Von einem Angebot zu einer Bestellung
Eine Bestellung wird aus einem gespeicherten Angebot aufgegeben, das zu einem Benutzerkonto gehört. Ein Gast-Token wird auf den Bestellrouten abgelehnt. Ein Programm arbeitet auf eine von zwei Arten für ein Benutzerkonto, beide beschrieben unter Für Entwickler und Assistenten:
- Ein API-Schlüssel. Die Person erstellt ihn in ihrem Benutzerkonto unter API-Schlüssel und wählt, was er tun darf. Senden Sie ihn als
Authorization: Bearer ulk_…. Ein Angebot, das mit dem Schlüssel erstellt wird, gehört zum Benutzerkonto. Ein Testschlüssel (ulk_test_…) funktioniert nur mit Beispieldaten. - Anmeldung für Programme. Ein Assistent registriert sich selbst, die Person sieht auf einer Seite der Website, worum er bittet, und drückt auf Zulassen, und der Assistent erhält ein Token, das auf diese Berechtigungen beschränkt ist.
Lesen Sie die gespeicherten Adressen mit GET /v1/addresses. Eine Adresse wird von der Person im Browser hinzugefügt oder geändert. Die Versandadresse muss im destinationCountry des Angebots liegen.
Geben Sie die Bestellung mit POST /v1/orders auf. Die Route braucht einen Idempotency-Key-Header: einen neuen Schlüssel von 8 bis 80 sichtbaren Zeichen pro beabsichtigter Bestellung und denselben Schlüssel erneut, wenn Sie es erneut versuchen:
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 ist der totalMinor des Angebots, dem die Person zugestimmt hat. termsVersion nennt die Version der Verkaufsbedingungen, die die Person akzeptiert hat. dangerousGoods sagt, ob die Sendung Batterien oder andere Gefahrgüter enthält.
Mit diesem Aufruf wird nichts aufgegeben. Die Antwort ist APPROVAL_REQUIRED (422) mit details.approvalUrl, für einen API-Schlüssel und für das Token eines Assistenten, der sich angemeldet hat, gleichermaßen. Geben Sie diesen Link an die Person. Sie öffnet ihn, meldet sich an, sieht die Bestellung und den Gesamtbetrag und gibt frei oder lehnt ab. Der Link funktioniert einmal, läuft nach 24 Stunden ab und hört auf zu funktionieren, wenn sich das Angebot oder der Gesamtbetrag ändert.
Nach der Freigabe existiert die Bestellung: Listen Sie die Bestellungen des Benutzerkontos mit GET /v1/orders auf und lesen Sie eine mit GET /v1/orders/{orderId}. Sie trägt order.number, die Pro-forma-Rechnungsnummer in proFormaNumber, das Konto, auf das zu zahlen ist, in sellerBank und, unter payments, die bankReference, die auf die Überweisung zu schreiben ist.
Die Zahlung erfolgt per Banküberweisung, vorgenommen von der Person. Kein Schlüssel und kein Assistent kann zahlen. Verfolgen Sie die Bestellung mit GET /v1/orders/{orderId}. Ein Ingenieur bestätigt jede Bestellung vor der Produktion.
| Code | Status | Was es bedeutet | Was zu tun ist |
|---|---|---|---|
APPROVAL_REQUIRED |
422 | Eine angemeldete Person muss zuerst freigeben. details.approvalUrl ist die Seite. |
Geben Sie den Link an die Person. Suchen Sie keinen Weg darum herum. |
TOTAL_MISMATCH |
422 | expectedTotalMinor ist nicht der Gesamtbetrag des Angebots. details.totalMinor ist der Gesamtbetrag. |
Lesen Sie das Angebot erneut und zeigen Sie der Person den Preis, bevor Sie erneut fragen. |
QUOTE_EXPIRED |
410 | Das Angebot ist über seine Gültigkeit hinaus. | Überarbeiten Sie das Angebot für einen neuen Preis und zeigen Sie ihn der Person. |
CONFLICT |
409 | details.reason ist quote_ordered oder quote_not_priced (ein Ingenieur muss zuerst einen Preis geben). |
Versuchen Sie es nicht erneut. Sagen Sie es der Person. |
INTAKE_CLOSED |
503 | Derzeit werden keine Bestellungen angenommen. details.reopensOn ist das Datum, wenn es eines gibt. |
Stoppen Sie. Sagen Sie es der Person. |
Derselbe Dienst wird Assistenten als benannte Werkzeuge über einen MCP-Server angeboten: siehe Was MCP ist und wie Agenten bestellen.