Antes de começar
O upload, a verificação de arquivos e o orçamento funcionam sem conta por meio de uma sessão de convidado. Um pedido precisa de uma conta: veja “De um orçamento a um pedido” abaixo. A API fica no endereço do próprio site sob /api. Defina-o uma vez:
API=https://uliketechnology.com/api
F=board.zip
board.zip é um zip simples com os seus arquivos Gerber e de furação. Sobre o que entra nele, veja Arquivos para fabricação e montagem. Os exemplos precisam de curl e jq.
Toda solicitação à API depois da sessão de convidado leva Authorization: Bearer <token>. Uma chave de API vai no mesmo cabeçalho no lugar do token de convidado. Todo erro tem a mesma forma:
{ "error": { "code": "VALIDATION_FAILED", "message": "…", "details": {}, "requestId": "…" } }
Ramifique pelo code. A message é para desenvolvedores.
- Sessão de convidado: o token é exibido uma vez.
- Upload: envie o zip com
PUTpara o endereço que a API indicar, com os cabeçalhos que ela indicar. - Conclua, depois consulte até a análise terminar.
- O relatório: apontamentos, quais verificações foram realizadas e quais não foram.
- A prévia de orçamento.
O fluxo com curl
Leia o que pode ser pedido. Isso não precisa de token:
curl -s $API/v1/capabilities | jq '.options[].id'
Abra uma sessão de convidado. O token é exibido uma vez e dura 30 dias:
T=$(curl -s -X POST $API/v1/guest-sessions | jq -r .token)
Anuncie o arquivo. A resposta tem uploadId, designId, uploadUrl e 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\"}")
Envie o arquivo para o endereço que a resposta indicar, com todos os cabeçalhos em requiredHeaders (tipo de conteúdo, comprimento e checksum; sem eles o upload é recusado com 403). Depois conclua o 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
O status é analysing no início. Leia o projeto até ele mudar. Quando for ready, o relatório está na resposta:
D=$(echo $J | jq -r .designId)
curl -s $API/v1/designs/$D -H "authorization: Bearer $T" | jq '.design.status, .report.headline, .report.counts'
O título é no_problems_in_checks_run, problems_found ou could_not_check. Leia também checksRun e checksNotRun: uma verificação que não foi realizada não é uma aprovação. Os outros status são needs_mapping (defina as camadas com PUT /v1/designs/{designId}/layer-mapping), needs_engineer e rejected.
Peça uma prévia de preço. selection e destinationCountry são obrigatórios; um selection vazio usa os padrões:
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 (o preço vale como exibido) ou review (um engenheiro o confirma); reviewReasons diz o motivo. totalMinor está em unidades menores da currency da resposta e fica ausente quando um engenheiro precisa precificar o trabalho. Para salvar um orçamento, POST /v1/quotes recebe o mesmo corpo.
O mesmo fluxo com o cliente JavaScript
O cliente @ulike/sdk envolve essas rotas. Ele é o cliente do nosso próprio site e não é um pacote público; esta é a sua forma, para que você possa escrever as mesmas chamadas com fetch. Nomes dos métodos:
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',
});
Entre os outros métodos estão createUpload, completeUpload, getDesign, setLayerMapping, validateDesign, getValidation, waitForValidation, createQuote, getQuote, reviseQuote, listAddresses, placeOrder, getOrder, listOrders e cancelOrder. Os erros são lançados como ApiClientError com um status e um code.
A verificação para um pedido
O relatório que você recebe após o upload é feito apenas com os arquivos. Para verificar os arquivos em relação a um pedido, chame POST /v1/designs/{designId}/validations (validateDesign) com order contendo quantities e selection. A resposta é um estado: running, failed ou done. Enquanto for running, leia GET /v1/validations/{reportId} (getValidation) a cada um ou dois segundos até ser done.
- Faça upload do zip.
- Leia o relatório.
- Corrija e faça upload como um novo projeto. Pare e pergunte à pessoa quando uma correção alterar a função, o preço ou o prazo de entrega.
- Arquivos limpos: execute a verificação para o pedido.
Um orçamento ou prévia com opções que trazem outros limites (cobre mais espesso, outra espessura) precisa de uma verificação para essa seleção. Se nenhuma existir, uma é iniciada, e a prévia traz o motivo de revisão file_check_pending e um check com seu reportId. O preço é exibido de imediato, mas o orçamento permanece em review até essa verificação terminar. Leia a verificação como acima e depois peça a prévia novamente.
Erros que você encontrará
| Code | Status | O que significa | O que fazer |
|---|---|---|---|
DESIGN_NOT_READY |
422 | O projeto ainda está sendo lido (details.status diz em qual estado), ou ainda não tem relatório. |
Leia o projeto até o status não ser analysing, depois peça novamente. |
VALIDATION_FAILED |
400 | A solicitação não tem a forma esperada, ou indica uma opção ou valor que o catálogo não tem. details lista as questões ou problemas. |
Corrija o campo indicado em details e envie novamente. Use ids e valores de opção de GET /v1/capabilities. |
NOT_MANUFACTURABLE |
422 | A seleção é algo que não fabricamos. details.because traz os motivos. |
Altere a seleção; não tente a mesma novamente. Pergunte à pessoa se a alteração mudaria a placa. |
ANONYMOUS_BUDGET_SPENT |
429 | A cota diária sem conta acabou. details.resetsOn é a data. |
Pare. Avise a pessoa; ela pode entrar ou esperar até essa data. |
REVISION_CONFLICT |
409 | Uma revisão indicou uma base que não é mais o head do orçamento. details traz os dois heads. |
Leia o head com GET /v1/quotes/{quoteId}, reaplique a sua alteração nele e envie novamente. |
Também são possíveis DESIGN_REJECTED (o upload foi recusado; veja details.reason), UNAUTHENTICATED para um token ausente ou incorreto (um token incorreto é recusado mesmo em rotas públicas), FORBIDDEN para uma chave ou um token de convidado que não pode chamar a rota e FEATURE_DISABLED para uma rota desativada.
A cota diária sem conta
Uma sessão de convidado tem uma cota diária de computação. Uploads e verificações iniciadas custam mais do que uma leitura simples, e abrir muitas sessões de convidado a partir de um mesmo endereço de rede também é contado. Uma verificação que o site inicia por conta própria para uma nova seleção é cobrada da mesma cota. Quando ela acaba, você recebe ANONYMOUS_BUDGET_SPENT com a data em que ela é reposta. Quem entrou com conta não é contado dessa forma.
De um orçamento a um pedido
Um pedido é feito a partir de um orçamento salvo que pertence a uma conta. Um token de convidado é recusado nas rotas de pedido. Um programa trabalha para uma conta de uma de duas formas, ambas descritas em Para desenvolvedores e assistentes:
- Uma chave de API. A pessoa a cria na conta dela em Chaves de API e escolhe o que ela pode fazer. Envie-a como
Authorization: Bearer ulk_…. Um orçamento criado com a chave pertence à conta. Uma chave de teste (ulk_test_…) só funciona com dados de exemplo. - Entrada para programas. Um assistente se registra, a pessoa vê o que ele solicita fazer em uma página do site e pressiona Permitir, e o assistente recebe um token limitado a essas permissões.
Leia os endereços salvos com GET /v1/addresses. Um endereço é acrescentado ou alterado pela pessoa no navegador. O endereço de envio precisa estar no destinationCountry do orçamento.
Faça o pedido com POST /v1/orders. A rota precisa de um cabeçalho Idempotency-Key: uma chave nova de 8 a 80 caracteres visíveis por pedido pretendido, e a mesma chave novamente quando você tentar de novo:
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 é o totalMinor do orçamento que a pessoa aceitou. termsVersion indica a versão dos termos de venda que a pessoa aceitou. dangerousGoods indica se o envio contém baterias ou outras mercadorias perigosas.
Nada é feito com esta chamada. A resposta é APPROVAL_REQUIRED (422) com details.approvalUrl, tanto para uma chave de API quanto para o token de um assistente que entrou. Entregue esse link à pessoa. Ela o abre, entra, vê o pedido e o total, e aprova ou recusa. O link funciona uma vez, expira após 24 horas e para de funcionar se o orçamento ou o total mudar.
Após a aprovação, o pedido existe: liste os pedidos da conta com GET /v1/orders e leia um com GET /v1/orders/{orderId}. Ele traz order.number, o número da fatura proforma em proFormaNumber, a conta para pagar em sellerBank e, em payments, o bankReference para escrever na transferência.
O pagamento é por transferência bancária, feito pela pessoa. Nenhuma chave e nenhum assistente podem pagar. Acompanhe o pedido com GET /v1/orders/{orderId}. Um engenheiro confirma cada pedido antes da produção.
| Code | Status | O que significa | O que fazer |
|---|---|---|---|
APPROVAL_REQUIRED |
422 | Uma pessoa que entrou precisa aprovar primeiro. details.approvalUrl é a página. |
Entregue o link à pessoa. Não procure uma forma de contornar isso. |
TOTAL_MISMATCH |
422 | expectedTotalMinor não é o total do orçamento. details.totalMinor é o total. |
Leia o orçamento novamente e mostre o preço à pessoa antes de pedir novamente. |
QUOTE_EXPIRED |
410 | O orçamento passou da validade. | Revise o orçamento para um preço novo e mostre-o à pessoa. |
CONFLICT |
409 | details.reason é quote_ordered ou quote_not_priced (um engenheiro precisa dar um preço primeiro). |
Não tente novamente. Avise a pessoa. |
INTAKE_CLOSED |
503 | Nenhum pedido é aceito no momento. details.reopensOn é a data, quando há uma. |
Pare. Avise a pessoa. |
O mesmo serviço é oferecido a assistentes como ferramentas nomeadas por meio de um servidor MCP: veja O que é o MCP e como os agentes pedem.