Sincronizzazione dei prodotti tramite API

La sincronizzazione dei prodotti tramite API consente di automatizzare la creazione e l'aggiornamento dei prodotti del tuo catalogo Connectif da un sistema esterno. Puoi sincronizzare i prodotti singolarmente o eseguire aggiornamenti di massa tramite un file CSV.

In questo articolo imparerai come importare automaticamente i prodotti tramite l'API di Connectif.

Prima di iniziare: casi d'uso

Questa API copre i seguenti casi d'uso:

• Se vuoi creare o aggiornare prodotti singolarmente da un sistema esterno.
• Se vuoi automatizzare periodicamente la sincronizzazione di tutti o gran parte dei tuoi prodotti tramite un file CSV.

PASSO 1. Creazione della chiave API

1. Accedi a Configurazione negozio nel menu laterale sinistro.

2. Nel selettore di schede, vai su "API e accessi IP" e clicca su API Keys.

3. Clicca sul pulsante Crea nuova API Key.

4. Nella sezione Importazioni e prodotti del pannello di creazione, abilita i permessi per "Leggere", "Scrivere" e "Cancellare" in modo massivo.

5. Salva la chiave API e copiala per utilizzarla successivamente nel tuo script di automazione.

PASSO 2. Scelta del metodo di sincronizzazione

(In questo passaggio sceglierai come inviare le informazioni dei prodotti a Connectif a seconda del volume e del modo in cui desideri aggiornare il tuo catalogo).

6. Scegli il metodo di sincronizzazione che meglio si adatta al tuo caso:

• API Prodotti: creare o aggiornare prodotti singolarmente.
• API Importazioni: creare o aggiornare grandi quantità di prodotti tramite un file CSV.

2.1. Sincronizzazione individuale dei prodotti

(In questa sezione configurerai le chiamate all'API Prodotti).

7. Crea lo script di automazione dal tuo sistema e includi in esso la API Key generata nel passaggio precedente.

8. Configura nello script una richiesta HTTP PATCH per creare o aggiornare il prodotto in Connectif: https://api.connectif.cloud/products/product-id/{id}

Nella richiesta, indica:

• La API Key per autenticare la chiamata.
• Il tipo di contenuto application/json.
• Le informazioni del prodotto nel corpo della richiesta.

9. Includi nel corpo della richiesta i seguenti attributi obbligatori:

• name: nome del prodotto.
• productDetailUrl: URL di dettaglio del prodotto, che deve essere accessibile.
• unitPrice: prezzo unitario del prodotto.

Esempio 1

Una volta creata, la richiesta avrà un aspetto simile a questo:

const apiKey = "TU_API_KEY";
const productId = "SKU-12345";
const url = `https://api.connectif.cloud/products/product-id/${productId}`;

const product = {
 name: "Scarpa Running",
 productDetailUrl: "https://www.midominio.com/prodotti/SKU-12345",
 unitPrice: 39.95
};

async function main() {
 const response = await fetch(url, {
   method: "PATCH",
   headers: {
     "Authorization": `apiKey ${apiKey}`,
     "Content-Type": "application/json"
   },
   body: JSON.stringify(product)
 });

 const result = await response.json();
 console.log(result);
}

main();

2.2. Sincronizzazione massiva dei prodotti

(In questa sezione configurerai un'importazione tramite API per creare o aggiornare prodotti in massa).

10. Crea e verifica che il tuo file CSV di importazione rispetti le seguenti condizioni:

• Utilizza la codifica “UTF-8”.
• La prima riga contiene le intestazioni dei campi.
• I dati dei prodotti devono utilizzare gli stessi nomi di campo indicati in questo articolo.

productDetailUrl,productId,name,unitPrice,availability,inStockUnits,brand
https://www.midominio.com/prodotti/SKU-12345,SKU-12345,Scarpa Running,39.95,instock,25,Marca Esempio
https://www.midominio.com/prodotti/SKU-67890,SKU-67890,Scarpa Trail,49.95,outofstock,0,Marca Esempio

11. Crea lo script di automazione dal tuo sistema e includi in esso la API Key generata nel PASSO 1.

12. Configura nello script una richiesta HTTP POST al seguente endpoint: https://api.connectif.cloud/imports/ 

13. Configura la richiesta con i dati necessari per effettuare l'importazione:

• Indica products come tipo di importazione.
• Indica il delimitatore utilizzato nel file CSV.
• Imposta se vuoi sovrascrivere i dati esistenti dei prodotti.
• Imposta se vuoi aggiornare solo i campi vuoti.
• Includi il file CSV che contiene i prodotti che vuoi importare.

14. Esegui la richiesta per avviare l'importazione

Esempio 2

Una volta creata, la richiesta avrà un aspetto simile a questo:

const fetch = require('node-fetch');
const fs = require('fs');
const FormData = require('form-data');

const apiKey = process.env.API_KEY;
const filePath = process.env.FILE_PATH;

async function main() {
   const form = new FormData();

   form.append('type', 'products');
   form.append('delimiter', ',');
   form.append('overrideExisting', 'true');
   form.append('updateOnlyEmptyFields', 'false');
   form.append('file', fs.createReadStream(filePath));

   const response = await fetch('https://api.connectif.cloud/imports', {
       method: 'POST',
       headers: {
           'Authorization': `apiKey ${apiKey}`,
           ...form.getHeaders()
       },
       body: form
   });

   if (!response.ok) {
       console.error(response.status, await response.json());
       process.exit(1);
   }

   const { id, total } = await response.json();

   while (true) {
       const getResponse = await fetch(
           `https://api.connectif.cloud/imports/${id}`,
           {
               method: 'GET',
               headers: {
                   'Authorization': `apiKey ${apiKey}`
               }
           }
       );

       const { success, errors, status } = await getResponse.json();

       console.log(`completed ${success + errors} of ${total}`);

       if (status === 'finished') {
           console.log('Success');
           process.exit(0);
       }

       await new Promise(resolve => setTimeout(resolve, 2000));
   }
}

main().catch(error => {
   console.error(error);
   process.exit(1);
});

Lo script crea un'importazione di prodotti a partire dal file CSV il cui percorso è impostato tramite la variabile d'ambiente FILE_PATH. Per questo, imposta products come tipo di importazione, usa , come delimitatore, sovrascrive i prodotti esistenti e mantiene updateOnlyEmptyFields su false.

Domande frequenti

Posso consultare da Connectif le importazioni effettuate tramite API?

Sì, il motore di importazione è lo stesso utilizzato dall'applicazione Connectif. Pertanto, potrai consultare nell'elenco delle importazioni sia quelle effettuate tramite API sia quelle effettuate da Connectif.

Quante importazioni si possono mettere in coda contemporaneamente?

È possibile mettere in coda un massimo di 10 importazioni contemporaneamente. Quando raggiungi questo limite, dovrai attendere il completamento di un'importazione prima di aggiungerne un'altra alla coda.

Qual è la dimensione massima del file CSV?

Il file CSV può avere una dimensione massima di 50 MB.

Posso eliminare un'importazione tramite API?

Attualmente, è possibile cancellare la cronologia delle importazioni solo negli stati finished o error.

Posso annullare un'importazione tramite API?

Una volta caricato il file tramite API, non è possibile annullare l'importazione.

Continua ad imparare!

Per sfruttare al massimo il potenziale del tuo account Connectif, ti consigliamo di proseguire con i seguenti articoli:

• Sincronizzazione massiva dei prodotti, per scoprire come funziona la sincronizzazione massiva e le differenze tra Web Scraping e Feed di Prodotti. 

• Metodi di sincronizzazione e verifica dei prodotti in Connectif, per conoscere i diversi modi per mantenere aggiornato il tuo catalogo. 

• Sincronizzazione dei Prodotti tramite Feed, per configurare una sincronizzazione massiva tramite un Feed di Prodotti. 

• Sincronizzazione dei Prodotti tramite Web Scraping, per configurare una sincronizzazione massiva tramite Web Scraping.