API - Panoramica

API - Viewer, Configurator e Customizer

Recupera i prodotti, collegali agli strumenti e crea sessioni di incorporamento sicure per Viewer, Configurator e Customizer.

Panoramica degli endpoint

MetodoEndpointDescrizioneAccesso
GET/public-api/v1/productsRestituisce prodotti/design del negozio con disponibilità di incorporamento e URL dei contenuti multimediali.products:read
GET/public-api/v1/products/:idRestituisce un prodotto/design del negozio.products:read
POST/public-api/v1/embed/sessionEmette un JWT di breve durata per gli strumenti incorporati, incluso il generatore di modelli.embed:session:create
GET/public-api/v1/runtime/bootstrapRisolve il contesto runtime da un JWT di incorporamento.token di incorporamento Bearer
POST/public-api/v1/runtime-bindings/sync-from-wordpressCrea o aggiorna associazioni runtime a partire dalle mappature dei prodotti WordPress.qualsiasi credenziale autenticata
PATCH/public-api/v1/runtime-bindings/:idModifica parzialmente un'associazione runtime.qualsiasi credenziale autenticata
POST/public-api/v1/runtime-bindings/:id/activateAttiva un'associazione runtime.qualsiasi credenziale autenticata
POST/public-api/v1/runtime-bindings/:id/deactivateDisattiva un'associazione runtime.qualsiasi credenziale autenticata

Prodotti del negozio

Gli endpoint dei prodotti restituiscono design del negozio incorporabili come esperienze Viewer, Configurator o Customizer.

ParametroObbligatorioDettagli
namenoCerca per nome del prodotto/design.
customizernotrue o false.
offsetnoPredefinito 0. Deve essere >= 0.
limitnoPredefinito 9, massimo 50.
order_bynoid, name o created_at.
directionnoASC o DESC.

Esempio di richiesta (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');

Esempio di risposta

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

Associazioni runtime

Le associazioni runtime collegano prodotti commerciali esterni a design e tipi di runtime Alter Product. Sono usate soprattutto dalle integrazioni WordPress/WooCommerce e dai backend avanzati dei negozi.

ParametroObbligatorioDettagli
designIdnoID del design Alter Product appartenente al negozio.
externalProductIdsì per la sincronizzazioneID del prodotto esterno, ad esempio un ID di prodotto WooCommerce.
runtimeTypesì per la sincronizzazioneviewer, configurator o customizer.
statusnodraft, active, inactive, archived o legacy_active.
legacyStorefrontProductIdnoID facoltativo della mappatura legacy.
legacyBindingMetanoMetadati JSON facoltativi, ad esempio manifestHash.

Esempio di richiesta (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'
          }
        }
      }
    ]
  })
});

Esempio di risposta

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

Sessioni di incorporamento e inizializzazione del runtime

Crea un token di incorporamento di breve durata dal server, passalo all'iframe/runtime e lascia che il runtime chiami bootstrap con un token Bearer.

ParametroObbligatorioDettagli
runtimeBindingIdconsigliatoIdentificatore preferito per le associazioni runtime attive.
toolobbligatorio senza runtimeBindingIddesigner | viewer | configurator | customizer | model-generator
toolIdtool: model-generatorID numerico positivo del progetto locale del generatore, non il suo UUID né l’ID del prodotto WooCommerce.
originsìOrigine in cui viene mostrato il contenuto incorporato, ad esempio https://yourstore.com.
designIdun identificatoreID del design Alter Product. Non combinare con orderId.
orderIdun identificatoreID dell'ordine Customizer. Valido solo per customizer.
cartKey + cartModenoContesto del carrello esclusivo del Customizer. cartMode è view o edit.

Esempio di richiesta (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 });

Note

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

Esempio di risposta

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