Прежде чем Вы начнёте
Загрузка, проверка файлов и расчёт стоимости работают без аккаунта, через гостевую сессию. Для заказа нужен аккаунт: см. «От расчёта стоимости к заказу» ниже. 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 и как заказывают агенты.