Di seguito viene spiegato come utilizzare le APIs di Contabilità in Cloud (REST) usando Agreement Grant Tokens (tokens di autorizzazione di accesso ai dati delle aziende) e App Secret Tokens (tokens segreti delle applicazioni), permettendo alle applicazioni o qualsiasi integrazione dei partners ad accedere ai dati sul gestionale senza dover memorizzare le credenziali dell'utente.
N.B. L'utente finale, per poter utilizzare l'applicazione, deve avere le stesse autorizzazioni richieste dall'applicazione.
Connettersi in 3 passi
Per iniziare a creare applicazioni/integrazioni su Contabilità in Cloud, è necessario seguire 3 passi:
Richiedere la registrazione come sviluppatore
Ottenere l'autorizzazione ad accedere con la propria applicazione ai dati dell'azienda del cliente tramite un App Secret Token (token segreto applicazione) e un Agreement Grant Token (token di autorizzazione di accesso ai dati dell'azienda)
Connettersi a Contabilità in Cloud via REST
1. Richiedere la registrazione come sviluppatore
Inviare una e-mail all'indirizzo api@reviso.com e richiedere l'attivazione di un contratto con profilo sviluppatore, indicando:
l'indirizzo e-mail da utilizzare per accedere al proprio contratto
il nome da assegnare all'applicazione .
Con l'attivazione di questo profilo è possibile creare più applicazioni.
Inviata la richiesta si riceve una e-mail con le credenziali di accesso per il nuovo contratto di sviluppo.
Prima di accedere è necessario creare il Teamsystem ID. Per fare questo leggere l'approfondimento Accedere con il TeamSystem ID
2. Ottenere l'autorizzazione di accesso ai dati dell'azienda
Accedere su Contabilità in Cloud con le credenziali ricevute via mail e cliccare su Sviluppatore posto nel menu laterale per visualizzare e creare le applicazioni.
Affinché l'applicazione possa accedere ai dati dell'azienda cliente è necessario inviare al cliente l'URL di richiesta autorizzazione di accesso ai dati. Per fare questo cliccare sul pulsante Request URL, copiare il link e inviarlo al cliente.
https://app.reviso.com/api1/requestaccess.aspx?appId=<PublicAppToken>&locale=<locale-code>
Supportiamo la traduzione delle pagine di Richiesta di Autorizzazione. Questo si ottiene aggiungendo all'url di richiesta di autorizzazione /requestaccess.aspx la stringa "locale". I seguenti codici sono supportati: en-GB, de-DE, es-ES, it-IT.
N.B.: Se si vogliono effettuare delle prove e/o visionare le funzionalità del nostro gestionale, ci si può registrare per un contratto demo italiano o per un contratto demo nel paese dei propri utenti, UK o ES. Per prolungare il periodo di trial dei propri contratti di test, inviare una e-mail ad api@reviso.com.
Ricezione manuale del Agreement Grant Token
Inviato l'URL per la richiesta di autorizzazione di accesso ai dati all'utente finale, quando l'utente clicca, viene riportato nella pagina di autorizzazione dove inserire le credenziali di accesso al proprio contratto, e quindi concedere all'applicazione esterna l'accesso ai propri dati.
Dopo aver autorizzato l'app, all'utente finale viene proposto il Grant Token che dovrà copiare ed inviare al proprietario dell'app.
Ricevuto il Grant Token, lo sviluppatore lo indicherà nella sua applicazione con il Secret token.
Ricezione automatica del Agreement Grant Token
Per ottenere automaticamente gli Agreement Grant Tokens (tokens di autorizzazione di accesso ai dati delle aziende) generati, si deve configurare un endpoint nella propria soluzione che sia in grado di ricevere il token da una richiesta GET dove il token è indicato nella query string.
Per reindirizzare gli utenti finali, è necessario includere un parametro redirectURL nel collegamento fornito agli utenti finali. L'URL di reindirizzamento può contenere una query string in cui è possibile specificare ulteriori informazioni necessarie per identificare un utente.
Esempio di reindirizzamento col parametro redirectURL:
redirectUrl=https://www.example.com%3userIdInMySystem=123
Esempio completo di URL di richiesta compreso reindirizzamento :
https://app.reviso.com/api1/requestaccess.aspx?appId=<PublicAppToken>&locale=en-GB&redirectUrl=https://www.example.com%3FuserIdInMySystem=123
Quando gli utenti finali cliccano sul collegamento, vengono portati nella pagina di autorizzazione. Dopo aver autorizzato l'app, gli utenti sono reindirizzati all'URL indicato col Agreement Grant Token (token di autorizzazione di accesso ai dati dell'azienda) attaccato alla query string.
Esempio:
https://www.example.com?userIdInMySystem=123&token=<GeneratedAgreementGrantToken>
3. Connettersi a Contabilità in Cloud
Una volta ottenuto un Agreement Grant Token (token di autorizzazione di accesso ai dati dell'azienda), è possibile connettersi usando le chiamate REST. Per fare questo:
1. Aggiungere questi tre headers alle proprie richieste HTTP:
Content-Type: application/json
X-AppSecretToken: <TheAppSecretToken>
X-AgreementGrantToken: <TheAgreementGrantToken>
2. Emettere una GET a https://rest.reviso.com/customers e controllare la risposta per verificare che tutto funzioni.
Utilizzare Postman per gestire le APIs
Postman è un tool che permette di creare, testare, documentare, monitorare e pubblicare documentazione per le API. Permette di eseguire qualsiasi tipo di richiesta verso un server ed è in grado di dar qualsiasi tipo di informazione di cui si necessita.
Postman permette di creare da zero le richieste specificando diversi parametri, conoscere ogni tipo di informazione sia della Request che della successiva Response.
Permette di effettuare chiamate HTTP in GET, POST, PUT e DELETE, salvarle e raggrupparle per non doverle ridefinire ogni volta.
Di seguito è disponibile una collezione di APIs di Contabilità in Cloud da importare su Postman.
Per importare la collezione è sufficiente scaricare e decomprimere il file, avviare Postman cliccare su Import e selezionare il file da importare.
Leggi anche