API - 3D model oluşturucu

3D Model Oluşturucu

Oluşturucunun içe aktarma uç noktaları, sunucular arasında yalnızca okuma isteklerini destekler. Standart API üstbilgilerini, embed:session:create yetkisini ve etkin bir planı gerektirir. İçe aktarma yetkilendirmesi bir düzenleyici oturumu oluşturmaz ve bu oturumun aylık kotasını tüketmez. Düzenleyiciyi açmak, diğer gömülü araçlarla aynı monthlyEmbedTokenLimit sayacını kullanır.

Oluşturucu içeren modelleri bulma ve içe aktarma

Oluşturucu içeren kullanılabilir modelleri listelemek için /model-generator/models kullanın. generator tanımlayıcısı, belirli projectId, revision, configurationId, templateRevision, productId ve productModel3dId değerlerini sabitler. Tam olarak bu kaynak revizyonunu almak için importPath yolunu izleyin. Ürün varlık bildirimleri ayrıca generators alanını ve her modelin generator tanımlayıcısını sunar. Şablonlar, yapılandırma ve revizyon temelinde ayrı olarak içe aktarılabilir.

Katalog filtreleri

Bir proje içe aktarımı document, revision, template ve bir files bildirimi içerir. Her dosya, /v1/model-generator/ altında bir path sunar; Alter Product'tan indirirken başına /public-api ekleyin. Gerekli dosyaları kendi depolama alanınıza kopyalayın ve kaynak referanslarını yerel referanslarla değiştirin. Mankenleri ve doku kitaplıklarını kendi katalog uç noktaları üzerinden içe aktarın; public-files yalnızca izin verilen kaynak yollarıyla sınırlıdır ve şablonlar yapılandırma/revizyon erişim kontrollerinden geçmelidir.

Örnek istek (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 });

Düzenleyici oturumu ve yerel depolama

Düzenleyici oturumunu tool: model-generator, yerel oluşturucu projesini tanımlayan pozitif sayısal bir toolId (projenin UUID'si veya WooCommerce ürün ID'si değil) ve mağazanın izin verilen origin değeriyle oluşturun. Bu araç için designId, orderId, runtimeBindingId veya sepet alanlarını iletmeyin. Oluşturucu projesinin UUID'si ayrı bir tanımlayıcıdır. Döndürülen tokenı iframe el sıkışması üzerinden iletin; runtime bootstrap, storageMode: wordpress_local içeren oluşturucu bağlamını döndürür.

// 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);

Örnek yanıt

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

WordPress köprüsünün kullandığı iframe mesajları

WordPress eklentisi, depolama köprüsünü barındırır ve yönetici veya WooCommerce mağaza yöneticisi izinlerini kontrol eder. iframe origin değerini, kaynak pencereyi, nonce değerini, istek kimliğini ve izin verilen proje yollarını doğrular. Köprü, yerel okuma ve yazma işlemlerini /wp-json/alter-wc/v1/model-generator adresine gönderir. API kimlik bilgileri sunucuda kalır. Özel bir entegrasyon, kimlik doğrulamalı eşdeğer bir depolama işleyişi uygulamalıdır; oluşturucunun herkese açık API'si projeleri Alter Product'a kaydetmez.

// 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.

Kaydetme işlemi expectedRevision, templateRevision, document ve çıktı dosyalarına referansları iletir. Değiştirilemez bir revizyon oluşturur; güncel olmayan expectedRevision, HTTP 409 döndürür. WordPress, meta verileri kendi veritabanında ve dosyaları uploads dizininde saklar. JSON küçültülür ve sıkıştırma boyutunu azaltıyorsa gzip ile sıkıştırılır.

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

Kaydedilmiş modeli tasarımda kullan eylemi, kaydedilmiş tam bir revizyonu bağlı bir tasarıma yayımlar. Müşteriler daha sonra bu revizyonu, mevcut Customizer, Configurator veya Viewer üzerinden, olağan ürün bağları ve abonelik kontrolleriyle görür. Oluşturucu düzenleyicisi satıcının kullandığı bir araç olarak kalır. Sipariş bağlantıları, kaydedilen proje ve revizyonu korur; böylece sonraki düzenlemeler geçmiş siparişleri otomatik olarak değiştirmez.