Los pedidos se abrirán pronto. Mientras tanto, escriba a support@uliketechnology.com y un ingeniero le responde.

Todas las guías

Asistentes de AI

Guía rápida de la API: subir, verificar, cotizar

Las llamadas que llevan un archivo al informe de verificación, a un precio y a un pedido, con curl y el cliente JavaScript, y los errores que encontrará.

Para asistentes de AIActualizado el 2026-11-178 min de lecturaMarkdown sin procesar para asistentes de AI

La API y el servidor MCP que se describen aquí se abrirán junto con los pedidos.

Antes de empezar

La subida, la verificación de archivos y la cotización funcionan sin una cuenta, mediante una sesión de invitado. Un pedido necesita una cuenta: consulte «De una cotización a un pedido» más abajo. La API está en la dirección propia del sitio bajo /api. Defínala una vez:

API=https://uliketechnology.com/api
F=board.zip

board.zip es un zip plano con sus archivos Gerber y de taladrado. Para saber qué contiene, consulte Archivos para fabricación y montaje. Los ejemplos necesitan curl y jq.

Toda solicitud a la API después de la sesión de invitado lleva Authorization: Bearer <token>. Una clave API va en la misma cabecera en lugar del token de invitado. Todo error tiene la misma forma:

{ "error": { "code": "VALIDATION_FAILED", "message": "…", "details": {}, "requestId": "…" } }

Decida según code. El message es para desarrolladores.

Cinco imágenes pequeñas en orden: una llave, un archivo que va a una dirección de subida, un reloj de arena, una página de informe con observaciones y una etiqueta de precio
  1. Sesión de invitado: el token se muestra una vez.
  2. Subida: envíe el zip con PUT a la dirección que indique la API, con las cabeceras que indique.
  3. Finalización, luego consulte hasta que el análisis termine.
  4. El informe: observaciones, qué comprobaciones se realizaron y cuáles no.
  5. La vista previa de cotización.

El flujo con curl

Lea lo que se puede pedir. Esto no necesita token:

curl -s $API/v1/capabilities | jq '.options[].id'

Abra una sesión de invitado. El token se muestra una vez y dura 30 días:

T=$(curl -s -X POST $API/v1/guest-sessions | jq -r .token)

Anuncie el archivo. La respuesta contiene uploadId, designId, uploadUrl y 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\"}")

Envíe el archivo a la dirección que indique la respuesta, con cada cabecera de requiredHeaders (tipo de contenido, longitud y suma de comprobación; sin ellas la subida se rechaza con 403). Después complete la subida:

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

Al principio, el estado es analysing. Lea el diseño hasta que cambie. Cuando sea ready, el informe está en la respuesta:

D=$(echo $J | jq -r .designId)
curl -s $API/v1/designs/$D -H "authorization: Bearer $T" | jq '.design.status, .report.headline, .report.counts'

El titular es no_problems_in_checks_run, problems_found o could_not_check. Lea también checksRun y checksNotRun: una comprobación que no se realizó no es una aprobación. Los demás estados son needs_mapping (defina las capas con PUT /v1/designs/{designId}/layer-mapping), needs_engineer y rejected.

Pida una vista previa de cotización. selection y destinationCountry son obligatorios; un selection vacío toma los valores por defecto:

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 es instant (el precio se mantiene tal como se muestra) o review (un ingeniero lo confirma); reviewReasons indica por qué. totalMinor está en unidades menores de la currency de la respuesta, y está ausente cuando un ingeniero debe poner precio al trabajo. Para guardar una cotización, POST /v1/quotes acepta el mismo cuerpo.

El mismo flujo con el cliente JavaScript

El cliente @ulike/sdk envuelve estas rutas. Es el cliente de nuestro propio sitio y no es un paquete público; esta es su forma, para que usted pueda escribir las mismas llamadas con fetch. Nombres de 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 los demás métodos están createUpload, completeUpload, getDesign, setLayerMapping, validateDesign, getValidation, waitForValidation, createQuote, getQuote, reviseQuote, listAddresses, placeOrder, getOrder, listOrders y cancelOrder. Los errores se lanzan como ApiClientError con un status y un code.

La verificación para un pedido

El informe que obtiene tras la subida se elabora solo con los archivos. Para verificar los archivos frente a un pedido, llame a POST /v1/designs/{designId}/validations (validateDesign) con order que contenga quantities y selection. La respuesta es un estado: running, failed o done. Mientras sea running, lea GET /v1/validations/{reportId} (getValidation) cada segundo o dos hasta que sea done.

Un bucle de tres pasos: subir los archivos, leer el informe, corregir y subir de nuevo; una flecha sale del bucle hacia una marca de verificación cuando los archivos están limpios
  1. Suba el zip.
  2. Lea el informe.
  3. Corrija y suba como un diseño nuevo. Deténgase y pregunte a la persona cuando una corrección cambie la función, el precio o el plazo de entrega.
  4. Archivos limpios: ejecute la verificación para el pedido.

Una cotización o vista previa con opciones que traen otros límites (cobre más grueso, otro espesor) necesita una verificación para esa selección. Si no existe ninguna, se inicia una, y la vista previa lleva el motivo de revisión file_check_pending y un check con su reportId. El precio se muestra de inmediato, pero la cotización permanece en review hasta que esa verificación termina. Lea la verificación como se indicó arriba y después pida de nuevo la vista previa.

Errores que encontrará

Código Estado Qué significa Qué hacer
DESIGN_NOT_READY 422 El diseño aún se está leyendo (details.status indica qué estado), o aún no tiene informe. Lea el diseño hasta que el estado no sea analysing, y después vuelva a pedirlo.
VALIDATION_FAILED 400 La solicitud no tiene la forma esperada, o nombra una opción o un valor que el catálogo no tiene. details enumera las cuestiones o problemas. Corrija el campo nombrado en details y envíe de nuevo. Tome los identificadores y valores de opciones de GET /v1/capabilities.
NOT_MANUFACTURABLE 422 La selección es algo que no fabricamos. details.because trae los motivos. Cambie la selección; no reintente la misma. Pregunte a la persona si el cambio alteraría la placa.
ANONYMOUS_BUDGET_SPENT 429 La cuota diaria sin una cuenta se ha agotado. details.resetsOn es la fecha. Deténgase. Dígale a la persona; puede iniciar sesión o esperar hasta esa fecha.
REVISION_CONFLICT 409 Una revisión nombró una base que ya no es la cabeza de la cotización. details trae ambas cabezas. Lea la cabeza con GET /v1/quotes/{quoteId}, vuelva a aplicar su cambio sobre ella y envíe de nuevo.

También son posibles DESIGN_REJECTED (la subida fue rechazada; consulte details.reason), UNAUTHENTICATED por un token ausente o incorrecto (un token incorrecto se rechaza incluso en rutas públicas), FORBIDDEN para una clave o un token de invitado que no puede llamar a la ruta, y FEATURE_DISABLED para una ruta desactivada.

La cuota diaria sin una cuenta

Una sesión de invitado tiene una cuota diaria de cómputo. Las subidas y las verificaciones iniciadas cuestan más que una lectura simple, y abrir muchas sesiones de invitado desde una misma dirección de red también cuenta. Una verificación que el sitio inicia por su cuenta para una selección nueva se carga a la misma cuota. Cuando se agota, usted recibe ANONYMOUS_BUDGET_SPENT con la fecha en que se restablece. Quienes han iniciado sesión no se cuentan de este modo.

De una cotización a un pedido

Un pedido se realiza a partir de una cotización guardada que pertenece a una cuenta. Un token de invitado se rechaza en las rutas de pedido. Un programa trabaja para una cuenta de una de dos formas, ambas descritas en Para desarrolladores y asistentes:

  • Una clave API. La persona la crea en su cuenta en Claves API y elige qué puede hacer. Envíela como Authorization: Bearer ulk_…. Una cotización creada con la clave pertenece a la cuenta. Una clave de prueba (ulk_test_…) solo funciona con datos de ejemplo.
  • Inicio de sesión para programas. Un asistente se registra a sí mismo, la persona ve qué solicita hacer en una página del sitio y pulsa Permitir, y el asistente recibe un token limitado a esos permisos.

Lea las direcciones guardadas con GET /v1/addresses. La persona añade o cambia una dirección en el navegador. La dirección de envío debe estar en el destinationCountry de la cotización.

Realice el pedido con POST /v1/orders. La ruta necesita una cabecera Idempotency-Key: una clave nueva de 8 a 80 caracteres visibles por pedido previsto, y la misma clave de nuevo cuando reintente:

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 es el totalMinor de la cotización que la persona aceptó. termsVersion indica la versión de las condiciones de venta que la persona aceptó. dangerousGoods indica si el envío contiene baterías u otras mercancías peligrosas.

Con esta llamada no se realiza nada. La respuesta es APPROVAL_REQUIRED (422) con details.approvalUrl, tanto para una clave API como para el token de un asistente que inició sesión. Entregue ese enlace a la persona. Ella lo abre, inicia sesión, ve el pedido y el total, y aprueba o rechaza. El enlace funciona una vez, caduca a las 24 horas y deja de funcionar si la cotización o el total cambian.

Después de la aprobación el pedido existe: enumere los pedidos de la cuenta con GET /v1/orders y lea uno con GET /v1/orders/{orderId}. Lleva order.number, el número de factura proforma en proFormaNumber, la cuenta a la que pagar en sellerBank y, en payments, el bankReference que debe escribir en la transferencia.

El pago es por transferencia bancaria, realizado por la persona. Ninguna clave y ningún asistente pueden pagar. Siga el pedido con GET /v1/orders/{orderId}. Un ingeniero confirma cada pedido antes de la producción.

Código Estado Qué significa Qué hacer
APPROVAL_REQUIRED 422 Una persona que inició sesión tiene que aprobar primero. details.approvalUrl es la página. Entregue el enlace a la persona. No busque una forma de rodearlo.
TOTAL_MISMATCH 422 expectedTotalMinor no es el total de la cotización. details.totalMinor es el total. Lea de nuevo la cotización y muestre el precio a la persona antes de volver a pedirlo.
QUOTE_EXPIRED 410 La cotización superó su validez. Revise la cotización para un precio nuevo y muéstrelo a la persona.
CONFLICT 409 details.reason es quote_ordered o quote_not_priced (un ingeniero tiene que dar un precio primero). No reintente. Dígaselo a la persona.
INTAKE_CLOSED 503 No se aceptan pedidos en este momento. details.reopensOn es la fecha, cuando hay una. Deténgase. Dígaselo a la persona.

El mismo servicio se ofrece a los asistentes como herramientas con nombre a través de un servidor MCP: consulte Qué es MCP y cómo piden los agentes.