API - Generador de modelos 3D

Generador de modelos 3D

Los endpoints de importación del generador solo admiten solicitudes de lectura entre servidores. Requieren las cabeceras API habituales, el permiso embed:session:create y un plan activo. La autorización de importación no crea una sesión del editor ni consume su cuota mensual. La apertura del editor utiliza el mismo contador monthlyEmbedTokenLimit que las demás herramientas integradas.

Buscar e importar modelos con generador

Utiliza /model-generator/models para listar los modelos disponibles con generador. El descriptor generator fija projectId, revision, configurationId, templateRevision, productId y productModel3dId. Sigue su importPath para obtener exactamente esa revisión de origen. Los manifiestos de recursos de producto también exponen generators y el descriptor generator de cada modelo. Las plantillas se pueden importar por separado según su configuración y revisión.

Filtros de los catálogos

La importación de un proyecto contiene document, revision, template y un manifiesto files. Cada archivo proporciona un path bajo /v1/model-generator/; antepón /public-api al descargarlo desde Alter Product. Copia los archivos necesarios a tu propio almacenamiento y sustituye las referencias de origen por referencias locales. Importa maniquíes y bibliotecas de texturas mediante sus endpoints de catálogo; public-files se limita a las rutas de recursos permitidas, y las plantillas deben superar las comprobaciones de acceso de su configuración y revisión.

Ejemplo de solicitud (fetch)

// Server-side: uses alterFetch and authHeaders from the API connection guide.
const catalog = await alterFetch('/model-generator/models?' + new URLSearchParams({
  scope: 'all', limit: '24', offset: '0'
}));

const selected = catalog.items[0];
if (!selected?.generator) throw new Error('Select an available generator model');

const importPath = selected.generator.importPath;
if (!importPath.startsWith('/v1/model-generator/projects/')) {
  throw new Error('Invalid generator import path');
}
const bundle = await alterFetch(importPath.slice('/v1'.length));

for (const file of bundle.files) {
  if (!file.path.startsWith('/v1/model-generator/')) {
    throw new Error('Invalid generator file path');
  }
  const response = await fetch('https://alterproduct.com/public-api' + file.path, {
    headers: authHeaders,
    redirect: 'error'
  });
  if (!response.ok) throw new Error(`File download failed: ${response.status}`);
  const bytes = new Uint8Array(await response.arrayBuffer());
  // Persist bytes in your local storage; record the mapping from
  // file.sourceHref / file.href to the resulting local file reference.
}
// Persist bundle.document, bundle.template and revision metadata locally.
// Import the related product asset and its textures/mockups as needed:
const product = await alterFetch('/assets/products/' + selected.generator.productId);
const mannequins = await alterFetch('/model-generator/mannequins');
console.log({ product, mannequins });

Sesión del editor y almacenamiento local

Crea la sesión del editor con tool: model-generator, un toolId numérico positivo que identifique el proyecto local del generador (no su UUID ni el ID del producto WooCommerce) y el origen permitido de la tienda. No envíes designId, orderId, runtimeBindingId ni campos del carrito para esta herramienta. El UUID del proyecto del generador es un identificador independiente. Transmite el token recibido mediante el intercambio inicial del iframe; la inicialización del runtime devuelve el contexto del generador con storageMode: wordpress_local.

// Server-side, after authorizing the merchant's access to this local project.
const localProjectId = 42; // Local generator project ID, not its UUID or WC product ID.
const session = await alterFetch('/embed/session', {
  method: 'POST',
  body: JSON.stringify({
    tool: 'model-generator',
    toolId: localProjectId,
    origin: 'https://yourstore.com'
  })
});

// The iframe receives session.token through ALTER_CUSTOMIZER_SESSION_READY.
// Do not put API credentials or the token in the iframe URL.
const bootstrapResponse = await fetch('https://alterproduct.com/public-api/v1/runtime/bootstrap', {
  headers: { Authorization: `Bearer ${session.token}` }
});
if (!bootstrapResponse.ok) throw new Error('Generator bootstrap failed');
const context = await bootstrapResponse.json();
console.log(context);

Ejemplo de respuesta

{
  "runtimeBindingId": null,
  "designId": null,
  "productId": 42,
  "toolId": 42,
  "runtimeType": "model-generator",
  "storageMode": "wordpress_local",
  "parentOrigin": "https://yourstore.com"
}

// Host page: WordPress returns a numeric toolId and a UUID in id.
const url = new URL('https://alterproduct.com/app/model-generator');
url.search = new URLSearchParams({
  embedded: '1',
  lng: 'en',
  parentOrigin: window.location.origin,
  toolId: String(localProject.toolId),
  serverProjectId: localProject.id
}).toString();
// Optional: serverProjectRevision pins an existing saved revision.
iframe.src = url.toString();
// Install the authenticated handshake and storage bridge described below.
// Setting iframe.src alone does not authorize the editor or provide storage.

Mensajes del iframe utilizados por el puente de WordPress

El plugin de WordPress aloja el puente de almacenamiento y comprueba los permisos de administrador o gestor de WooCommerce. Valida el origen del iframe, la ventana de origen, el nonce, el identificador de solicitud y las rutas de proyecto permitidas. El puente envía las lecturas y escrituras locales a /wp-json/alter-wc/v1/model-generator. Las credenciales API permanecen en el servidor. Una integración personalizada debe implementar una gestión autenticada del almacenamiento equivalente; la API pública del generador no guarda proyectos en Alter Product.

// Messages after ALTER_CHILD_HELLO / ALTER_PARENT_ACK agree on the nonce.
// Iframe -> parent:
const sessionRequest = {
  type: 'ALTER_CUSTOMIZER_INIT_SESSION',
  nonce: handshakeNonce,
  payload: {
    tool: 'model-generator', alterProductId: localProject.toolId, mode: 'edit'
  }
};

// Parent -> iframe, after the server authorizes the merchant and issues a token:
const sessionReady = {
  type: 'ALTER_CUSTOMIZER_SESSION_READY',
  nonce: handshakeNonce,
  token: session.token,
  tool: 'model-generator',
  cartKey: `model-generator:${localProject.id}`,
  mode: 'edit',
  localSession: false,
  adminSession: true
};
// Send only to the validated iframe's exact origin and source window.
// An authorized token and successful bootstrap are still required.

Al guardar se envían expectedRevision, templateRevision, document y las referencias a los artefactos. Se crea una revisión inmutable; un valor expectedRevision desactualizado devuelve HTTP 409. WordPress almacena los metadatos en su base de datos y los archivos en su directorio uploads. El JSON se minifica y se comprime con gzip cuando la compresión reduce su tamaño.

// Example message from the iframe; savedSnapshot and artifact IDs come
// from the generator. The host checks origin/source/nonce/project permissions.
const message = {
  type: 'ALTER_MODEL_GENERATOR_REQUEST',
  requestId: crypto.randomUUID(),
  nonce: handshakeNonce,
  request: {
    method: 'POST',
    path: `/pattern-generator/projects/${projectUuid}/revisions`,
    data: {
      expectedRevision: loadedRevision,
      name: projectName,
      templateRevision,
      document: savedSnapshot,
      references: { artifactIds: savedArtifactIds }
    },
    responseType: 'json'
  }
};

Usar el modelo guardado en el diseño publica una revisión guardada completa en un diseño de producto vinculado. Los clientes la ven después mediante el Customizer, Configurator o Viewer existente, con las vinculaciones de producto y las comprobaciones de suscripción habituales. El editor del generador sigue siendo una herramienta para el comerciante. Los enlaces de los pedidos conservan el proyecto y la revisión guardados para que los cambios posteriores no alteren los pedidos anteriores sin aviso.