The following explains how to use the Reviso APIs (REST and SOAP) using Agreement Grant Tokens (tokens for accessing company data) and App Secret Tokens (secret application tokens), allowing applications or any integration of partners to access the data on the management system without having to memorize the user's credentials.
N.B. The end user, in order to use the application, must have the same permissions required by the application.
Connecting in 3 steps
To get started, you need to complete 3 steps:
Request for a developer agreement
Obtain authorization to access customer company data with your application through an App Secret Token (application secret token) and an Agreement Grant Token (company data access authorization token)
Connect to Reviso via REST or SOAP
1. Request for a developer agreement
Send an e-mail to api@reviso.com and request the activation of an agreement with a developer profile, indicating:
the e-mail address to use to access your agreement
the name to assign to the application.
By activating this profile you can create multiple applications.
Once the request has been sent, you will receive an e-mail with the access credentials for the new development contract.
Before logging in, you need to create the TeamsystemID. To do this, read
2. Obtain an Agreement Grant Token
Log into your Reviso developer agreement and go to the Developer menu.
Copy the request URL of your app and send it to the customer.
We support translating the Request Access page. This is done by appending a "locale" query string to the /requestaccess.aspx request. The following codes are supported: en-GB, de-DE, es-ES, it-IT.
Note: If you want to test and explore the functionality of Reviso, sign up for a trial agreement in the country of your primary user base and test against this. To prolong the trial period of your test agreements, please contact us at api@reviso.com.
Manual delivery of Agreement Grant Token
Send the request access URL to the end-user. When the end-users click the link, they are taken to the Grant access page where they can enter their agreement credentials and grant the app access to their agreement data.
After granting access to the app, end-users are presented with the created token which they need to copy and send to you.
Received the Grant Token, the developer will indicate it in his application with the Secret token.
Automated delivery of Agreement Grant Token
To automatically obtain generated Agreement Grant Tokens, you need to set up an endpoint in your solution that is capable of receiving the token from a GET request where the token is supplied in the query string.
To redirect end-users, you must include a redirectURL parameter in the link you supply to end-users. The redirect URL can contain a querystring where you can specify additional information you may need to identify a user on your end.
Example of the redirect URL parameter:
redirectUrl=https://www.example.com%3userIdInMySystem=123
Example of a complete request URL including a redirect:
When end-users click the link, they are taken to the Grant access page. After granting access, users are redirected to the URL you supplied with the fresh Agreement Grant Token appended to the querystring.
Example:
Note: Please be aware that the Grant Tokens expire after 360 days, at which time you must repeat the request process to facilitate continued use.
3. Connect to Reviso
Once you have obtained an Agreement Grant Token, there are two ways of connecting to Reviso: Either using REST, or using a SOAP call.
Using REST
Add these three headers to your requests:
Content-Type: application/json
X-AppSecretToken: <TheAppSecretToken>
X-AgreementGrantToken: <TheAgreementGrantToken>
2. Issue a GET to https://rest.reviso.com/customers and inspect the response to
validate that everything is working.
Using Postman to manage APIs
Postman is a tool for creating, testing, documenting, monitoring and publishing documentation for APIs. It allows you to make any kind of request to a server and is able to give you any kind of information you need.
Postman makes it possible to create requests from scratch by specifying various parameters, to know all kinds of information of both the Request and the subsequent Response.
It allows you to make HTTP calls in GET, POST, PUT and DELETE, save them and group them so you don't have to redefine them each time.
Below is a collection of Cloud Accounting APIs for importing into Postman.
To import the collection, simply download and unzip the file, start Postman, click on Import and select the file to be imported.
