Fermo!Point API

Fermo!Point APIGuida all’integrazioneVersione RedirectAPI: 0.9Versione AsyncAPI: 1.1Ultimo aggiornamento: 28-07-2015Autore: Fermopoint Srl

SommarioIl servizio Fermo!Point ................................................................................................................................................................ 3Compilare la lettera di vettura ................................................................................................................................................ 3Riferimenti utili ...................................................................................................................................................................... 3Introduzione alle API .................................................................................................................................................................. 4Account Merchant .................................................................................................................................................................. 4Area Sandbox ......................................................................................................................................................................... 4Modelli di integrazione: RedirectAPI e AsyncAPI .................................................................................................................... 4AsyncAPI ............................................................................................................................................................................ 4RedirectAPI ......................................................................................................................................................................... 4Codice di esempio .................................................................................................................................................................. 5Guida all’integrazione: AsyncAPI ................................................................................................................................................ 6Come effettuare una chiamata ............................................................................................................................................... 6Convenzioni ........................................................................................................................................................................ 6Calcolo dell’auth_code ........................................................................................................................................................ 6Indirizzi di riferimento per l’utilizzo delle API ........................................................................................................................... 7Changelog ............................................................................................................................................................................... 7AsyncAPI Reference ................................................................................................................................................................... 8Api pubbliche ......................................................................................................................................................................... 8Api pubbliche: Utenti .............................................................................................................................................................. 8Api pubbliche: Negozi (Point) ................................................................................................................................................. 9Api private .............................................................................................................................................................................. 9Api private: Merchant ............................................................................................................................................................. 9Api private: Utenti ................................................................................................................................................................. 10Api private: Negozi (Point) .................................................................................................................................................... 10Api private: Consegne ........................................................................................................................................................... 11Api private: Prenotazioni ....................................................................................................................................................... 11Definizione degli oggetto utilizzati ........................................................................................................................................ 14Guida all’integrazione: RedirectAPI ........................................................................................................................................... 17Flusso delle azioni e delle chiamate ....................................................................................................................................... 17Normal Flow ...................................................................................................................................................................... 17Modifiche richieste all’interfaccia e al backend dell’e-commerce ........................................................................................... 17Indirizzi di riferimento per l’utilizzo delle API ......................................................................................................................... 18Changelog ............................................................................................................................................................................. 18RedirectAPI Reference ...............................................................................................................................................................19Richiedere una sessione autenticata: /Init..........................................................................................................................19Procedere alla prenotazione della consegna ......................................................................................................................... 20Ricevere la conferma (o l’annullamento) della prenotazione di consegna ............................................................................. 20Approvare o annullare la consegna ........................................................................................................................................ 21Fermo!Point API – Guida all’integrazione pag. 2/22

Il servizio Fermo!PointFermo!Point (F!P) è il nuovo servizio di PickUp Point che sfrutta una rete di negozi selezionati e certificati come recapito deipacchi per i tuoi clienti.Integrare F!P nel tuo sito e-commerce significa fornire un servizio comodo, sicuro e moderno per i tuoi clienti.Il servizio funziona tramite l’acquisto di Fermo!Ticket (coupon di consegna) che vengono assegnati a un utente del sito epermettono il ritiro anonimo e sicuro della merce presso un nostro negozio abilitato esibendo nickname e codice Fermo!Ticket.Per fornire il servizio dal tuo e-commerce dovrai pre-acquistare un certo numero di ticket (secondo le tue esigenze) a prezzoscontato. Questi ticket verranno allocati al tuo e-commerce e quando un utente sceglierà F!P per ricevere la tua merce uno diquesti gli verrà assegnato. Il tuo cliente quindi non corrisponderà alcuna cifra a F!P, pagherà la consegna direttamente a te, alprezzo che riterrai opportuno.Compilare la lettera di vetturaPer rendere identificabile il pacco come consegna Fermo!Point e assegnarlo ad uno specifico cliente è necessario seguireattentamente le linee guida per la compilazione della lettera di vettura.Attenzione! Se non si rispetta il formato specificato per la lettera di vettura i pacchi potrebbero non giungere al destinatarioIl negoziante che ritira il pacco dal corriere deve in primo luogo capire che si tratta di una consegna Fermo!Point, quindi devetrovare la dicitura Fermo!Point da qualche parte sul pacco.Per riconoscere il cliente a cui consegnare la merce è necessario che il destinatario sia il nickname dell’utente registrato alservizio Fermo!Point.Il formato finale deve quindi essere questo:Nickname - Insegna del negozio - Fermo!PointIndirizzo del negozioCittà - CAP - Provincia – ItaliaEsempio compilato con dati fittizi:oscar - Fermo!Point Treviglio 1 - Fermo!PointVia Matteotti, 1ATreviglio - 24047 - Bergamo - ItaliaAttenzione! Se ci fossero problemi di lunghezza nel campo del destinatario è importante non “tagliare” il nickname.Eventualmente inserite come destinatario il nickname e la prima parte dell’insegna del negozio. Si prega inoltre di riportare ladicitura Fermo!Point in bella evidenza su un lato visibile del pacco.Riferimenti utiliQuesta guida è liberamente scaricabile nell’ultima versione aggiornata all’indirizzo:http://api.fermopoint.it/Content/files/ApiReference.pdfAltri riferimenti utili:http://sandbox.fermopoint.it : Area sandbox (vedi capitolo Area Sandbox) e test online delle AsyncAPIhttp://ecommercetest.fermopoint.it : Esempio scaricabile in Microsoft .NET dell’integrazione con Fermo!Pointsupport@fermopoint.it : Supporto tecnico Fermo!Point, per richiedere supporto o le credenziali di produzioneFermo!Point API – Guida all’integrazione pag. 3/22

Introduzione alle APIAccount MerchantPer utilizzare le API di Fermo!Point (F!P) è necessario possedere un account Merchant.L’account Merchant viene rilasciato su richiesta dallo staff di F!P. La richiesta può essere fatta dal modulo di contatto sul sito allapagina http://www.fermopoint.it/contatti-ecommerce, inserendo i dati dell’e-commerce da cui si vorrà utilizzare il servizio.Ad avvenuta registrazione vi verranno inviate le credenziali di riconoscimento: il client_id e il client_secret.Il client_id è il codice univoco identificativo del vostro account, mentre il client_secret è un codice segreto da utilizzare pervalidare l’account merchant durante le richieste alle API.Area SandboxPer verificare la correttezza della propria integrazione sarà resa disponibile un’area Sandbox di test ove sarà possibile accederecon le proprie credenziale e provare ad effettuare prenotazioni di consegna su un database separato da quello ufficiale. L’indirizzoufficiale dell’area sandbox è http://sandbox.fermopoint.it.Modelli di integrazione: RedirectAPI e AsyncAPIPer integrare il servizio F!P nel vostro e-commerce sono disponibili due soluzioni alternative: AsyncAPI e RedirectAPI.AsyncAPIÈ il modello alternativo al RedirectAPI che prevede uno scambio di richieste HTTP POST autenticate con payload formattato inJSON.Le AsyncAPI permettono l’integrazione completa di F!P all’interno del proprio portale a scapito di un maggior sforzoimplementativo per il programmatore. Da queste considerazioni risulta ovvio che le AsyncAPI sono perfette per l’integrazione diuna piattaforma su cui si poggiano più portali, ma anche per fornire un’esperienza più fluida al cliente che non dovrà mai “uscire”dal vostro e-commerce.Con le AsyncAPI oltre alla funzionalità di prenotazione di una consegna, l’e-commerce avrà a disposizione la lista delleprenotazioni effettuate e relativo dettaglio per la parte di backend e la lista dei negozi (point), completa o filtrata per posizione egiorno/ora di apertura, da utilizzare per la visualizzazione su una mappa (es. Google Maps, Bing Maps), i dettagli dei singoli point.L’integrazione con le AsyncAPI prevede la creazione di un’interfaccia utente per la scelta del negozio a cui spedire la merce e perl’inserimento dei dati necessari alla prenotazione ed eventualmente alla creazione di un nuovo utente F!P.Specifichiamo che per motivi di sicurezza tutta la procedura di prenotazione dovrà essere fatta tramite richiesta server-servercompleta di client_id e di un token di controllo generato grazie al client_secret (vedere il paragrafo Come effettuare unachiamata) e che l’e-commerce non verrà mai a conoscenza della password dell’utente F!P, nemmeno in caso di creazione di nuovoutente (la password verrà generata da F!P e spedita all’indirizzo email fornito).RedirectAPIÈ un modello basato su semplici chiamate HTTP e redirect simile alla classica integrazione con un sistema di pagamento online.Questo secondo metodo permette ai programmatori di singoli e-commerce custom un'integrazione veloce, senza la necessità diprogettare l'interfaccia grafica necessaria all’inserimento dei dati, in quanto tutta la fase di prenotazione avviene sul portale F!P.In questo caso il programmatore deve solamente prevedere il salvataggio dell'ordine in uno stato temporaneo ed effettuareun redirect verso F!P dopo aver fatto richiesta del link di una sessione autorizzata.Finita la fase di prenotazione l'utente verrà rediretto di nuovo verso il sito e-commerce dove potrà concludere l'ordine. Allaconferma finale (quando l’ordine è ritenuto definitivo per l’e-commerce, es. dopo il pagamento) il backend dell'e-commercedovrà effettuare un’ultima chiamata a F!P per confermare la prenotazione.Fermo!Point API – Guida all’integrazione pag. 4/22

Codice di esempioIl nostro team ha sviluppato un applicativo di riferimento per semplificare l’analisi e l’intervento ai programmatori:Fermo!Point E-commerce Test (ET).Il progetto è sviluppato su piattaforma Microsoft .NET utilizzando il framework per la programmazione web ASP.NET MVC ed èpubblicato e utilizzabile all’indirizzo http://ecommercetest.fermopoint.it. Il codice è liberamente scaricabile dalla homepage.ET contiene l’esempio di integrazione per entrambi i metodi AsyncAPI e RedirectAPI ed è focalizzato a mostrare il flusso dichiamate necessarie all’integrazione senza perdersi in fronzoli e quindi privo di stili CSS di contorno.E’ compreso anche un riferimento dell’interfaccia da integrare per AsyncAPI in stile “copia e incolla”, quindi comprendente tuttala parte Javascript per la visualizzazione dei negozi come marker su una mappa di Google (partner scelto come riferimento, mache può essere sostituito) e in forma di lista, per abilitare la ricerca dei negozi in base alla località (tramite geolocation) e filtrarliin base all’orario d’apertura.Oltre al flusso di prenotazione, per AsyncAPI è presente anche una pagina che mostra le chiamate necessarie a ricevere leinformazioni utili alla parte backend dell’e-commerce quali il numero di crediti disponibile o la lista di tutti gli ordini effettuati.L’esempio mostra è da considerarsi una guida per il programmatore, ma questo non vuol dire che sia l’unico modo perimplementare la comunicazione con Fermo!Point. Facendo riferimento alle ApiReference un occhio attento potrà trovare lavariante più adatta al proprio contesto.Per fare un esempio possiamo citare metodo per l’ottenimento della lista dei negozi. Nell’esempio viene scaricata tutta la listadei negozi in forma di array JSON e messa in una variabile javascript (quindi renderizzata nella pagina). Successivamente tutti ifiltri e ordinamenti vengono fatti tramite manipolazioni di questo array. Un mix di programmazione client/server che è sembratala più semplice per l’esempio in quanto isola bene le parti.Una alternativa potrebbe essere mantenere la lista in una variabile in cache ed effettuare le ricerche tramite chiamate lato server.Oppure utilizzare l’interfaccia pubblica /public/points/search direttamente in javascript tramite chiamata Ajax (le interfaccepubbliche supportano CORS) per recuperare una lista di tutti i punti entro un certo raggio rispetto alla posizione richiesta.Lo staff tecnico di Fermo!Point è comunque a disposizione per eventuali chiarimenti all’indirizzo support@fermopoint.it.Fermo!Point API – Guida all’integrazione pag. 5/22

Guida all’integrazione: AsyncAPIIn questo capitolo verranno elencate le interfacce di integrazione del modello AsyncAPI.Per ogni interfaccia verrà proposto del codice di esempio per miglior chiarezza.Come effettuare una chiamataLe AsyncAPI sono accessibili tramite richieste HTTP di tipo GET o POST.Le chiamate pubbliche sono raggiungibili tramite chiamata GET e supportano la specifica Cross-Origin Resource Sharing (CORS)che permette di effettuare le richieste lato client tramite JavaScript.Per le chiamate private è necessario effettuare richieste utilizzando il metodo POST accompagnato da un unico oggetto JSONcome parametro.Il formato di questo oggetto segue sempre la stessa struttura e comprende i seguenti campi:client_id: è l’identificativo dell’account comunicato dalla staff di F!P ad attivazione avvenuta.ts: è il timestamp della richiesta. Non saranno accettati orari che differiscano sensibilmente dall’orario dei nostri server.Fare riferimento al paragrafo Convenzioni per il formato da utilizzare.auth_token: è il codice di sicurezza da generare a ogni richiesta per validare la richiesta. Vedi Calcolo dell’auth_code.data: è l’oggetto che contiene i parametri di input specifico della chiamata. [opzionale]Struttura dell’oggetto JSON che accompagna ogni richiesta POST:{"client_id": "stringa identificativa","ts": "timestamp della richiesta in format UTC","auth_token": "stringa generate da client_id, client_secret e ts","data": { "oggetto che contiene i parametri di input di ogni richiesta" }}ConvenzioniI numeri devono essere specificati senza separatore per le migliaia e utilizzando il punto ‘.’ come separatore dei decimali.Ad esempio il numero 120.783,23 sarà rappresentato da:120783.23Tutte le date e gli orari devono essere specificate secondo la specifica ISO 8601 in Tempo Coordinato Universale (UTC/GMT)Ad esempio la data 14 ottobre 2014 alle ore 8 minuti 36 secondi 13 e 124 millesimi con fuso orario UTC sarà rappresentata da:2014-10-21T08:03:25.4238996Z o abbreviazioni come 2014-10-21T08:03:25 o 2014-10-21Calcolo dell’auth_codeL’auth_code può essere calcolato applicando al valore del parametro ts della richiesta la funzione HMAC 1 con algoritmo SHA-256 utilizzando come chiave di segreta (chiave) la stringa ottenuta concatenando il client_id e il client_secret.Di seguito un esempio di calcolo dell’auth_code:ts: 2014-10-21T08:03:25.4238996Zclient_id: peHFRa141xCu4WFnyF8eclient_secret: Q32V3b00nb9c55*JEcbSO0r54IW23*&LwV70_9IfG56#BK3*chiave: peHFRa141xCu4WFnyF8eQ32V3b00nb9c55*JEcbSO0r54IW23*&LwV70_9IfG56#BK3*auth_code = HMAC(ts, chiave, sha-256) = 9722487d44b88c093ea140fc771a43aa2ea6edccea8f40a3bf7e69f6729cd09b1HMAC (keyed-hash message authentication code) è un codice per la validazione dell’integrità di un messaggio tramite una funzione di hash e una chiave segretaFermo!Point API – Guida all’integrazione pag. 6/22

Indirizzi di riferimento per l’utilizzo delle APIOgni versione che verrà rilasciata delle API avrà un indirizzo base differente per garantire, ove possibile, il supporto anche alleversioni precedenti e semplificare la fase di aggiornamento.API server di produzione:http://api.fermopoint.it/api/vX.XAPI server sandbox:http://sandbox.fermopoint.it/api/vX.XVersione attuale: 1.1Indirizzo di riferimento per la versione attuale:Produzione: http://api.fermopoint.it/api/v1.1Sandbox: http://sandbox.fermopoint.it/api/v1.1ChangelogVersione 1.1:- Inserita nuova chiamata per verificare la coppia nickname / data di nascita (/public/users/check e /users/check)- Inserito il conteggio degli ordini nella chiamata /merchant- Modificata la richiesta della lista degli ordini. Suddivisa in /orders con filtro, paginazione e ordinamento e /orders/lastcon la lista degli ultimi ordini- Aggiunta del check sull’utente OSPITE (/users/guest-check)Versione 1.0:- Inserita la data di nascita nella prenotazione (/booking/book) per identificare l’utente- Aggiunta la ricerca dei point nelle API pubbliche- Aggiunte le chiamate di validazione di nickname e email nelle API pubblicheVersione 0.9:- Prima versione pubblicaFermo!Point API – Guida all’integrazione pag. 7/22

AsyncAPI ReferenceLe AsyncAPI sono divise in interfacce pubbliche e interfacce private.Le prime possono essere utilizzate da chiunque ad esempio per ottenere la lista dei point da inserire in una mappa sul web. LeApi private, viceversa, possono essere utilizzate solo da chi ha un account merchant attivo e permettono l’integrazione completacon Fermo!Point.Attenzione: in questa guida verrà indicato per ogni tipologia di chiamata l’indirizzo relativo. Questo deve essere concatenato conl’indirizzo base di produzione o dell’ambiente Sandbox alla versione corretta.Api pubblicheLe chiamate pubbliche non necessitano di payload di autenticazione e possono essere effettuate direttamente lato client tramiteJavaScript grazie al supporto di CORS.HTTP GET/POST http://(sandbox|api).fermopoint.it/api/v{versione}/{indirizzo}HEADERS:Content-Type: application/jsonAccept: text/jsonApi pubbliche: UtentiVerifica disponibilità nicknameDescrizione: Ritorna TRUE se un nickname è disponibile per la creazione di un nuovo utenteMetodo: POSTIndirizzo: /public/users/nicknameParametri: nessunoInput: ApiNicknameStringOutput: booleano, true se il nickname è disponibile e validoVerifica disponibilità emailDescrizione: Ritorna TRUE se un indirizzo email è disponibile per la creazione di un nuovo utenteMetodo: POSTIndirizzo: /public/users/emailParametri: nessunoInput: ApiEmailStringOutput: booleano, true se l’email è disponibile e validoVerifica dell’utente tramite la coppia nickname e data di nascitaDescrizione: Ritorna TRUE se la coppia nickname e data di nascita corrisponde a un utente registratoMetodo: POSTIndirizzo: /public/users/checkParametri: nessunoInput: ApiUserCheckOutput: booleano, true se la coppia nickname e data di nascita è validaFermo!Point API – Guida all’integrazione pag. 8/22

Api pubbliche: Negozi (Point)Lista dei pointDescrizione: Ritorna la lista di tutti i Point con le informazioni base (nome, posizione) senza i dettagli sugli orari d’aperturaMetodo: GETIndirizzo: /public/pointsParametri: nessunoInput: nessunoOutput: array di ApiPointDettaglio di un singolo pointDescrizione: Ritorna la lista di tutti i Point con tutte le informazioni compresi i dettagli sugli orari d’aperturaMetodo: GETIndirizzo: /public/points/point/{id}Parametri: {id}, è l’identificativo univoco del point.Input: nessunoOutput: ApiPointFullRicerca dei pointDescrizione: Filtra i Point per posizione (entro un certo raggio) e per giorno/ora di apertura.ATTENZIONE! Il raggio di ricerca massimo è 50 km. Per raggi superiori è necessario utilizzare le API private.Metodo: POSTIndirizzo: /public/points/searchParametri: nessunoInput: ApiSearchDataOutput: array di ApiPointFullApi privateTutte le chiamate private vanno effettuate tramite metodo POST con payload di autenticazione in JSON:HTTP POST http://(sandbox|api).fermopoint.it/api/v{versione}/{indirizzo}HEADERS:Content-Type: application/jsonAccept: text/jsonINPUT:{"client_id": "peHFRa141xCu4WFnyF8e","ts": "2014-10-21T08:03:25.4238996Z","auth_token": "9722487d44b88c093ea140fc771a43aa2ea6edccea8f40a3bf7e69f6729cd09b","data": { … }}Api private: MerchantRiepilogo account merchantDescrizione: Ritorna il numero di Fermo!Ticket in possesso dell’e-commerce e il conteggio delle richieste di prenotazioneraggruppate per stato.Metodo: POSTIndirizzo: /merchantParametri: nessunoInput: nessunoOutput: ApiSummaryFermo!Point API – Guida all’integrazione pag. 9/22

Api private: UtentiVerifica disponibilità nicknameDescrizione: Ritorna TRUE se un nickname è disponibile per la creazione di un nuovo utenteMetodo: POSTIndirizzo: /users/nicknameParametri: nessunoInput: ApiNicknameStringOutput: booleano, true se il nickname è disponibile e validoVerifica disponibilità emailDescrizione: Ritorna TRUE se un indirizzo email è disponibile per la creazione di un nuovo utenteMetodo: POSTIndirizzo: /users/emailParametri: nessunoInput: ApiEmailStringOutput: booleano, true se l’email è disponibile e validoVerifica dell’utente tramite la coppia nickname e data di nascitaDescrizione: Ritorna TRUE se la coppia nickname e data di nascita corrisponde a un utente registratoMetodo: POSTIndirizzo: /users/checkParametri: nessunoInput: ApiUserCheckOutput: booleano, true se la coppia nickname e data di nascita è validaVerifica dell’utente OSPITE dell’e-commerce tramite la coppia nickname e data di nascitaDescrizione: Ritorna TRUE se la coppia nickname e data di nascita corrisponde all’utente attivo come OSPITE dell’e-commerceMetodo: POSTIndirizzo: /users/guest-checkParametri: nessunoInput: ApiUserCheckOutput: booleano, true se l’utente è valido ed è attivo come utente OSPITE dell’e-commerceApi private: Negozi (Point)Lista dei point con dettaglioDescrizione: Ritorna la lista di tutti i Point con le informazioni complete dei dettagli sugli orari d’apertura.ATTENZIONE! Il quantitativo di dati è corposo, si consiglia di salvare la risposta in una cache locale.Metodo: GETIndirizzo: /pointsParametri: nessunoInput: nessunoOutput: array di ApiPointFermo!Point API – Guida all’integrazione pag. 10/22

Definizione degli oggetto utilizzatiApiOrderState[]"Init","WaitingForPayment","WaitingForPaymentConfirm","WaitingForPaymentCapture","Booked","Sent","Arrived","Collected","Canceled","ToDeposit","InDeposit","Error"// ordine inizializzato// in attesa della conferma dall’e-commerce// non usato dalle api// non usato dalle api// prenotato// non usato dalle api// arrivato al negozio// ritirato// annullato// giacenza scaduta, in ritiro da parte di Fermo!Point// nel deposito Fermo!Point// erroreApiOrderSummary{}"state": "WaitingForPayment","count": 1// ApiOrderStateApiSummary{"credits": 7,"orders_count": 2,"orders": [{"state": "WaitingForPayment","count": 1},{"state": "Collected","count": 1}]}// Fermo!Ticket disponibili// Numero totale di ordini effettuati// ApiOrderSummaryApiOrderFilter{"skip": 0,// numero ordini del filtro da saltare"take": 10,// numero ordini del filtro da ritornare"orderby": "date",// ordinamento*"nickname": "",// filtro sul nickname"state": "All",// filtro sullo stato"pointId": null,// filtro sull’ID del negozio"merchantId": "",// filtro sull’ID univoco fornito dal merchant"date_from": "2014-03-10T17:32:00.3158Z", // filtro data (da)"date_to": "2016-03-10T17:32:00.3158Z" // filtro data (a)}* ordinamento: date (data decrescente), nickname, state, pointid, merchantidApiOrderList{"orders_count": 2,"orders": [{...},{...}]}// Numero di ordini non paginati// Array di ApiOrder paginatiFermo!Point API – Guida all’integrazione pag. 14/22

ApiOpening{"d": 1,"h": [{ "o": 9.0, "c": 13.0 },{ "o": 16.0, "c": 19.0 }]}// giorno della settimana, 0 = domenica – 6 = sabato// array degli orari d’apertura, o = apre, c = chiude, orari in decimaleApiPointFull{"id": 1,// identificativo del point"n": "Cartoleria nuova stella", // nome del point"lt": 45.5183661,// latitudine"ln": 9.5920823,// longitudine"d": 0,// distanza in km"a": { ... },// ApiAddress indirizzo del point"p": "Anna Deda",// proprietario"s": "Cartoleria, Merceria",// settore merceologico"o": [// array di ApiOpening, orari d’apertura{ "d": 1, "h": [ { "o": 9.0, "c": 19.0 } ] },{ "d": 2, "h": [ { "o": 9.0, "c": 19.0 } ] },{ "d": 3, "h": [ { "o": 9.0, "c": 19.0 } ] },{ "d": 4, "h": [ { "o": 9.0, "c": 19.0 } ] },{ "d": 5, "h": [ { "o": 9.0, "c": 19.0 } ] }]}ApiRequest{}"point_id": "1","merchant_id": "3","merchant_notes": "Ordine n.3","existing_user": false,"user": { ... },"nickname": "mario","email": "mario@email.com","phone_number": "333 8778902"// ID del point scelto// ID univoco fornito dal merchant// Nota di accompagnamento del merchant// true se l'utente è già registrato, false se nuovo utente// entità ApiUser per la creazione di un nuovo utente// ATTENZIONE, questo nickname verrà ignorato in caso di nuovo utente// ATTENZIONE, email e numero di telefono per le notifiche dell’ordine// possono differire da quelli forniti alla registrazione dell’utenteApiOrder{"ticketId": "C032FNA239044","merchant_id": null,"merchant_notes": null,"point_id": 1,"nickname": "mario","email": "mario@email.com ","phone_number": "333 8778902","state": Arrived,"notes": [{"date": "2014-09-05T16:24:37.3127685Z","note": "Arrivato al Fermo!Point"}],"last_update": "2014-10-17T16:51:05.73Z"}Fermo!Point API – Guida all’integrazione pag. 16/22

Guida all’integrazione: RedirectAPIIn questo capitolo verranno elencate le chiamate necessarie all’integrazione con RedirectAPI.Per ogni chiamata verrà proposto del codice di esempio per miglior chiarezza.Flusso delle azioni e delle chiamateDESCRIZIONE DEL FLUSSO DELLE AZIONI E CHIAMATE0. L’utente seleziona la merce dal vostro e-commerce e comincia la fase di checkout1. L’utente sceglie Fermo!Point come metodo di spedizione2. Inizializzazione di una sessione autenticata fornendo le credenziali e i link di ritorno al vostro sito web: /Init3. Redirect verso Fermo!Point tramite l’url della sessione autenticata4. Prenotazione della consegna da parte dell’utente sul portale Fermo!Point*5. Redirect sulle pagine di ritorno comunicate al punto 1 per autorizzazione o annullamento della prenotazione.Rispettivamente:a. ReturnUrl (pagina di atterraggio per autorizzazione)b. CancelUrl (pagina di atterraggio per annullamento)6. L’utente porta a termine la procedura di checkout7. Comunicazione dello stato finale della prenotazione tramite chiamata a F!P dal backend:a. Approvazione: ApprovalUrl (quando l’ordine sarà definitivo)b. Cancellazione: RejectionUrl (a scadenza o all’annullamento dell’acquisto o della prenotazione verso F!P)* Durante la navigazione sul portale Fermo!Point sarà sempre visibile in sovrimpressione una barra che ricorda all’utente di essere arrivato su Fermo!Point dalvostro e-commerce e sarà sempre presente un link per annullare la prenotazione e tornare all’e-commerce.RIASSUNTO DELLE CHIAMATE1. Ecommerce effettua una chiamata HTTP POST /Init2. Ecommerce effettua una chiamata HTTP 302 BookUrl3. Fermo!Point effettua una chiamata HTTP 302 ReturnUrl o HTTP 302 CancelUrl4. Ecommerce effettua una chiamata HTTP POST ApprovalUrl o HTTP POST RejectionUrlNormal FlowFLUSSO DELLE AZIONIL'utente scegliela spedizionea Fermo!PointInizializzazionedella sessioneautenticataRedirectverso F!PPrenotazionesu F!P(autorizzazione)Confermaautorizzazionee chiusura delcheckoutApprovazioneprenotazione aordine definitivoFLUSSO DELLE CHIAMATEIntervento dell'utentesull'e-commerceHTTP POSTF!P InitHTTP 302F!P BookUrlHTTP 302EC ReturnUrlInterventodell'utentesull'e-commerceHTTP POSTF!P ApprovalUrlLegenda: Azioni sull’e-commerce Azioni su Fermo!PointModifiche richieste all’interfaccia e al backend dell’e-commerceRedirectAPI è stato affiancato al più completo AsyncAPI come alternativa valida ma dal costo più contenuto.Tenendo conto del fatto che le fasi di prenotazione della consegna e registrazione dell’utente saranno svolte direttamente sulportale F!P, gli interventi di programmazione lato e-commerce saranno minimi.Per riassumere, le modifiche al codice necessarie saranno:Fermo!Point API – Guida all’integrazione pag. 17/22

1. Inserimento di F!P come metodo alternativo di spedizione2. Sviluppo dell’interfaccia di comunicazione in standard HTTP per le chiamate /Init, GetBookingUrl, ApprovalUrl eRejectionUrl3. Salvataggio dell’ordine in stato temporaneo prima di redirigere l’utente su Fermo!Point (come avviene per i POS online)4. Salvataggio della sessione autenticata (un campo testo da aggiungere all’ordine)5. Pagine di ritorno ReturnUrl e CancelUrl per ricaricare l’ordine, cambiarne lo stato e riprendere il checkoutIndirizzi di riferimento per l’utilizzo delle APIRedirectApi, al momento, non supporta endpoint multiversione.Endpoint produzione:http://www.fermopoint.it/RedirectApiEndpoint sandbox:http://www.sandbox.fermopoint.it/RedirectApiVersione attuale: 0.9ChangelogVersione 0.9:- Prima versione pubblicaFermo!Point API – Guida all’integrazione pag. 18/22

RedirectAPI ReferenceRedirectAPI è un set di chiamate HTTP POST server-server e http GET o 302 (REDIRECT) lato client.Le chiamate server-server contengono informazioni sensibili, quindi è necessario renderle NON visibili all’utente finale.Esempio chiamata POST server-serverHTTP POST /Init=POST http://www.fermopoint.it/RedirectApi/Init HTTP/1.1Esempio chiamata REDIRECT lato clientHTTP 302 ApprovalUrl=HTTP/1.1 302 FoundLocation: http://www.fermopoint.it/RedirectApi/Approve...Ogni chiamata REDIRECT può essere sostituita da una chiamata GET:Esempio chiamata GET in sostituzione alla REDIRECTHTTP 302 ApprovalUrl = HTTP GET ApprovalUrl=GET http://www.fermopoint.it/RedirectApi/Approve... HTTP/1.1Come da specifica del flusso, tutto inizia con una chiamata server-server /Init che permette di autenticarsi, creare una nuovasessione e ottenere gli url necessari ai passi successivi.La risposta a questa chiamata è l’unica informazione aggiuntiva da salvare nel vostro database.Parametri fittizi utilizzati negli esempiCLIENT_IDpeHFRa141xCu4WFnyF8eCLIENT_SECRETQ32V3b00nb9c55*JEcbSO0r54IW23*&LwV70_9IfG56#BK3*URL DELL’E-COMMERCE http://ecommerce.comURL CONSEGNA AUTORIZZATA http://ecommerce.com/authorized/{merchantId}URL CONSEGNA ANNULLATA http://ecommerce.com/canceled/{merchantId}Attenzione la struttura degli url di ritorno all’e-commerce può essere differente, quello riportato è da intenderesolamente come un suggerimento.CODICI DI RISPOSTA ALLE CHIAMATE (ResultCode)200 = Ok201 = Authorized202 = Approved401 = Canceled402 = Rejected500 = Error501 = NoTicketsSe il codice è tra 200 e 299 tutto è andato bene, diversamente gli altri codice identificano vari errori possibili.Richiedere una sessione autenticata: /InitUna volta che l’utente, durante il processo di checkout, seleziona Fermo!Point come metodo di spedizione, dovrà essere redirettoverso la pagina di Fermo!Point che permetta di procedere alla prenotazione della consegna.Per ottenere il link di F!P a cui fare il redirect è necessario autenticarsi e aprire una sessione autenticata tramite la chiamata /Init.La /Init è una semplice chiamate HTTP POST con payload JSON composta da:ClientId e ClientSecret per l’autenticazione dell’e-commerceLinks che contiene i link alle pagine di ritorno da F!P per le due casisticheo ReturnUrl: prenotazione autorizzata, si dovrà ricaricare l’ordine salvato e far procedere l’utente dallo stepsuccessivo alla scelta della spedizioneo CancelUrl: prenotazione annullata, il cliente ha deciso di non spedire a un Fermo!Point, quindi si torna allapagina della scelta della spedizioneFermo!Point API – Guida all’integrazione pag. 19/22

La risposta alla chiamata /Init contiene anch’essa un payload JSON contenente tutte le informazioni utili alla prenotazione.Questa risposta deve essere salvata assieme all’ordine temporaneo nel vostro database prima di effettuare il redirect verso F!Ppoiché le informazioni in essa contenute serviranno nei passi successivi.I parametri contenuti nella risposta sono:SessionId è l’id di sessione autenticataAuthToken è il token di autorizzazioneResultCode è il codice di risposta. Vedi la specifica dei codici di risposta.Links contiene gli url alle pagine per proseguire la prenotazione:o BookUrl è l’url a cui l’utente dovrà essere rediretto per iniziare la prenotazione presso Fermo!Pointo GetBookingUrl serve ad ottenere le informazioni sulla consegna prenotatao ApprovalUrl è l’url che dovrà essere chiamato per confermare la prenotazione una volta che l’ordine saràdefinitivo. Deve contenere le informazioni per richiamare l’ordine (es. id dell’ordine)o RejectionUrl è l’url che dovrà essere chiamato per annullare la prenotazione. L’annullamento può essereeffettuato fino a che il pacco non è ancora giunto al negozio F!P. Deve contenere le informazioni per richiamarel’ordine (es. id dell’ordine)HTTP POST /InitPAYLOAD DELLA REQUEST{ClientId = "peHFRa141xCu4WFnyF8e",ClientSecret = "Q32V3b00nb9c55*JEcbSO0r54IW23*&LwV70_9IfG56#BK3*",Links = {ReturnUrl = "http://ecommerce.com/authorized/2015010101" // consegna autorizzataCancelUrl = "http://ecommerce.com/canceled/2015010101" // consegna annullata}}PAYLOAD DELLA RESPONSE{SessionId = "aqZSPQz5Gbp7dGHl6s07",AuthToken = "KvQ#O07DQpme2O4-Xn940*mgez10cs0JLg3P#8IWG96U29*i",ResultCode = "201",Links = {BookUrl = "http://www.fermopoint.it/RedirectApi/Book..."GetBookingUrl = "http://www.fermopoint.it/RedirectApi/GetBooking..."ApprovalUrl = "http://www.fermopoint.it/RedirectApi/Approve..."RejectionUrl = "http://www.fermopoint.it/RedirectApi/Reject..."}}Un Fermo!Ticket acquistato dall’e-commerce verrà collegato a questa sessione autenticata e bloccato in attesa di conferma oannullamento. I Fermo!Ticket in attesa da più di un mese verranno automaticamente sbloccati.La sessione autenticata dovrà essere salvata nel database dell’ecommerce assieme all’ordine in stato temporaneo. Questo ènecessario poiché al prossimo passo l’utente verrà rediretto su una pagina di Fermo!Point e quindi uscirà temporaneamente dalvostro sito web. All’ordine dovrà essere assegnato un identificativo per essere richiamato nelle fasi successive.Procedere alla prenotazione della consegnaUna volta creata e salvata la sessione autenticata è necessario redirigere l’utente al sito Fermo!Point per procedere con laprenotazione della consegna.L’unica azione necessaria è il redirect verso l’url contenuto nel campo BookUrl presente nell’oggetto Links della sessioneautenticata.HTTP 302 BookUrlRicevere la conferma (o l’annullamento) della prenotazione di consegnaCome comunicato nella richiesta della sessione autenticata l’e-commerce deve prevedere due pagine di ritorno pubblicate agliindirizzi ReturnUrl e CancelUrl.Le due pagine hanno il compito di ricaricare l’ordine salvato temporaneamente, cambiarne lo stato e procedere con il checkout.Fermo!Point API – Guida all’integrazione pag. 20/22

In particolare se l’utente autorizzerà la prenotazione verso Fermo!Point verrà rediretto alla pagina corrispondente al ReturnUrl.In questa pagina verrà ricaricato l’ordine, verrà impostato il nickname e l’indirizzo del negozio scelto come destinazione dellaspedizione.I dati necessari possono essere ottenuti direttamente dalla pagina ResultUrl effettuando una chiamata GET al GetBookingUrl.HTTP GET GetBookingUrlLa risposta sarà un frammento JSON con i dettagli dell’ordine ed in particolare una campo Nickname con il nome del destinatarioun campo PointName con l’insegna del negozio e un oggetto Address con l’indirizzo del negozio.PAYLOAD DELLA RESPONSE{PointName: "Fermo!Point Treviglio 1",Address: {Street: "via Matteotti, 1A",Extended: null,City: "Treviglio",Locality: null,PostalCode: "24047",District: "BG",Country: "Italia"},State: "Booked",Notes: [{ Date: "2015-07-28T08:22:21.1395139Z", Text: "Consegna prenotata" },{ Date: "2015-07-28T08:21:28.0147768Z", Text: "Consegna autorizzata" }],LastUpdate: "2015-07-28T08:21:28.013Z",BookingUrl: http://www.fermopoint.it/fermoticket/C000BBF904005,TicketId: "C000BBF904005",Nickname: "admin"}Con questi dati dovrà essere compilata la lettera di vettura nel formato specificato nel capitolo Fermo!Point (F!P) è il nuovo serviziodi PickUp Point che sfrutta una rete di negozi selezionati e certificati come recapito dei pacchi per i tuoi clienti.Integrare F!P nel tuo sito e-commerce significa fornire un servizio comodo, sicuro e moderno per i tuoi clienti.Il servizio funziona tramite l’acquisto di Fermo!Ticket (coupon di consegna) che vengono assegnati a un utente del sito epermettono il ritiro anonimo e sicuro della merce presso un nostro negozio abilitato esibendo nickname e codice Fermo!Ticket.Per fornire il servizio dal tuo e-commerce dovrai pre-acquistare un certo numero di ticket (secondo le tue esigenze) a prezzoscontato. Questi ticket verranno allocati al tuo e-commerce e quando un utente sceglierà F!P per ricevere la tua merce uno diquesti gli verrà assegnato. Il tuo cliente quindi non corrisponderà alcuna cifra a F!P, pagherà la consegna direttamente a te, alprezzo che riterrai opportuno.Compilare la lettera di vettura.Come dettagli aggiuntivi ci saranno lo stato (State) e le note di accompagnamento alla consegna (Notes array di coppiedata/testo) utili a fornire un tracciamento (opzionale) della consegna direttamente dal vostro e-commerce.Approvare o annullare la consegnaL’ultimo step dell’integrazione con RedirectAPI prevede la conferma finale, o l’annullamento, della consegna da parte del vostrobackend, rispettivamente ApprovalUrl e RejectionUrl.La chiamata ApprovalUrl deve essere effettuata quando l’ordine sul vostro e-commerce diventa definitivo (ad esempio quandoricevete conferma del pagamento di un bonifico o del POS online).La chiamata RejectionUrl invece può essere effettuata fintantoché il pacco non è ancora stato ritirato dal negoziante.I motivi per richiedere l’annullamento possono essere molteplici, riportiamo alcuni esempi:Ordine abbandonato: un ordine non concluso scadrà dopo circa un mese, ma nel frattempo il ticket assegnato resteràbloccato. Se volete liberare con scadenze differenti i ticket di ordini abbandonati potete farlo annullando la consegna.Fermo!Point API – Guida all’integrazione pag. 21/22

Problemi con l’ordine: dopo la conferma dell’ordine (ApprovalUrl), per qualsiasi motivo, l’ordine è da annullare (adesempio merce difettosa o non più a magazzino). Potete annullare la consegna e recuperare il ticket prima dellaconsegna effettiva del pacco.Le chiamate ApprovalUrl e RejectionUrl sono semplici chiamate POST server-server senza payload.HTTP POST ApprovalUrlHTTP POST RejectionUrlLa chiamata di RejectionUrl è definitiva. Non si possono riattivare consegne annullate.Fermo!Point API – Guida all’integrazione pag. 22/22