Versioni

Con il tempo le API evolvono, vengono aggiunti nuovi metodi, tolti altri e modificate richieste e risposte. Alle applicazioni che usano le API di Open2b Commerce Ready viene garantita la compatibilità con le precedenti versioni grazie al versionamento.

Le seguenti sono le versioni di Open2b Commerce Ready con le versioni delle API supportate:

Open2b Commerce Ready API
2012 v1
2013 v1 e v2
2015 v1 e v2
2016 v2 e v3

Se state realizzando una nuova applicazione, valutate prima di tutto per quale versione di Open2b Commerce Ready la dovete realizzare e dopodiché scegliete la versione più recente supportata delle API.

Se la versione di Open2b Commerce Ready non è l'ultima allora valutate, o proponete al vostro cliente, di fare un aggiornamento alla versione più recente in modo che possiate da subito utilizzare l'ultima versione delle API.

Garanzia di compabilità

La garanzia di compatibilità vi consente di realizzare applicazioni per il vostro negozio o per i vostri clienti con la tranquillità che continueranno a funzionare anche dopo gli aggiornamenti alla piattaforma di commerce elettronico, sempre che la nuova versione di Open2b Commerce Ready supporti la versione delle API da voi usata e comunque tenendo conto di eventuali considerazioni fatte presenti al momento del rilascio dell'aggiornamento.

Cosa garantisce

Con la garanzia di compatibilità ci impegnamo a non modificare i metodi, il formato delle richieste e delle risposte, non verranno cambiati i nomi dei campi, non ne verranno tolti o aggiunti di nuovi, non ne verrà cambiato il tipo e l'ordinamento e non cambieranno i tipi dei messaggi di errore ritornati.

Cosa non garantisce

Pur garantendo quanto indicato in precedenza, a volte le modifiche funzionali alle nuove versioni di Open2b Commerce Ready possono essere tali da non poter garantire lo stesso identico comportamento delle API in tutte le circostanze. In questo caso verrà documentato in dettaglio quali comportamenti diversi delle API ci si deve aspettare, in questo modo potete valutare meglio tempi e condizioni per l'aggiornamento del negozio e dell'applicazione.

Novità versione 3

La versione 3 è stata introdotta con Open2b Commerce Ready a Febbraio 2016. Se avete realizzato applicazioni che usano la versione 1 delle API allora dovete aggiornare le vostre applicazioni affinché usino la versione 2 o 3 delle API in quanto la versione 1 non è più supportata. Se invece avete realizzato applicazioni che usano la versione 2 allora potete:

  1. Non fare nulla. Le vostre applicazioni continueranno a funzionare correttamente in quanto il nuovo Open2b Commerce Ready supporta anche la versione 2 delle API. Fate solo attenzione ai seguenti accorgimenti:
    • Se per le referenze usate il campo stock considerate che internamente ha cambiato tipo da int a decimal con 2 cifre decimali. I metodi delle API versione 2 per compatibilità non ritornano le cifre decimali, ad esempio invece di 23.67 verrà ritornato 23. Inoltre se assegnate a stock un valore maggiore di 999999999 verrà assegnato comunque 999999999.
    • Il metodo commerce.movements.create può ritornare un errore InvalidValue se adjustment è minore di -999999999 o maggiore di 999999999.
    • I metodi commerce.movements.get e commerce.movements.find ritornano adjustment senza le cifre decimali.
    • Se per i prodotti usate i campi minOrder, maxOrder e minQuote considerate che internamente hanno cambiato tipo da int a decimal con 2 cifre decimali. I metodi delle API versione 2 per compatibilità non ritornano le cifre decimali, ad esempio invece di 23.67 verrà ritornato 23.
    • Se usate i metodi commerce.promotions.create e commerce.promotions.update con i campi discountAmount e discountPercent allora verificate che abbiano rispettivamente tipo decimal[8,2](0..) e int(0..99).
  2. Passare alla versione 3 delle API. In questo caso dovete:
    • Sostituite v2 con v3 nella URL delle chiamate.
    • Verificare che tutti i campi passati nella richiesta siano effettivamente presenti nella documentazione del relativo metodo. Le precedenti versioni non verificano che i campi dell'oggetto JSON passato come richiesta effettivamente esistano.
    • Se usate i metodi commerce.products.find e commerce.products.count e in questi usate il campo conditions.keywords allora mettetene il valore all'interno di un array: [ "shirt" ] invece di "shirt" come indicato anche in seguito.
    • Se usate il campi code del prodotto o i campi sku e supplierSKU delle referenze o il campo sku dei documenti allora considerate che in una delle prossime versioni di Open2b Commerce Ready la lunghezza aumenterà da 32 a 40 caratteri. Affinché la vostra applicazione sia compatibile con questo cambiamento, quando verrà introdotto, deve fin da subito gestire una lunghezza massima per questi campi di 40 caratteri anche se al momento è di fatto 32.
    • Se per le referenze usate il campo stock considerate che ha cambiato tipo da int a decimal con 2 cifre decimali e il range dei possibili valori è passato dal precedente 0 → 2147483647 al nuovo 0.00 → 999999999.99.
    • Se per i prodotti usate i campi minOrder, maxOrder e minQuote considerate che hanno cambiato tipo da int a decimal con 2 cifre decimali e il range dei possibili valori è passato dal precedente 1 → 2147483647 al nuovo 0.01 → 999999.99.
    • Se usate il metodo commerce.items.update-stock considerate che il parametro itemsStock ora si chiama stock e che la quantità ha cambiato tipo da int a decimal con 2 cifre decimali e il range dei possibili valori è passato dal precedente 0 → 2147483647 al nuovo 0.00 → 999999999.99.
    • Se usate il campo productsLayout considerate che non ha più columnsOnFirstRow, rows, imageSizeOnFirstRow e showDescriptionOnFirstRow mentre è stato aggiunto products. Ai valori consentiti per imageSize si sono aggiunti Optimal e Large. columns non può più prendere il valore 5 ma solo 1, 2, 3, 4 e 6.
    • Per i movimenti il campo adjustment ha cambiato tipo da intero a decimale e il range dei possibili valori è cambiato dal precedente -2147483648 → 2147483647 al nuovo -999999999.99 → 999999999.99.
    • Se usate il metodo commerce.product-images.find allora:
      • per leggere tutte le immagini ora dovete fare più chiamate perché ora ne vengono ritornate al massimo 1000.
      • per avere la URL di un'immagine dovete leggere il campo resized invece di sizes.
    • Se usate il metodo commerce.product-images.get per leggere l'immagine originale di un prodotto allora adesso dovete usare al suo posto il metodo commerce.product-images.find, individuare l'immagine tra quelle ritornate e quindi recuperare l'immagine originale facendo una GET HTTP direttamente alla sua URL presente nel campo original.
    • Se usate i metodi commerce.product-files.find o commerce.product-files.get per leggere il contenuto di un file di un prodotto allora adesso dovete recuperare il file facendo una GET HTTP direttamente alla sua URL presente nel campo address.
    • Se usate il metodo commerce.product-files.count per leggere il numero di file di un prodotto allora dovrete cambiate la richiesta da {"product":281} a {"conditions":{"product":281}}.
    • Se usate il metodo commerce.departments.update allora considerate che ora il campo largeImage non accetta più immagini di dimensioni fino a 32767 pixel ma solo fino a 2500 pixel. Inoltre il formato GIF non è più supportato.
    • Se usate i metodi commerce.promotions.get e commerce.promotions.find, il campo discountAmount ora ha 3 cifre decimali invece di 2 e il campo discountPercent ha cambiato tipo da int a decimal con 3 cifre decimali.
    • Se usate i metodi commerce.promotions.get e commerce.promotions.find, il campo smallImage può ritornare una immagine con larghezza e altezza fino a 255 pixel invece dei precedenti 200 pixel, e il campo largeImage può ritornare una immagine con larghezza e altezza fino a 2500 pixel invece dei precedenti 500 pixel.
    • Se usate i metodi commerce.tax-areas.create e commerce.tax-areas.update verificate di non impostare a false il campo isActive per l'area fiscale di default perché ritornerebbero un errore.
    • Se usate i metodi di commerce.shipping-methods allora rinominate il campo percentCost di shippingRates in unitCost.
    • Se usate i metodi site.menus.get e site.menus.find rinominate il campo openAsPopup in openAsModal.
    • Se usate i metodi create o update dei documenti (ordini, preventivi, fatture, ricevute e DDT) allora dovete rimuovere il campo taxArea in quanto rimosso. Nelle precedenti versioni anche se il campo era presente non era comunque utilizzato.

Templates

Aggiunti i metodi per la gestione dei templates. In particolare sono stati aggiunti i metodi:

Ricerca prodotti per rilevanza

Per consentire una ricerca sui prodotti per parole chiave con i risulati ordinati per rilevanza, nei metodi commerce.products.find e commerce.products.count il tipo del campo conditions.keywords è cambiato da string ad array di string ed è stato aggiunto relevance come possibile valore per order.

Condizioni sui prodotti

Al campo conditions dei metodi commerce.products.find e commerce.products.count sono stati aggiunti i campi promotion per ritornare solo i prodotti che hanno una determinata promozione applicata, codes per ritornare solo quelli con i codici prodotto indicati e hasZeroPrice per ritornare i prodotti che hanno o meno prezzo zero per il listino indicato.

Al metodo commerce.products.count è stato aggiunto il campo priceList da utilizzare in combinazione con il campo hasZeroPrice di conditions per indicarne il listino prezzi.

Layout dei prodotti

Per supportare al meglio i template responsive, al campo productsLayout, utilizzato da diversi metodi, è stato aggiunto products e sono stati invece rimossi i campi columnsOnFirstRow, rows, imageSizeOnFirstRow e showDescriptionOnFirstRow.

Ai valori consentiti per il campo imageSize di productsLayout si sono aggiunti Optimal e Large.

Ai valori consentiti per il campo columns di productsLayout è stato tolto 5, pertanto i valori consentiti ora sono 1, 2, 3, 4 e 6.

Se si ha bisogno di leggere o aggiornare i vecchi campi di productsLayout, non più presenti nella versione 3, allora si possono chiamare gli stessi metodi ma con la versione 2 delle API.

Aggiornamento dei prezzi

È stato aggiunto il metodo commerce.items.update-prices per aggiornare i prezzi di listino e vendita di più referenze assieme. Si possono aggiornare i prezzi, di un unico listino, per 100 referenze con una sola chiamata.

Codice prodotto e referenza da 32 a 40 caratteri

Per quanto riguarda il campo code del prodotto, i campi sku e supplierSKU delle referenze e il campo sku dei documenti, la lunghezza massima che possono ritornare i metodi per questi campi passa da 32 a 40 caratteri. Invece la lunghezza massima che accettano i metodi nelle richieste rimane di 32.

Ad esempio, come conseguenza di quanto detto, la vostra applicazione deve aspettarsi che un metodo ritorni una referenza con sku lungo 40 caratteri e deve gestire il fatto di non poterla modificare in quanto al momento i metodi nella richiesta consentono solo sku con al massimo 32 caratteri.

Questo particolare comportamento delle API è richiesto per compatibilità con la versione 2. Nel momento in cui la versione 2 non sarà più supportata, verrà introdotta una nuova versione delle API che rimuove queste limitazioni.

Immagini dei prodotti

Per i metodi commerce.products.find, commerce.products.get, commerce.items.find e commerce.items.get ai campi thumbnailImage, smallImage, mediumImage e largeImage è stato aggiunto il campo url2x con l'URL dell'immagine per gli schermi a doppia risoluzione.

Il metodo commerce.product-images.find è stato modificato di conseguenza. Ora ritorna i nuovi campi original e resized. Sono stati invece rimossi i campi baseURL e sizes. Sono stati inoltre aggiunti alla nuova versione del metodo i campi limit e first che limitano il numero di immagini da ritornare a 1000. Le versioni precedenti ritornavano tutte le immagini che soddisfavano le condizioni.

Le immagini dei prodotti ora possono avere una dimensione massima di 2 MB. Nelle precedenti versioni il limite era 1 MB.

È stato aggiunto il metodo commerce.product-images.resize per scalare le immagini dei prodotti alle dimensioni indicate di default nel gestionale.

Il metodo commerce.product-images.get non è più presente.

Giacenze con due cifre decimali

Il campo stock delle referenze ha cambiato tipo da int a decimal consentendo di gestire giacenze con due cifre decimali. Il range dei possibili valori è passato dal precedente 0 → 2147483647 al nuovo 0.00 → 999999999.99. Oltre ai metodi di commerce.items è coinvolto nella modifica anche il metodo commerce.products.create.

Di conseguenza sono cambiati i tipi dei campi minOrder, maxOrder e minQuote del prodotto da int a decimal con 2 cifre decimali. Il range dei possibili valori è passato dal precedente 1 → 2147483647 al nuovo 0.01 → 999999.99.

I metodi commerce.movements.get e commerce.movements.find ritornano adjustment con due cifre decimali e anche il metodo commerce.movements.create accetta adjustment con due cifre decimali.

Inoltre per il metodo commerce.items.update-stock il parametro itemsStock ora si chiama stock e la quantità ha cambiato tipo da int a decimal con 2 cifre decimali e il range dei possibili valori è passato dal precedente 0 → 2147483647 al nuovo 0.00 → 999999999.99.

Unità di misura

Per i prodotti è disponibile il nuovo campo unitOfMeasure che indica l'unità di misura della quantità. L'unità di misura consente sia di mostrare l'unità di misura su cui si basa un prezzo ( es: "23,99/kg", "12,15 a confezione" ) e sia di ordinare quantità con uno o più decimali ( es: "3,19 Kg", "55,9 mq" ). Per la gestione delle unità di misura sono state aggiunti i seguenti metodi:

Codice a barre

Il metodo commerce.items.find ora prende in order anche barcode e -barcode per poter ordinare le referenze in base al codice a barre.

File dei prodotti

Il parametro description del metodo commerce.product-files.update ora non è più obbligatorio.

Il campo file dei metodi commerce.product-files.find e commerce.product-files.get è stato rimosso e adesso dovete recuperare il file facendo una GET HTTP direttamente alla sua URL presente nel campo address.

Il parametro conditions del metodo commerce.product-files.find non è più obbligatorio ed ora è possibile utilizzare il metodo commerce.product-files.count per avere il numero totale dei file e non solo quelli di un determinato prodotto.

Immagini dei reparti

Per il metodo commerce.departments.update il campo smallImage ora può prendere una immagine fino a 2500 pixel invece dei precedenti 255 pixel. Se l'immagine è comunque superiore a 255 pixel viene scalata mantenendone le proporzioni. Il campo largeImage ora può prendere una immagine fino a solo 2500 pixel invece dei precedenti 32767 pixel.

Non sono più supportate le immagini in formato GIF, lo sono quelle in formato JPEG e PNG.

Promozioni

Per le promozioni sul carrello si può fare in modo che vengano applicate solo se il costo totale del carrello è maggiore o uguale ad un minimo importo oppure se è minore o uguale ad un massimo importo. Allo scopo sono stati aggiunti alle promozioni i campi minSubtotal e maxSubtotal.

Nelle promozioni il campo discountAmount ora ha 3 cifre decimali invece di 2 e il campo discountPercent ha cambiato tipo da int a decimal con 3 cifre decimali.

È possibile ora modificare le immagini piccola e larga delle promozioni. Sono stati aggiunti i nuovi campi smallImage e largeImage al metodo commerce.promotions.update. La dimensione massima dell'immagine da caricare è di 2500 pixel. Per l'immagine piccola se la dimensione dell'immagine caricata è superiore a 255 pixel allora l'immagine viene scalata preservandone le proporzioni.

Per i metodi commerce.promotions.get e commerce.promotions.find, il campo smallImage può ritornare una immagine con larghezza e altezza fino a 255 pixel invece dei precedenti 200 pixel, e il campo largeImage può ritornare una immagine con larghezza e altezza fino a 2500 pixel invece dei precedenti 500 pixel.

Il parametro name del metodo commerce.promotions.create non è più obbligatorio.

Produttori

Aggiunto il parametro language ai metodi commerce.producers.get e commerce.producers.find per ritornare i campi del SEO per una sola lingua.

Inoltre il campo name del produttore ora più avere lunghezza zero.

Varianti

Aggiunto il campo showName alle varianti per indicare se il nome della variante deve essere visualizzato o meno assieme ai nomi delle opzioni.

Clienti

Aggiunto il campo canLogin alle condizioni del metodo commerce.customers.find per ritornare solo i clienti che possono fare il login al sito.

Aree fiscali

Ora viene ritornato un errore se si cerca di impostare a non attiva l'area fiscale di default.

Documenti

Il campo taxArea passato come parametro ai metodi create e update dei documenti (ordini, preventivi, fatture, ricevute e DDT) è stato rimosso. Nelle precedenti versioni anche se il campo era presente non era comunque utilizzato.

Metodi di spedizione

Nei metodi di commerce.shipping-methods il campo percentCost di shippingRates è stato rinominato in unitCost e il range di valori è stato esteso dal precendente 0.00 → 99.99 al nuovo 0.000 → 9999999.999.

Pagine

Ai metodi di site.pages sono stati aggiunti due nuovi campi: image e isAlwaysVisible.

I metodi site.pages.find e site.pages.get ora ritornano ProductLayout anche per la pagina di template wish-list.html. Nelle versioni precedenti veniva ritornato null.

Lingue

È stato aggiunto il nuovo campo isDefault al metodo site.languages.find che indica se la lingua è quella di default del sito.

Gestori

Per ogni gestore del negozio è possibile ora indicare la lingua del gestionale. Per questo è stato aggiunto il campo locale ai gestori site.accounts.

Menu

È stato aggiunto il metodo site.menus.update per aggiornare un menù. Sono stati aggiunti i campi description e showTo alle voci dei menù e il campo openAsPopup è stato rinominato in openAsModal.

Banners

I banner ora possono avere una dimensione massima di 500 KB invece di 200 KB. Inoltre il campo link, oltre alle URL che iniziano con http:// e https://, consente ora anche le URL che iniziano con /.

Notifiche

Sono state aggiunte le seguenti notifiche:

Validazione dei campi

Diversamente dalle versioni 1 e 2, viene ritornato un errore UnknownField se l'oggetto passato nella richiesta presenta un campo che non è presente nella documentazione del metodo.

Novità versione 2

La versione 2 delle API introduce nuovi metodi e alcuni piccoli cambiamenti. Se avete realizzato applicazioni che usano la versione 1 delle API allora potete:

  1. Non fare nulla. Le vostre applicazioni continueranno a funzionare correttamente in quanto Open2b Commerce Ready 2013 e 2015 supportano anche la versione 1 delle API.
  2. Passare alla versione 2 delle API. In questo caso dovete:
    • Sostituite v1 con v2 nella URL delle chiamate.
    • Controllate che nel corpo della chiamata siano presenti esclusivamente caratteri UTF-8. La versione 2 ritorna un errore se sono presenti caratteri non UTF-8.
    • Se usate i metodi commerce.items.count e commerce.items.find e in questi usate il campo conditions.product allora sostituitelo con il campo conditions.products come indicato in seguito.
  3. Passare alla versione 3 delle API. In questo caso oltre a fare quanto indicato in precedenza per passare alla versione 2 dovete fare quanto indicato per passare dalla versione 2 alla versione 3 come indicato all'inizio di questa pagina.

La versione 2 è stata introdotta con Open2b Commerce Ready a Settembre 2013. Le seguenti sono le differenze rispetto alla prima versione.

Referenze

Nei metodi commerce.items.count e commerce.items.find il campo conditions.product è diventato conditions.products e ora prende più identificatori di prodotto invece che uno solo.

Ordinamento dei prodotti

È stato aggiunto il nuovo campo sortOrder per gestire l'ordinamento dei prodotti nelle pagine reparti, produttori, promozioni, home e novità.

Ordinamento dei reparti

È stato aggiunto il nuovo campo position per gestire l'ordinamento dei reparti.

Contatti

Aggiunti i metodi per la gestione dei contatti. In particolare sono stati aggiunti i metodi:

Promozioni

Alle promozioni sono stati aggiunti i campi per la gestione del SEO:

Metodi di pagamento e spedizione

È stato aggiunto il nuovo campo isDefault ai metodi di pagamento e ai metodi di spedizione per indicare il metodo selezionato di default nel carrello.

Recensioni e Rating

Sono state aggiunte le recensioni ai prodotti. In particolare sono stati aggiunti i metodi:

Inoltre è stato aggiunto il campo rating per i prodotti e il relativo metodo per aggiornare il rating di più prodotti con una sola chiamata:

Caratteri UTF-8

Diversamente dalla versione 1, viene ritornato un errore (HTTP 400) se sono presenti nel corpo della chiamata dei caratteri non UTF-8.