Modalita di accesso ai servizi ¶

Introduzione¶

Le API saranno HTTP con risposte JSON e gli HTTP STATUS CODE

Le risposte hanno sempre questo formato:

{

"version": "1.0.0" // versione API

"result_code":int%, // codice che indica se la risposta ha avuto successo o meno. Sono gli stessi http status code% 

"error_message": string %{font-size: 7pt;}// eventuale messaggio di errore per debug%

"data": {}; %{font-size: 7pt;}// la risposta del server%

}

Per "result_code" vengono riutilizzati per semplicità gli status code HTTP; i seguenti codici valgono per tutte le chiamate, codici specifici saranno disponibili per alcune chiamate e verranno specificati nella documentazione:

• 200: successo
• 500: in caso di eccezione interna del programma
• 400: in caso di DTO o parametri della richiesta null

Ambiente di produzione¶

Url: http://webapi.duebit.com/ 

Ambiente di test¶

Url: http://webapitest.duebit.com/

Credenziali¶

User: 2bit@2bit.it

Password: *2bit*

Help: http://webapi.duebit.com/help / http://webapitest.duebit.com/help

A questo indirizzo si trova la lista di tutte le API Disponibili.

Autenticazione¶

Per ottenere il token:

http://webapi.duebit.com/Token

Verb: *POST*

Header: *Content-Type: application/x-www-form-urlencoded*

Body: *x-www-form-urlencoded*

grant_type: *password*

username: * 2bit@2bit.it *

password: *2bit*

clientId: *identificatore univoco del client* (stringa)

appName: passare una delle stringhe previste, tipo: *DueMobileRetail* o *EasyPosMobile*, o WebAppSelfOrder

appVersion: *versione Major.Minor (separate da punto) *

 

Esempio:

Response - 200 Ok:

Response - 400 Bad Request:

Se il clientid è vuoto:

{

"error": "invalid_grant",

"error_description": " Il clientID è vuoto"

}

Numero massimo di client raggiunto

{

"error": "invalid_grant",

"error_description": " Accesso non consentito. Slot terminati."

}

Il client è già registrato e attivo con token valido. Non viene emanato il token.

{

"error": "already_granted",

"error_description": " Il client è già autorizzato. Il token è già stato staccato."

}

Altri errori possibili:

• -19: L'appName è vuoto
• -20: L'appName non è stato riconosciuto: {0}. [I nomi previsti: AppRetail, AppRistorazione, altri]
• -21: L'appVersion è vuota.
• -22: L'appVersion non è stata riconosciuto: {0}. [Formato accettato: major.minor]
• -23: L'appVersion non è compatibile con le WebApi. [Versione app accettata: {0}, Versione app attuale: {1}]

Verifica compatibilità web api¶

Una volta ottenuto il token lanciare la chiamata di verifica della compatibilità tra WebApi e Client:

API:

GET api/CheckCompatibility?clientId={clientId}

Response:

True se ok, altrimenti 500 con messaggio di errore.

• Se AppVersion ha come major version 0 il controllo di versione viene saltato perché si assume che sia l'app in versione beta.
• Viene confrontata la major version spedita dall'app con il il numero inserito nel file di configurazione del server.
• La minor version per adesso viene ignorata, quindi prestare attenzione all'utilizzo.

Interrogazione WebApi¶

Una volta ottenuto il token si possono fare le chiamate.

Esempio:

API:

http://webapi.duebit.com/Api/Cliente

Verb: GET

Header: Content-Type: application/json

Authorization: Bearer Zsxw5sypHKs4ljbj9hsAmDXJwwZkx3VFkUL

Response example:

 

Altro esempio:

Formato delle date¶

I dati serializzati in JSON rispettano questi standard:

var serializerSettings = new JsonSerializerSettings()

   {

ReferenceLoopHandling = ReferenceLoopHandling.Ignore, 

DateFormatHandling = DateFormatHandling.IsoDateFormat,

DateTimeZoneHandling = DateTimeZoneHandling.Unspecified,

NullValueHandling = NullValueHandling.Ignore

};