Introduzione

Il primo gestionale su smartphone che vende online, anche su Amazon, e comunica con i tuoi clienti.

Con MagazzinoPerfetto puoi:

  • Gestire il tuo negozio direttamente dallo smartphone

  • Semplificare ed automatizzare tutti i processi di codifica, inventario, carico, vendita e molto altro ancora

  • Avere In 48 ore avrai un e-commerce online, personale, completamente sincronizzato con il tuo negozio fisico

  • Accedere ad una dashboard accessibile da qualsiasi dispositivo, con cui monitorare tutto il flusso di vendita, gestire i tuoi clienti, fornitori ed anche i commessi in negozio.

Per permettere ad altri software terzi di interfacciarsi con la piattaforma, abbiamo implementato e rilasciato una serie di API REST, elencate in questo documento.

Nota che l'accesso alle API è strettamente legato dall'avere attivo una licenza in MagazzinoPerfetto https://www.magazzinoperfetto.it/prezzi/
Il numero di richieste API disponibili sono limitate ad un numero giornaliero in base al tipo di abbonamento che si è scelto

HTTP status codes

Di seguito sono riportate gli HTTP status code che possono essere ricevuti da un client dell’API di MagazzinoPerfetto.

Status code Significato

200 OK

Risposta standard per le richieste HTTP andate a buon fine.

403 Forbidden

La richiesta è valida ma il server si rifiuta di soddisfarla. L’utente potrebbe non disporre delle autorizzazioni necessarie per accedere alla risorsa. In tal caso, seguire il paragrafo Autenticazione

500 Limit exceed

La richiesta è valida ma il numero di richieste effettuate ha sforato il limite di richieste previste dall'account.

Autenticazione

Per poter accedere al servizio API di MagazzinoPerfetto è necessario procedere con l’autenticazione, che consiste nell'includere nella richiesta effettuata una chiave API.

Sarà necessario accedere al pannello cloud e generare una chiave API dall'apposito menu

Dopodichè, inserire il token generato nella HEADER della richiesta, con parametro di nome x-api-key

Gestione CORS Policy

Il Cross-Origin Resource Sharing (CORS) è un meccanismo che usa header HTTP addizionali per indicare a un browser che un'applicazione Web in esecuzione su un'origine (dominio) dispone dell'autorizzazione per accedere alle risorse selezionate da un server di origine diversa. Un'applicazione web invia una cross-origin HTTP request quando richiede una risorsa che ha un'origine (protocollo, dominio e porta) differente dalla propria.

Riferimento o altre informazioni: Qui

MagazzinoPerfetto gestisce tali controlli nel modo seguente:

Quando la fonte della richiesta HTTP viene giudicata come non sicura, viene inviata una richiesta di handshake (preflight) con metodo OPTION, che elencherà tutte le caratteristiche richieste per validare il chiamante.
La validazione avverrà tramite i seguenti passaggi:

  • Validazione del metodo: (Access-Control-Allow-Methods) metodi HTTP fuori dall'elenco dei metodi permessi verranno scartati. I metodi HTTP accettati varieranno in base alla API invocata, ma che comunque ciclano tra GET, POST, OPTION.

  • Validazione dell'header: (Access-Control-Allow-Headers) se la richiesta inviata contiene headers non supportati, allora la richiesta non verrà soddisfatta.
    Al momento, la lista di header supportati ed accettati è la seguente:

    • Content-Type
    • X-Amz-Date
    • Authorization
    • X-Api-Key
    • X-Amz-Security-Token

    Se viene inserito un header non supportato, l'errore generato e visibile nella console del browser sarà simile al seguente:
    Access to XMLHttpRequest at 'https://1v7y6w1ki1.execute-api.eu-west-1.amazonaws.com/X/Y' from origin 'ORIGIN' has been blocked by CORS policy: Request header field CAMPO_NON_SUPPORTATO is not allowed by Access-Control-Allow-Headers in preflight response.
  • Validazione dell'origine: (Access-Control-Allow-Origin) lista dei domini di provenienza accettati, settati a Tutti (*)

Articoli

Questa sezione elenca tutti i metodi disponibili per la gestione della risorsa Articolo.

A1. ottieniArticoli

GET https://1v7y6w1ki1.execute-api.eu-west-1.amazonaws.com/get/article

Ottiene la lista delle anagrafiche articoli create in MagazzinoPerfetto.

Richiesta HTTP

GET https://1v7y6w1ki1.execute-api.eu-west-1.amazonaws.com/get/article HTTP/1.1
Accept-Encoding: gzip,deflate
x-api-key: Your-API-Key
Connection: Keep-Alive
	

Parametri Richiesta

Campo Tipo Descrizione Vincoli

max_results

Integer

Intero che indica quanti risultati massimi ritornare

Maggiore di zero

Default: 25

page_number

Integer

Indica il numero di pagina richiesto dall'utente. Utile per eventuali paginazioni

Maggiore di zero

Default: 1

search_key

String

Eventuale chiave di ricerca da applicare alla ricerca

Risposta HTTP

HTTP/1.1 200 OK
Date: Thu, 23 May 2019 13:35:40 GMT
Content-Type: application/json
Content-Length: 96
Connection: keep-alive
x-amzn-RequestId: a4da5d82-7d5f-11e9-8897-19a42a5e3db5
x-amz-apigw-id: aI4yIG5mDoEFnGQ=
x-custom-header: header_api
X-Amzn-Trace-Id: Root=1-5ce6a1a7-6fa0dac81921f322a865c51c;Sampled=0

{
	"result" : true,
	"message" : "Procedura conclusa con successo",
	"response" : {
		"items" : [],
		"message" : ""
	}
}
							

Parametri risposta

Campo Tipo Descrizione

result

Boolean

Indica un esito in stile booleano

message

String

Eventuale informazione che ha prodotto l'esito ricevuto in 'result'

response

Json

Contenitore del risultato finale

response.items

Json Array

Lista dei risultati che la procedura ha prodotto

response.items[i].item_id

String

ID dell'articolo

response.items[i].item_barcode

String

Barcode (EAN) dell'articolo

response.items[i].item_code

String

Codice primario dell'articolo

response.items[i].item_code_2

String

Codice secondario dell'articolo

response.items[i].item_code_3

String

Codice terziario / produttore dell'articolo

response.items[i].item_brand

String

Brand (marca) dell'articolo

response.items[i].item_supplier

String

Lista dei fornitori (ragione sociale) dell'articolo

response.items[i].item_description

String

Descrizione dell'articolo

response.items[i].item_category

String

Lista delle categorie dell'articolo

response.items[i].item_um

String

Unità di misura primaria dell'articolo

response.items[i].item_um_2

String

Unità di misura secondario dell'articolo

response.items[i].item_pieces

Integer

Numero di pezzi per confezione dell'articolo

response.items[i].item_cost

Float

Costo d'acquisto (imponibile) dell'articolo

response.items[i].item_price_no_tax

Float

Prezzo di vendita (imponibile) dell'articolo

response.items[i].item_tax

Float

Aliquota IVA applicata nelle transazioni dell'articolo

response.items[i].item_weight

Float

Peso (in grammi) dell'articolo

response.items[i].item_image_url

String

URL pubblica della principale immagine dell'articolo

response.items[i].item_volume

Float

Volume dell'articolo

response.items[i].item_min_stock

Float

Scorta minima dell'articolo

response.message

String

Eventule messaggio accompagnatorio ai risultati

Clienti

Questa sezione elenca tutti i metodi disponibili per la gestione della risorsa Cliente.

C1. ottieniClienti

GET https://1v7y6w1ki1.execute-api.eu-west-1.amazonaws.com/get/customer

Ottiene la lista dei clienti creati in MagazzinoPerfetto.

Richiesta HTTP

GET https://1v7y6w1ki1.execute-api.eu-west-1.amazonaws.com/get/customer HTTP/1.1
Accept-Encoding: gzip,deflate
x-api-key: Your-API-Key
Connection: Keep-Alive
	

Parametri Richiesta

Campo Tipo Descrizione Vincoli

max_results

Integer

Intero che indica quanti risultati massimi ritornare

Maggiore di zero

Default: 25

page_number

Integer

Indica il numero di pagina richiesto dall'utente. Utile per eventuali paginazioni

Maggiore di zero

Default: 1

search_key

String

Eventuale chiave di ricerca da applicare alla ricerca

Risposta HTTP

HTTP/1.1 200 OK
Date: Thu, 23 May 2019 13:35:40 GMT
Content-Type: application/json
Content-Length: 96
Connection: keep-alive
x-amzn-RequestId: a4da5d82-7d5f-11e9-8897-19a42a5e3db5
x-amz-apigw-id: aI4yIG5mDoEFnGQ=
x-custom-header: header_api
X-Amzn-Trace-Id: Root=1-5ce6a1a7-6fa0dac81921f322a865c51c;Sampled=0

{
	"result" : true,
	"message" : "Procedura conclusa con successo",
	"response" : {
		"items" : [],
		"message" : ""
	}
}
							

Parametri risposta

Campo Tipo Descrizione

result

Boolean

Indica un esito in stile booleano

message

String

Eventuale informazione che ha prodotto l'esito ricevuto in 'result'

response

Json

Contenitore del risultato finale

response.items

Json Array

Lista dei risultati che la procedura ha prodotto

response.message

String

Eventule messaggio accompagnatorio ai risultati

Depositi

Questa sezione elenca tutti i metodi disponibili per la gestione della risorsa Deposito / Destinazione Merce.

D1. contaDepositi

GET https://1v7y6w1ki1.execute-api.eu-west-1.amazonaws.com/get/warehouse/count

Questa funzione ritorna il numero di depositi aziendali presenti nella piattaforma MagazzinoPerfetto

Richiesta HTTP

GET https://1v7y6w1ki1.execute-api.eu-west-1.amazonaws.com/get/warehouse/count HTTP/1.1
Accept-Encoding: gzip,deflate
x-api-key: Your-API-Key
Connection: Keep-Alive
								

Risposta HTTP

HTTP/1.1 200 OK
Date: Fri, 28 Jun 2019 07:20:36 GMT
Content-Type: application/json
Content-Length: 84
Connection: keep-alive
x-amzn-RequestId: 365e1703-9975-11e9-9e2b-4fde437c1ac3
Access-Control-Allow-Origin: *
x-amz-apigw-id: b-rl5F63DoEFTLA=
x-custom-header: header_api
X-Amzn-Trace-Id: Root=1-5d15bfbf-11d6bd257b534f803a1ec095;Sampled=0

{
	"result" : true,
	"message" : "Procedura conclusa con successo",
	"response" : [
		{
			"count" : 6
		}
	]
}
								

Parametri risposta

Campo Tipo Descrizione

result

Boolean

Indica un esito in stile booleano

message

String

Eventuale informazione che ha prodotto l'esito ricevuto in 'result'

response

Json Array

Contenitore del risultato finale

response[0].count

Integer

Numero dei depositi rilevati

D2. ottieniDepositi

GET https://1v7y6w1ki1.execute-api.eu-west-1.amazonaws.com/get/warehouse

Questa funzione ritorna i depositi (o destinazioni merci) presenti nella piattaforma MagazzinoPerfetto

Richiesta HTTP

GET https://1v7y6w1ki1.execute-api.eu-west-1.amazonaws.com/get/warehouse?search_key=Napoli HTTP/1.1
Accept-Encoding: gzip,deflate
x-api-key: Your-API-Key
Connection: Keep-Alive
								

Parametri Richiesta

Campo Tipo Descrizione Vincoli

max_results

Integer

Intero che indica quanti risultati massimi ritornare

Maggiore di zero

Default: 25

page_number

Integer

Indica il numero di pagina richiesto dall'utente. Utile per eventuali paginazioni

Maggiore di zero

Default: 1

search_key

String

Eventuale chiave di ricerca da applicare alla ricerca

Risposta HTTP

HTTP/1.1 200 OK
Date: Wed, 29 May 2019 08:08:04 GMT
Content-Type: application/json
Content-Length: 96
Connection: keep-alive
x-amzn-RequestId: e21d0833-81e8-11e9-9db8-bd50b4af1cd4
x-amz-apigw-id: ab6blG8aDoEF2zA=
x-custom-header: header_api
X-Amzn-Trace-Id: Root=1-5cee3de3-5619f42ed98b3d73cf6eee0b;Sampled=0

{
	"result" : true,
	"message" : "Procedura conclusa con successo",
	"response" : {
		"items" : [
			{
				"item_id": "X.X.X.X",
				"item_code": 1,
				"item_name": "Test Warehouse",
				"item_country": "Italy",
				"item_city": "Rome",
				"item_address": "Address address",
				"item_state": "",
				"item_zone": "",
				"item_note": "First warehouse"
			 }
		],
		"message" : ""
	}
}
								

Parametri risposta

Campo Tipo Descrizione

result

Boolean

Indica un esito in stile booleano

message

String

Eventuale informazione che ha prodotto l'esito ricevuto in 'result'

response

Json

Contenitore del risultato finale

response.items

Json Array

Lista dei risultati che la procedura ha prodotto

response.items[i].item_id

String

ID dell'i-esimo elemento trovato

response.items[i].item_code

Integer

Codice dell'i-esimo elemento trovato

response.items[i].item_name

String

Ragione sociale dell'i-esimo elemento trovato

response.items[i].item_country

String

Nazione dell'i-esimo elemento trovato

response.items[i].item_city

String

Città / Comune / Località dell'i-esimo elemento trovato

response.items[i].item_address

String

Indirizzo dell'i-esimo elemento trovato

response.items[i].item_state

String

Provincia dell'i-esimo elemento trovato

response.items[i].item_zone

String

CAP dell'i-esimo elemento trovato

response.items[i].item_note

String

Eventuali note aggiuntive dell'i-esimo elemento trovato

response.message

String

Eventule messaggio accompagnatorio ai risultati

Fornitori

Questa sezione elenca tutti i metodi disponibili per la gestione della risorsa Fornitore.

F1. ottieniFornitori

GET https://1v7y6w1ki1.execute-api.eu-west-1.amazonaws.com/get/supplier

Ottiene la lista dei fornitori creati in MagazzinoPerfetto.

Richiesta HTTP

GET https://1v7y6w1ki1.execute-api.eu-west-1.amazonaws.com/get/supplier?max_results=1&page_number=1 HTTP/1.1
Accept-Encoding: gzip,deflate
x-api-key: Your-API-Key
Connection: Keep-Alive
	

Parametri Richiesta

Campo Tipo Descrizione Vincoli

max_results

Integer

Intero che indica quanti risultati massimi ritornare

Maggiore di zero

Default: 25

page_number

Integer

Indica il numero di pagina richiesto dall'utente. Utile per eventuali paginazioni

Maggiore di zero

Default: 1

search_key

String

Eventuale chiave di ricerca da applicare alla ricerca

Risposta HTTP

HTTP/1.1 200 OK
Date: Thu, 23 May 2019 13:35:40 GMT
Content-Type: application/json
Content-Length: 96
Connection: keep-alive
x-amzn-RequestId: a4da5d82-7d5f-11e9-8897-19a42a5e3db5
x-amz-apigw-id: aI4yIG5mDoEFnGQ=
x-custom-header: header_api
X-Amzn-Trace-Id: Root=1-5ce6a1a7-6fa0dac81921f322a865c51c;Sampled=0

{
	"result" : true,
	"message" : "Procedura conclusa con successo",
	"response" : {
		"items" : [],
		"message" : ""
	}
}
							

Parametri risposta

Campo Tipo Descrizione

result

Boolean

Indica un esito in stile booleano

message

String

Eventuale informazione che ha prodotto l'esito ricevuto in 'result'

response

Json

Contenitore del risultato finale

response.items

Json Array

Lista dei risultati che la procedura ha prodotto

response.message

String

Eventule messaggio accompagnatorio ai risultati

Magazzino

Questa sezione elenca tutti i metodi disponibili per la gestione della risorsa Magazzino, intesa come gestione dei progressivi di magazzino, quali esistenza, ordinato da clienti, ecc..

M1. ottieniDatiMagazzino

GET https://1v7y6w1ki1.execute-api.eu-west-1.amazonaws.com/get/counters

La funzione restituisce la lista degli ARTICOLI MOVIMENTATI, nonchè i vari progressivi di magazzino ad essi associati.

Richiesta HTTP

GET https://1v7y6w1ki1.execute-api.eu-west-1.amazonaws.com/get/counters?max_results=5&page_number=1&search_item=libro HTTP/1.1
Accept-Encoding: gzip,deflate
x-api-key: Your-API-Key
Connection: Keep-Alive
								

Parametri Richiesta

Campo Tipo Descrizione Vincoli

max_results

Integer

Intero che indica quanti risultati massimi ritornare

Maggiore di zero

Default: 25

page_number

Integer

Indica il numero di pagina richiesto dall'utente. Utile per eventuali paginazioni

Maggiore di zero

Default: 1

search_item

String

Eventuale chiave di ricerca da applicare. Tale chiave filtrerà cercando un ID articolo oppure un codice articolo oppure una descrizione articolo

warehouse_id

String

Eventuale ID del deposito da filtrare.
Per info sui depositi, leggi questo paragrafo

Risposta HTTP

HTTP/1.1 200 OK
Date: Tue, 28 May 2019 15:32:00 GMT
Content-Type: application/json
Content-Length: 83
Connection: keep-alive
x-amzn-RequestId: b9f603a9-815d-11e9-aa93-a7efb415d2d8
x-amz-apigw-id: aZog7HzfjoEFVRQ=
x-custom-header: header_api
X-Amzn-Trace-Id: Root=1-5ced546c-1a89158fd4dad7b268d39960;Sampled=0

{
	"result" : true,
	"message" : "Procedura conclusa con successo",
	"response" : {
		"items" : []
	}
}
								

Parametri risposta

Campo Tipo Descrizione

result

Boolean

Indica un esito in stile booleano

message

String

Eventuale informazione che ha prodotto l'esito ricevuto in 'result'

response

Json

Contenitore del risultato finale

response.items

Json Array

Lista dei risultati che la procedura ha prodotto

response.items[i].item_barcode

String

Codice a barre dell'i-esimo articolo rilevato

response.items[i].item_stock

Float

Esistenza dell'i-esimo articolo rilevato

response.items[i].item_customer_ord

Float

Quantità di Ordinato-Da-Clienti dell'i-esimo articolo rilevato

response.items[i].item_supplier_ord

Float

Quantità di Ordinato-A-Fornitori dell'i-esimo articolo rilevato

response.items[i].item_load

Float

Esistenza positiva (carico) dell'i-esimo articolo rilevato

response.items[i].item_code

String

Codice primario dell'i-esimo articolo rilevato

response.items[i].item_location

JSON

Ubicazioni dell'i-esimo articolo rilevato
NB: Ciascuna riga sarà composta da IDDeposito e Ubicazione. Esempio:
{
ID1 : Ubi1
ID1 : Ubi2
}

Per info sui depositi, leggi questo paragrafo

response.items[i].item_in_transf

Float

Quantità trasferita positiva (DDT Trasferimento IN) dell'i-esimo articolo rilevato

response.items[i].item_min_stock

Float

Scorta minima dell'i-esimo articolo rilevato

response.items[i].item_out_transf

Float

Quantità trasferita negativa (DDT Trasferimento OUT) dell'i-esimo articolo rilevato

response.items[i].item_download

Float

Esistenza negativa (scarico) dell'i-esimo articolo rilevato

response.items[i].item_description

String

Descrizione dell'i-esimo articolo rilevato