API - 3D-Modellgenerator

3D-Modellgenerator

Die Importendpunkte des Generators erlauben nur lesende Anfragen zwischen Servern. Sie erfordern die üblichen API-Header, den Scope embed:session:create und einen aktiven Tarif. Die Importautorisierung erstellt keine Editorsitzung und verbraucht deren monatliches Kontingent nicht. Beim Öffnen des Editors gilt derselbe Zähler monthlyEmbedTokenLimit wie für die anderen eingebetteten Werkzeuge.

Generatormodelle finden und importieren

Über /model-generator/models können Sie verfügbare Modelle mit Generator auflisten. Der Deskriptor generator legt projectId, revision, configurationId, templateRevision, productId und productModel3dId fest. Rufen Sie seinen importPath auf, um genau diese Quellrevision abzurufen. Die Manifeste der Produkt-Assets enthalten ebenfalls generators sowie den Deskriptor generator jedes Modells. Vorlagen können anhand ihrer Konfiguration und Revision separat importiert werden.

Katalogfilter

Ein Projektimport enthält document, revision, template und ein Manifest files. Jede Datei liefert einen path unter /v1/model-generator/; stellen Sie beim Herunterladen von Alter Product /public-api voran. Kopieren Sie die benötigten Dateien in Ihren eigenen Speicher und ersetzen Sie die Quellverweise durch lokale Verweise. Importieren Sie Schaufensterpuppen und Texturbibliotheken über ihre Katalogendpunkte; public-files ist auf erlaubte Ressourcenpfade beschränkt, und Vorlagen müssen die Zugriffsprüfung für ihre Konfiguration und Revision bestehen.

Beispielanfrage (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 });

Editorsitzung und lokale Speicherung

Erstellen Sie die Editorsitzung mit tool: model-generator, einer positiven numerischen toolId zur Identifizierung des lokalen Generatorprojekts (nicht dessen UUID oder der WooCommerce-Produkt-ID) und dem erlaubten Ursprung des Shops. Übergeben Sie für dieses Werkzeug weder designId, orderId, runtimeBindingId noch Warenkorbfelder. Die UUID des Generatorprojekts ist ein separater Bezeichner. Übermitteln Sie das zurückgegebene Token über den Iframe-Handshake; der Runtime-Bootstrap liefert den Generatorkontext mit 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);

Beispielantwort

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

Iframe-Nachrichten der WordPress-Brücke

Das WordPress-Plugin stellt die Speicherbrücke bereit und prüft Administrator- oder WooCommerce-Manager-Berechtigungen. Es validiert Iframe-Ursprung, Quellfenster, nonce, Anfrage-ID und erlaubte Projektpfade. Die Brücke leitet lokale Lese- und Schreibvorgänge an /wp-json/alter-wc/v1/model-generator weiter. API-Zugangsdaten bleiben auf dem Server. Eine eigene Integration muss eine gleichwertige authentifizierte Speicherverarbeitung bereitstellen; die öffentliche Generator-API speichert keine Projekte bei 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.

Beim Speichern werden expectedRevision, templateRevision, document und Artefaktverweise übermittelt. Dadurch entsteht eine unveränderliche Revision; ein veralteter Wert für expectedRevision führt zu HTTP 409. WordPress speichert Metadaten in seiner Datenbank und Dateien im Uploads-Verzeichnis. JSON wird minifiziert und mit gzip komprimiert, wenn dies die Dateigröße verringert.

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

Gespeichertes Modell im Design verwenden veröffentlicht eine vollständige gespeicherte Revision in einem verknüpften Produktdesign. Kunden sehen sie anschließend im bestehenden Customizer, Configurator oder Viewer mit den üblichen Produktzuordnungen und Abonnementprüfungen. Der Generatoreditor bleibt ein Werkzeug für Händler. Bestellverknüpfungen behalten das gespeicherte Projekt und dessen Revision bei, sodass spätere Änderungen frühere Bestellungen nicht unbemerkt verändern.