Le API permettono a un programma esterno, come il tuo gestionale, un'app di magazzino o uno strumento realizzato dal tuo sviluppatore, di leggere e aggiornare i dati del negozio senza passare dal pannello: le categorie, i prodotti con giacenze e prezzi, gli ordini con il cambio di stato e il tracking. Il programma si presenta al negozio con una chiave che crei tu dal pannello, e può fare solo quello che quella chiave gli permette.

Finché non generi una chiave, nessun programma può usare le API del tuo negozio e non cambia nulla.

Dove si trova

Nel menu a sinistra clicca su Impostazioni; nel Pannello Di Controllo, nella sezione Configurazioni Generali, clicca su API. La pagina si apre sulla scheda API REST v1. La voce API non è presente in tutti i negozi: se nel tuo pannello non la trovi, scrivi all'assistenza.

Se il tuo negozio usava già la vecchia interfaccia XML, accanto trovi anche la scheda API Legacy (XML) con le credenziali di allora: restano attive per i collegamenti che già le usano, ma per un nuovo collegamento usa le API REST e genera una chiave come spiegato qui sotto.

Generare una chiave

In Genera una nuova chiave scrivi nell'Etichetta un nome che ti ricordi a chi hai dato la chiave, per esempio il nome del gestionale o del fornitore: lo ritrovi poi nell'elenco delle chiavi. Poi scegli i Permessi: spunta una risorsa, cioè Categorie, Prodotti o Ordini, per concederla per intero, oppure clicca su Personalizza e spunta solo i permessi che servono. Nel paragrafo successivo trovi cosa permette ciascuno.

Se vuoi, imposta una Scadenza: la chiave funziona fino a quel giorno compreso e poi smette da sola, comodo per un collaboratore che lavora per un periodo limitato. Clicca su Genera chiave.

Copiare la chiave

In alto nella pagina compare la nuova chiave, nascosta dai puntini. Clicca su Copia per copiarla, oppure su Mostra per vederla, e consegnala a chi realizza il collegamento. Trattala come una password: chi ha la chiave può fare tutto quello che i suoi permessi consentono.

La chiave viene mostrata solo questa volta: il pannello ne conserva un'impronta per riconoscerla, ma non può più mostrartela. Se la perdi, genera una nuova chiave e revoca quella vecchia.

Quali permessi concedere

Concedi a ogni programma solo quello che gli serve, e genera una chiave diversa per ogni programma o fornitore: così puoi revocarne una senza fermare le altre.

Categorie

categories:read permette di leggere l'albero delle categorie con i testi in tutte le lingue, categories:write di creare e modificare le categorie, categories:delete di cancellarle.

Prodotti

products:read permette di leggere i prodotti con varianti, immagini, prezzi netti, listini e offerte; products:read_cost aggiunge il prezzo d'acquisto, un dato che di solito non vuoi far vedere a tutti. products:write_stock aggiorna le giacenze, products:write_price aggiorna i prezzi netti e i listini, products:write crea nuovi prodotti e ne modifica qualsiasi campo.

Le giacenze e i prezzi cambiati tramite le API vengono inviati a eBay e agli altri marketplace collegati, come quando li cambi dal pannello. I prodotti creati tramite le API invece non vengono pubblicati su nessun marketplace: li pubblichi tu, quando vuoi.

Ordini

orders:read permette di leggere gli ordini con i dati dei clienti: nomi, indirizzi, e-mail, telefono e dati per la fattura elettronica. Concedilo solo ai programmi e ai fornitori che devono davvero trattare questi dati. orders:read_cost aggiunge il costo delle righe d'ordine.

orders:write_status permette di cambiare lo stato degli ordini, con il codice di tracking e un commento. Valgono le regole degli stati del negozio: uno stato va solo avanti, da In attesa fino a Spedizione Consegnata, un ordine si può annullare da qualsiasi stato e un ordine annullato non torna indietro. Il cliente riceve l'e-mail del cambio di stato solo se il programma la richiede, e il nuovo stato viene comunicato a eBay e agli altri marketplace collegati.

Revocare o riattivare una chiave

In fondo alla pagina trovi l'elenco delle chiavi, con l'etichetta, l'inizio della chiave, i permessi, lo stato, l'ultimo utilizzo, la scadenza e la data di creazione. Ultimo utilizzo ti dice se un programma sta ancora usando la chiave.

Per bloccare subito una chiave clicca su Revoca: da quel momento ogni richiesta fatta con quella chiave viene rifiutata. Fallo quando cambi fornitore o quando temi che la chiave sia finita nelle mani sbagliate. Se ti serve di nuovo, clicca su Riattiva. I permessi di una chiave non si possono modificare: se ne servono altri, genera una nuova chiave e revoca la vecchia.

La documentazione per lo sviluppatore

In cima alla pagina, in Endpoint e documentazione, trovi l'URL di base, cioè l'indirizzo delle API del tuo negozio, e le guide in PDF da passare a chi realizza il collegamento: per categorie, prodotti e ordini c'è una Guida rapida, con i primi passi e degli esempi, e una Documentazione tecnica con tutti i dettagli. Le guide sono in inglese, come si usa per la documentazione tecnica. Ogni chiave funziona solo sul negozio in cui l'hai generata: se hai più negozi, genera una chiave per ciascuno.

Da sapere

Per proteggere il negozio, ogni chiave può fare al massimo 200 richieste al minuto. Le richieste alle API fanno lavorare il server come le visite al sito: un programma che interroga il negozio di continuo fa crescere i consumi, come spiegato in Consumi Server Cloud. Se i consumi salgono dopo aver collegato un programma, chiedi al fornitore di ridurre la frequenza delle richieste.