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

We are going to :

• authenticate ourselves to use Sage Active Public API V2,
• request the list of organizations authorized for this user,
• 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. Run Postman

• Either download and install the Postman for Windows application, then launch it.
• Or access Postman on the web.

2. Add the collection and the environment in Postman

1. Download the collection for Postman
   Download the Sage Active Public API collection for Postman

2. Depending on your Sage Active subscription environment, download the corresponding Postman environment.
   Download the Sage Active Public API FR environment for Postman
   Download the Sage Active Public API ES environment for Postman
   Download the Sage Active Public API DE environment for Postman

3. Open Postman, go to Collections.
4. Click on Import.
5. Click on Choose Files.

6. Select and open the first downloaded file: Sage Active Public API V2.postman_collection.json.

   

7. 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 FR/ES/DE.postman_environment.

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

As well as the environment Environment Sage Active Public API related to Your Sage Active.

3. Authentication process

Complete the list of variables

• Note that the Postman environment already has the following values set for :

  • Here are the different URLs for using the FR, ES, DE API and authenticating your application.
  • The URLs for the SBCAuth authentication service are the same for all three production environments.

  • In Postman environnement baseAddress = API Address without /graphql.

    Sage Active Prod FR

    API Address

    Sage Active Prod ES

    API Address

    Sage Active Prod DE

    API Address

    Authentication

    AuthUrl
    AccessTokenUrl
    Revoke Token URL prod

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

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.
   • If you are using Postman Web, then the callback URL is imposed by Postman.
     You will need to add the callback URL below in the Solutions tab of your application, and you will not need to provide the callBackUrl VARIABLE.
   • In callBackUrl VARIABLE (Postman for windows only), 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 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.

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

   

2. 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 Your Sage Active,
     Click on Configuration / Public API / Consents

     
     
     

   • The list of consents, granted for the different applications using the Sage Active Public API V2, 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:

     
     
     

3. You now have an access token. Click on Use Token.

   

4. Move up to the authentication page to see the Token field:

   

5. Click once in the field to display the complete token, then click 3 times to select it, then click Set as variable

   

6. 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 Environment Sage Active Public API environment.

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

4. Choose an organization and request the list of Journals

For our example we are going to request :

• the list of authorized organizations for the current user to retrieve the id of an organization, as well as the tenantId in which this organization is hosted.
• then the list of journals in this organization.

Request the list of organizations

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

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

   

2. Now click on Q.organizations sorted by most recent, first record X-OrganizationId, X-TenantId, LegislationCode automatically filled in,
3. then click Send button.

4. The list of organizations authorized for the current user is returned by the API.

   

5. To save time, a script in the Tests tab will automatically store in the environment variables:
   • X-TenantId, the tenantId of the first organization in the list,
   • X-OrganizationId, the ID of this organization,
   • and finally LegislationCode, representing the organization’s legislation (this value is used within the collection context to assign consistent values according to the legislation).

   This saves you from having to manually assign these values.

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 simple 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 {
     

   

5. Recommendations

Testing Queries with an Organization Containing Demo Data Already

To maintain consistency, take account of current FR, ES, or DE legislation, and optimize data additions, we recommend you test queries wit an organization that already contains demo data.

Pre-request Script and Test tabs

Please also note that certain values are defined in the Pre-request Script and Test tabs.
The green light indicates whether scripting has been defined:

6. Well done!