Introduzione

Questo articolo guida gli utenti su come creare un prodotto utilizzando le API pubbliche fornite da HITLEAD. Approfondisce anche i casi d'uso e le varie tipologie di prodotto di cui puoi avvalerti durante la creazione.

Prodotti

I prodotti sono una delle entità principali in HITLEAD: consentono di vendere ciò che desideri attraverso diversi canali di vendita, tra cui E-commerce Store, Fatture, Preventivi e altro ancora.

Tipologie di Prodotto

In HITLEAD esistono principalmente due tipi di prodotto:

  • Prodotti con prezzo
  • Prodotti con varianti

Prodotti con Prezzo

Sono prodotti semplici, privi di varianti. Qualsiasi prodotto che non richiede varianti (o) ha una sola classificazione di variante può essere creato in questo formato. Un esempio tipico è un poster disponibile in più formati.

Prodotti con Varianti

Sono prodotti che presentano molteplici variazioni per un singolo articolo. Un esempio tipico è una t-shirt disponibile in più colori e taglie.

Creare un Prodotto tramite API Pubblica

Autorizzazione

Per eseguire operazioni CRUD (Create, Read, Update, Delete) sulle entità di HITLEAD tramite API pubblica, è necessario un access token. Il processo di autorizzazione è spiegato al seguente link:

Creazione del Prodotto

Per creare un prodotto utilizzeremo le seguenti API pubbliche:

  • Crea un Prodotto -
  • Crea un Prezzo per il Prodotto -

Si consiglia di seguire l'ordine dei contenuti per creare correttamente un prodotto.

Creare il Prodotto

Per prima cosa devi creare un prodotto usando la Create a Product API. Di seguito le proprietà fondamentali richieste per la creazione del prodotto:

  • name — nome del prodotto
  • locationId — il sub-account per cui viene creato il prodotto
  • description — breve descrizione del prodotto, utile nei canali di vendita per presentarlo
  • productType — imposta come DIGITAL
  • image — immagine in evidenza mostrata di default al cliente finale
  • availableInStore — indica se il prodotto deve essere disponibile negli E-commerce Store
  • medias — array
    • id — identificatore univoco del media
    • title — titolo del media
    • url — URL sorgente del media
    • type — attualmente è supportata solo l'immagine
    • isFeatured — imposta a true se deve essere mostrato al cliente finale
  • variants — richiesto solo per prodotti con varianti
    • id — ID univoco della variante
    • name — nome della variante
    • options — array
      • id — ID univoco dell'opzione di variante (necessario per la creazione del Prezzo)
      • name — nome dell'opzione

Esempio di Payload per Prodotto con Prezzo:

{
  "name": "High Speed Memory Drive",
  "description": "A high speed memory drive with latest safety features and breath taking design",
  "locationId": "<sub-account_ID>",
  "availableInStore": true,
  "productType": "PHYSICAL",
  "image": "https://via.placeholder.com/150",
  "medias": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "High Speed Memory Drive",
      "url": "https://via.placeholder.com/150",
      "type": "image",
      "isFeatured": true
    }
  ]
}

Esempio di Payload per Prodotto con Varianti:

{
  "name": "T-shirt",
  "description": "Latest t-shirt with latest design and quality",
  "locationId": "<sub_account_id>",
  "availableInStore": true,
  "productType": "PHYSICAL",
  "image": "https://via.placeholder.com/150",
  "medias": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "T-shirt",
      "url": "https://via.placeholder.com/150",
      "type": "image",
      "isFeatured": true
    }
  ],
  "variants": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Color",
      "options": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440002",
          "name": "Red"
        },
        {
          "id": "550e8400-e29b-41d4-a716-446655440001",
          "name": "Blue"
        },
        {
          "id": "550e8400-e29b-41d4-a716-446655440003",
          "name": "Green"
        }
      ]
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440111",
      "name": "Size",
      "options": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440112",
          "name": "Small"
        },
        {
          "id": "550e8400-e29b-41d4-a716-446655440113",
          "name": "Medium"
        },
        {
          "id": "550e8400-e29b-41d4-a716-446655440114",
          "name": "Large"
        }
      ]
    }
  ]
}

Nota: per i prodotti con varianti, tieni traccia degli ID delle opzioni: saranno fondamentali durante la creazione del prezzo.

Dopo aver creato il prodotto, riceverai una risposta contenente la proprietà _id, che rappresenta il productId appena creato. Questo valore sarà utilizzato per creare il prezzo del prodotto.

Creare il Prezzo per un Prodotto

Useremo la Create Price for a Product API per creare un prezzo per il prodotto. Di seguito le proprietà fondamentali richieste:

  • product — ID del prodotto per cui viene creato il prezzo
  • locationId — ID del sub-account
  • name — nome del prezzo
  • type — poiché sono supportati anche i prodotti ricorrenti, i valori disponibili sono one_time e recurring
  • currency — valuta del prezzo
  • amount — importo nella valuta indicata
  • description — descrizione del prezzo
  • variantOptionIds — richiesto per prodotti con varianti
    • Ad esempio, se la combinazione di variante è Red/Small, i valori di variantOptionIds devono essere:
  ["550e8400-e29b-41d4-a716-446655440002","550e8400-e29b-41d4-a716-446655440112"]
  • dove 550e8400-e29b-41d4-a716-446655440002 corrisponde a Red e 550e8400-e29b-41d4-a716-446655440112 corrisponde a Small
  • Per i prodotti con varianti, variantOptionIds è obbligatorio per il corretto rendering delle combinazioni; l'assenza di questa proprietà causerà un rendering errato
  • trackInventory — imposta a true se è necessario tracciare l'inventario
  • availableQuantity — quantità disponibile, applicabile se trackInventory è true
  • allowOutOfStockPurchases — consente acquisti anche se il prodotto è esaurito; applicabile solo se trackInventory è true
  • sku — SKU del prezzo (o) della variante
  • isDigitalProduct — true se si tratta di un prodotto digitale
  • shippingOptions — proprietà di spedizione per prodotti PHYSICAL (utile per le integrazioni di spedizione)
    • weight — opzioni di peso
      • value — valore del peso
      • unit — unità di misura. Valori supportati: kg, g, lb, oz
    • dimensions — dimensioni del prodotto fisico
      • height — numero
      • width — numero
      • length — numero
      • unit — unità di misura per le dimensioni. Valori supportati: cm, in, m

Esempio di Payload per Prezzo Semplice (Senza Varianti):

    {
  "product": "66b6021be68f7a98102ba272",
  "locationId": "<sub_account_id>",
  "name": "256 GB",
  "type": "one_time",
  "currency": "USD",
  "amount": 100,
  "description": "256 GB of storage",
  "sku": "PS-256GB",
  "isDigitalProduct": false,
  "shippingOptions": {
    "weight": {
      "value": 100,
      "unit": "g"
    },
    "dimensions": {
      "length": 10,
      "width": 10,
      "height": 10,
      "unit": "cm"
    }
  }
}

Esempio di Payload per Prezzo di Prodotto con Varianti

{
  "product": "66b6021be68f7a98102ba272",
  "locationId": "<sub_account_id>",
  "name": "Red / Small",
  "type": "one_time",
  "currency": "USD",
  "amount": 100,
  "description": "Red / Small",
  "sku": "PS-RED-SMALL",
  "isDigitalProduct": false,
  "variantOptionIds": ["550e8400-e29b-41d4-a716-446655440002","550e8400-e29b-41d4-a716-446655440112"],
  "shippingOptions": {
    "weight": {
      "value": 100,
      "unit": "g"
    },
    "dimensions": {
      "length": 10,
      "width": 10,
      "height": 10,
      "unit": "cm"
    }
  }
}

Nota: gli ID delle opzioni di variante sono necessari per il corretto rendering delle variazioni del prodotto.

Aggiungere un'Immagine a una Variante tramite API Pubblica

Questa funzionalità è disponibile solo per i prodotti con varianti, non per quelli con prezzo semplice. Dopo aver creato il prezzo per un prodotto, nella risposta otterrai l'ID interno del prezzo. Utilizzando tale ID, aggiornerai le immagini per varianti specifiche. Con i priceId ricevuti, aggiorna nuovamente il prodotto con il payload seguente.

Esempio di Payload per Aggiornamento Media del Prodotto con PriceId

Nel payload del prodotto è presente un array medias. Ogni elemento dell'array dispone di una proprietà chiamata priceIds, che è a sua volta un array. Assegnando i rispettivi priceId, il media verrà automaticamente associato alle varianti corrispondenti.

{
  "name": "T-shirt",
  "description": "Latest t-shirt with latest design and quality",
  "locationId": "<sub_account_id>",
  "availableInStore": true,
  "productType": "PHYSICAL",
  "image": "https://via.placeholder.com/150",
  "medias": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "T-shirt",
      "url": "https://via.placeholder.com/150",
      "type": "image",
      "priceIds": ["<created_price_Id>"],
      "isFeatured": true
    }
  ],
  "variants": [
   {...existing variants data}
  ]
}

Al momento è supportata la mappatura di una sola immagine per priceId. Associare più priceId a una singola immagine causerà problemi nel rendering dei prodotti.

Conclusione

Tramite le API descritte sopra è possibile creare un prodotto fisico ONE TIME di base, sia con prezzo semplice che con varianti. La flessibilità non si esaurisce qui: poiché HITLEAD supporta anche i prodotti ricorrenti, puoi consultare la documentazione dell'API Price in dettaglio e sfruttare le proprietà specifiche previste per i prodotti ricorrenti.