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

We are going to :

1. Run Postman

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. img

  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. img

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

3. Authentication process

Complete the list of variables

  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

    img

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

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.
    img

Note that all parameters of this Auth tab that contain variables will have their values populated by the variables defined in the chosen environment.

img

  • Postman Windows:
    Check that the CallBack URL mentioned in the environment variable is the same as one of those in the Solution tab of your application.

  • Postman Web:
    Check that the callback URL below is the same as one of those in the Solution tab of your application.

Example of callBack URL mismatch error for Postman Windows img

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.

    img

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

    postman authorization

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

      img

    • 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.

      img

    • 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:

      img

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

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

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

    img

    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 :

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.

    img

  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. img
  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.

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

    We recommend selecting an organization that includes a dataset with demo data to assist you in utilizing this collection.

  2. then right click and select Set: Environment Sage Active Public API,
  3. then select X-TenantId to save the value in the X-TenantId variable. img

  4. repeat the operation with id for X-OrganizationId img

  5. And finally with legislationCode for legislationCode img


Just click on Body to find out.

img


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.

    img

  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.

    img

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

    img


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.

Import demo data

Discover how then sample quotes app now seamlessly enables the importation of a comprehensive set of demo data into your current company, should it find the data vaults empty.

A simple, streamlined process to kickstart your experience with fully populated data!

How to import Demo Data in your organization ?

Importing a demo dataset through the Samples quotes app, provided as an API usage example, is straightforward.

Follow these steps:

  1. Launch the Online version of the sample quotes. Sample quotes / 2. Test the app Online
  2. Select the organization where you wish to import the demo data.
  3. If this organization does not yet contain customers, fiscal years, or accounting accounts, a dialog box will appear, offering to import the demo data.
img

The imported data pertains to:

  • Customers: A batch of customers from the legislation, customers in France, one customer per VIES country
  • Suppliers: A batch of suppliers from the legislation, suppliers in France
  • Employees: A list of employees with names in line with the legislation
  • Products: A list of products with titles and descriptions in the language of the legislation
  • Accounting accounts: The accounts from the first standard accounting plan of the legislation
  • Fiscal years: Two calendar years, n-1 and n
  • Accounting entries: A set of accounting entries consistent with the legislation
  • In each legislation, a customer and a supplier have been chosen to assist with demonstrations; they have a larger number of accounting entries than other third parties.
    • customer: CARAT - Carat S.a.r.l
    • supplier: BILLOT - Billot
    • customer: 8008 - José Martínez Pérez
    • supplier: 1005 - Carmines Juanan
    • customer: 10135 - Krause Bürotechnik GmbH
    • supplier: 70028 - Manderscheid Gmbh
  • To always stay in the same context of demonstration, each month contains the same accounting entries, so no matter the day of the demonstration, the journal entries will always present the same information.

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:

img

img


6. Well done!

You have just executed your first requests to Sage Active Public API V2.

Now continue to discover the collection :

  1. Discover queries with filters, sorting and pagination.
  2. Discover mutations to create, update, delete.
  3. Reference of all objects common to all organizations with all available queries and mutations.
  4. Reference of all objects related to an organization with all available queries and mutations.

Then you will be able to start developing your first application.
img