bindCommerce API v. 2 - Import Prodotti

L’API import prodotti consente ad un sistema esterno (ad esempio un gestionale di magazzino) di aggiungere e modificare i prodotti su bindCommerce, per poter successivamente essere inviati ai canali di vendita.

Configurazione connettore su bindCommerce

Per consentire al gestionale API di creare ed aggiornare i prodotti su bindCommerce sarà necessario creare una configurazione apposita e il relativo connettore.

Per creare la configurazione andare al menù:

API >> Import prodotti

Cliccare su Aggiungi e compilare i campi come segue:

Nome configurazione: scegliere il nome che si ritiene più adeguato
Tipo d'azione: è possibile scegliere tra - Creazione - Creazione e aggiornamento - Aggiornamento
Informazioni da considerare: Titolo - Descrizione - Descrizione breve - Produttore - Fornitore - Dimensioni e peso - Quantità - Attributi - Tags - Prezzi - Alternative - Immagini - Categorie
Eliminazione dati non trasmessi: Barcode - Immagini - Prodotti
Calcolare quantità prodotto parent dalla somma delle varianti?: opzione che consente di determinare se i prodotti parent dovranno avere la quantità calcolata in base alla somma dello stock delle singole varianti
Calcolare prezzo del parent dal minimo delle varianti?: opzione che consente di determinare se i prodotti parent dovranno avere il prezzo calcolato in base al prezzo più basso delle singole varianti

Cliccare su SALVA E CHIUDI.

Per creare il connettore che consentirà di di importare i prodotti dal gestionale API a bindCommerce è necessario andare al menù:

Processi >> Connettori

Cliccare su Aggiungi e compilare i campi come segue:

Nome connettore: usare il nome che si preferisce
Tipo nodo (tecnologia): API
Nodo: il nodo creato in precedenza
Tipo connettore: API [import prodotti]

Cliccando su SALVA E CONTINUA si avrà accesso agli ulteriori campi da compilare.

Il sistema chiamante dovrà utilizzare la seguente stringa: copiare l’URL presente in questo campo e incollarlo nell’apposito campo sul pannello di controllo del gestionale
Configurazione connettore: selezionare la configurazione creata prima
Filtro prodotti: per creare un filtro sui prodotti si invita a seguire le istruzioni riportate all'interno della guida apposita Filtri sui prodotti

Cliccare su SALVA E CHIUDI.

Chiamata ed autenticazione

La chiamata viene effettuata all’URL generato da bindCommerce per lo specifico connettore (da configurare preventivamente attraverso l’interfaccia di bindCommerce).
L’autenticazione avviene attraverso token assegnato per il nodo API. Il parametro viene trasmesso nell'header della richiesta.

Esempio script PHP per eseguire la chiamata

<?php
ini_set('display_errors', true);
error_reporting(E_ALL);

$strXml = file_get_contents(__DIR__.'/Products.xml');

$curl = curl_init();
curl_setopt_array($curl, array(

CURLOPT_URL => "https://miohost.bindcommerce.cloud/integrator-tool/api/products.php?connector=N",
CURLOPT_SSL_VERIFYPEER => 0,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_VERBOSE => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $strXml,
CURLOPT_HTTPHEADER => array(

"cache-control: no-cache",

"content-type: text/xml",

"token: 0435a03b361d7cc24fc1acacdeaae1d7"

),
));

$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}

Questa chiamata restituisce un json così formato:

[
'status' => success || error
'message' => Stringa con la descrizione del log del connettore
'code' => un codice numerico che esprime successo o fallimento v. di seguito (CHIAMATA DI CONTROLLO DELLO STATO) per un elenco completo
'id_exec' => opzionale - id esecuzione, viene fornito nel caso sia necessario utilizzarlo nella CHIAMATA DI CONTROLLO DELLO STATO
'id_procedure' => opzionale -  id procedura, viene fornito nel caso sia necessario utilizzarlo nella CHIAMATA DI CONTROLLO DELLO STATO
]

File prodotti

Esempio file

<?xml version="1.0" encoding="UTF-8"?>

<Title>6 MATITE PER FALEGNAMI 18CM.</Title>

<DescriptionHtml>6 MATITE PER FALEGNAMI 18CM. COLORE ROSSO</DescriptionHtml>

<Category>Scarpe|Donna|Scarpe da ginnastica</Category>

<Category>Promo</Category>

</Categories>

</Alternative>

</Alternatives>

<Price>

<ListCode>Public</ListCode>

<ListName>Prezzo pubblico</ListName>

</Price>

<Price>

</Price>

<Price>

<ListCode>Sconti quantità</ListCode>

</Price>

<Price>

<ListCode>Sconti quantità</ListCode>

</Price>

<Price>

<ListName>Listino 46</ListName>

</Price>

</Prices>

<Manufacturer>METRICA</Manufacturer>

<MPN />

</Dimensions>

<URL>http://miosito.com/shop/images/341011.jpg</URL>

</Picture>

<URL>http://miosito.com/shop/images/3410116.jpg</URL>

</Picture>

<URL>http://miosito.com/shop/images/3410116.jpg</URL>

</Picture>

</Pictures>

<Name>Materiale</Name>

<Value>Gomma</Value>

</Attribute>

<Name>Colore</Name>

<Value>Rosso</Value>

</Attribute>

<Name>Color</Name>

</Attribute>

</Attributes>

<WarehouseKey>Magazzino Roma</WarehouseKey>

</Warehouse>

<WarehouseKey>Magazzino Milano</WarehouseKey>

</Warehouse>

</Warehouses>

<Title>BRIKO Maschera sci discesa snowboard unisex S3 nero bianco 100383[701]</Title>

<URL>http://miosito.com/shop/images/341011.jpg</URL>

</Picture>

<URL>http://miosito.com/shop/images/3410116.jpg</URL>

</Picture>

<URL>http://miosito.com/shop/images/3410116.jpg</URL>

</Picture>

</Pictures>

</Attribute>

</Attributes>

<Price>

<ListName>Prezzo pubblico</ListName>

</Price>

</Prices>

<WarehouseKey>Magazzino Roma</WarehouseKey>

</Warehouse>

<WarehouseKey>Magazzino Milano</WarehouseKey>

</Warehouse>

</Warehouses>

</Variant>

</Variants>

<Title>Confezione 60 MATITE PER FALEGNAMI 18CM.</Title>

</Derivate>

</Derivatives>

</Product>

….

</Product>

</Products>

<sku>SKUTEST123</sku>

<sku>SKUTEST456</sku>

</Delete>

</bindCommerceProducts>

Campi del file

DICHIARAZIONI GENERALI

Campo	Descrizione
Mode	Tipo di invio: full = invio completo incremental = invio incrementale (parziale)
Products	Contiene uno o più tag <Product>

INFORMAZIONI SUL PRODOTTO

Campo	Descrizione
Language	Lingua nella quale viene descritto il prodotto in formato ISO 639-1 (es. IT)
Code	Codice prodotto / SKU (es. 3410116)
Barcode	Codice a barre (es. 8001066510405)
BarcodeKind	Tipo di codice a barre (es. EAN, UPS, ISBN)
Title	Titolo del prodotto
DescriptionHtml	Descrizione estesa in HTML
ShortDescription	Descrizione breve
Notes	Note
Categories	Gruppo contenente le categorie
Alternatives	Gruppo contenente le descrizioni alternative
Prices	Gruppo contenente i prezzi
Manufacturer	Produttore o Marchio (es. Adidas)
MPN	Manufacturer Product Number, ovvero codice originale del produttore (es. PERT-G-8678)
Supplier	Fornitore (es. Rossi Distribuzioni S.p.A.)
Dimensions	Gruppo contenente le dimensioni
Qty	Quantità a magazzino. Sono accettati sia valori interi, che decimali (con separatore .), es. 1 oppure 55.31 Se un prodotto è strutturato per varianti, aggiornando lo stock della variante verrà automaticamentre calcolato lo stock del relativo prodotto padre come somma dello stock delle varianti.
MetaTitle	Meta Title
MetaDescription	Meta Description
MetaKeywords	Meta Keywords
Warehouses	Gruppo contenente le disponibilità sui magazzini alternativi
Pictures	Gruppo contenente le immagini
Attributes	Gruppo contenente gli attributi
Variants	Gruppo contenente le varianti

CATEGORIA (CONTENUTO NEL TAG < CATEGORY >)

Campo	Descrizione
Category	Alberatura della categoria con separatore pipe Esempio: Scarpe\|Donna\|Scarpe da ginnastica

Se si desidera abbinare più alberature di categorie ad un prodotto, è possibile aggiungere più tag Category

ALTERNATIVA (CONTENUTO NEL TAG < ALTERNATIVE >)

Campo	Descrizione
Language	Lingua nella quale viene descritta l’alternativa del prodotto in formato ISO 639-1 (es. EN)
Title	Traduzione del titolo
DescriptionHtml	Traduzione della descrizione HTML
ShortDescription	Traduzione della descrizione breve
Notes	Traduzione delle note

PREZZO (CONTENUTO NEL TAG < PRICE >)

Campo	Descrizione
ListCode	Codice identificativo del listino (es. Public01) corrispondente alla chiave listino “Key Gest (Chiave listino gestionale ed API)”
ListName	Nome identificativo del listino (es. Pubblico scontato)
Currency	Valuta
Vat	Aliquota IVA (es. 0.2200)
NetPrice	Prezzo IVA esclusa (es. 1.08200)
GrossPrice	Prezzo IVA compresa (es. 1.32000)
OverridePrice	Prezzo scontato (es. 0)
Override	Applicazione prezzo scontato Valori ammessi: 0 = prezzo scontato disabilitato 1 = prezzo scontato abilitato (considera IVA compresa) -1 = prezzo scontato abilitato (considera IVA esclusa) E’ consigliabile l’uso dei valori 0 ed 1 (il caso -1 è difficilmente applicabile ai canali di vendita)
PriceQuantityStart	Limite quantità inferiore
PriceQuantityStart	Limite quantità superiore

La necessità di popolare sia NetPrice che GrossPrice è giustificata dalla certezza di arrotondamento dei valori. Nel caso in cui uno dei 2 valori non dovesse essere compilato (sconsigliato), sarà comunque possibile farlo calcolare a bindCommerce al termine dell’importazione.

Se un prodotto è strutturato per varianti, aggiornando il prezzo della variante verrà automaticamentre calcolato il prezzo relativo prodotto padre come minimo dei prezzi delle varianti.

Relativamente all’identificazione dei listini valgono le seguenti regole:

Se nel file XML è presente solo ListCode viene utilizzata la chiave listino per identificarlo ed abbinarlo a quelli esistenti, oppure eventualmente crearne uno nuovo qualora non si riscontrasse alcun abbinamento (in tal caso il codice listino verrà utilizzato anche come nome dello stesso)
Se nel file XML è presente solo ListName viene utilizzato il nome del listino per identificarlo ed abbinarlo a quelli esistenti, oppure eventualmente crearne uno nuovo (senza chiave, solo con il nome) qualora non si riscontrasse alcun abbinamento
Se nel file XML sono peesenti sia ListCode che ListName, per i confronti viene considerato solo ListCode

DIMENSIONI (CONTENUTO NEL TAG < DIMENSIONS >)

Campo	Descrizione
Weight	Peso (es. 0.50)
WeightUom	Unità di misura del peso (es. Kg)
WeightVolume	Peso volumetrico (es. 0.67). Questo valore viene utilizzato in rare elaborazioni
LwhUom	Unità di misura lineare (es. cm)
Length	Lunghezza (es. 15.12)
Width	Base (es. 32.00)
Height	Altezza (es. 5.00)

MAGAZZINI (CONTENUTO NEL TAG < WAREHOUSE >)

Campo	Descrizione
WarehouseKey	Un identificativo univoco da associare al magazzino. In automatico, la chiamata API assegna il nome seguente che potrà essere visualizzato (e cambiato) nell’interfaccia bind. Esempio se la chiave è “Magazzino Milano” il nome sarà-> Magazzino Milano created by API
Qty	La quantità di prodotto presente nel magazzino avente chiave “WarehouseKey” Se un prodotto è strutturato per varianti, aggiornando lo stock della variante verrà automaticamentre calcolato lo stock del relativo prodotto padre come somma dello stock delle varianti.

IMMAGINI (CONTENUTO NEL TAG < PICTURE >)

Campo	Descrizione
URL	URL assoluto dell’immagine da importare. L’immagine principale viene identificata dall’ordine in base a cui sono inviate. La prima è quella principale.

L’ordine di importazione (che determina l’ordine di esportazione) è determinato dall’ordine dei tag nel file XML, salvo che per l’immagine main, che apparirà sempre per prima).

Ogni immagine può contenere dei tags separati da virgole che devono essere passati nel modo seguente:

ATTRIBUTO (CONTENUTO NEL TAG < ATTRIBUTE >)

Campo	Descrizione
Name	Nome dell’attributo Il nome verrà confrontato con la “Chiave attributo gestionale” presente nella scheda attributo
Value	Valore dell’attributo

Per poter creare un nuovo attributo è necessario che il tag <Attribute lang=”it”> sia completo della lingua

VARIANTE (CONTENUTO NEL TAG < VARIANT >)

Campo	Descrizione
Code	Codice SKU della variante
Barcode	Codice a barre della variante
BarcodeKind	Tipo di codice a barre della variante
Title	Titolo della variante
Qty	Quantità a magazzino della variante
Attributes	Gruppo contenente gli attributi
Prices	Gruppo contenente i prezzi
Warehouses	Gruppo contenente le disponibilità sui magazzini alternativi

PRODOTTI DERIVATI (CONTENUTO NEL TAG < DERIVATIVES >)

Campo	Descrizione
Code	Codice SKU del prodotto derivato
Barcode	Codice a barre del prodotto derivato
BarcodeKind	Tipo di codice a barre
Title	Titolo della variante
PackageQty	Quantità necessarie del prodotto originale
MultiplierPrice	Prezzo

I prodotti derivati sono composti da altri prodotti e a loro volta generano un prodotto.

RICODIFICHE SKU (CONTENUTE NEL TAG < RECODES >)

Campo	Descrizione
CodeExt	Codice esterno a cui si vuole abbinare lo sku del prodotto
NodeId	Nodo bindCommerce per il quale si vuole eseguire la ricodifica
eBaySiteId	id mercato eBay per il quale si vuole eseguire la ricodifica
AmazonMarket	Codice mercato Amazon per il quale si vuole eseguire la ricodifica (es. APJ6JRA9NG5V4)

Ogni singola ricodifica deve essere contenuta nei tag <Recode></Recode>. Il tag <Recode> può avere un attributo “action” impostabile con valore “delete” (<Recode action="delete">) per cancellare una specifica ricodifica precedentemente caricata. L’abbinamento viene fatto con i dati inviati. E’ possibile, per esempio, cancellare tutte le ricodifiche legate ad un nodo inviando solo il tag “NodeId”. Per questo motivo il consiglio è di essere il più precisi possibile con l’invio dei tag, per evitare cancellazioni massive accidentali.

CANCELLAZIONE SPICIFICI SKU (TAG < DELETE >)

Campo	Descrizione
Sku	Sku del prodotto su bindCommerce da contrassegnare come annullato. Tutti i prodotti figlio verranno contrassegnati come annullati.

CHIAMATA DI CONTROLLO DELLO STATO

La chiamata precedente di importazione dei prodotti via API prende in consegna tutti i prodotti e fornisce un risultato di successo solo in merito alla presa in consegna, ma non in merito all’esito finale di importazione. Ciò perché è una chiamata batch che può richiedere diversi minuti. Per controllare invece l’esito dell’importazione occorre invece effettuare una nuova chiamata che fornisce il log di stato dell’esecuzione.

Lo stesso log può essere consultato cliccando sui pulsanti “Connettori” e “In Esecuzione” nell’interfaccia bindCommerce nel menu in alto.

api product import buttons

Per farlo invece a livello programmatico si può usare invece la seguente usando l’id del connettore di cui si vuole conoscere lo stato. N = id del connettore.

In aggiunta al parametro id (che è sempre obbligatorio) è possibile utilizzare i parametri id_exec e id_procedure così come restituiti dalla chiamata precedente (v. Chiamata ed autenticazione).

L’autenticazione avviene attraverso lo stesso token assegnato per il nodo API.

Esempio script PHP per eseguire il controllo del log del connettore

<?php

$curl = curl_init();

curl_setopt_array($curl, array(

CURLOPT_URL => "https://miohost.bindcommerce.cloud/integrator-tool/api/connector_status.php?id=N",

CURLOPT_RETURNTRANSFER => true,

CURLOPT_ENCODING => "",

CURLOPT_MAXREDIRS => 10,

CURLOPT_TIMEOUT => 30,

CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,

CURLOPT_CUSTOMREQUEST => "GET",

CURLOPT_HTTPHEADER => array(

"cache-control: no-cache",

"content-type: text/xml",

"token: 0a09039b989e7b705da2575ec4ae882f"

));

$response = curl_exec($curl);

$err = curl_error($curl);

curl_close($curl);

if ($err) {

echo "cURL Error #:" . $err;

} else {

echo $response;

}

Questa chiamata restituisce un json così formato:

[
'status' => success || error
'message' => Stringa con la descrizione del log del connettore
'code' => un codice numerico che esprime successo o fallimento
]

Nel caso in cui vengano specificati i parametri id_exec oppure id_exec e id_procedure il campo "message" verrà valorizzato con il contenuto del file di log in formato CSV.

Di seguito si riportano i valori del parametro code

200 => nessun connettore in esecuzione

201 => connettore in esecuzione

401 => errore interno

402 => manca il connettore

403 => errore interno

404 => manca il token di autenticazione

405 => token non configurato nel nodo

406 => autenticazione fallita

407 => connettore inesistente

509 => Procedura ( id procedura ) già in esecuzione dal ( data )

3 su 5 - 4 valutazioni

Grazie per aver valutato questo contenuto.

Servizio online self service

Servizio chiavi in mano

Import prodotti

bindCommerce API v. 2 - Import Prodotti

Configurazione connettore su bindCommerce

Chiamata ed autenticazione

File prodotti

Campi del file

DICHIARAZIONI GENERALI

INFORMAZIONI SUL PRODOTTO

CATEGORIA (CONTENUTO NEL TAG < CATEGORY >)

ALTERNATIVA (CONTENUTO NEL TAG < ALTERNATIVE >)

PREZZO (CONTENUTO NEL TAG < PRICE >)

DIMENSIONI (CONTENUTO NEL TAG < DIMENSIONS >)

MAGAZZINI (CONTENUTO NEL TAG < WAREHOUSE >)

IMMAGINI (CONTENUTO NEL TAG < PICTURE >)

ATTRIBUTO (CONTENUTO NEL TAG < ATTRIBUTE >)

VARIANTE (CONTENUTO NEL TAG < VARIANT >)

PRODOTTI DERIVATI (CONTENUTO NEL TAG < DERIVATIVES >)

RICODIFICHE SKU (CONTENUTE NEL TAG < RECODES >)

CANCELLAZIONE SPICIFICI SKU (TAG < DELETE >)

CHIAMATA DI CONTROLLO DELLO STATO

Guide

bindCommerce s.r.l.

Informazioni

In evidenza