Maxpho Commerce 11 Application Program Interface - API Instant Notifcation Service - INS Data : 20 / 09 / 2011 Versione : 1.2 Autore: Maxpho Srl
Indice generale 1 - Introduzione... 3 1.1 - Struttura di interazione API... 4 1.2 - Struttura di interazione INS... 4 2 - API...5 2.1 - Struttura di una richiesta API...5 2.2 - Lista chiamate API supportate... 6 3 - Instant Notification Service... 7 3.1 - Struttura di interazione INS... 7 3.2 - Casi d'uso... 7 Pag. 2 di 8
1 Introduzione Maxpho API è un'interfaccia che permette di collegare applicativi esterni a Maxpho Commerce, in modo da consentirne la configurazione e l'aggiornamento direttamente da un applicativo esterno. Maxpho API è web-service che offre un servizio remoto in grado di processare transazioni provenienti da chiamate esterne. I vantaggi principali derivanti dall'utilizzo di chiamate API nell'interfacciamento con Maxpho sono: Semplicità di interazione: il vantaggio principale derivante dall'utilizzo di chiamate API è la semplicità. Attraverso la costruzione di un messaggio XML relativo al tipo di richiesta che si intende fare e notificandola all'application entry-point, Maxpho provvederà a processare la transazione e a fornire un risultato (successo / insuccesso e dettagli del risultato) mediante un tipo di interazione state-less. Sicurezza: ciascuna chiamata API è composta da una parte di HeadStack che prevede un meccanismo di autenticazione del mittente della richiesta. L'autenticazione è fornita mediante un token di autenticazione con lease con durata biennale che l'applicativo esterno deve utilizzare in ciascun interfacciamento con l'interfaccia Maxpho API. Indipendenza dall'applicativo di interfacciamento: qualsiasi applicativo esterno può interfacciarsi con Maxpho API, gli unici requisiti richiesti sono una libreria XML per la costruzione delle chiamate e conoscenze base nella struttura di una chiamata API tra un'applicazione client-server. Questo sistema è particolarmente pensato per scenari in cui è necessario avere una elevata sincronizzazione tra il magazzino fisico e quello virtuale dell'applicativo Maxpho Commerce. Tra i servizi offerti dall'interfacciamento si distinguono due servizi fondamentali: Aggiornamento del magazzino virtuale: tramite chiamate API l'applicativo esterno può aggiungere prodotti, aggiornarne le informazioni e rimuoverli. Aggiornamento del magazzino fisico: il sistema di interfacciamento prevede la configurazione di un indirizzo di notifica a cui il sistema provvederà a notificare le variazioni delle quantità a magazzino. Pag. 3 di 8
1.1 Struttura di interazione API La struttura base di una chiamata API è la seguente: L'applicazione client una volta costruita la richiesta provvede ad inviarla all'entry-point dell'interfaccia Maxpho API che una volta processata restituisce il risultato della computazione. 1.2 Struttura di interazione INS Il sistema di notifica per lo storico degli ordini e per la sincronizzazione del magazzino tra l'applicativo Maxpho Commerce e un applicativo esterno a scelta del cliente è strutturata come segue: Il sistema notifica le informazioni relative all'ordine all'indirizzo specificato in configurazione allegando i dettagli relativi alla variazione sul magazzino dei prodotti venduti. Pag. 4 di 8
2 API Le chiamate API vengono processate da un REST Server che processa il messaggio in formato XML inviato dall'applicativo esterno. 2.1 Struttura di una richiesta API Ciascuna chiamata API è composta da due sezioni: HeadStack: ciascuna richiesta deve includere la sezione di autenticazione all'interno della Request, in questa sezione devono essere incluse informazioni relative a: Version: versione delle chiamata API utilizzata in ingresso Token: ciascuna richiesta deve utilizzare un token di autenticazione compatibile con quelli riconosciuti dall'entry-point Dettagli della richiesta: ciascuna richiesta deve necessariamente includere tutti i campi marcati come required nella documentazione specifica per ciascuna richiesta. Una classica chiamata API avrà quindi la strutturazione seguente: <?xml version="1.0" encoding="utf-8"?> <CallRequest> <HeadStack> <Version></Version> <Token></Token> <Action></Action> </HeadStack> <RequestDetail> <!-- Request detail nodes --> </RequestDetail> </CallRequest> Pag. 5 di 8
2.2 Lista chiamate API supportate Attualmente le chiamate API supportate sono quelle che permettono di manipolare i prodotti presenti nell'applicativo Maxpho Commerce e quindi sono: InsertProducts: permette l'inserimento di nuovi prodotti [ 1... 5 ] UpdateProducts: permette di aggiornare tutte le informazioni sul prodotto [ 1... 5 ] UpdateStockProducts: permette di aggiornare solo prezzo e quantità di più prodotti [ 1... 20 ] DeleteProducts: permette la rimozione di prodotti [ 1... 10 ] OrdersList: permette la ricezione di tutti gli ordini che hanno subito una variazione all'interno di una fascia oraria indicata in fase di chiamata [1] GetOrder: permette di recuperare informazioni relative ad un orderid indicato come parametro in ingresso alla chiamata [1] CreateCategories: permette l'inserimento di categorie [ 1.. 5 ] DeleteCategories: permette la cancellazione di categorie [ 1.. 10 ] UpdateCategories: permette di aggiornare le informazioni relative alle categorie, non è prevista la modifica della struttura delle categorie da questa chiamata [ 1.. 5 ] CreateManufacturers: permette l'inserimento di produttori [ 1.. 5 ] DeleteManufacturers: permette la cancellazione di produttori [ 1.. 10 ] UpdateManufacturers: permette di aggiornare le informazioni relative ai produttori [ 1.. 5 ] Pag. 6 di 8
3 Instant Notification Service INS è un sistema sviluppato per notificarne all'esterno dell'applicativo eventi interni. 3.1 Struttura di interazione INS Maxpho Commerce provvede a notificare in POST, su un endpoint esterno HTTP/HTTPS tramite un URL, le informazioni relative alla variazione in corso. Gli eventi notificati sono: Ricezione Ordine [OrderNotify]: il sistema alla ricezione di un ordine da uno dei marketplace configurati su Maxpho Commerce, provvede a inviare i dettagli della transazione appena completata. Aggiornamento stato dell'ordine [OrderStatusUpdate]: una qualsiasi variazione dello stato degli ordini, Maxpho Commerce provvede a notificarne l'aggiornamento (esempio: pagamento ricevuto, spedito, annullato etc...). Per processare o ricevere notifiche dal sistema di INS è necessario sviluppare sull'endpoint di destinazione della notifica, un listener o un handler che rimanga in ascolto delle notifiche provenienti da Maxpho e che alla loro ricezione implementi una opportuna gestione del messaggio. Il sistema non richiede caratteristiche particolari sull'endpoint, in quanto vengono inviate notifiche in POST nel formato XML con encoding UTF8. Il meccanismo di notifica è state-less, ovvero non prevede una gestione di errori riportati dal client in fase di parsing del messaggio ricevuto. Attualmente la gestione del fallimento è gestita unicamente sulla base della raggiungibilità dell'endpoint. In caso di irraggiungibilità del server o dell'entry point (codice di errore 401, 403, 404 e 500 di Apache) il sistema INS provvederà a notificare via email all'indirizzo email dello store l'impossibilità di comunicazione del sistema con l'endpoint esterno. 3.2 Casi d'uso Di seguito elenchiamo alcuni casi d'uso fornendo un'idea di come poter sfruttare sulla propria piattaforma il sistema di notifica INS di Maxpho Commerce: Pag. 7 di 8
1. In un'interazione basilare è possibile sfruttare la OrderNotify per tenere sincronizzato il proprio magazzino fisico con il magazzino virtuale gestisto tramite Maxpho, a sua volta replicato su tutti i marketplace gestiti dal buyer; 2. Con una gestione più curata, in ricezione di un evento OrderNotify, si può salvare l'ordine ricevuto e sincronizzare le quantità vendute avendo informazioni relative all'acquirente e ai dettagli della vendita (destinazione della merce, prodotti acquistati, informazioni sulla spedizione e sul metodo di pagamento selezionati dal buyer). Mediante la chiamata API OrdersList, o tramite il servizio INS OrderStatusUpdate, è possibile gestire la variazione dello stato, aggiornata sull'amministrazione o da uno dei marketplace; 3. Interfacciare il sistema di notifica con sistemi BI (Business Intelligence) con l'obbiettivo di profilare e geo localizzare in modo dettagliato il proprio ebusiness. I casi d'uso proposti hanno l'obbiettivo di illustrare alcune semplici soluzioni di integrazione con piattaforme esterne, ma vanno considerate solo a titolo di esempio in quanto un'ottimale sfruttamento di questo servizio va definito ad hoc sulla base dell'infrastruttura del cliente. Pag. 8 di 8