Documentazione delle API di interfacciamento

Softvision Agenda dispone di un sistema di interfacciameno (API) di tipo REST grazie al quale altri applicativi possono collegarsi al sistema per ottenere dati, inserire prenotazioni etc..

Tecnologie utilizzate

Le API utilizzano il modello REST con autenticazione basata su Token. Lo scambio di dati da e verso i servizi esposti avviene utilizzando il formato Json.

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.
Esempi:
2020-07-27T18:51:45
2019-07-17T10:51:14.2321

Registrazione dell'applicazione da realizzare

Per utilizzare i servizi lo sviluppatore dovrà richiedere un codice denominato "Tenancyname" una mail all'indirizzo info@softvision.it con i seguenti dati :

Nome e cognome / azienda.
Login utilizzato per accedere all'applicativo Agenda

Esempi di utilizzo

E' disponibile un progetto C# contenente esempi di chiamate alle API. Occorre far riferimento a questo progetto anche per i dettagli delle strutture dati utilizzate dalle API (CustomerDto, ServiceDto, ResourceDto etc.)

Clicca qui per scaricare il progetto

Utilizzo delle API

Vediamo ora più in dettaglio come utilizzare le API di Softvision Agenda.
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. Il token dovrà essere inserito nell'header Authorization", valorizzato a "Bearer +token"
Ad esempio se il token è "a35gdfdf453gfsd32", il valore dell'header dovrà essere "Bearer a35gdfdf453gfsd32". Tutte le risposte delle chiamate sono incapsulate nella seguente struttura:

Error: descrizone dell'errore
UnAuthorizedRequest:boolean
Result: risultato della chimata in formato json

Elenco delle API disponibili

Autenticazione

ENDPOINT: https://agapi.softvision.it/api/TokenAuth/Authenticate
Metodo:POST
Parametri:
userNameOrEmailAddress:string
Password:string
TenancyName:string

Risposta:
AccessToken:string
ExpireInSeconds:number
UserId:number
AccountExpired:boolean

Richiesta lista clienti

ENDPOINT: https://agapi.softvision.it/api/services/app/customers/getall
Metodo:POST
Parametri:
skipCount:number
maxResultCount:number
Risposta:
totalCount:number
items:lista di clienti (struttura CustomerDto)

Richiesta singolo cliente

ENDPOINT: https://agapi.softvision.it/api/services/app/customers/IDCLIENTE
Metodo:GET
Parametri:
IDCLIENTE:number
Risposta:
struttura CustomerDto

Cancellazione cliente

ENDPOINT: https://agapi.softvision.it/api/services/app/customers/IDCLIENTE
Metodo:DELETE
Parametri:
IDCLIENTE:number
Risposta:
nessun dato

Modifica cliente

ENDPOINT: https://agapi.softvision.it/api/services/app/customers/IDCLIENTE
Metodo:PUT
Parametri:
IDCLIENTE:number (url)
Struttura CustomerDto (message body)
Risposta:
struttura CustomerDto

Inserimento cliente

ENDPOINT: https://agapi.softvision.it/api/services/app/customers
Metodo:POST
Parametri:
Struttura CustomerDto (message body)
Risposta:
struttura CustomerDto

Risorse, Servizi, Membri dello Staff e Location

Le chiamate relative a questi elementi sono strutturalmente identiche alle precedenti. Gli endpoint sono:

Risorse:https://agapi.softvision.it/api/services/app/resources
Servizi:https://agapi.softvision.it/api/services/app/services
Risorse:https://agapi.softvision.it/api/services/app/staffmembers
Locations: https://agapi.softvision.it/api/services/app/locations

Richiesta lista appuntamenti

ENDPOINT: https://agapi.softvision.it/api/services/app/Reservations/GetReport
Metodo:POST
Parametri:
skipCount:number
maxResultCount:number
start: date
end: date
locationId:number (filtro obbligatorio)
resourceId:number (filtro facoltativo)
staffMemberId::number (filtro facoltativo)
Risposta:
totalCount:number
items:lista di appuntamenti (struttura ReportReservationDto)