Before following any of the examples in this article, ensure your site has been correctly configured for use with the API.  Further information about the setup of the Native API for Sage 200 Professional can be found here>

NOTE: This article has been created as a gesture of goodwill to ease the testing of the Sage 200 API. Setup and configuration of Postman is not supported by Sage 200 technical support or Sage Developer Services. For information on our support boundaries see here >

Contents:

• What is Postman
• Constructing your Authorization Header
• Developer Subscription Key
• Authentication
• Authenticating via the Authorization tab (Confidential client)
• Authenticating via the Token Generator Desktop Application (Public)
• X-Site and X-Company Values
• Making a Basic GET Request in Postman
• Filter using customer_id
• Filter using the $filter query parameter
• What’s Next

What is Postman

Postman is an open-source API development environment (ADE) which enables developers to build and test API queries to many different APIs and endpoints.  You can find out more information and obtain a copy of Postman here.

Constructing your Authorization Header

The following sections discuss how to obtain the prerequisite information required to construct your Authorization header in Postman.

Developer Subscription Key:

Your developer subscription key is a unique ID which is used when making API calls against your account. It is therefore important that these keys are not shared. This is passed as the ocp-apim-subscription-key value in your Authorization header.

For further information on acquiring your developer subscription key please see here >

Authentication

The following sections discusses how to authenticate your API requests for both a Confidential client (Web) and a Public client (Desktop).

CAUTION: For this, you will require a Client ID and Client Secret to be able to authenticate. If you do not have these, or have not yet requested them then please fill out this form. Developer Services will have these credentials created for you (this may take up to 48 hours). You will then be able to continue working with Postman or your choice of ADE.

Authenticating via the Authorization tab (Confidential client)

1. Open Postman and browse the Authorization tab.
2. Set the Type as OAuth 2.0 and the Add authorization data to as Request Headers.
3. In the Current Token section, set the Header Prefix value to 'Bearer ' (omitting the apostrophe and ensuring to include a space after Bearer).
   CAUTION: If you do not add a space you will receive the following error in your response body when you attempt to make an API request: "Message": "Authorization has been denied for this request." 
4. Set the Configure New Token values as follows (ensuring to populate your Token Name, Callback URL, Client ID, Client Secret and State):
   1. Token Name:
   2. Grant Type: Authorization Code
   3. Callback URL:
   4. Authorize using browser: Unticked
   5. Auth URL: https://id.sage.com/authorize?audience=s200ukipd/sage200
   6. Access Token URL: https://id.sage.com/oauth/token
   7. Client ID:
   8. Client Secret:
   9. Scope: openid profile email offline_access
      NOTE: Removing offline_access from the Scope still allows you to authenticate, however, a refresh token will not be returned in the body of your access token request. 
   10. State:
   11. Client Authentication: Send as Basic Auth header
5. Select Get New Access Token.
6. A new window will appear asking you to enter your Sage ID Email Address.
7. You will then be asked to enter your Password and grant permission to your 3rd party application.
8. The Manage Access Tokens screen will then appear with a new Access Token and the Token Name you entered in step 4.
9. Select Use Token and the Access Token field, in the Current Token screen, will now be populated with your new Access Token.

Authenticating via the Token Generator Desktop Application (Public)

To aid development and testing of 3rd party API credentials, the Sage Developer Services team has produced a basic Windows Form application which allows users to enter their Client ID and request an access token using the method detailed in the Sample Application and Client Library. This token can then be copied into the Postman Headers section as detailed below.

1. Download and run SageCloudIDTokenGeneratorv1.2.exe.
   NOTE: This download is only available to members of the Developer Programme. If you are unable to download the application, please contact Developer Services who will send you an alternate link. 
2. Enter your Client ID and select Generate Access Token.
   NOTE: If you encounter an Unexpected Exception when attempting to generate an access token, please ensure you have entered a valid Public Client ID. Should the issue persist, please contact Developer Services. 
3. When prompted enter your Sage ID email address and password.
4. A message will appear advising "Access Token Copied to Clipboard".
5. Close the message and open Postman.
6. Browse the Headers tab and add a new key called Authorization.
7. Paste your token into the Value field.

X-Site and X-Company Values

In order to make database specific requests via the Sage 200 API, such as a GET request against the Customers endpoint, you must specify the Site ID (X-Site) and the Company ID (X-Company) your request relates to in the request header.

In order to acquire these values a GET request can be ran against the sites endpoint to return the ID values of all the sites/companies your Sage ID is the API User.

To request site information via Postman:

1. Open Postman and select File and then New (Ctrl + N).
2. Select Request and enter your Request name and select a Collection.
   
   

   TIP: Further information on creating collections in Postman can be found here.

3. Acquire a valid access token (for either Sage ID or Cloud ID) as per the Authentication section of this article.
4. Browse the Headers tab and enter the following Key(s) and Value(s):
   
   ocp-apim-subscription-key: Your Developer Subscription Key.
   Content-Type: application/json
   
   
5. Ensure the HTTP Method is set to GET and enter the correct sites endpoint URL for your application:
   
   For Sage 200 Standard, this would be: https://api.columbus.sage.com/uk/sage200/accounts/v1/sites
   For Sage 200 Professional, this would be: https://api.columbus.sage.com/uk/sage200extra/accounts/v1/sites
   
   
6. Send your request.
7. A successful 200 OK HTTP response code should be returned, and your response body will contain an array of site’s information.
8. Note the site_id and company_id values as these will be set as your X-Site and X-Company values, respectively.
   
   

   TIP: Once you have acquire the X-Site and X-Company values you may wish to add these to the your collection variables so that they can be easily generate create new requests for a specific company.

Making a Basic GET Request in Postman

After acquiring your X-Site and X-Company values you will now have all the information required to construct a database specific request. The following section discusses how to run a GET request to the Customers endpoint for a specific customer record.

1. Ensure your Authorization Header information is still populated, your Access Token has not expired, and you have added the X-Site and X-Company values acquired in the previous section. Your Headers tab should therefore show the following:
   
   ocp-apim-subscription-key: Your Developer Subscription Key.
   Content-Type: application/json
   Authorization: A valid access token (if authenticating using Cloud ID)
   X-Site: The site_id value of the Site. 
   X-Company: The company_id of the Company.
   
   
2. Ensure the HTTP Method is set to GET enter the customers endpoint URL for your application:
   
   For Sage 200 Standard, this would be: https://api.columbus.sage.com/uk/sage200/accounts/v1/customers
   For Sage 200 Professional, this would be: https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers
   
   
3. If you wish to return information for all Sage 200 customers, select Send. If, however, your wish to only return information for a specific record you can filter as described in the following sections.

Filter using customer_id

If you know the ID of the record you wish to run the GET request for you can append this to the end of your request URL.

Example: https://api.columbus.sage.com/uk/sage200/accounts/v1/customers/17

Filter using the $filter query parameter

As the customer_id is not surfaced in the Sage 200 application, it is likely that you will not know this prior to making your GET request. In these cases, a query parameter can be used to filter based on a known field.

An example of this would be using the (Sales Ledger) reference, as this is visible in the application and unique to each Customer record.

Example: https://api.columbus.sage.com/uk/sage200/accounts/v1/customers?$filter=reference eq 'A1D001'

Further information on supported query parameters for the Sage 200 Standard and Sage 200 Professional APIs can be found here.

What’s Next

Now you can construct API requests using Postman, you wish to start querying additional endpoints, creating new records, or updating existing records via the Sage 200 API.

A list of all available endpoints, and supported methods, can be found in our API documentation.

For Sage 200 Standard see here.

For Sage 200 Professional see here.

We also have a collection of API example requests which can be found below and ran in Postman.

You may also wish to start developing a desktop or web application that makes use of the Sage 200 API. A sample application and client library to get you started can be found here.

Prior to going live with your application, please ensure that you have requested live API credentials by completing our request form.

If you encounter issues authenticating your requests, or querying the Sage 200 API, using Postman, please see our Common Queries and Frequently Asked Questions article which can be found here.

NOTE: Please be aware that Sage Developer Services only support the API endpoints and not the implementation, troubleshooting or debugging of applications that make use of the Sage 200 API. This is further explained in our support boundaries which can be found here.

[BCB:180:Andy Footer:ECB]