Conceptos: archivos, presupuestos y trabajos

1. Autenticación y Seguridad

Todos los endpoints requieren autenticación con su token de API de Quote3D, con una excepción: la ruta pública de subida documentada en Gestión de archivos. Para llamadas externas, use la ruta base https://api.quote3d.com/v2. Envíe el token como Authorization: Bearer YOUR_TOKEN o como X-API-Token. Genere los tokens desde su panel de Quote3D y manténgalos en secreto.

Los tokens pueden tener alcances definidos. Un token de acceso total llega a todos los endpoints, mientras que un token con alcance de widget está restringido a los endpoints que el widget incrustado necesita. Cualquier llamada fuera del alcance de un token devolverá un error 403. Puede ver y cambiar el alcance de un token en la página de Tokens de su panel de control.

2. Gestión de Cuenta

Administre su cuenta, cargas y estadísticas de uso a través de endpoints dedicados:

• GET /v2/user Recupere los datos de su cuenta, su plan y sus cuotas mensuales: aquí se encuentran quotes_used, quotes_limit, storage_used, storage_limit y reset_date
• GET /v2/user/uploads Liste todos los archivos que ha subido a su cuenta. Estos se listan del más reciente al más antiguo.
• GET /v2/quota Recupere sus límites de frecuencia: el límite global más un desglose por endpoint con las llamadas restantes y los tiempos de reinicio, junto con sus recuentos de solicitudes de hoy, este mes, este año y de siempre
• GET /v2/usage Obtenga análisis de uso detallados incluyendo estadísticas de endpoints, uso de materiales y tendencias basadas en el tiempo
• GET /v2/config Las tecnologías activas de la cuenta, sus impresoras, sus materiales con sus colores (en stock o no) y sus valores de precio por defecto: todo lo que ofrece el widget. Los tokens de widget también pueden leerlo.

3. Gestión de archivos

Suba, descargue y gestione sus archivos de modelo 3D (formatos STL, 3MF, OBJ, STEP):

• GET /v2/file/upload-id — Obtenga un upload_id temporal para subir un nuevo archivo con la ruta de subida pública.
• POST /v2/file/public/{upload_id} — Esta ruta NO requiere autenticación. Utilícela en su lado del cliente para subir archivos directamente a nuestro almacenamiento.

  Utilizar la ruta de Subida Pública le permite evitar enrutar archivos grandes a través de su servidor backend. Esto previene exponer su token de API y reduce la carga del servidor.

• POST /v2/file — Suba un archivo desde su lado del servidor (requiere autenticación, utilice esto cuando quiera subir desde su backend)
• GET /v2/file/{file_id} — Descargue un archivo utilizando su file_id
• DELETE /v2/file/{file_id} — Elimine un archivo que ya no necesita

La subida se rechazará si el archivo no es un modelo STL, 3MF, OBJ o STEP válido, o si supera el límite de tamaño de archivo de la plataforma (50 MB por defecto). Los archivos STEP (.step/.stp) se teselan en el servidor con la misma configuración que usa OrcaSlicer (desviación lineal de 0,003 mm, desviación angular de 0,5 rad); todos los cuerpos de un ensamblaje se combinan y las longitudes se convierten a milímetros. Ambas rutas de subida aplican las mismas comprobaciones.

Cómo se almacenan sus archivos

Los modelos subidos se almacenan de forma cifrada y nunca son accesibles públicamente — no existe ningún enlace que sirva un archivo almacenado directamente. El campo file_path en las respuestas es la ruta de descarga autenticada (GET /v2/file/{file_id}), no una ubicación en el disco, así que trátelo como un endpoint en lugar de una URL que pueda compartir. Eliminar un archivo lo elimina del almacenamiento, no solo de sus listados.

4. Información de la pieza y análisis técnico

Verifique si sus modelos son imprimibles, obtenga dimensiones de la pieza y métricas técnicas avanzadas:

• POST /v2/printability/{file_id} Análisis Instantáneo – Verifique medidas, volumen, área de superficie e integridad geométrica (bordes abiertos/non-manifold) antes de generar un presupuesto.

Quote3D va más allá de las simples verificaciones de dimensiones; analiza la integridad manifold del modelo y evalúa el riesgo de adhesión a la cama, crítico para la impresión 3D. Estas métricas se proporcionan tanto en las respuestas de Printability como de Quote.

5. Operaciones de Cotización

Genere cotizaciones instantáneas para sus impresiones 3D y gestione el historial de cotizaciones:

• POST /v2/file/quote/{file_id} — Inicia el cálculo asíncrono de un presupuesto para un modelo 3D. Devuelve un ID de trabajo; utilice el endpoint de trabajos para obtener el resultado completado.
• POST /v2/file/quote/{file_id}/async — Endpoint asíncrono alternativo para generar presupuestos. Devuelve un ID de trabajo que puede usar para verificar el estado y obtener el resultado completado.
• GET /v2/jobs/{job_id} — Verifique el estado de un trabajo de cotización asíncrono. Devuelve el porcentaje de progreso y el estado de finalización.
• GET /v2/quotes — Recupere todo su historial de cotizaciones con soporte de paginación
• GET /v2/quotes/{quote_id} — Obtenga información detallada sobre una cotización específica
• DELETE /v2/quotes/{quote_id} — Elimina una cotización de su historial

Parámetros de Solicitud de Cotización

Al generar una cotización, puede proporcionar una configuración personalizada en el cuerpo de la solicitud. Cualquier parámetro que no especifique se tomará automáticamente de la configuración de su Perfil de Rebanado en el Panel de Control. Esto le permite anular configuraciones específicas por cotización mientras mantiene los valores predeterminados para otras.

Las tablas a continuación cubren los parámetros que las integraciones suelen anular con más frecuencia. No son la lista completa; el motor de cotización acepta muchos más campos de impresora, material y precios, y cada uno de ellos puede configurarse una vez en sus Perfiles de laminado del Dashboard en lugar de enviarse en cada solicitud. Configure sus perfiles allí y envíe solo lo que varía por cotización; la lista completa de campos se encuentra en el esquema OpenAPI.

Request Validation

Los campos numéricos de printer_config, material_config y quote_config se comprueban contra sus límites antes de encolar el trabajo. Un valor fuera de rango, un número no finito (NaN, Infinity), un tipo incorrecto o un número negativo donde solo tienen sentido el cero y los valores superiores se rechaza con HTTP 400 y un VALIDATION_ERROR que indica el campo exacto. El cero se sigue aceptando allí donde tiene sentido: una velocidad o aceleración de 0 para un rol concreto significa «usar el valor predeterminado de la impresora», la misma convención que utiliza OrcaSlicer.

• Límites de temperatura: las temperaturas del material (temperature y bed_temperature, tanto si se envían en la petición como si se leen del Perfil de material) se comprueban contra los valores min_hotend_temp / max_hotend_temp y min_bed_temp / max_bed_temp de la impresora. Un material que necesita más calor del que puede aportar la impresora seleccionada se rechaza en lugar de cotizarse. Solo FDM: las tecnologías de resina y polvo no tienen boquilla ni cama caliente. Deje los límites de la impresora sin definir para omitir la comprobación.
• Tecnologías habilitadas: si ha restringido las tecnologías en su Configuración global, se rechaza toda solicitud de cotización de una tecnología deshabilitada. Deje el ajuste vacío para aceptar todas las tecnologías.
• Campos de precio del material: price_per_gram es el valor que cobra el motor. Al guardar un Perfil de material, price_per_kg se recalcula automáticamente a partir de él (y price_per_gram se deriva de price_per_kg cuando solo se indica el precio por kilogramo), de modo que ambos nunca pueden discrepar.

Parámetros Raíz

Lógica de Cantidad y Producción por Lotes

Nuestro sistema utiliza un algoritmo de empaquetado avanzado basado en la 'cantidad' especificada:

• Tecnología FDM: Las piezas se colocan lado a lado en la placa de construcción (ejes X e Y) según el espacio disponible.
• Tecnología SLA: Las piezas se posicionan lado a lado en el recipiente de resina (ejes X e Y).
• Tecnología SLS: Las piezas se pueden apilar en todos los ejes (X, Y y Z) para utilizar completamente la capacidad de la cama de polvo.

printer_config

Parámetros de configuración de la impresora. Todos los campos son opcionales y utilizarán los valores predeterminados de su Perfil de Impresora si no se proporcionan.

material_config

Parámetros de configuración del material. Todos los campos son opcionales y utilizarán los valores predeterminados de su Perfil de Material si no se proporcionan.

quote_config

Parámetros de configuración de precios de la cotización. Todos los campos son opcionales y utilizarán los valores predeterminados de su Configuración Global si no se proporcionan. La moneda predeterminada es la de su panel de control (por ejemplo, 'USD', 'TRY', 'EUR').

6. Perfiles de Impresora y Presupuesto

Configure los ajustes de la impresora y los precios para obtener presupuestos precisos. Puede administrar sus perfiles predeterminados en la sección Perfiles de Rebanado del Panel de Control, que se utilizarán automáticamente cuando no especifique parámetros en las solicitudes de API.

Tipos de perfil

• Perfil de Impresora - Configure los ajustes de su impresora (tamaño de la cama, diámetro de la boquilla, velocidad de impresión, altura de capa, aceleración, jerk, temperaturas, etc.) para que coincidan con su impresora real. Establezca esto como su perfil predeterminado en el Panel de Control y se utilizará para todas las solicitudes de presupuesto a menos que anule parámetros específicos.
• Perfil de Material - Establezca las propiedades del material (tipo de filamento, densidad, diámetro, temperaturas, velocidad del ventilador, ajustes de retracción, precios) para cada material que utilice. La API utilizará automáticamente el perfil de material que coincida con el filament_type que especifique en la solicitud.
• Configuración Global - Configure la configuración global de cotización, como la tasa de impuestos, las tarifas fijas, los costos de energía y la moneda predeterminada. Estos ajustes se aplican a todas las cotizaciones a menos que se anulen en la solicitud.

Cómo Funcionan las Mezclas de Perfiles

Cuando realiza una solicitud de presupuesto, la API combina los parámetros de su solicitud con sus perfiles del Panel de Control utilizando esta prioridad:

1. Parámetros de Solicitud - Los valores que proporciona explícitamente en la solicitud de API tienen la prioridad más alta
2. Perfil de Usuario - Si tiene un perfil específico del usuario establecido como predeterminado, se utiliza a continuación
3. Perfil Global - Si no existe un perfil de usuario, el sistema recurre a los valores predeterminados globales

Esto significa que puede anular solo los parámetros que necesita (por ejemplo, solo layer_height o fill_density) mientras mantiene todos los demás ajustes de sus perfiles del Panel de Control.

7. Webhooks

Reciba notificaciones en tiempo real cuando se producen eventos en su cuenta:

• POST /v2/webhooks - Crear un nuevo punto final de webhook
• GET /v2/webhooks - Listar todos sus webhooks
• GET /v2/webhooks/{webhook_id} - Obtener los detalles del webhook y las estadísticas de entrega
• PUT /v2/webhooks/{webhook_id} - Actualizar la configuración del webhook
• DELETE /v2/webhooks/{webhook_id} - Eliminar un webhook
• POST /v2/webhooks/{webhook_id}/deliveries/{delivery_id}/resend - Volver a enviar una entrega anterior, por ejemplo después de arreglar tu endpoint

Eventos admitidos: quote.completed, quote.failed, file.uploaded, file.deleted, job.status_changed, widget.added_to_cart, usage.alert. Los webhooks incluyen firmas HMAC-SHA256 para la verificación de seguridad.

Referencia de webhooks: estructura del payload, verificación de la firma, reintentos y reenvío

8. Analítica e Informes

Obtenga información sobre el uso de su API y las estadísticas de cotizaciones:

• GET /v2/analytics/quotes - Obtenga estadísticas completas de cotizaciones, incluyendo el total de cotizaciones, precios promedio y tendencias de uso de materiales
• GET /v2/analytics/popular - Visualice sus materiales y configuraciones de impresora más populares
• GET /v2/analytics/cost-trends - Analiza las tendencias de costos a lo largo del tiempo (agrupación diaria, semanal o mensual)
• GET /v2/analytics/export - Exporte sus cotizaciones y datos de uso como CSV o JSON

9. Catálogo y stock

Gestiona las impresoras, materiales, colores, el stock por color, los precios y las tecnologías propios de la cuenta con un token de servidor. El widget lee el mismo catálogo, así que un cambio llega al formulario de presupuesto al momento. Los tokens de widget se rechazan y estas llamadas no cuentan para la cuota mensual de peticiones:

• GET /v2/store/catalog - Todo lo que ofrece la cuenta, con el estado de preparación por tecnología y los colores que se agotan
• GET /v2/store/catalog/schema - Los formularios de impresora, material y precios del panel, con límites, unidades y textos de ayuda en el idioma pedido
• POST /v2/store/catalog/adopt - Copiar impresoras y materiales globales a la cuenta, con los colores, el precio y el stock inicial que elijas
• POST /v2/store/catalog/materials - Crear un material, opcionalmente a partir de uno global
• GET · PATCH · DELETE /v2/store/catalog/materials/{id} - Leer, cambiar o borrar un material, incluidos sus ajustes de stock
• PUT /v2/store/catalog/materials/{id}/colors - Sustituir la lista de colores de un material; se conserva el stock de los colores existentes
• GET · PATCH · DELETE /v2/store/catalog/printers/{id} - Leer, cambiar o borrar una impresora
• GET · PATCH · DELETE /v2/store/catalog/pricing - Leer, cambiar o restablecer los precios; cambiar la moneda cambia la de la cuenta sin convertir los importes
• GET · PUT /v2/store/catalog/technologies - Qué tecnologías permite el plan y cuáles están activas
• GET · POST /v2/store/stock/movements - Registrar una entrada, un recuento o una merma, y listar el historial de stock
• POST /v2/store/stock/orders - Descontar, devolver o comprobar el material de un pedido pagado, como mucho una vez por presupuesto

Los cuerpos PATCH llevan values y updated_at. values usa los mismos nombres de campo snake_case que la lista del catálogo (un nombre que el formulario no tiene se rechaza con 400); si el perfil cambió desde que lo leíste, la llamada responde 409 con error_key stale.

10. Limitación de Velocidad y Cuotas

Quote3D utiliza la limitación de velocidad para asegurar un uso justo y la estabilidad del sistema:

• Los límites de velocidad se aplican por token de API y varían según el endpoint
• La información sobre los límites de velocidad se incluye en las cabeceras de la respuesta: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Window
• Cuando se alcanza el límite de velocidad, recibirá una respuesta 429 Too Many Requests con una cabecera Retry-After
• Tu plan fija un cupo de presupuestos, que se restablece en cada periodo de facturación, y un cupo de almacenamiento, que nunca se restablece y solo se libera al eliminar archivos
• Los límites son configurables por despliegue, así que lea los valores actuales en lugar de codificarlos de forma fija. Tanto los encabezados de respuesta anteriores como este endpoint los informan: GET /v2/quota

11. Respuestas y errores

Las respuestas correctas tienen dos formas. Las llamadas de presupuesto, trabajo, detalle de presupuesto guardado, webhook, analítica, uso, cuota y configuración envuelven su contenido con success: true y el resultado en data. Las llamadas de archivo, ID de subida, usuario, subidas, lista de presupuestos, imprimibilidad y Catálogo y stock devuelven sus campos en el nivel superior. La referencia de la API muestra el esquema exacto de cada llamada. Las descargas de archivos y las exportaciones CSV devuelven el contenido del archivo tal cual.

{
  "success": true,
  "data": { "...": "endpoint-specific payload" }
}

Paginación y ordenación

Los endpoints de listado como /v2/quotes y /v2/user/uploads están paginados con los parámetros de consulta limit y offset (por defecto 50 resultados, máximo 100). Junto con los resultados, devuelven un objeto de paginación que contiene total, limit, offset, has_more, page y total_pages, por lo que se recomienda usar has_more en lugar de recalcular el final de la lista por su cuenta. La ordenación utiliza un único parámetro repetible en el formato field:direction, por ejemplo ?sort=created_at:desc&sort=total_price:asc; las cargas (uploads) se ordenan por defecto de la más reciente a la más antigua.

Respuestas de error

Todos los errores tienen la misma forma: una lista detail que nombra el parámetro o campo (loc, msg, code), un error_code como AUTH_001, un error_summary y, cuando es útil, recovery_suggestions y documentation_url. Decide según el estado HTTP y el error_code, no según el texto, que puede cambiar.

Los presupuestos asíncronos son diferentes: el encolamiento del trabajo tiene éxito con un 202, y un cálculo que falle posteriormente se presenta como un estado de error con un mensaje de error en el endpoint del trabajo, no como un error HTTP. Inspeccione siempre el estado del trabajo, no solo el código de estado que recibió al iniciarlo.

12. API RESTful y versionada

• Todos los endpoints están versionados (ej., /v2/)
• Utiliza métodos HTTP estándar: GET, POST, PUT, DELETE
• Descrita mediante un esquema OpenAPI 3.0.3 que puede importar en sus propias herramientas
• Los cambios incompatibles y las incorporaciones se registran en el registro de cambios de la API