API - Viewer, Configurator και Customizer

Ανακτήστε προϊόντα, συνδέστε τα με τα εργαλεία και δημιουργήστε ασφαλείς συνεδρίες ενσωμάτωσης για το Viewer, το Configurator και το Customizer.

Επισκόπηση endpoints

Μέθοδος	Endpoint	Περιγραφή	Πρόσβαση
`GET`	`/public-api/v1/products`	Επιστρέφει προϊόντα/σχέδια καταστήματος με διαθεσιμότητα ενσωμάτωσης και URL πολυμέσων.	`products:read`
`GET`	`/public-api/v1/products/:id`	Επιστρέφει ένα προϊόν/σχέδιο καταστήματος.	`products:read`
`POST`	`/public-api/v1/embed/session`	Εκδίδει ένα JWT μικρής διάρκειας για ενσωματωμένα εργαλεία, συμπεριλαμβανομένης της γεννήτριας μοντέλων.	`embed:session:create`
`GET`	`/public-api/v1/runtime/bootstrap`	Επιλύει το πλαίσιο εκτέλεσης από JWT ενσωμάτωσης.	`token ενσωμάτωσης Bearer`
`POST`	`/public-api/v1/runtime-bindings/sync-from-wordpress`	Δημιουργεί ή ενημερώνει συνδέσεις εκτέλεσης από αντιστοιχίσεις προϊόντων WordPress.	`οποιαδήποτε έγκυρα διαπιστευτήρια`
`PATCH`	`/public-api/v1/runtime-bindings/:id`	Ενημερώνει μερικώς μια σύνδεση εκτέλεσης.	`οποιαδήποτε έγκυρα διαπιστευτήρια`
`POST`	`/public-api/v1/runtime-bindings/:id/activate`	Ενεργοποιεί μια σύνδεση εκτέλεσης.	`οποιαδήποτε έγκυρα διαπιστευτήρια`
`POST`	`/public-api/v1/runtime-bindings/:id/deactivate`	Απενεργοποιεί μια σύνδεση εκτέλεσης.	`οποιαδήποτε έγκυρα διαπιστευτήρια`

Προϊόντα καταστήματος

Τα endpoints προϊόντων επιστρέφουν σχέδια καταστήματος που μπορούν να ενσωματωθούν ως Viewer, Configurator ή Customizer.

Παράμετρος	Υποχρεωτικό	Λεπτομέρειες
`name`	`όχι`	Αναζητά όνομα προϊόντος/σχεδίου.
`customizer`	`όχι`	true ή false.
`offset`	`όχι`	Προεπιλογή 0. Πρέπει να είναι >= 0.
`limit`	`όχι`	Προεπιλογή 9, μέγιστο 50.
`order_by`	`όχι`	id, name ή created_at.
`direction`	`όχι`	ASC ή DESC.

Παράδειγμα αιτήματος (fetch)

const params = new URLSearchParams({
  limit: '20',
  offset: '0',
  name: 't-shirt',
  customizer: 'true',
  order_by: 'created_at',
  direction: 'DESC'
});

const products = await alterFetch(`/products?${params.toString()}`);
const product = await alterFetch('/products/381');

Παράδειγμα απάντησης

{
  "products": {
    "items": [
      {
        "id": 381,
        "name": "Men's T-Shirt",
        "createdAt": "2026-01-03T23:55:05.000Z",
        "productId": 4,
        "media": {
          "img": {
            "big": "https://alterproduct.com/public-api/v1/file/public/products/4/big.png",
            "medium": "https://alterproduct.com/public-api/v1/file/public/products/4/medium.png",
            "small": "https://alterproduct.com/public-api/v1/file/public/products/4/small.png"
          },
          "mockups": []
        },
        "storefrontProduct": {
          "id": 89,
          "idUserDesign": 381,
          "shareAccess": "public",
          "isCustomizer": 1
        },
        "runtimeBindings": [
          {
            "id": 42,
            "runtimeType": "customizer",
            "status": "active",
            "externalProductId": "wc_123"
          }
        ],
        "embeddable": {
          "viewer": true,
          "configurator": true,
          "customizer": true
        }
      }
    ],
    "total": 1
  }
}

Συνδέσεις περιβάλλοντος εκτέλεσης

Οι συνδέσεις περιβάλλοντος εκτέλεσης συνδέουν εξωτερικά εμπορικά προϊόντα με σχέδια Alter Product και τύπους εργαλείων. Χρησιμοποιούνται κυρίως από ενσωματώσεις WordPress/WooCommerce και προηγμένα backend καταστημάτων.

Παράμετρος	Υποχρεωτικό	Λεπτομέρειες
`designId`	`όχι`	ID σχεδίου Alter Product που ανήκει στο κατάστημα.
`externalProductId`	`ναι για συγχρονισμό`	Εξωτερικό ID προϊόντος, π.χ. ID προϊόντος WooCommerce.
`runtimeType`	`ναι για συγχρονισμό`	viewer, configurator ή customizer.
`status`	`όχι`	draft, active, inactive, archived ή legacy_active.
`legacyStorefrontProductId`	`όχι`	Προαιρετικό ID παλαιάς αντιστοίχισης.
`legacyBindingMeta`	`όχι`	Προαιρετικά μεταδεδομένα JSON, π.χ. manifestHash.

Παράδειγμα αιτήματος (fetch)

await alterFetch('/runtime-bindings/sync-from-wordpress', {
  method: 'POST',
  body: JSON.stringify({
    bindings: [
      {
        externalProductId: 'wc_123',
        runtimeType: 'customizer',
        status: 'active',
        designId: 381,
        legacyBindingMeta: {
          manifestHash: 'a3b1...'
        }
      }
    ]
  })
});

await alterFetch('/runtime-bindings/42', {
  method: 'PATCH',
  body: JSON.stringify({
    status: 'inactive'
  })
});

await alterFetch('/runtime-bindings/42/activate', { method: 'POST' });
await alterFetch('/runtime-bindings/42/deactivate', { method: 'POST' });

wordpress_local

await alterFetch('/runtime-bindings/sync-from-wordpress', {
  method: 'POST',
  body: JSON.stringify({
    bindings: [
      {
        externalProductId: 'wc_123',
        runtimeType: 'viewer',
        status: 'active',
        externalDesign: {
          externalDesignKey: 'wp-design-381',
          productId: 4,
          title: 'WooCommerce local design',
          manifestUrl: 'https://yourstore.com/wp-content/uploads/alter/381/manifest.json',
          assetBaseUrl: 'https://yourstore.com/wp-content/uploads/alter/381/',
          manifestHash: 'a3b1...',
          sourceMeta: {
            pluginVersion: '1.2.0'
          }
        }
      }
    ]
  })
});

Παράδειγμα απάντησης

{
  "message": "runtimeBinding.syncCompleted",
  "runtimeBindings": [
    {
      "id": 42,
      "designId": 381,
      "externalProductId": "wc_123",
      "runtimeType": "customizer",
      "status": "active"
    }
  ]
}

Συνεδρίες ενσωμάτωσης και αρχική φόρτωση περιβάλλοντος εκτέλεσης

Δημιουργήστε βραχύβιο token ενσωμάτωσης στον διακομιστή, περάστε το στο iframe/περιβάλλον εκτέλεσης και αφήστε το περιβάλλον να καλέσει bootstrap με token Bearer.

Παράμετρος	Υποχρεωτικό	Λεπτομέρειες
`runtimeBindingId`	`συνιστάται`	Προτιμώμενο αναγνωριστικό για ενεργές συνδέσεις εκτέλεσης.
`tool`	`υποχρεωτικό χωρίς runtimeBindingId`	designer \| viewer \| configurator \| customizer \| model-generator
`toolId`	`tool: model-generator`	Θετικό αριθμητικό ID του τοπικού έργου της γεννήτριας, όχι το UUID του ή το ID προϊόντος WooCommerce.
`origin`	`ναι`	Origin όπου εμφανίζεται η ενσωμάτωση, π.χ. https://yourstore.com.
`designId`	`ένα αναγνωριστικό`	ID σχεδίου Alter Product. Μην το συνδυάζετε με orderId.
`orderId`	`ένα αναγνωριστικό`	ID παραγγελίας Customizer. Ισχύει μόνο για customizer.
`cartKey + cartMode`	`όχι`	Πλαίσιο καλαθιού μόνο για Customizer. Το cartMode είναι view ή edit.

Παράδειγμα αιτήματος (fetch)

const session = await alterFetch('/embed/session', {
  method: 'POST',
  headers: {
    'x-alter-client-fingerprint': '9f1b7a5e4b3c2d1f9f1b7a5e4b3c2d1f'
  },
  body: JSON.stringify({
    runtimeBindingId: 42,
    origin: 'https://yourstore.com'
  })
});

const bootstrapResponse = await fetch('https://alterproduct.com/public-api/v1/runtime/bootstrap', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${session.token}`
  }
});

const bootstrap = await bootstrapResponse.json();
console.log({ session, bootstrap });

Σημειώσεις

await alterFetch('/embed/session', {
  method: 'POST',
  body: JSON.stringify({
    tool: 'customizer',
    origin: 'https://yourstore.com',
    orderId: 123
  })
});

await alterFetch('/embed/session', {
  method: 'POST',
  body: JSON.stringify({
    tool: 'viewer',
    origin: 'https://yourstore.com',
    designId: 381
  })
});

Παράδειγμα απάντησης

{
  "token": "eyJhbGciOiJIUzI1NiIsImtpZCI6IjEifQ...",
  "expiresIn": 900,
  "kid": "1",
  "mode": "design",
  "runtimeBindingId": 42,
  "runtimeType": "customizer"
}

Runtime bootstrap

{
  "runtimeBindingId": 42,
  "designId": 381,
  "productId": "wc_123",
  "runtimeType": "customizer",
  "storageMode": "wordpress_local",
  "manifestUrl": "https://yourstore.com/wp-content/uploads/alter/381/manifest.json",
  "assetBaseUrl": "https://yourstore.com/wp-content/uploads/alter/381/",
  "manifestHash": "a3b1...",
  "planCapabilities": {
    "viewer": true,
    "configurator": true,
    "customizer": true
  },
  "cartKey": null,
  "cartMode": null,
  "orderId": null
}