Vai al contenuto

curl

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

Cos'è curl?

curl è uno strumento a riga di comando e una libreria per trasferire dati da o verso un server tramite URL. Supporta moltissimi protocolli, HTTPS incluso. Sebbene il suo utilizzo possa risultare non immediatamente ovvio a chi non lo conosce, è in circolazione fin dai primi tempi dell'informatica ed è supportato su ogni tipo di piattaforma.

Citando il sito web:

curl is also used in cars, television sets, routers, printers, audio equipment, mobile phones, tablets, medical devices, settop boxes, computer games, media players and is the Internet transfer engine for thousands of software applications in over twenty billion installations. curl is used daily by virtually every Internet-using human on the globe.

curl è ovunque.

Usare curl con le API Amica

Per poter usare curl o altri semplici 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, curl è 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. Per provare velocemente con curl, il flusso Client Credentials è il più diretto:

    curl -X POST 'https://auth.amica20.it/connect/token' \
    -d 'grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>&scope=read write'

La risposta contiene l'access_token da inviare poi nell'header Authorization: Bearer.

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 curl

Recuperare un elenco di nazioni (GET, con query)

curl -i -X GET --location 'https://{host}/api/v3/1/nazione?filter=nome%20%24ct%20cina' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

HTTP/1.1 200 OK
{"$id":"1","$values":[{"$id":"2","nome":"Cina","id":1176,"concurrencyToken":838276}]}

Note

La parte di query dell'URL (?filter=nome $ct cina, ovvero "nome contiene cina") va inviata codificata in URL: ?filter=nome%20%24ct%20cina.

Recuperare un articolo di magazzino (GET)

curl -i -X GET --location 'https://{host}/api/v3/1/articolo/'  \
    -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

HTTP/1.1 200 OK
{"$id":"1","categoriaMerceologicaId":null,"categoriaMerceologica":null,"gruppoMerceologicoId":null,"gruppoMerceologico":null,"causaleIvaId":null,"causaleIva":null,"tagliaId":null,"taglia":null,"marcaId":null,"marca":null,"produttoreId":null,"produttore":null,"repartoId":null,"reparto":null,"nome":"Alveari per Scatole Medie","codice":"CELM","nomeBreve":"Alveari Scatole Medie","codiceFornitore":null,"codiceProduttore":null,"gestioneArticolo":"Standard","contestoArticolo":"Sempre","barCode":null,"costoUltimo":0.2,"costoMedio":0.2,"unitàMisuraIntera":false,"articoloComposto":false,"stato":true,"dataInserimento":"2005-01-11T00:00:00Z","unitàMisuraMovimenti":"N","unitàMisuraInventario":"N","fattoreConversioneUnitàMisura":1,"note":null,"mediaFile":null,"contoRawVendita":null,"contoRawAcquisto":null,"distintaBase":null,"id":1,"concurrencyToken":835853}

Aggiornare un articolo di magazzino (PUT)

curl -i -X PUT --location 'https://{host}/api/v3/1/articolo/1' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
    --data '{"categoriaMerceologicaId":null,"categoriaMerceologica":null,"gruppoMerceologicoId":null,"gruppoMerceologico":null,"causaleIvaId":null,"causaleIva":null,"tagliaId":null,"taglia":null,"marcaId":null,"marca":null,"produttoreId":null,"produttore":null,"repartoId":null,"reparto":null,"nome":"Alveari per Scatole Medie","codice":"CELM","nomeBreve":"Alveari Scatole Medie","codiceFornitore":null,"codiceProduttore":null,"gestioneArticolo":"Standard","contestoArticolo":"Sempre","barCode":null,"costoUltimo":0.2,"costoMedio":0.2,"unitàMisuraIntera":false,"articoloComposto":false,"stato":true,"dataInserimento":"2005-01-11T00:00:00Z","unitàMisuraMovimenti":"N","unitàMisuraInventario":"N","fattoreConversioneUnitàMisura":1,"note":null,"mediaFile":null,"contoRawVendita":null,"contoRawAcquisto":null,"distintaBase":null,"id":1,"concurrencyToken":835853}'

HTTP/1.1 200 OK
{"$id":"1","categoriaMerceologicaId":null,"categoriaMerceologica":null,"gruppoMerceologicoId":null,"gruppoMerceologico":null,"causaleIvaId":null,"causaleIva":null,"tagliaId":null,"taglia":null,"marcaId":null,"marca":null,"produttoreId":null,"produttore":null,"repartoId":null,"reparto":null,"nome":"Alveari per Scatole Medie","codice":"CELM","nomeBreve":"Alveari Scatole Medie","codiceFornitore":null,"codiceProduttore":null,"gestioneArticolo":"Standard","contestoArticolo":"Sempre","barCode":null,"costoUltimo":0.2,"costoMedio":0.2,"unitàMisuraIntera":false,"articoloComposto":false,"stato":true,"dataInserimento":"2005-01-11T00:00:00Z","unitàMisuraMovimenti":"N","unitàMisuraInventario":"N","fattoreConversioneUnitàMisura":1,"note":null,"mediaFile":null,"contoRawVendita":null,"contoRawAcquisto":null,"distintaBase":null,"id":1,"concurrencyToken":835854}

Rimuovere un articolo di magazzino (DELETE)

curl -i -X DELETE --location 'https://{host}/api/v3/1/articolo/1' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

HTTP/1.1 204 No Content

Aggiungere una nazione (POST)

curl -i --location 'https://{host}/api/v3/1/nazione' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
    --data '{ "nome": "Cina" }'

HTTP/1.1 201 Created
{"$id":"1","nome":"Cina","id":1176,"concurrencyToken":838276}