BETA

By using Postman, you will be able to test your first requests via Sage Active Public API V0.

We are going to :

• authenticate ourselves to use Sage Active Public API V0,
• request to obtain the tenant Id for the current user,
• then request the list of organizations in this tenant,
• choose an organization,
• and then request, for this organization, the list of accounting journals that we have previously seen from the Sage Active interface.

1. Add the collection and the environment in Postman

Download the Sage Active Public API collection for Postman
Download the Sage Active Public API environment for Postman

1. Open Postman, go to Collections.
2. Click on Import.
3. Click on Choose Files.
4. Select and open the first downloaded file: Sage Active Public API V0.postman_collection.json.

Repeat the same operation for the second file:

1. Stay in the same place.
2. Click again on Import.
3. Click on Choose Files.

4. Select and open the second downloaded file: Sage Active Public API.postman_environment.json.

   

The collection Sage Active Public API is now available in Postman.

As well as the environment Sage Active Public API

2. Authentication process

Complete the list of variables

1. Click on Environment in Postman to see the environment named Sage Active Public API.
   
2. Click Sage Active Public API

   Note that this environment already has the following values set for :

   baseAddress

   AuthUrl

   accessTokenUrl

3. Fill in CURRENT VALUE column following values that you will retrieve from the Solutions tab of your application :

   Attention
   In the context of this quickstart, for scopes, please choose :
   RDSA Read Sage Active Data and WDSA Write Sage Active Data to remain consistent with the rest of the journey and the read and write permissions you just granted in your application.
   
   • In callBackUrl VARIABLE, the first Callback URL that you have filled,
   • in clientId VARIABLE, the Client ID,
   • in clientSecret VARIABLE, the Client Secret,

   • in scopes VARIABLE, the Permissions :

     • RDSA if you have chosen Read Sage Active Data
     • WDSA as well if you have chosen Write Sage Active Data
   • in subscriptionKey VARIABLE, the Subscription Primary key.

4. Click Save

   

   Remember, get the values from the Solutions tab of your application:

Ask a New Access Token

1. Go to Collections and choose Sage Active Public API.
2. In the header, on the right, choose the environment Sage Active Public API.
3. Open folder Authenticate and choose your organization, then Oauth Authentication.
4. Click Auth tab,
5. Then click Get New Access Token button.
   

Authentication checking

You will now be prompted to login to your application.

• The window for connecting to your application appears.
  Enter the email and password of your Sage account and validate.

  

• Now you need to give your app permission to access your Sage Active data

  

  Do you want to know how a user can revoke their consent?

  • From Sage Active stage,
    Click on Configuration / Public API / Consents

    
    
    

  • The list of consents, granted for the different applications using the Sage Active Public API V0, appears.
    From this list, it is possible to revoke consents.

    
    
    

  • If an app’s consents have been revoked, when you later relaunch the app, the consent approval request will be offered again.

  • If the user has not granted any consent, this screen will be displayed:

    
    
    

• You now have an access token.

  1. Click on Use Token.
  2. Move up to the authentication page to see the Token field:
  3. Click once in the field to display the complete token, then click 3 times to select it, then click Set as variable
  4. Choose from the list of variables: accessToken,

     Attention, do not mistake, choose accessToken and especially not accessTokenUrl

     

• This will add the token to the variable accessToken in the Sage Active Public API environment.

  Great, you now have an authentication token and you can run your first query.

3. Choose an organization and request the list of Journals

For our example we are going to request :

• the tenant ID of the current user,
• the list of organizations to retrieve the identifier of an organization in this tenant,
• then the list of journals in this organization.

Request the tenant id

1. First, check in the environment Sage Active Public API, if the variable accessToken is now filled.

   Otherwise, without access Token you cannot query the current Tenant Id and you need to repeat the previous step.
   
   

2. Click on the Sage Active Public API collection and open folder Authenticate and choose your organization.
3. Click on Q.userProfile - {{X-TenantId}} filled in,
4. then click Send button.

5. Information about the authenticated user is returned by the API, including activeTenantId which contains the id of the tenant.

   Tips and tricks
   For simplicity, the Tests tab contains a script that automatically adds the id to the X-tenantId variable of the environment.
   The X-tenantId will then be known by the whole collection.

Request the list of organizations

1. First, check in the environment Sage Active Public API, if the variable X-tenantId is now filled.

   Otherwise, you cannot query the list of organizations and you need to repeat the previous step.
   
   

2. Now click on Q.organizations List - choose one and manually fill in {X-OrganizationId},
3. then click Send button.

4. The list of organizations of the current tenant is returned by the API.

   Can’t wait to know the syntax of the query?

   Just click on Body to find out.

   

Define your organization as variable

1. Choose your organization, then select its id (without quotation marks),

   We suggest you choose the Bijou SA organization that contains a dataset that will help you use this collection.

2. then right click and select Set: Sage Active Public API (without quotation marks),

3. then select X-OrganizationId to save the id in the variable.

   
   
   

Request the list of journals

1. First, check in the environment Sage Active Public API, if you have now a value for X-TenantId and X-OrganizationId

   Otherwise, you cannot query the list of journalTypes of the organization and you need to repeat the previous step.
   
   

2. Return in the collection and open the folder Reference : related to an organization.
3. Open sub folder Journal Types.
4. Click on Q.journalTypes - first id filled in {{currentId}},
5. then click Send button.

6. The list of journals is returned by the API.

   

   How about adding a little filter to our Journals query?

   • Click Body tab
   • As an example, to obtain only the list of journals of type purchase or sales, add a where expression :

     query {
     journalTypes (
         where:{ type:{in: [PURCHASE_INVOICE, SALES_INVOICE]}}
     ) {
         edges {