API - Generator de modele 3D

Generator de modele 3D

Endpointurile de import ale generatorului permit doar citirea în comunicarea dintre servere. Necesită antetele API standard, permisiunea embed:session:create și un plan activ. Autorizarea importului nu creează o sesiune de editor și nu consumă limita lunară a acesteia. Deschiderea editorului folosește același contor monthlyEmbedTokenLimit ca celelalte instrumente încorporate.

Găsirea și importarea modelelor cu generator

Folosește /model-generator/models pentru a lista modelele disponibile cu generatoare. Descriptorul generator fixează valorile projectId, revision, configurationId, templateRevision, productId și productModel3dId. Urmează importPath pentru a prelua exact acea revizie sursă. Manifestele resurselor de produs expun și generators, precum și descriptorul generator al fiecărui model. Șabloanele pot fi importate separat, după configurație și revizie.

Filtre de catalog

Un import de proiect conține document, revision, template și un manifest files. Fiecare fișier furnizează un path sub /v1/model-generator/; adaugă /public-api înaintea lui când descarci din Alter Product. Copiază fișierele necesare în propriul spațiu de stocare și înlocuiește referințele sursă cu referințe locale. Importă manechinele și bibliotecile de texturi prin endpointurile lor de catalog; public-files permite numai căile de resurse aprobate, iar șabloanele trebuie să treacă verificările de acces la configurație și revizie.

Exemplu de solicitare (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 });

Sesiunea editorului și stocarea locală

Creează sesiunea editorului cu tool: model-generator, un toolId numeric pozitiv care identifică proiectul local al generatorului (nu UUID-ul acestuia sau ID-ul produsului WooCommerce) și originea permisă a magazinului. Nu transmite designId, orderId, runtimeBindingId sau câmpuri de coș pentru acest instrument. UUID-ul proiectului generatorului este un identificator separat. Transmite tokenul primit prin handshake-ul iframe; runtime bootstrap returnează contextul generatorului cu 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);

Exemplu de răspuns

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

Mesaje iframe folosite de puntea WordPress

Pluginul WordPress găzduiește puntea de stocare și verifică permisiunile de administrator sau manager WooCommerce. Validează originea iframe-ului, fereastra sursă, nonce, identificatorul cererii și căile de proiect permise. Puntea trimite citirile și scrierile locale către /wp-json/alter-wc/v1/model-generator. Datele de acces API rămân pe server. O integrare personalizată trebuie să implementeze un mecanism echivalent de stocare autentificată; API-ul public al generatorului nu salvează proiecte în 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.

O salvare transmite expectedRevision, templateRevision, document și referințe la artefacte. Creează o revizie imuabilă; o valoare expectedRevision neactualizată returnează HTTP 409. WordPress stochează metadatele în baza sa de date, iar fișierele în directorul uploads. JSON este minificat și comprimat cu gzip atunci când comprimarea îi reduce dimensiunea.

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

Acțiunea Folosește modelul salvat în design publică o revizie salvată completă într-un design asociat. Clienții o văd apoi prin Customizer, Configurator sau Viewer, cu asocierile obișnuite ale produselor și verificările de abonament. Editorul generatorului rămâne un instrument al comerciantului. Legăturile comenzilor păstrează proiectul și revizia salvate, astfel încât modificările ulterioare să nu schimbe automat comenzile anterioare.