API - 3D-modelgenerator

3D-modelgenerator

Generatorens importendpoints er skrivebeskyttede server-til-server-anmodninger. De kræver de almindelige API-headere, rettighedsomfanget embed:session:create og et aktivt abonnement. Importtilladelsen udsteder ikke en redigeringssession og bruger ikke af dens månedlige kvote. Når editoren åbnes, bruges den samme monthlyEmbedTokenLimit-tæller som til de øvrige indlejrede værktøjer.

Find og importér generatormodeller

Brug /model-generator/models til at vise tilgængelige modeller med generatorer. Beskrivelsen generator fastlåser projectId, revision, configurationId, templateRevision, productId og productModel3dId til bestemte værdier. Følg dens importPath for at hente præcis den pågældende kilderevision. Manifester for produktressourcer indeholder også generators og hver models generator-beskrivelse. Skabeloner kan importeres separat efter konfiguration og revision.

Katalogfiltre

En projektimport indeholder document, revision, template og et files-manifest. Hver fil angiver en path under /v1/model-generator/; sæt /public-api foran stien, når filen hentes fra Alter Product. Kopiér de nødvendige filer til dit eget lager, og erstat kildereferencer med lokale referencer. Importér mannequiner og teksturbiblioteker via deres katalogendpoints; public-files er begrænset til tilladte ressourcestier, og skabeloner skal bestå adgangskontrollen for deres konfiguration og revision.

Eksempel på anmodning (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 });

Redigeringssession og lokal lagring

Opret redigeringssessionen med tool: model-generator, et positivt numerisk toolId, der identificerer det lokale generatorprojekt (ikke dets UUID eller WooCommerce-produkt-ID), samt den tilladte origin for butikken. Send ikke designId, orderId, runtimeBindingId eller kurvfelter til dette værktøj. Generatorprojektets UUID er en separat identifikator. Send det returnerede token via iframe-håndtrykket; initialiseringen af kørselsmiljøet returnerer generatorkonteksten med 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);

Eksempel på svar

{
  "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-beskeder, som WordPress-broen bruger

WordPress-pluginet stiller lagringsbroen til rådighed og kontrollerer administrator- eller WooCommerce-butiksadministratorrettigheder. Det validerer iframe-vinduets origin, kildevinduet, nonce, anmodnings-ID og tilladte projektstier. Broen sender lokale læsninger og skrivninger til /wp-json/alter-wc/v1/model-generator. API-legitimationsoplysninger bliver på serveren. En tilpasset integration skal implementere tilsvarende godkendt lagringshåndtering; generatorens offentlige API gemmer ikke projekter hos 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.

Ved lagring sendes expectedRevision, templateRevision, document og referencer til resultatfiler. Der oprettes en uforanderlig revision; en forældet expectedRevision returnerer HTTP 409. WordPress gemmer metadata i databasen og filer i mappen uploads. JSON kompakteres og komprimeres med gzip, når komprimeringen reducerer størrelsen.

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

Brug gemt model i design udgiver en fuldstændig gemt revision til et tilknyttet design. Kunderne ser den derefter gennem den eksisterende Customizer, Configurator eller Viewer med de sædvanlige produkttilknytninger og abonnementskontroller. Generatoreditoren forbliver et værktøj til forhandleren. Ordretilknytninger bevarer det gemte projekt og dets revision, så senere redigeringer ikke ændrer tidligere ordrer ubemærket.