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 viene garantita la compatibilità con le precedenti versioni grazie al versionamento.

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

Open2b API
2012 v1
2013 v1 e v2
2015 v1 e v2
2016 v2 e v3
2018 v2, v3 e v4
2018 GDPR v2, v3, v4 e v5
2018 Fattura Elettronica v2, v3, v4, v5 e v6
2019 v2, v3, v4, v5 e v6

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

Se la versione di Open2b 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 compatibilità

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 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 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 6

La versione 6 è stata introdotta con Open2b 2018 Fatturazione Elettronica. Se avete realizzato applicazioni che usano la versione 5 allora potete continaure a usare questa versione oppure potete passare alla nuova versione sostituendo v5 con v6 nella URL delle chiamate.

Codice e PEC Destinatario

Con l'introduzione della fatturazione elettronica da Gennaio 2019, sono state apportate modifiche ai clienti e ai documenti per consentire la registrazione del codice e della PEC del destinatario della fattura elettronica.

Ai seguenti è stato aggiunto il nuovo campo invoiceRecipient che può contenere o il codice destinatario o l'indirizzo email della PEC a cui inviare la fattura elettronica:

Novità versione 5

La versione 5 è stata introdotta con Open2b 2018 GDPR. Se avete realizzato applicazioni che usano la versione 4 allora potete continaure a usare questa versione oppure potete passare alla nuova versione sostituendo v4 con v5 nella URL delle chiamate.

Gestione di trattamenti e consensi dei dati personali

Come adeguamento alla nuova normativa sulla privacy (GDPR), la versione 5 delle API introduce nuovi metodi per gestire i trattamenti e i consensi sui dati personali dei clienti.

Si possono definire i trattamenti che vengono fatti sui dati personali dei clienti in modo da visualizzare sul sito la relativa informativa ed eventualmente richiedere il consenso al trattamento. Sono stati aggiunti alle API i seguenti metodi:

Per ogni trattamento e per ogni cliente, ordine e preventivo si possono raccogliere i consensi ricevuti e revocati. Per la loro gestione sono stati aggiunti i seguenti metodi:

Gestione visibilità dei reparti

Con la nuova versione di Open2b è possibile scegliere, per ogni reparto, se questo è visibile sul sito, se è visibile solo se contiene dei prodotti oppure se non deve essere per nulla visibile ad esempio perché lo si sta ancora allestendo.

Allo scopo è stato aggiunto il nuovo campo visibility ai metodi dei reparti.

Metodi di pagamento e spedizione per gruppi clienti

Per le edizioni B2B è ora possibile scegliere per ogni gruppo clienti quali sono i metodi di pagamento e spedizione che il cliente può selezionare nel carrello e nella fase d'ordine.

Allo scopo ai gruppi clienti sono stati aggiunti i nuovi campi paymentMethods e shippingMethods che possono avere come valore una lista rispettivamente di metodi di pagamento e spedizione ai quali il cliente è limitato nella scelta.

Novità versione 4

La versione 4 è stata introdotta con Open2b 2018. Se avete realizzato applicazioni che usano la versione 1 delle API allora dovete aggiornare le vostre applicazioni affinché usino la versione 2, 3 o 4 delle API in quanto la versione 1 non è più supportata, in particolare dovete prima seguire le indicazioni per passare dalla versione 2 alla versione 3. Se avete realizzato applicazioni che usano la versione 3 allora potete:

  1. Continuare ad usare la versione 3 ma con i seguenti accorgimenti:
    • Se usate il metodo commerce.price-lists.update allora considerate che non è più possibile leggere il listino base e il cambio ( sconto o ricarico ) di un listino derivato, il metodo ritorna un errore interno se viene passato come argomento baseList o change.
    • Se usate il metodo commerce.price-lists.get allora considerate che non è più possibile leggere il listino base di un listino derivato, il metodo ritorna un errore interno se il campo fields è null o contiene il campo baseList.
    • Se usate il metodo commerce.price-lists.find allora considerate che non è più possibile leggere il listino base di un listino derivato, il metodo ritorna un errore interno se il campo fields è null o contiene il campo baseList.
    • Se usate il metodo commerce.price-lists.find allora considerate che non è più possibile ordinare i listini ritornati per il listino base, il metodo ritorna un errore interno se il campo order contiene il campo baseList.
    • Se usate i metodi di site.banners allora considerate che i banner non sono più disponibili. Le chiamate ai metodi di site.banners ritornano un errore interno.
    • Se usate i metodi di site.menus allora considerate che i menu non sono più disponibili. Le chiamate ai metodi di site.menus ritornano un errore interno.
    • Gli indirizzi delle pagine del negozio sono cambiati. Se si richiamano i vecchi indirizzi verrà eseguito un redirect (301) ai nuovi indirizzi. Se si vogliono conoscere i nuovi indirizzi allora bisogna leggere il campo canonicalURL delle varie risorse con i metodi get e find della versione 4.
  2. Passare alla versione 4 delle API. In questo caso dovete:
    • Sostituite v3 con v4 nella URL delle chiamate.
    • Se usate i metodi find e non passate il campo limit oppure il campo limit è null allora considerate che questi metodi nella versione 4 vi potranno ritornare più risultati di quanti vi aspettavate in precedenza. Avete due alternative:
      • passare il campo limit con valore massimo previsto dalla versione 3 del metodo chiamato, in genere è 100.
      • continuare a non passare il campo limit o passarlo null e sfruttare il fatto che i metodi con la versione 4 ritornano più risultati di prima.
    • Se usate i metodi di commerce.price-lists allora considerate che quelle che erano le proprietà dei listini ora sono state suddivise tra i listini e i gruppi clienti e pertanto potrebbe essere necessario fare anche delle chiamate ai metodi di commerce.customer-groups.
    • Se usate i metodi di commerce.customers per leggere o modificare il campo priceList allora considerate che questo campo ora si chiama group.
    • Se usate i metodi commerce.customers.create e commerce.customers.update per impostare la password dei clienti e usate il campo cryptedBy con valore "CommerceReady" allora dovete sostituirlo con il valore "Open2b".
    • Se usate il metodo commerce.products.find con il campo order che comprende "position" allora aggiungete "id" dopo "position" per avere i prodotti ordinati nello stesso modo con cui venivano ordinati precedentemente.
    • Se usate il metodi commerce.products.get, commerce.products.find, commerce.items.get e commerce.items.find e leggete il campo departments allora considerate che questo campo non contiene più i livelli di reparto dal reparto superiore fino al reparto finale ma contiene i reparti finali in cui si trova il prodotto. Questo perché ora un prodotto può stare in più reparti. Per avere tutti i reparti da quello di livello più superiore a quello di livello più inferiore si può chiamare il metodo commerce.departments.get leggendo il campo ancestors.
    • Se usate il metodo commerce.products.create allora dovete rinominare il campo department in departments e il valore che passate va messo in un array. Ad esempio se department era 56 allora departments sarà [ 56 ].
    • Se usate il metodo commerce.products.update e passate il campo department allora considerate che è stato rinominato in departments e ora non contiene solo un reparto ma contiene tutti i reparti del prodotto, fino a cinque. Se siete sicuri che il prodotto sta in un solo reparto allora basta seguire le indicazioni del precedente punto. Se il prodotto potrebbe stare in più reparti allora dovrete modificare il vostro programma perché passi al metodo tutti i reparti.
    • Se leggete un prezzo di una referenza o di un prodotto, considerate dove prima ritornava 0.000 come prezzo ora ritorna invece null.
    • Se modificate il prezzo di una referenza, considerate dove prima usavate il valore 0.000 ora dovete usare il valore null per indicare che non ha prezzo.
    • Se usate il metodi commerce.products.get e commerce.products.find per leggere il campo listPrice allora considerate che ora comprende anche le tasse se il relativo gruppo clienti include le tasse.
    • Se usate il metodi commerce.products.get e commerce.products.find per leggere il campo sellingPrice allora considerate che questo campo non è più presente.
    • Se usate il metodi commerce.products.get e commerce.products.find per leggere il campo price allora considerate che è stato rinominato in salePrice e ora comprende anche le tasse se il relativo gruppo clienti include le tasse.
    • Se usate il metodi commerce.items.get e commerce.items.find per leggere il campo listPrice allora considerate che ora ritorna sia i prezzi per i listini prezzo che per i gruppi clienti e che i prezzi per i gruppi clienti comprendono anche le tasse se il relativo gruppo clienti include le tasse.
    • Se usate il metodi commerce.products.get e commerce.products.find per leggere il campo sellingPrice allora considerate che questo campo non è più presente.
    • Se usate il metodi commerce.items.get e commerce.items.find per leggere il campo price allora considerate che ora ritorna sia i prezzi per i listini prezzo che per i gruppi clienti e che i prezzi per i gruppi clienti comprendono anche le tasse se il relativo gruppo clienti include le tasse.
    • Se usate il metodi commerce.items.get e commerce.items.find per leggere il campo costPrice allora considerate che questo campo non è più presente. Al momento dell'aggiornamento alla nuova versione 2018, se almeno un prodotto aveva il prezzo di costo maggiore di zero allora è stato creato un nuovo listino per il prezzo di costo. Pertanto per leggere il vecchio prezzo di costo bisogna leggere il campo price per il listino usato per il prezzo di costo. Il listino per il prezzo di costo è quello chiamato "Costo" ( a meno che non sia stato rinominato o eliminato dopo l'aggiornamento ).
    • Se usate il metodo commerce.items.update-prices per aggiornare i prezzi delle referenze allora con la versione 4 dovete usare al suo posto il metodo commerce.item-prices.update.
    • Se usate i metodi commerce.tax-areas.get e commerce.tax-areas.find per leggere il campo isDefault allora considerate che questo campo non è più presente. L'area fiscale di default ora è l'area fiscale del gruppo clienti di default. Pertanto dovete richiamare il metodo commerce.customer-groups.find con la condizione isDefault a true e indicare taxArea nel campo fields.
    • Se usate i metodi commerce.promotions.create o commerce.promotions.update allora verificate che il campo coupon non contenga spazi all'inizio o alla fine, che il campo elements non contenga elementi duplicati e che la data del campo startTime sia maggiore della data del campo endTime.
    • Se usate i metodi commerce.categories allora considerate che le categorie potrebbero essere state convertite in valori di un attributo ( questo avviene automaticamente all'aggiornamento, se non sono presenti categorie, o in un momento successivo ). Se sono state convertite allora dovete usare al loro posto i metodi di commerce.attribute-values usando come valore per il campo attribute l'identificatore dell'attributo usato per le categorie ( lo si riconosce in quanto la conversione gli assegna il codice "CATEGORY" ).
    • Se usate i metodi commerce.departments.get e commerce.departments.find e leggete il campo parent allora dove vi aspettavate il valore 0 ora viene ritornato null.
    • Se usate i metodi commerce.departments.get e commerce.departments.find e leggete il campo parents allora dovrete modificare il codice in quanto questo campo ora compreden solo gli identificatori dei reparti. Per avere anche i nomi dovete fare una successiva chiamata al metodo commerce.departments.find passando gli identificatori nel campo ids di conditions.
    • Se leggete o modificate i documenti ( ordini, preventivi, fatture, ricevute e DDT ) allora dovrete modificare il campo id in quanto il tipo è cambiato da bigint a int. Se avete dei vecchi identificatori da convertire ai nuovi allora eseguite una operazione di shift a destra di 32 bit ( id >> 32 ) sui vecchi identificatori per ricavare i nuovi. Il viceversa non è possibile. Si noti che l'operazione deve essere eseguita su un intero a 64 bit e pertanto in base al linguaggio di programmazione utilizzato potrebbe essere necessario utilizzare una libreria apposita.
    • Se usate i metodi find dei documenti con il campo address in conditions allora considerate che vi vengono ritornati anche i documenti che hanno come indirizzo email quello indicato in address.
    • Se usate i metodi find e get dei documenti allora considerate che il campo taxClass in items, shippingMethod e paymentMethod non è più presente, al suo posto potete leggere il campo taxCode per poi determinare il corrispondente taxClass chiamando il metodo commerce.tax-classes.find.
    • Se usate il metodo site.languages.delete allora considerate che ora vengono cancellati tutti i testi per le lingue eliminate.
    • Se usate i metodi per leggere, modificare o creare banners e menù allora non potrete più usarli perché non sono più presenti.
    • Se usate il metodo site.templates.find-files allora ponete attenzione che adesso vi ritorna anche i file che contengono più di un punto nel nome (ma comunque non consecutivi).
    • Se ricevete le notifiche site.banners.create, site.banners.delete, site.banners.update o site.menus.update allora non le riceverete più.

Limite del numero di risultati delle find

Quasi tutti i metodi find consentono di indicare, con il parametro limit, il numero massimo di risultati da ritornare.

Se limit è presente ed è compreso tra 1 e 100 allora vengono ritornati al più limit risultati. Se ne vengono ritornati meno di limit allora significa che non ne sono presenti altri. Questo comportamento è lo stesso per tutte le versioni delle API.

Se invece limit non è presente oppure è null allora con le precedenti versioni 2 e 3 la find li ritorna tutti o al più 100, mentre con la versione 4 li ritorna tutti o al più un multiplo di 100.

Etichette

Con la nuova versione delle API è possibile assegnare delle etichette, eventualmente visibili nel gestionale, ai prodotti, ai clienti e ai documenti ( ordini, preventivi, fatture, ricevute e DDT ). Allo scopo sono stati aggiunti i seguenti metodi:

Se una etichetta deve essere mostrata nel gestionale allora è possibile da JavaScript chiamare il metodo Admin.Labels.set tramite Admin SDK per impostarne nome e colore.

URL

Con la nuova versione è possibile gestire le URL del sito tramite i seguenti metodi:

Canonical URL

È stato aggiunto il campo canonicalURL a prodotti, reparti, produttori, promozioni, valori di attributo (ex opzioni), pagine e articoli del blog. Il nuovo campo riporta per ogni lingua del sito l'indirizzo canonico della relativa pagina del sito. L'indirizzo canonico viene inizialmente assegnato da Open2b in base al nome ( del prodotto, reparto ecc... ) e per cambiarlo bisogna o modificare il nome oppure creare un rewrite tramite il metodo site.url-rewrites.set.

Prodotto in più reparti

Con la nuova versione 2018 è possibile aggiungere un prodotto a più reparti, fino a cinque.

Allo scopo il campo department dei prodotti ora si chiama departments ed è la lista di tutti i reparti del prodotto. L'ordine dei reparti viene mantenuto. Inoltre il campo departments ha cambiato significato, mentre prima era il percorso dal reparto superiore al reparto finale in cui si trova il prodotto, nella versione 4 è invece la lista di tutti i reparti del prodotto.

Gruppi clienti

I gruppi clienti sostituiscono i vecchi listini prezzi con la differenza che un gruppo clienti non definisce nessun nuovo prezzo per i prodotti e le referenze. I prezzi da gestire si continuano a definire tramite i listini prezzo mentre nei gruppi clienti sono indicati i listini a utilizzare per i clienti del gruppo. Dove prima si assegnava ad un cliente un listino prezzi ora si assegna un gruppo clienti. Un cliente pertanto come prezzi avrà i prezzi dei listini del gruppo clienti a cui è stato assegnato.

Per ogni gruppo clienti, tramite il campo taxArea, è possibile indicare l'area fiscale da utilizzare per i prezzi mostrati ai clienti.

Per gestire i gruppi clienti sono stati aggiunti i seguenti metodi:

La somma del numero di listini prezzo e del numero dei gruppi clienti non può essere maggiore di 255.

Listini prezzo

Parte delle funzioni dei listini prezzo sono ora state trasferite ai nuovi gruppi clienti. Aggiungere un nuovo listino ora significa avere la possibilità di gestire un nuovo prezzo liberamente modificabile con eventualmente più fasce prezzo per ogni referenza. Non è più possibile associare un listino prezzi ai clienti, per questo ora ci sono i gruppi clienti.

Prezzi

I campi dei prezzi per i prodotti e per le referenze sono cambiati. Per le referenze i campi listPrice, sellingPrice e costPrice sono stati accorpati nell'unico campo price.

Il nuovo campo price delle referenze riporta i prezzi per i listini liberi, derivati e per i gruppi clienti. I prezzi per i listini liberi e derivati sono sempre iva esclusa mentre i prezzi per i gruppi clienti sono iva esclusa o inclusa in base al valore del campo includeTaxes del gruppo clienti.

Per i prodotti il campo price è stato rinominato in salePrice e il campo sellingPrice è stato rimosso. Pertanto i campi dei prezzi dei prodotti ora sono listPrice e salePrice che riportano rispettivamente i prezzi di listino e vendita per i gruppi clienti. I prezzi sono iva esclusa o inclusa in base al valore del campo includeTaxes del gruppo clienti.

Ordinamento prodotti

Il valore "position" del campo order del metodo commerce.products.find ordinava i prodotti per posizione e a parità di posizione per id del prodotto. Nella versione 4, "position" ordina i prodotti solo per posizione.

Clienti

Il campo priceList è stato cambiato in group e ora indica il gruppo clienti invece del listino prezzi.

Aree fiscali

Per le aree fiscali è stato rimosso il campo isDefault in quanto ora l'area fiscale di default per i clienti non registrati è quella indicata nel gruppo clienti di default.

Senza prezzo invece di prezzo zero

Nella precedente versione un prezzo di una referenza poteva essere zero ( "0.000" ) per un listino e in tal caso la referenza e il suo prodotto non erano visibili ai clienti del listino. Nella nuova versione una referenza può non avere prezzo ( null ) per un listino e in tal caso la referenza non sarà visibile ai clienti del listino. Il prodotto, diversamente dalla precedente versione, non sarà visibile solo se nessuna referenza è visibile.

Sconti quantità

La nuova versione consente di gestire gli sconti quantità ossia definire più fasce di prezzo per ogni referenza e listino in base alla quantità ordinata dal cliente.

Per leggere i prezzi delle referenze sono stati aggiunti i seguenti metodi:

Il metodo find ritorna esclusivamente i prezzi della prima fascia, ossia quella con quantità minore, mentre il metodo find-tiers ritorna i prezzi per tutte le fasce compresa la quantità minima di ogni fascia.

Il metodo find è più comodo da usare quando non si gestiscono gli sconti quantità o serve leggere solo il prezzo della prima fascia.

Per aggiornare i prezzi delle referenze sono stati aggiunti i seguenti metodi:

Il metodo update aggiorna esclusivamente il prezzo della prima fascia, ossia quella con quantità minore, mentre il metodo update-tiers aggiorna i prezzi per tutte le fasce compresa la quantità minima di ogni fascia.

Si fa notare che se si assegna ad un prezzo il valore null, allo scopo di rimuovere una referenza da un listino, allora verranno rimossi i prezzi per tutte le fasce. Questo avverrà sia che sia usi il metodo update che il metodo update-tiers.

Con l'introduzione di questi nuovi metodi è stato rimosso il metodo commerce.items.update-prices, al suo posto può essere usato commerce.item-prices.update con le dovute differenze.

Promozioni

Le promozioni si possono ora applicare a tutti i clienti o solo ai clienti di specifici gruppi. Siccome un prodotto di conseguenza può avere più promozioni applicate, una diversa per gruppo clienti, è stato rimosso dal prodotto il campo promotion ed è stato aggiunto il campo promotions che riporta la promozione, o null se non presente, per ogni gruppo clienti.

È stato aggiunto un nuovo tipo di promozione: Shippings. Le promozioni di tipo Shippings vengono applicate alle spedizioni e possono consistere di uno sconto in percentuale, uno sconto fisso o un prezzo fisso sulle spedizioni indicate.

Alle promozioni è stato aggiunto il campo priority per indicare una priorità che può variare da 0 a 100. Se si hanno più promozioni applicabili ora la scelta viene fatta in base a quale promozione ha priorità maggiore mentre nella precedente versione era a discrezione del sistema.

Per le promozioni sui prodotti, reparti e produttori è ora possibile indicare, tramite il nuovo campo discountList, se lo sconto fisso deve essere applicato al prezzo di listino invece che a quello di vendita. Nelle precedenti versioni di Open2b era possibile applicarlo solo al prezzo di listino.

Nella nuova versione, se il gruppo clienti ha una area fiscale o meno determina alcuni comportamenti delle promozioni ad esso applicate:

Il metodo commerce.promotions.find ora consente di leggere solo le promozioni con gli identificatori indicati nel campo ids di conditions.

La versione 4 dei metodi commerce.promotions.create e commerce.promotions.update ritornano un errore se:

Attributi

Ad ogni prodotto è ora possibile associare degli attributi, con i rispettivi valori, da mostrare nella scheda del singolo prodotto sul sito e da usare per l'applicazione dei filtri.

Quelle che prima erano le varianti ora sono gli attributi, il termine variante indica ora un attributo utilizzato in un prodotto come variante. Quelle che prima erano le opzioni ora sono i valori di attributo e, come per le varianti, il termine opzione viene usato per un valore di attributo quando è usato come opzione per una referenza.

I metodi sulle varianti e sulle opzioni sono stati pertanto rinominati in:

Rispetto alle varianti, agli attributi è stato aggiunto il campo position per indicare la posizione dell'attributo nelle URL.

Filtri

Ricerca per codice a barre

Se il campo keywords di conditions del metodo commerce.products.find contiene uno o più codici a barre allora verranno ritornati anche i prodotti che hanno almeno una referenza con uno dei codici a barre indicati. Se la ricerca è per rilevanza questi prodotti saranno i primi nei risultati della ricerca.

Reparti

I campi parent e parents ritornati dai metodi commerce.departments.get e commerce.departments.find sono cambiati. Per i reparti principali, ossia che non hanno reparto genitore, parent è null invece di 0. Invece parents non comprende più i nomi dei reparti genitori ma solo i loro identificatori.

Il metodo commerce.departments.find ora consente di leggere solo i reparti con gli identificatori indicati nel campo ids del nuovo parametro conditions. Il parametro parent è ora un campo di conditions.

Produttori

Il metodo commerce.producers.find ora consente di leggere solo i produttori con gli identificatori indicati nel campo ids del nuovo parametro conditions.

Documenti

L'identificatore dei documenti ( ordini, preventivi, fatture, ricevute e DDT ) ha cambiato tipo da bigint a int e sono cambiati di conseguenza anche gli identificatori dei documenti. Le API v2 e v3 accettano e ritornano i vecchi identificatori mentre le API v4 accettano e ritornano i nuovi identificatori.

I vecchi identificatori sono convertibili ai nuovi identificatori attraverso una operazione di shift a destra di 32 bit: id >> 32. Il viceversa non è possibile. Si noti che l'operazione deve essere eseguita su un intero a 64 bit e pertanto in base al linguaggio di programmazione utilizzato potrebbe essere necessario utilizzare una libreria apposita.

I documenti ora sono ricercabili per email dell'indirizzo di fatturazione tramite il campo address del parametro conditions.

Agli ordini è stato aggiunto il campo ip che indica il numero IP del dispositivo da cui è stato concluso l'ordine.

Ai documenti di trasporto (DDT) sono stati aggiunti i campi goodsAppearance, trackingNumber e transportReason.

Lingue

Quando si cancella una lingua, tramite il metodo site.languages.delete ora vengono rimossi tutti i testi che sono stati in precedenza inseriti per la lingua cancellata.

Pagine

Il metodo site.pages.find ora consente di leggere solo le pagine con gli identificatori indicati nel campo ids del nuovo parametro conditions.

Blog

Al parametro conditions del metodo site.blog-posts.find è stato aggiunto il campo ids per leggere gli articoli con gli identificatori indicati.

Banners e menù

I banner e i menù sono stati rimossi dalla versione 4. Tutti i relativi metodo non sono più disponibili.

Templates

Un path ora può contenere più caratteri punto "." ma comunque sempre non consecutivi.

Notifiche

Sono state aggiunte le seguenti notifiche:

Sono state rimosse le seguenti notifiche:

Novità versione 3

La versione 3 è stata introdotta con Open2b 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 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 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 [ Rimosso dalla versione 4 ] e site.menus.find [ Rimosso dalla versione 4 ] 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 [ Rimosso dalla versione 4 ] 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 [ Rimosso dalla versione 4 ] 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 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 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.

`