API per gli sviluppatori
Grazie alle API di Softvision Fidelity Card gli sviluppatori possono interfacciare le loro applicazioni/siti Web con i servizi offerti dalla nostra piattaforma. Le API possono essere utilizzate ad esempio per ottenere la lista dei clienti, l'elenco dei gruppi, per aggiungere, cancellare o modificare dei clienti e molto altro.
Elenco completo delle API disponibili
Tecnologie utilizzate
Per quanto riguarda l'autenticazione viene utilizzato il protocollo OAuth 2
con la modalità 3-legged OAuth, mentre le chiamate ai servizi avvengono in modalità REST.
Lo scambio di dati da e verso i servizi esposti avviene utilizzando i formati Json e XML ed il set di caratteri utf-8.
Formato dei dati
- Valuta : viene usato il simbolo "." per separare i decimali. Esempio di formati validi sono i seguenti : 10.5 , 0.5 , 35.0 , 35
- Data e ora : le api utilizzano il formato ISO 8601. Le date UTC sono scritte con la Z finale.
Esempi :
2012-07-27T18:51:45.53403Z // UTC
2012-07-27T11:51:45.53403-07:00 // Locale
Registrazione dell'applicazione da realizzare
Per utilizzare i servizi lo sviluppatore dovrà effettuare una registrazione inviando una mail all'indirizzo info@softvision.it con i seguenti dati :
- Nome e cognome / azienda.
- Login utilizzato per accedere all'applicativo Softvision Fidelity Card.
Utilizzo delle API
Vediamo ora più in dettaglio come utilizzare le API di Softvision Fidelity Card.
Il vostro applicativo dovrà innanzitutto ottenere un Token (stringa alfanumerica) dal nostro server. Questo Token, la cui validità è di 24 ore,
dovrà essere poi inserito in ogni successiva richiesta di chiamata alle API.
Per ottenere il Token è necessario effettuare una chiamata al nostro server utilizzando il protocollo OAuth 2.
I parametri di cui avrete bisogno sono i seguenti :
- client_id e client_sectret (forniti dalla Softvision dopo la registrazione dell'applicativo)
- Authorization end point : https://fcapp.softvision.it/OAuth/Authorize
- Token end point : https://fcapp.softvision.it/OAuth/Token
- Scope : rappresenta i privilegi richiesti dall'applicativo. Può assumere i valori 'READ', 'WRITE' o 'READ WRITE'
- Return url : è la url a cui si viene reindirizzati dopo la richiesta di inserimento delle vostre credenziali di accesso. Generalmente coincide con la pagina principale del vostro applicativo/sito web.
Il flusso dello operazioni è a grandi linee il seguente :
1) L'applicativo effettua una chiamata all'Authorization end point. All'utente viene richiesto di inserire le proprie credenziali di accesso del suo account Softvision Fidelity Card.
Al termine dell'operazione si viene reindirizzati all'url di ritorno del vostro applicativo.
2) L'applicativo richiede il Token con una chiamata al Token end point.
3) L'applicativo riceve il Token ed il Refresh Token. Il primo può essere utilizzato per 24 ore al termine delle quali è possibile ripetere
le procedure 1) e 2) per ottenere un nuovo Token oppure è possibile utilizzare il Refresh Token per rinnovare la scadenza del Token originale.
Una volta ottenuto il Token possiamo effettuare le chiamate alle API effettuando delle richieste REST all'indirizzo fcapi.softvision.it.
Vediamo ad esempio una chiamata per ottenere la lista dei clienti del nostro account Softvision Fidelity Card.
Richiesta
GET https://fcapi.softvision.it/v1/customers HTTP/1.1
Accept: application/json
Content-type: application/json
Accept-Charset: UTF-8
Authorization: Bearer TOKEN
Risposta
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Content-Length: 753
Date: Sat, 28 Apr 2012 13:19:40 GMT
[{"CustomerID":1276,"CardCode":"123864344365","FirstName":"Antonio","LastName":"Albanese","Address":"Via dei mille","City":"Roma",
"Province":null,"ZipCode":null,"DocumentIssuedBy":null,"BornDate":null,"RegistrationDate":"2012-08-27T16:04:00","DocumentIssuedDate":null,"DocumentNumber":null,"Country":null,"Telephone":null,
"EMail":null,"MobilePhone":null,"TaxCode":null,"Note":null,"Description":null,"AllowProfiling":false,"Credit":700.0000,"DiscountCredit":0.0000,"Points":2660,
"Male":false,"CustomersGroupID":24,"DocumentTypeID":0,"SMSSendType":0,"EMailSendType":0,"PresentedByCustomerID":null},
{"CustomerID":1277,"CardCode":"123864465","FirstName":"Antonio","LastName":"Rossi","Address":"Via roma","City":"Torino","Province":"To","ZipCode":"543434",
"DocumentIssuedBy":null,"BornDate":null,"RegistrationDate":"2012-08-27T16:19:00","DocumentIssuedDate":null,"DocumentNumber":null,"Country":null,"Telephone":null,
"EMail":null,"MobilePhone":null,"TaxCode":null,"Note":null,"Description":null,"AllowProfiling":true,"Credit":710.0000,"DiscountCredit":0.0000,"Points":2660,
"Male":false,"CustomersGroupID":24,"DocumentTypeID":0,"SMSSendType":0,"EMailSendType":0,"PresentedByCustomerID":null}]
Elenco completo delle API disponibili
Esempi in ASP.Net e PHP
Sono disponibili due esempi completi (Asp.net e PHP) che mostrano come effettuare l'autenticazione OAuth 2 e come effettuare le chiamate alle API:
