API - Vue d’ensemble

API - Viewer, Configurator et Customizer

Récupérez les produits, associez-les aux outils et créez des sessions d’intégration sécurisées pour Viewer, Configurator et Customizer.

Vue d’ensemble des points d’accès

MéthodePoint d’accèsDescriptionAccès
GET/public-api/v1/productsRenvoie les produits/designs de la boutique avec les possibilités d’intégration et les URL des médias.products:read
GET/public-api/v1/products/:idRenvoie un produit/design de la boutique.products:read
POST/public-api/v1/embed/sessionÉmet un JWT de courte durée pour les outils intégrés, dont le générateur de modèles.embed:session:create
GET/public-api/v1/runtime/bootstrapDétermine le contexte d’exécution à partir d’un JWT d’intégration.jeton d’intégration Bearer
POST/public-api/v1/runtime-bindings/sync-from-wordpressCrée ou met à jour les associations d’exécution à partir des associations de produits WordPress.tout identifiant authentifié
PATCH/public-api/v1/runtime-bindings/:idModifie une association d’exécution.tout identifiant authentifié
POST/public-api/v1/runtime-bindings/:id/activateActive une association d’exécution.tout identifiant authentifié
POST/public-api/v1/runtime-bindings/:id/deactivateDésactive une association d’exécution.tout identifiant authentifié

Produits de la boutique

Les points d’accès des produits renvoient les designs de la boutique pouvant être intégrés dans Viewer, Configurator ou Customizer.

ParamètreObligatoireDétails
namenonRecherche le nom du produit/design.
customizernontrue ou false.
offsetnonValeur par défaut : 0. Doit être >= 0.
limitnonValeur par défaut : 9, maximum : 50.
order_bynonid, name ou created_at.
directionnonASC ou DESC.

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

Exemple de réponse

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

Associations des environnements d’exécution

Les associations d’exécution relient les produits commerciaux externes aux designs Alter Product et aux types d’outils. Elles sont principalement utilisées par les intégrations WordPress/WooCommerce et les systèmes e-commerce avancés.

ParamètreObligatoireDétails
designIdnonIdentifiant du design Alter Product appartenant à la boutique.
externalProductIdoui pour la synchronisationIdentifiant du produit externe, par exemple celui d’un produit WooCommerce.
runtimeTypeoui pour la synchronisationviewer, configurator ou customizer.
statusnondraft, active, inactive, archived ou legacy_active.
legacyStorefrontProductIdnonIdentifiant d’association historique facultatif.
legacyBindingMetanonMétadonnées JSON facultatives, par exemple manifestHash.

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

Exemple de réponse

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

Sessions d’intégration et initialisation de l’environnement d’exécution

Créez un jeton d’intégration de courte durée depuis votre serveur, transmettez-le à l’iframe ou à l’environnement d’exécution, puis laissez ce dernier appeler le point d’initialisation avec un jeton Bearer.

ParamètreObligatoireDétails
runtimeBindingIdrecommandéIdentifiant à privilégier pour les associations d’exécution actives.
toolobligatoire sans runtimeBindingIddesigner | viewer | configurator | customizer | model-generator
toolIdtool: model-generatorIdentifiant numérique positif du projet local du générateur, et non son UUID ni l’identifiant du produit WooCommerce.
originouiOrigine sur laquelle l’outil intégré est affiché, par exemple https://yourstore.com.
designIdun identifiantIdentifiant du design Alter Product. Ne pas combiner avec orderId.
orderIdun identifiantIdentifiant de commande Customizer. Valide uniquement pour customizer.
cartKey + cartModenonContexte de panier propre à Customizer. cartMode vaut view ou edit.

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

Remarques

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

Exemple de réponse

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