API - 3D-modelgenerator

3D-modelgenerator

De importeindpunten van de generator ondersteunen alleen leesverzoeken tussen servers. Ze vereisen de gebruikelijke API-headers, de scope embed:session:create en een actief abonnement. Importautorisatie maakt geen editorsessie aan en verbruikt het maandelijkse quotum daarvoor niet. Het openen van de editor gebruikt dezelfde teller monthlyEmbedTokenLimit als de andere ingesloten tools.

Modellen met generator zoeken en importeren

Gebruik /model-generator/models om beschikbare modellen met een generator op te vragen. De descriptor generator legt projectId, revision, configurationId, templateRevision, productId en productModel3dId vast. Volg de bijbehorende importPath om precies die bronrevisie op te halen. Manifesten van productassets bevatten ook generators en de descriptor generator van elk model. Sjablonen kunnen afzonderlijk worden geïmporteerd op basis van configuratie en revisie.

Catalogusfilters

Een projectimport bevat document, revision, template en een manifest files. Elk bestand levert een path onder /v1/model-generator/; voeg /public-api vóór dit pad toe wanneer je het van Alter Product downloadt. Kopieer de benodigde bestanden naar je eigen opslag en vervang de bronverwijzingen door lokale verwijzingen. Importeer mannequins en textuurbibliotheken via hun cataloguseindpunten; public-files is beperkt tot toegestane bronpaden en sjablonen moeten de toegangscontroles voor hun configuratie en revisie doorlopen.

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

Editorsessie en lokale opslag

Maak de editorsessie aan met tool: model-generator, een positieve numerieke toolId die het lokale generatorproject identificeert (niet de UUID ervan of het WooCommerce-product-ID) en de toegestane oorsprong van de winkel. Geef voor deze tool geen designId, orderId, runtimeBindingId of winkelwagenvelden mee. De UUID van het generatorproject is een aparte identificatie. Geef het ontvangen token door via de iframe-handshake; de runtime-bootstrap retourneert de generatorcontext met 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);

Voorbeeldantwoord

{
  "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-berichten van de WordPress-brug

De WordPress-plugin verzorgt de opslagbrug en controleert beheerdersrechten of rechten voor WooCommerce-beheer. De plugin valideert de oorsprong van het iframe, het bronvenster, de nonce, het verzoek-ID en de toegestane projectpaden. De brug stuurt lokale lees- en schrijfverzoeken naar /wp-json/alter-wc/v1/model-generator. API-inloggegevens blijven op de server. Een aangepaste integratie moet gelijkwaardige, geauthenticeerde opslagafhandeling implementeren; de openbare generator-API slaat geen projecten op bij 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.

Bij het opslaan worden expectedRevision, templateRevision, document en artefactverwijzingen meegestuurd. Dit maakt een onveranderlijke revisie aan; een verouderde expectedRevision levert HTTP 409 op. WordPress bewaart metadata in zijn database en bestanden in zijn uploads-map. JSON wordt geminificeerd en met gzip gecomprimeerd wanneer compressie de omvang verkleint.

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

Opgeslagen model in ontwerp gebruiken publiceert een volledige opgeslagen revisie naar een gekoppeld productontwerp. Klanten zien deze vervolgens via de bestaande Customizer, Configurator of Viewer, met de gebruikelijke productkoppelingen en abonnementscontroles. De generatoreditor blijft een tool voor de verkoper. Bestellingskoppelingen behouden het opgeslagen project en de revisie, zodat latere bewerkingen eerdere bestellingen niet ongemerkt wijzigen.