Cómo usar la API de PrintStash para automatizar

PrintStash expone la misma API REST que usa su interfaz web. En una instalación Docker por defecto llegas a ella por el origen del frontend, en http://localhost:3000/api/v1, porque el servicio api solo expone el puerto 8000 en la red interna de Compose y el nginx del frontend hace de proxy de /api/v1 hacia él. La documentación interactiva de Swagger en /docs no pasa por el proxy, así que verla implica publicar tú mismo el puerto de la API desde un docker-compose.override.yml; la referencia de la API tiene ese fragmento.

Usa una clave de API para los scripts. La clave es una credencial de inicio de sesión, no un token Bearer permanente. Cámbiala por un token de acceso de corta vida antes de llamar a endpoints protegidos.

Consigue una clave de API

Abre Ajustes -> Usuarios y acceso, crea una clave de API con nombre y cópiala cuando aparezca. PrintStash muestra la clave completa una sola vez. Un nombre como nas scan o backup job facilita la limpieza más adelante.

Cambia el nombre de usuario y la clave de API en el endpoint de login:

curl -s -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"automation","api_key":"<api-key>"}'

Copia el access_token devuelto y mándalo como token Bearer:

TOKEN="<access-token>"
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/api/v1/models

El token lleva los permisos de la cuenta dueña de la clave. Usa una cuenta aparte sin permisos de administración cuando la automatización no los necesite. Revoca las claves viejas desde la misma página de ajustes.

Sube un modelo de origen

Las mallas de origen usan el endpoint de ingesta. El procesado es asíncrono, así que la respuesta trae un identificador de trabajo en lugar de un modelo terminado:

curl -X POST http://localhost:3000/api/v1/ingest/model \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@bracket.stl" \
  -F "model_name=Voron panel bracket" \
  -F "tags=voron,abs"

Consulta GET /api/v1/ingest/jobs/{job_id} si el script necesita esperar a que terminen el hash, el análisis, la generación de miniaturas y la deduplicación.

Sube G-code de OrcaSlicer

El endpoint de OrcaSlicer acepta G-code más el contexto opcional de modelo y colección:

curl -X POST http://localhost:3000/api/v1/ingest/orca \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@bracket.gcode" \
  -F "model_name=Voron panel bracket" \
  -F "collection=Functional/Brackets"

PrintStash ya trae un hook de posprocesado de OrcaSlicer para este trabajo. Usa la API directamente cuando necesites otra lógica de nombres, etiquetado o planificación.

Lanza un escaneo de un volumen compartido

Las carpetas compartidas se exponen como bibliotecas en la API. Arranca un escaneo con el identificador de la biblioteca:

curl -X POST http://localhost:3000/api/v1/libraries/12/scan \
  -H "Authorization: Bearer $TOKEN"

La respuesta también devuelve un identificador de trabajo. PrintStash puede planificar escaneos por su cuenta, así que un disparo externo es más útil justo después de que termine un trabajo aparte de descarga o sincronización.

Consulta antes de construir un informe

GET /api/v1/models admite búsqueda, filtrado y paginación. Los parámetros exactos de consulta pueden cambiar a medida que mejoran los filtros de la biblioteca, así que usa la página de Swagger de tu versión en ejecución como contrato en lugar de copiar una URL vieja de una entrada de blog.

Ese endpoint es suficiente para un panel personal o un informe de inventario. Endpoints relacionados exponen colecciones, etiquetas, estado de impresoras, perfiles de filamento, copias de seguridad e información de salud.

Que el primer script sea pequeño

Empieza con una tarea repetible: subir la salida de otra herramienta, escanear una carpeta del NAS después de una sincronización o exportar los metadatos de los modelos. Confirma que el script maneja un token caducado y una respuesta que no sea 2xx antes de meterlo en cron.

No incrustes la contraseña de una cuenta en un hook. Guarda la clave de API como secreto, pide un token de acceso nuevo cuando el trabajo se ejecute y mantén los permisos de la cuenta de automatización tan estrechos como permita la tarea.

La guía de automatización de copias de seguridad en S3 aplica este flujo de login a un endpoint solo para superusuarios. Para las subidas automáticas desde el slicer, la guía de revisiones de G-code explica dónde encaja el archivo subido en el historial del modelo.