API

Envia um ficheiro e uma configuração e devolvemos-te o preço de imediato: impressão 3D e corte a laser de acrílico. É o mesmo motor que calcula os preços no site, por isso, se tiveres tarifas acordadas, são aplicadas.

Começar

Precisas de uma conta e de uma chave. A chave é criada em Conta → Chaves de API e só é mostrada uma vez: não a guardamos em claro, por isso, se a perderes, tens de a revogar e criar outra.

Tudo funciona por HTTPS e responde em JSON. Os pedidos com corpo esperam-no em JSON e com Content-Type: application/json; os que levam ficheiro, em multipart.

Para verificar se a chave funciona, qualquer endpoint serve:

curl https://haztupieza.es/api/v1/orders \
  -H "Authorization: Bearer htp_TU_CLAVE"

Orçamentar

Orçamentar é grátis e não cria nada: nem orçamento guardado, nem carrinho, nem encomenda. Podes chamar o endpoint em ciclo enquanto ajustas as medidas.

Com um ficheiro

POST/api/v1/quotes/file

A forma rápida: carregas a peça e nós medimo-la. Serve para impressão 3D e para corte a laser; o processo é deduzido pela extensão.

Impressão 3D — um STL, um 3MF, um STEP:

curl https://haztupieza.es/api/v1/quotes/file \
  -H "Authorization: Bearer htp_TU_CLAVE" \
  -F "file=@soporte.stl" \
  -F 'config={"materialId":"pla","colorId":"negro","qualityId":"standard","infillId":"i25","quantity":4,"supports":true,"leadTimeId":"standard"}'

Corte a laser — um SVG ou um DXF. As medidas são obtidas a partir do próprio desenho:

curl https://haztupieza.es/api/v1/quotes/file \
  -H "Authorization: Bearer htp_TU_CLAVE" \
  -F "file=@tapa.svg" \
  -F 'config={"sheetId":"pmma-colada-incoloro-3","quantity":10,"leadTimeId":"standard"}'

A resposta inclui o que medimos, além do preço:

200 OK

{
  "ok": true,
  "errors": [],
  "total": 24.18,
  "breakdown": {
    "unitPrice": 6.045,
    "lines": [
      { "id": "material", "label": "Material", "amount": 4.12 },
      { "id": "machine", "label": "Máquina", "amount": 11.4 },
      { "id": "finishing", "label": "Acabados", "amount": 4.9 }
    ],
    "taxRate": 0.21,
    "leadTimeDays": 3
  },
  "file": {
    "name": "soporte.stl",
    "mesh": {
      "volumeCm3": 18.42,
      "surfaceCm2": 96.3,
      "boundingBoxMm": { "x": 62.4, "y": 41, "z": 18 },
      "triangles": 24680,
      "watertight": true,
      "hash": "9f2c1a7b"
    }
  }
}

Não guardamos nada do ficheiro. É medido em memória e descartado. Se não soubermos abrir o formato —um SolidWorks, um Illustrator— a resposta é 200 com «manualReview» a true e o motivo: nesse caso, o orçamento é feito por uma pessoa.

Com a geometria já medida

POST/api/v1/quotes

Se já tiveres o volume e a caixa da peça —porque a medes tu ou porque os guardaste de um orçamento anterior— podes evitar carregar o ficheiro.

curl https://haztupieza.es/api/v1/quotes \
  -H "Authorization: Bearer htp_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "process": "FDM_3D",
    "label": "soporte.stl",
    "config": {
      "materialId": "pla",
      "colorId": "negro",
      "qualityId": "standard",
      "infillId": "i25",
      "quantity": 4,
      "supports": true,
      "leadTimeId": "standard"
    },
    "mesh": {
      "volumeCm3": 18.42,
      "surfaceCm2": 96.3,
      "boundingBoxMm": {
        "x": 62.4,
        "y": 41,
        "z": 18
      },
      "triangles": 24680,
      "watertight": true,
      "hash": "9f2c1a7b"
    }
  }'

Um 200 nem sempre quer dizer que sim. Quando a peça não pode ser fabricada —essa placa já não é fornecida, a medida não cabe na máquina— a resposta continua a ser 200 com «ok» a false e o motivo em «errors». É uma resposta, não uma falha: voltar a tentar daria exatamente o mesmo resultado. Verifica sempre «ok».

Corte a laser, todos os campos

Sem ficheiro, podes pedir qualquer forma do catálogo. Este exemplo inclui absolutamente tudo o que o endpoint aceita, com os valores predefinidos visíveis; quase nada é obrigatório.

curl https://haztupieza.es/api/v1/quotes \
  -H "Authorization: Bearer htp_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "process": "LASER_ACRYLIC",
    "label": "frontal",
    "config": {
      "sheetId": "pmma-colada-incoloro-3",
      "shape": "ROUNDED_RECT",
      "shapeId": "rounded-rect",
      "shapeParams": {
        "w": 300,
        "h": 200,
        "radius": 12
      },
      "widthMm": 300,
      "heightMm": 200,
      "cornerRadiusMm": 12,
      "innerDiameterMm": 0,
      "quantity": 10,
      "cutouts": [
        {
          "id": "ventana",
          "shapeId": "circle",
          "params": {
            "d": 22
          },
          "xMm": 60,
          "yMm": 100,
          "rotationDeg": 0,
          "conservarPieza": true
        },
        {
          "id": "ranura",
          "shapeId": "stadium",
          "params": {
            "w": 40,
            "h": 8
          },
          "xMm": 240,
          "yMm": 100,
          "rotationDeg": 90
        },
        {
          "id": "rotulo",
          "shapeId": "texto",
          "params": {},
          "texto": {
            "texto": "SALIDA",
            "tipografiaId": "stardos-stencil",
            "alturaMm": 25
          },
          "xMm": 150,
          "yMm": 100,
          "rotationDeg": 0
        }
      ],
      "holes": {
        "pattern": "CORNERS",
        "diameterMm": 4,
        "edgeDistanceMm": 10,
        "count": 4,
        "edgeCounts": [
          2,
          2,
          2,
          2
        ],
        "rows": 0,
        "columns": 0,
        "centerDistanceMm": 0,
        "points": []
      },
      "engraveAreaCm2": 0,
      "leadTimeId": "express",
      "vectorPendingReview": false,
      "notes": "Cantos pulidos por la cara vista."
    }
  }'

Só estes são obrigatórios: sheetId, shape, widthMm, heightMm, quantity, leadTimeId

shapeId: "texto" — corta o texto como contorno da peça, com o tipo de letra e a altura que indicares.

curl https://haztupieza.es/api/v1/quotes \
  -H "Authorization: Bearer htp_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "process": "LASER_ACRYLIC",
    "config": {
      "sheetId": "pmma-colada-incoloro-3",
      "shape": "CUSTOM",
      "shapeId": "texto",
      "texto": {
        "texto": "ABIERTO",
        "tipografiaId": "anton",
        "alturaMm": 80
      },
      "widthMm": 400,
      "heightMm": 80,
      "quantity": 2,
      "leadTimeId": "standard"
    }
  }'

Impressão 3D, todos os campos

O mesmo para FDM: o exemplo longo, com os campos opcionais incluídos.

curl https://haztupieza.es/api/v1/quotes/file \
  -H "Authorization: Bearer htp_TU_CLAVE" \
  -F "file=@pieza.3mf" \
  -F 'config={"materialId":"pla","colorId":"negro","qualityId":"standard","infillId":"i25","quantity":4,"supports":true,"leadTimeId":"standard","finishIds":["sanding"],"extraColorIds":["rojo"],"plateId":"auto","nozzleId":"auto","pauses":[{"layer":40,"action":"Colocar 4 tuercas M3 en los alojamientos","inserts":[{"optionId":"tuerca-m3","quantity":4}]}],"notes":"La cara buena es la de arriba."}'

Opções

Os identificadores aceites por «materialId», «sheetId» e semelhantes. Esta lista vem do mesmo catálogo que a oficina usa e muda quando ele muda: não a copies, pede-a.

Tudo o que está abaixo, numa única chamada e sempre atualizado:

GET/api/v1/catalog

curl https://haztupieza.es/api/v1/catalog \
  -H "Authorization: Bearer htp_TU_CLAVE"

E hoje está assim:

Materiais (impressão 3D)

Identificador	Nome	Detalhe
pla	PLA	PLA · 15 colores
pla-alta-resistencia	PLA alta resistencia	PLA · 9 colores
pla-mate	PLA Mate	PLA · 3 colores
pla-reciclado	PLA Reciclado	PLA · 3 colores
pla-seda	PLA Silk	PLA · 7 colores
pla-madera	PLA Madera	PLA · 3 colores
pla-marmol	PLA Marmol	PLA · 2 colores
pla-glitter	PLA Glitter	PLA · 4 colores
pla-fluorescente	PLA Fluorescente (glow in the dark)	PLA · 2 colores
pla-metalizado	PLA Metalizado	PLA · 4 colores
petg	PETG	PETG · 7 colores
abs	ABS-E	ABS · 5 colores
asa	ASA	ASA · 4 colores
tpu-95a	TPU 95A Flex	TPU · 5 colores
nylon-pa	Nylon PA	PA · 2 colores
hips	HIPS	HIPS · 2 colores

Cada material inclui as suas cores em «colors». O id da cor vai em «colorId».

Qualidades

Identificador	Nome	Detalhe
draft	Borrador 0,28 mm	0.28 mm
standard	Estándar 0,20 mm	0.2 mm
fine	Fina 0,16 mm	0.16 mm
ultra	Ultrafina 0,12 mm	0.12 mm

Enchimentos

Identificador	Nome	Detalhe
i15	15 % ligero	15 %
i25	25 % estándar	25 %
i40	40 % resistente	40 %
i60	60 % robusto	60 %
i100	100 % macizo	100 %

Placas de acrílico (corte a laser)

Identificador	Nome	Detalhe
pmma-colada-incoloro-3	Metacrilato transparente 3 mm	3 mm · 1000×600 mm
pmma-colada-incoloro-5	Metacrilato transparente 5 mm	5 mm · 1000×600 mm
pmma-colada-incoloro-6	Metacrilato transparente 6 mm	6 mm · 1000×600 mm
pmma-colada-incoloro-8	Metacrilato transparente 8 mm	8 mm · 1000×600 mm
pmma-colada-incoloro-10	Metacrilato transparente 10 mm	10 mm · 1000×600 mm
pmma-extrusion-incoloro-3	Metacrilato extrusión transparente 3 mm	3 mm · 1000×600 mm
pmma-extrusion-incoloro-5	Metacrilato extrusión transparente 5 mm	5 mm · 1000×600 mm
pmma-blanco-3	Metacrilato opal 3 mm	3 mm · 1000×600 mm
pmma-negro-3	Metacrilato negro 3 mm	3 mm · 1000×600 mm
pmma-tintado-3-rojo	Metacrilato tintado rojo 3 mm	3 mm · 1000×600 mm
pmma-tintado-3-azul	Metacrilato tintado azul 3 mm	3 mm · 1000×600 mm
pmma-tintado-3-verde	Metacrilato tintado verde 3 mm	3 mm · 1000×600 mm
pmma-tintado-3-ambar	Metacrilato tintado ámbar 3 mm	3 mm · 1000×600 mm
pmma-tintado-3-fume	Metacrilato tintado fumé 3 mm	3 mm · 1000×600 mm
dm-3	DM 3 mm	3 mm · 800×400 mm
pmma-fluor-3-naranja	Metacrilato fluorescente naranja 3 mm	3 mm · 1000×600 mm
pmma-fluor-3-rojo	Metacrilato fluorescente rojo 3 mm	3 mm · 1000×600 mm
pmma-fluor-3-verde	Metacrilato fluorescente verde 3 mm	3 mm · 1000×600 mm

Formas do catálogo

Identificador	Nome	shapeParams
rect	Rectángulo	w, h
rect-bevel	Rectángulo achaflanado	w, h, bevel
rect-corner	Rectángulo con esquina cortada	w, h, cutW, cutH
rect-slant	Rectángulo con lado inclinado	w, hLeft, hRight
separador	Separador de estantería	w, h, frente
triangle	Triángulo	w, h
triangle-right	Triángulo rectángulo	w, h
triangle-right-mirror	Triángulo rectángulo invertido	w, h
trapezoid	Trapecio	wTop, wBottom, h
parallelogram	Paralelogramo	w, h, offset
hexagon	Hexágono	w, h
octagon	Octágono	w, h, bevel
polygon	Polígono regular	sides, d
rounded-rect	Rectángulo redondeado	w, h, radius
circle	Círculo	d
ring	Corona	d, inner
oval	Óvalo	w, h
stadium	Óvalo plano	w, h
semicircle	Semicírculo	d
quarter-circle	Cuarto de círculo	r
arch	Arco	w, h
barrel	Tonel	w, h, bulge
star	Estrella	points, d, inner
heart	Corazón	w, h
drop	Gota	w, h
arrow	Flecha	w, h, stem, head
kite	Cometa	w, h, cross
gem	Gema	w, h, crown, top

«shapeId» escolhe a forma e «shapeParams» passa-lhe as medidas, que são diferentes em cada uma. Com um ficheiro ou com um retângulo por medida, não precisas de nenhum dos dois.

Padrões de furos

Identificador	Nome	Detalhe
NONE	Sin agujeros	—
CORNERS	En las esquinas	diameterMm, edgeDistanceMm
PERIMETER	Repartidos por el borde	diameterMm, edgeDistanceMm, count o edgeCounts
RADIAL	En círculo	diameterMm, count, centerDistanceMm
GRID	En cuadrícula	diameterMm, rows, columns, centerDistanceMm
POINTS	En coordenadas concretas	diameterMm, points[{ xMm, yMm }]
CUSTOM	Los que traiga el archivo	—

Prazos

Identificador	Nome	Detalhe
standard	Estándar	3 días laborables
express	Exprés 48 h	2 días laborables
urgent	Urgente 24 h	1 días laborables

Formatos de ficheiro

Formatos que aceitamos e o que fazemos com cada um:

Identificador	Proceso	Detalhe
.stl .obj .3mf .ply	FDM_3D	Se miden solas. Precio al momento.
.step .stp .iges .igs .brep	FDM_3D	Se teselan en el servidor. Precio al momento.
.sldprt .ipt .f3d .3dm .sat .x_t	FDM_3D	CAD propietario: lo cotiza una persona.
.svg .dxf	LASER_ACRYLIC	Se miden solas. Precio al momento.
.ai	LASER_ACRYLIC	Lo cotiza una persona.

Encomendas

GET/api/v1/orders

As cinquenta mais recentes, da mais nova para a mais antiga, com o respetivo estado e seguimento.

GET/api/v1/orders/{code}

Uma encomenda específica, com as suas linhas e valores.

200 OK

{
  "order": {
    "code": "HTP-3MQ8N-LY45L",
    "status": "IN_PRODUCTION",
    "total": 43.05,
    "trackingCarrier": "MRW",
    "trackingNumber": "0123456789",
    "items": [
      { "label": "tapa.svg", "quantity": 10, "process": "LASER_ACRYLIC",
        "unitPrice": 3.55, "total": 35.5 }
    ]
  }
}

Os estados possíveis são: AWAITING_PAYMENT, PAID, IN_PRODUCTION, QUALITY_CHECK, READY_FOR_PICKUP, SHIPPED, DELIVERED, CANCELLED, REFUNDED

Limite de pedidos

60 pedidos por minuto e por chave. Cada resposta indica quantos te restam, por isso não precisas de atingir o limite para saber onde está:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 42

Se ultrapassares o limite, recebes um 429 com «Retry-After» em segundos. Não é um castigo: orçamentar monta a geometria da peça e consulta o armazém, e um ciclo mal fechado deixa os outros sem serviço.

Quando algo corre mal

Sempre um JSON com «code» —estável, para poderes decidir com base nele— e «error», que é a mensagem para ler.

401 unauthorized — a chave está em falta, está errada ou foi revogada.
404 not_found — essa encomenda não é tua. Respondemos da mesma forma se não existir: caso contrário, seria possível descobrir que códigos existem.
422 invalid_request — a configuração não é válida. Vem com «details» campo a campo.
429 rate_limited — ultrapassaste o limite.

Para assistentes e agentes

Se estiveres a integrar isto num assistente: com a chave do cliente e um ficheiro, o orçamento é feito numa única chamada, sem passos prévios e sem carregar nada para lado nenhum antes.

Há uma descrição legível por máquina em dois formatos:

/openapi.json — o contrato completo, para gerar um cliente ou carregá-lo como ferramenta.
/llms.txt — um resumo curto em texto simples, para colocar no contexto.

O que ainda não é possível

Fechar uma encomenda. Orçamentar sim, comprar não. Para isso, primeiro é preciso acordar como se paga —contra fatura, a crédito— e isso é uma conversa, não um endpoint. Se te interessar, escreve-nos e falamos: está quase pronto.

Falta-te alguma coisa ou algo não responde como está descrito aqui? Diz-nos. Responde quem escreveu isto.