Перш ніж Ви почнете
Завантаження, перевірка файлів і розрахунок вартості працюють без облікового запису, через гостьову сесію. Для замовлення потрібен обліковий запис: див. «Від розрахунку вартості до замовлення» нижче. API перебуває за власною адресою сайту, у шляху /api. Установіть його один раз:
API=https://uliketechnology.com/api
F=board.zip
board.zip — це плоский zip із Вашими файлами Gerber і файлом свердління. Що в нього входить, див. у статті Файли для виготовлення та монтажу. Прикладам потрібні curl і jq.
Кожен запит до API після гостьової сесії приймає Authorization: Bearer <token>. Ключ API входить у той самий заголовок замість гостьового токена. Кожна помилка має однакову форму:
{ "error": { "code": "VALIDATION_FAILED", "message": "…", "details": {}, "requestId": "…" } }
Гілкуйтеся за code. Поле message — для розробників.
- Гостьова сесія: токен показується один раз.
- Завантаження: надішліть zip методом
PUTна адресу, яку називає API, із заголовками, які він називає. - Завершення, потім опитування, доки аналіз не буде готовий.
- Звіт: зауваження, які перевірки виконано, а які ні.
- Попередній розрахунок вартості.
Процес із curl
Прочитайте, що можна замовити. Для цього токен не потрібен:
curl -s $API/v1/capabilities | jq '.options[].id'
Відкрийте гостьову сесію. Токен показується один раз і діє 30 днів:
T=$(curl -s -X POST $API/v1/guest-sessions | jq -r .token)
Оголосіть файл. У відповіді є uploadId, designId, uploadUrl і 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\"}")
Надішліть файл на адресу, яку називає відповідь, із кожним заголовком із requiredHeaders (тип умісту, довжина та контрольна сума; без них завантаження відхиляється з кодом 403). Потім завершіть завантаження:
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
Статус спочатку analysing. Читайте проєкт, доки він не зміниться. Коли він буде ready, звіт міститься у відповіді:
D=$(echo $J | jq -r .designId)
curl -s $API/v1/designs/$D -H "authorization: Bearer $T" | jq '.design.status, .report.headline, .report.counts'
Заголовок — no_problems_in_checks_run, problems_found або could_not_check. Прочитайте також checksRun і checksNotRun: перевірка, яка не виконалася, — не пройдена. Інші статуси — needs_mapping (установіть шари викликом PUT /v1/designs/{designId}/layer-mapping), needs_engineer і rejected.
Запросіть попередню ціну. Поля selection і destinationCountry обов’язкові; порожнє selection бере значення за замовчуванням:
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 — instant (ціна діє як показано) або review (інженер її підтверджує); поле reviewReasons каже чому. Поле totalMinor — у молодших одиницях валюти currency відповіді та відсутнє, коли інженер має оцінити роботу. Щоб зберегти розрахунок вартості, виклик POST /v1/quotes приймає те саме тіло.
Той самий процес із JavaScript-клієнтом
Клієнт @ulike/sdk обгортає ці маршрути. Це клієнт нашого власного сайту, і він не є публічним пакетом; це його форма, щоб Ви могли написати ті самі виклики за допомогою fetch. Імена методів:
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',
});
Інші методи — createUpload, completeUpload, getDesign, setLayerMapping, validateDesign, getValidation, waitForValidation, createQuote, getQuote, reviseQuote, listAddresses, placeOrder, getOrder, listOrders і cancelOrder. Помилки викидаються як ApiClientError із полями status і code.
Перевірка для замовлення
Звіт, який Ви отримуєте після завантаження, зроблено лише за файлами. Щоб перевірити файли проти замовлення, викличте POST /v1/designs/{designId}/validations (validateDesign) із полем order, що містить quantities і selection. Відповідь — стан: running, failed або done. Доки running, читайте GET /v1/validations/{reportId} (getValidation) кожну секунду або дві, доки не буде done.
- Завантаження zip.
- Читання звіту.
- Виправлення та завантаження як новий проєкт. Зупиніться й запитайте людину, коли виправлення змінює функцію, ціну або термін постачання.
- Чисті файли: запустіть перевірку для замовлення.
Розрахунок вартості або попередній розрахунок з опціями, які приносять інші обмеження (товстіша мідь, інша товщина), потребує перевірки для цього вибору. Якщо такої нема, одна запускається, і попередній розрахунок несе причину перевірки file_check_pending і поле check із його reportId. Ціна показується одразу, але розрахунок вартості залишається в review, доки ця перевірка не буде готова. Прочитайте перевірку, як вище, потім запросіть попередній розрахунок знову.
Помилки, які Ви зустрінете
| Код | Статус | Що це означає | Що робити |
|---|---|---|---|
DESIGN_NOT_READY |
422 | Проєкт ще читається (details.status каже, який стан), або в нього ще нема звіту. |
Читайте проєкт, доки статус не перестане бути analysing, потім запитайте знову. |
VALIDATION_FAILED |
400 | Запит не має очікуваної форми або називає опцію чи значення, яких нема в каталозі. Поле details перелічує проблеми. |
Виправте поле, назване в details, і надішліть знову. Ідентифікатори опцій і значення беріть із GET /v1/capabilities. |
NOT_MANUFACTURABLE |
422 | Вибір — те, що ми не виготовляємо. Поле details.because несе причини. |
Змініть вибір; не повторюйте той самий. Запитайте людину, чи змінить зміна плату. |
ANONYMOUS_BUDGET_SPENT |
429 | Денний ліміт без облікового запису вичерпано. Поле details.resetsOn — дата. |
Зупиніться. Скажіть людині; вона може увійти або зачекати до цієї дати. |
REVISION_CONFLICT |
409 | Ревізія назвала базу, яка більше не голова розрахунку вартості. Поле details несе обидві голови. |
Прочитайте голову викликом GET /v1/quotes/{quoteId}, повторно застосуйте зміну на ній і надішліть знову. |
Також можливі коди DESIGN_REJECTED (завантаження було відхилено; див. details.reason), UNAUTHENTICATED за відсутнього або невірного токена (невірний токен відхиляється навіть на публічних маршрутах), FORBIDDEN для ключа або гостьового токена, який не може викликати маршрут, і FEATURE_DISABLED для маршруту, який вимкнено.
Денний ліміт без облікового запису
Гостьова сесія має денний ліміт обчислень. Завантаження та запущені перевірки коштують більше за просте читання, а відкриття багатьох гостьових сесій з однієї мережевої адреси також рахується. Перевірка, яку сайт запускає сам для нового вибору, списується на той самий ліміт. Коли його вичерпано, Ви отримуєте ANONYMOUS_BUDGET_SPENT із датою його скидання. Користувачі, які увійшли, так не рахуються.
Від розрахунку вартості до замовлення
Замовлення розміщується зі збереженого розрахунку вартості, який належить обліковому запису. Гостьовий токен відхиляється на маршрутах замовлення. Програма працює на обліковий запис одним із двох способів, обидва описано на сторінці Для розробників та асистентів:
- Ключ API. Людина створює його у своєму обліковому записі в розділі Ключі API та вибирає, що він може робити. Надсилайте його як
Authorization: Bearer ulk_…. Розрахунок вартості, створений ключем, належить обліковому запису. Тестовий ключ (ulk_test_…) працює лише на прикладах даних. - Вхід для програм. Асистент реєструється сам, людина бачить на сторінці сайту, що він просить робити, і натискає Дозволити, а асистент отримує токен, обмежений цими дозволами.
Прочитайте збережені адреси викликом GET /v1/addresses. Адреса додається або змінюється людиною в браузері. Адреса відправлення має бути в destinationCountry розрахунку вартості.
Розмістіть замовлення викликом POST /v1/orders. Маршрутові потрібен заголовок Idempotency-Key: один новий ключ із 8–80 видимих символів на намічене замовлення та той самий ключ знову при повторі:
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 — це totalMinor розрахунку вартості, із яким людина погодилася. Поле termsVersion називає версію умов продажу, які людина прийняла. Поле dangerousGoods каже, чи містить відправлення батареї або інші небезпечні товари.
Цим викликом нічого не розміщується. Відповідь — APPROVAL_REQUIRED (422) із полем details.approvalUrl, однаково для ключа API та для токена асистента, який увійшов. Дайте це посилання людині. Вона відкриває його, входить, бачить замовлення та разом і схвалює або відхиляє. Посилання працює один раз, спливає через 24 години та перестає працювати, якщо зміниться розрахунок вартості або разом.
Після схвалення замовлення існує: перераховуйте замовлення облікового запису викликом GET /v1/orders та читайте одне викликом GET /v1/orders/{orderId}. Воно несе поле order.number, номер проформи в полі proFormaNumber, рахунок для оплати в полі sellerBank і, у полі payments, поле bankReference, яке треба вказати в переказі.
Оплата — банківським переказом, який робить людина. Жоден ключ і жоден асистент не може заплатити. Відстежуйте замовлення викликом GET /v1/orders/{orderId}. Інженер підтверджує кожне замовлення до виробництва.
| Код | Статус | Що це означає | Що робити |
|---|---|---|---|
APPROVAL_REQUIRED |
422 | Людина, яка увійшла, має спочатку схвалити. Поле details.approvalUrl — сторінка. |
Дайте посилання людині. Не шукайте обходу. |
TOTAL_MISMATCH |
422 | Поле expectedTotalMinor — не разом розрахунку вартості. Поле details.totalMinor — разом. |
Прочитайте розрахунок вартості знову та покажіть людині ціну, перш ніж питати знову. |
QUOTE_EXPIRED |
410 | Термін дії розрахунку вартості минув. | Перегляньте розрахунок вартості для нової ціни та покажіть його людині. |
CONFLICT |
409 | Поле details.reason — quote_ordered або quote_not_priced (інженер має спочатку дати ціну). |
Не повторюйте. Скажіть людині. |
INTAKE_CLOSED |
503 | Замовлення зараз не приймаються. Поле details.reopensOn — дата, коли вона є. |
Зупиніться. Скажіть людині. |
Ту саму службу пропонують асистентам як іменовані інструменти через сервер MCP: див. статтю Що таке MCP і як замовляють агенти.