API - Generatore di modelli 3D

Generatore di modelli 3D

Gli endpoint di importazione del generatore accettano solo richieste di lettura tra server. Richiedono gli header API standard, lo scope embed:session:create e un piano attivo. L’autorizzazione all’importazione non crea una sessione dell’editor e non ne consuma la quota mensile. L’apertura dell’editor utilizza lo stesso contatore monthlyEmbedTokenLimit degli altri strumenti incorporati.

Trovare e importare modelli con generatore

Usa /model-generator/models per elencare i modelli disponibili con generatore. Il descrittore generator fissa projectId, revision, configurationId, templateRevision, productId e productModel3dId. Segui il suo importPath per recuperare esattamente quella revisione sorgente. I manifest delle risorse di prodotto espongono anche generators e il descrittore generator di ogni modello. I template possono essere importati separatamente in base a configurazione e revisione.

Filtri dei cataloghi

L’importazione di un progetto contiene document, revision, template e un manifest files. Ogni file fornisce un path sotto /v1/model-generator/; anteponi /public-api quando lo scarichi da Alter Product. Copia i file necessari nel tuo spazio di archiviazione e sostituisci i riferimenti sorgente con riferimenti locali. Importa manichini e librerie di texture tramite i rispettivi endpoint di catalogo; public-files è limitato ai percorsi di risorse consentiti e i template devono superare i controlli di accesso per la propria configurazione e revisione.

Esempio di richiesta (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 });

Sessione dell’editor e archiviazione locale

Crea la sessione dell’editor con tool: model-generator, un toolId numerico positivo che identifichi il progetto locale del generatore (non il suo UUID né l’ID del prodotto WooCommerce) e l’origine consentita del negozio. Per questo strumento non inviare designId, orderId, runtimeBindingId o campi del carrello. L’UUID del progetto del generatore è un identificatore separato. Trasmetti il token ricevuto tramite l’handshake dell’iframe; il bootstrap del runtime restituisce il contesto del generatore 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);

Esempio di risposta

{
  "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.

Messaggi iframe utilizzati dal ponte WordPress

Il plugin WordPress ospita il ponte di archiviazione e verifica i permessi di amministratore o gestore WooCommerce. Convalida l’origine dell’iframe, la finestra sorgente, il nonce, l’ID della richiesta e i percorsi di progetto consentiti. Il ponte invia le letture e le scritture locali a /wp-json/alter-wc/v1/model-generator. Le credenziali API rimangono sul server. Un’integrazione personalizzata deve implementare una gestione autenticata dell’archiviazione equivalente; l’API pubblica del generatore non salva progetti su 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.

Il salvataggio invia expectedRevision, templateRevision, document e i riferimenti agli artefatti. Crea una revisione immutabile; un valore expectedRevision non aggiornato restituisce HTTP 409. WordPress memorizza i metadati nel proprio database e i file nella directory uploads. Il JSON viene minificato e compresso con gzip quando la compressione ne riduce le dimensioni.

// 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'
  }
};

Usa il modello salvato nel design pubblica una revisione salvata completa in un design di prodotto collegato. I clienti la visualizzano poi tramite Customizer, Configurator o Viewer esistenti, con le consuete associazioni di prodotto e verifiche dell’abbonamento. L’editor del generatore rimane uno strumento per il commerciante. I collegamenti degli ordini conservano il progetto e la revisione salvati, in modo che le modifiche successive non alterino silenziosamente gli ordini precedenti.