API - Visão geral

API - Viewer, Configurator e Customizer

Obtenha produtos, vincule-os às ferramentas e crie sessões de incorporação seguras para Viewer, Configurator e Customizer.

Visão geral dos endpoints

MétodoEndpointDescriçãoAcesso
GET/public-api/v1/productsRetorna produtos/designs da loja com disponibilidade de incorporação e URLs de mídia.products:read
GET/public-api/v1/products/:idRetorna um produto/design da loja.products:read
POST/public-api/v1/embed/sessionEmite um JWT de curta duração para ferramentas incorporadas, incluindo o gerador de modelos.embed:session:create
GET/public-api/v1/runtime/bootstrapResolve o contexto do runtime a partir de um JWT de incorporação.token de incorporação Bearer
POST/public-api/v1/runtime-bindings/sync-from-wordpressCria ou atualiza associações de runtime a partir das associações de produtos do WordPress.qualquer credencial autenticada
PATCH/public-api/v1/runtime-bindings/:idAltera parcialmente uma associação de runtime.qualquer credencial autenticada
POST/public-api/v1/runtime-bindings/:id/activateAtiva uma associação de runtime.qualquer credencial autenticada
POST/public-api/v1/runtime-bindings/:id/deactivateDesativa uma associação de runtime.qualquer credencial autenticada

Produtos da loja

Os endpoints de produtos retornam designs da loja que podem ser incorporados como experiências de Viewer, Configurator ou Customizer.

ParâmetroObrigatórioDetalhes
namenãoPesquisa pelo nome do produto/design.
customizernãotrue ou false.
offsetnãoPadrão 0. Deve ser >= 0.
limitnãoPadrão 9, máximo 50.
order_bynãoid, name ou created_at.
directionnãoASC ou DESC.

Exemplo de solicitação (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');

Exemplo de resposta

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

Associações de runtime

As associações de runtime conectam produtos de e-commerce externos a designs e tipos de runtime do Alter Product. São usadas principalmente por integrações WordPress/WooCommerce e backends avançados de lojas.

ParâmetroObrigatórioDetalhes
designIdnãoID do design do Alter Product pertencente à loja.
externalProductIdsim para sincronizaçãoID do produto externo, por exemplo, um ID de produto do WooCommerce.
runtimeTypesim para sincronizaçãoviewer, configurator ou customizer.
statusnãodraft, active, inactive, archived ou legacy_active.
legacyStorefrontProductIdnãoID opcional da associação legada.
legacyBindingMetanãoMetadados JSON opcionais, por exemplo, manifestHash.

Exemplo de solicitação (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'
          }
        }
      }
    ]
  })
});

Exemplo de resposta

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

Sessões de incorporação e inicialização do runtime

Crie um token de incorporação de curta duração no seu servidor, passe-o ao iframe/runtime e deixe o runtime chamar bootstrap com um token Bearer.

ParâmetroObrigatórioDetalhes
runtimeBindingIdrecomendadoIdentificador preferencial para associações de runtime ativas.
toolobrigatório sem runtimeBindingIddesigner | viewer | configurator | customizer | model-generator
toolIdtool: model-generatorID numérico positivo do projeto local do gerador, não seu UUID nem o ID do produto WooCommerce.
originsimOrigem em que a incorporação é renderizada, por exemplo, https://yourstore.com.
designIdum identificadorID de design do Alter Product. Não combine com orderId.
orderIdum identificadorID de pedido do Customizer. Válido somente para customizer.
cartKey + cartModenãoContexto do carrinho exclusivo do Customizer. cartMode é view ou edit.

Exemplo de solicitação (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 });

Notas

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

Exemplo de resposta

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