API

Invia un file e una configurazione e ti restituiamo subito il prezzo: stampa 3D e taglio laser dell’acrilico. È lo stesso motore che calcola i prezzi sul sito, quindi se hai tariffe concordate vengono applicate automaticamente.

Inizia

Ti servono un account e una chiave. La chiave si crea da Account → Chiavi API e viene mostrata una sola volta: non la salviamo in chiaro, quindi se la perdi devi revocarla e crearne un’altra.

Tutto passa tramite HTTPS e risponde in JSON. Le richieste con corpo lo prevedono in JSON e con Content-Type: application/json; quelle con file, in multipart.

Per verificare che la chiave funzioni va bene qualsiasi endpoint:

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

Calcola preventivo

Calcolare un preventivo è gratuito e non crea nulla: né un preventivo salvato, né un carrello, né un ordine. Puoi chiamare l’endpoint in ciclo mentre regoli le misure.

Con un file

POST/api/v1/quotes/file

La via più breve: carichi il pezzo e lo misuriamo noi. Vale sia per la stampa 3D sia per il taglio laser; il processo viene dedotto dall’estensione.

Stampa 3D — un STL, un 3MF, un 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"}'

Taglio laser — un SVG o un DXF. Le misure vengono ricavate direttamente dal disegno:

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"}'

La risposta include ciò che abbiamo misurato, oltre al prezzo:

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"
    }
  }
}

Del file non salviamo nulla. Viene misurato in memoria e poi scartato. Se non sappiamo aprire il formato —per esempio SolidWorks o Illustrator— la risposta è 200 con «manualReview» impostato su true e il motivo: in quel caso il preventivo lo fa una persona.

Con la geometria già misurata

POST/api/v1/quotes

Se hai già il volume e il bounding box del pezzo —perché li misuri tu o li hai salvati da un preventivo precedente— puoi evitare di caricare il file.

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"
    }
  }'

Un 200 non significa sempre sì. Quando il pezzo non può essere prodotto —quella lastra non è più disponibile, la misura non entra nella macchina— la risposta resta 200 con «ok» impostato su false e il motivo in «errors». È una risposta, non un errore: riprovare darebbe esattamente lo stesso risultato. Controlla sempre «ok».

Taglio laser, tutti i campi

Senza file puoi richiedere qualsiasi forma del catalogo. Questo esempio contiene tutto ciò che l’endpoint accetta, con i valori predefiniti visibili; quasi nulla è obbligatorio.

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."
    }
  }'

Sono obbligatori solo questi: sheetId, shape, widthMm, heightMm, quantity, leadTimeId

shapeId: "texto" — taglia il testo come contorno del pezzo, con il font e l’altezza che indichi.

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"
    }
  }'

Stampa 3D, tutti i campi

Lo stesso per FDM: l’esempio completo, con anche le opzioni facoltative.

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."}'

Opzioni

Gli identificatori accettati da «materialId», «sheetId» e simili. Questa lista proviene dallo stesso catalogo usato dall’officina e cambia quando cambia il catalogo: non copiarla, richiedila.

Tutto quello che segue, con una sola chiamata e sempre aggiornato:

GET/api/v1/catalog

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

E oggi è così:

Materiali (stampa 3D)

Identificatore	Nome	Dettaglio
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

Ogni materiale include i propri colori in «colors». L’id del colore va in «colorId».

Qualità

Identificatore	Nome	Dettaglio
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

Riempimenti

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

Lastre di acrilico (taglio laser)

Identificatore	Nome	Dettaglio
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

Forme del catalogo

Identificatore	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» sceglie la forma e «shapeParams» le passa le relative misure, che cambiano per ogni forma. Con un file o con un rettangolo su misura non serve nessuno dei due.

Schemi di fori

Identificatore	Nome	Dettaglio
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	—

Tempi

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

Formati di file

Formati che accettiamo e cosa facciamo con ciascuno:

Identificatore	Proceso	Dettaglio
.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.

Ordini

GET/api/v1/orders

Gli ultimi cinquanta, dal più recente al più vecchio, con stato e tracciamento.

GET/api/v1/orders/{code}

Uno specifico, con le sue righe e i relativi importi.

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 }
    ]
  }
}

Gli stati possibili sono: AWAITING_PAYMENT, PAID, IN_PRODUCTION, QUALITY_CHECK, READY_FOR_PICKUP, SHIPPED, DELIVERED, CANCELLED, REFUNDED

Limite di richieste

60 richieste al minuto per chiave. Ogni risposta indica quante te ne restano, quindi non devi raggiungere il limite per sapere dov’è:

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

Se lo superi, ricevi un 429 con «Retry-After» in secondi. Non è una punizione: calcolare un preventivo costruisce la geometria del pezzo e consulta il magazzino, e un ciclo non chiuso correttamente può lasciare gli altri senza servizio.

Quando qualcosa va storto

Sempre un JSON con «code» —stabile, così puoi usarlo per decidere— e «error», che è il messaggio da leggere.

401 unauthorized — la chiave manca, è errata o è stata revocata.
404 not_found — quell’ordine non è tuo. Rispondiamo allo stesso modo anche se non esiste: altrimenti si potrebbero scoprire quali codici esistono.
422 invalid_request — la configurazione non è valida. Include «details» campo per campo.
429 rate_limited — hai superato il limite.

Per assistenti e agenti

Se stai integrando questa API in un assistente: con la chiave del cliente e un file puoi ottenere il preventivo in una sola chiamata, senza passaggi preliminari e senza dover prima caricare nulla altrove.

È disponibile una descrizione leggibile dalla macchina in due formati:

/openapi.json — il contratto completo, per generare un client o caricarlo come strumento.
/llms.txt — un breve riepilogo in testo semplice, da inserire nel contesto.

Quello che ancora non si può fare

Chiudere un ordine. Il preventivo sì, l’acquisto no. Prima bisogna concordare come si paga —a fattura, a credito— e questa è una conversazione, non un endpoint. Se ti interessa, scrivici e ne parliamo: manca davvero poco.

Ti manca qualcosa o qualcosa non risponde come descritto qui? Diccelo. Ti risponde chi l’ha scritto.