API - Générateur de modèles 3D

Générateur de modèles 3D

Les points de terminaison d’import du générateur n’acceptent que les requêtes en lecture entre serveurs. Ils nécessitent les en-têtes API habituels, le scope embed:session:create et un abonnement actif. L’autorisation d’import ne crée pas de session d’édition et ne consomme pas son quota mensuel. L’ouverture de l’éditeur utilise le même compteur monthlyEmbedTokenLimit que les autres outils intégrés.

Rechercher et importer des modèles avec générateur

Utilisez /model-generator/models pour lister les modèles disponibles dotés d’un générateur. Le descripteur generator fixe projectId, revision, configurationId, templateRevision, productId et productModel3dId. Suivez son importPath pour récupérer exactement cette révision source. Les manifestes des ressources produit exposent aussi generators et le descripteur generator de chaque modèle. Les gabarits peuvent être importés séparément selon leur configuration et leur révision.

Filtres des catalogues

Un import de projet contient document, revision, template et un manifeste files. Chaque fichier fournit un path sous /v1/model-generator/ ; ajoutez /public-api devant ce chemin pour le télécharger depuis Alter Product. Copiez les fichiers nécessaires dans votre propre espace de stockage et remplacez les références sources par des références locales. Importez les mannequins et les bibliothèques de textures via leurs points de terminaison de catalogue ; public-files n’autorise que certains chemins de ressources, et les gabarits restent soumis aux contrôles d’accès de leur configuration et de leur révision.

Exemple de requête (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 });

Session d’édition et stockage local

Créez la session d’édition avec tool: model-generator, un toolId numérique positif identifiant le projet local du générateur (et non son UUID ni l’ID du produit WooCommerce), ainsi que l’origine autorisée de la boutique. Ne transmettez pas designId, orderId, runtimeBindingId ni les champs du panier pour cet outil. L’UUID du projet du générateur est un identifiant distinct. Transmettez le jeton reçu via la négociation iframe ; l’initialisation du runtime renvoie le contexte du générateur avec 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);

Exemple de réponse

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

Messages iframe utilisés par la passerelle WordPress

L’extension WordPress héberge la passerelle de stockage et vérifie les droits d’administrateur ou de gestionnaire WooCommerce. Elle valide l’origine de l’iframe, la fenêtre source, le nonce, l’identifiant de requête et les chemins de projet autorisés. La passerelle transmet les lectures et écritures locales à /wp-json/alter-wc/v1/model-generator. Les identifiants API restent sur le serveur. Une intégration personnalisée doit fournir un traitement du stockage authentifié équivalent ; l’API publique du générateur n’enregistre pas les projets sur 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.

Un enregistrement transmet expectedRevision, templateRevision, document et les références aux artefacts. Il crée une révision immuable ; une valeur expectedRevision obsolète renvoie HTTP 409. WordPress stocke les métadonnées dans sa base de données et les fichiers dans son répertoire uploads. Le JSON est minifié et compressé avec gzip lorsque la compression réduit sa taille.

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

Utiliser le modèle enregistré dans le design publie une révision enregistrée complète dans un design produit lié. Les clients la voient ensuite via les outils Customizer, Configurator ou Viewer existants, avec les associations produit et les contrôles d’abonnement habituels. L’éditeur du générateur reste un outil réservé au marchand. Les liens des commandes conservent le projet et la révision enregistrés afin que les modifications ultérieures ne changent pas discrètement les commandes passées.