Vai al contenuto

Postman

Questa pagina contiene le istruzioni su come usare Postman per interagire con le API Amica.

Cos'è Postman?

Citando il sito web di Postman:

Postman is an API platform for building and using APIs. Postman simplifies each step of the API lifecycle and streamlines collaboration so you can create better APIs—faster.

Postman è un client molto diffuso, usato da oltre 25 milioni di sviluppatori in tutto il mondo. È disponibile per Windows, Mac e Linux.

Prerequisiti

Installare Postman

Se non l'hai ancora fatto, scarica e installa Postman. È disponibile anche una versione web, ma per usarla dovrai prima creare un account.

Una volta avviato Postman, è probabile che ti venga chiesto di creare un account (al momento in cui scriviamo puoi saltare questo passaggio, ma è probabile che la cosa cambi in futuro). Un account gratuito sarà sufficiente per le tue esigenze.

Importare la specifica OpenAPI

Postman può importare direttamente la nostra specifica OpenAPI: genera automaticamente una collection con tutti gli endpoint dell'Amica Cloud API, sempre allineata all'API. In Postman scegli Import, incolla l'URL della specifica (https://customerws1.amica20.it/api/v3/swagger.json) e conferma (vedi queste istruzioni sull'importazione). Fatto questo, sei pronto per interagire con le API Amica.

Usare Postman con le API Amica

Per poter usare Postman o altri client REST con le API Amica Cloud, ti servono alcune informazioni in anticipo:

  • Un access token valido
  • La versione dell'API di destinazione (es. v3)
  • L'host che memorizza i dati dell'utente
  • L'ID Azienda di destinazione (potrebbe non essere necessario per alcuni endpoint)

Autenticazione

Dal punto di vista dell'API, Postman è un client come gli altri: ogni richiesta deve includere un access token valido. Per ottenerlo:

  • Registra un'app sull'App Store; per gli esperimenti conviene un'app privata dedicata.
  • Ottieni un access token con uno dei flussi di autenticazione. Il flusso Client Credentials è il più diretto per provare da Postman (puoi anche configurarlo nella scheda Authorization → OAuth 2.0 della richiesta).

Host dell'utente

Il token contiene informazioni sull'host dell'utente. Puoi usare un sito come jwt.io per decodificare il token ed estrarre l'host. L'host dell'Amica Cloud API in produzione è customerws1.amica20.it.

Versione dell'API e ID Azienda

In generale, gli URL delle API Amica Cloud sono fatti così:

https://{host}/api/{version}/{company_id}/endpoint

Negli esempi seguenti, la versione dell'API è v3 e l'ID Azienda è 1.

Esempi di richieste Postman

Impostare il token di autorizzazione

Nell'immagine sottostante ci stiamo preparando a eseguire una richiesta GET verso l'endpoint /articolo/. La prima cosa da fare è aprire la scheda Authorization della richiesta, selezionare Bearer Token come tipo e poi incollare il token ottenuto nel passaggio di Autenticazione descritto sopra:

Impostazione del bearer token della richiesta in Postman

Recuperare un articolo di magazzino (GET)

Una volta impostate l'autorizzazione e gli header richiesti, eseguire una richiesta è semplice.

Nell'immagine sottostante abbiamo navigato l'albero della collection Amica Cloud API fino al nodo GET Articolo. Assicurati di impostare correttamente i valori companyId (Azienda) e id nell'URL.

Recupero di un elemento dall'API Amica con Postman

Il payload della risposta contiene il body dell'oggetto richiesto.

POST, PUT, DELETE

Eseguire richieste POST (aggiunta), PUT (aggiornamento) e DELETE è simile alle richieste GET. Per le operazioni di scrittura come POST e PUT devi fornire nel body della richiesta l'oggetto da aggiungere o aggiornare. Naturalmente, assicurati di cambiare il metodo della richiesta in modo appropriato (se usi la collection dell'API, il metodo sarà già selezionato per te).