API - Panoramica

API - Risorse e importazioni

Esplora il catalogo delle risorse, recupera manifest e file e importa progetti.

Panoramica degli endpoint

MetodoEndpointDescrizioneAccesso
GET/public-api/v1/assetsElenca gli elementi del catalogo delle risorse per il tipo richiesto.qualsiasi credenziale autenticata
GET/public-api/v1/assets/:type/:assetIdRestituisce un manifesto della risorsa con i ruoli dei file scaricabili.qualsiasi credenziale autenticata
GET/public-api/v1/assets/:type/:assetId/files/:roleScarica un file di risorsa in base al ruolo.qualsiasi credenziale autenticata
GET/public-api/v1/design-importsElenca i design ospitati su Alter disponibili per l'importazione.credenziale autenticata, piano Business richiesto
GET/public-api/v1/design-imports/:idRestituisce un payload di importazione del design e descrittori dei file.credenziale autenticata, piano Business richiesto
GET/public-api/v1/design-imports/:id/files/:fileIdScarica un file da un descrittore di importazione del design.credenziale autenticata, piano Business richiesto

Catalogo delle risorse

Il catalogo delle risorse espone risorse originali dei prodotti, sfondi, ambienti, elementi della libreria grafica, modelli di design e risorse mockup. Gli endpoint di elenco restituiscono descrittori leggeri; quelli di dettaglio includono manifesti dei file.

TipoDescrizione
productsRisorse base del prodotto, anteprime, modelli 3D e descrittori di materiali e texture.
backgroundsSfondi statici del Viewer.
environmentsMappe ambientali e immagini di anteprima.
image_libraryRisorse della libreria grafica, incluse grafiche limitate al negozio.
design_templatesAnteprime dei modelli di design e riferimenti ai file dei livelli. Supporta il filtro product_id.
mockupsRisorse del generatore di mockup, sfondi e mappe di sovrapposizione. Supporta il filtro product_id.

Esempio di richiesta (fetch)

const assets = await alterFetch('/assets?' + new URLSearchParams({
  type: 'products',
  limit: '20',
  offset: '0',
  search: 'mug'
}));

const details = await alterFetch('/assets/products/4');

const fileResponse = await fetch(
  'https://alterproduct.com/public-api/v1/assets/products/4/files/preview_medium',
  {
    headers: authHeaders
  }
);

const fileBlob = await fileResponse.blob();

Esempio di risposta

{
  "type": "products",
  "items": [
    {
      "assetType": "products",
      "assetId": "4",
      "title": "Mug 450ml",
      "slug": "product-4",
      "description": "Base product 4",
      "primaryRole": "preview_big",
      "fileCount": 8,
      "remoteVersion": "1.0",
      "thumbnail": {
        "role": "preview_small",
        "fileName": "product-4-preview-small.png",
        "mime": "image/png",
        "downloadPath": "/v1/assets/products/4/files/preview_small"
      },
      "metadata": {
        "productCategoryId": 2,
        "productModelCount": 1,
        "isDedicated": false
      }
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Importazioni di design

Le importazioni di design espongono i design ospitati su Alter e i relativi file per flussi esterni di produzione o migrazione. L'API verifica l'idoneità del piano Business.

ParametroObbligatorioDettagli
searchnoCerca per titolo o ID del design.
offsetnoPredefinito 0.
limitnoPredefinito 20, massimo 100.

Esempio di richiesta (fetch)

const imports = await alterFetch('/design-imports?' + new URLSearchParams({
  limit: '20',
  offset: '0',
  search: 'mug'
}));

const details = await alterFetch('/design-imports/381');

const fileId = details.files[0].id;
const fileResponse = await fetch(
  `https://alterproduct.com/public-api/v1/design-imports/381/files/${fileId}`,
  {
    headers: authHeaders
  }
);

const fileBlob = await fileResponse.blob();

Esempio di risposta

{
  "eligible": true,
  "requiredPlan": "Business",
  "currentPlanName": "Business",
  "designs": [
    {
      "id": 381,
      "title": "Men's T-Shirt",
      "createdAt": "2026-01-03T23:55:05.000Z",
      "sourceStorefrontId": 12,
      "productId": 4,
      "productName": {
        "pl": "Koszulka",
        "en": "T-Shirt"
      },
      "storageMode": "alter",
      "runtimeStatus": {
        "designer": true,
        "viewer": true,
        "configurator": true,
        "customizer": true
      },
      "thumbnail": {
        "kind": "design-mockup",
        "fileId": "7df7...",
        "downloadPath": "/v1/design-imports/381/files/7df7..."
      }
    }
  ],
  "total": 1
}