Sage 200 API - Common Queries and Frequently Asked Questions

Contents:

• Setup and Configuration
  • Getting Started
  • Common Errors
• Development
  • Getting Started
  • Postman
  • Common Error Codes
  • Querying the Sage 200 API
• Help and Further Support

Setup and Configuration

Getting Started

Q. How do I setup and configure my Sage 200 site for use with the Sage 200 API?

A.The steps required to configure a site for API access vary based on the version of Sage 200 you, or your client, is using:

Sage 200 Standard: the API is enabled by default and simply requires users be enabled for API access.

Sage 200 Professional: With the release of Sage 200 Professional Spring 2018 there are 2 methods to enable external connection to your site for the Sage 200 API. The recommended connection method for Spring 2018 and above is to use the Native API. The Native API uses Azure Active Directory tunnelling to establish a connection with the site and requires far less configuration than using an externally facing web server. Further information on setting up the Sage 200 Native API can be found here.

Q. Is there a cost associated with developing for the Sage 200 API?

A. Developing for the Sage 200 API does not require a membership to the Sage Developer Programme, however, in order to effectively develop for the Sage 200 application using the API, it is recommended that you or your client have a test environment which matches the live version of the production environment.

Q. Is the API supported with Sage 200 Standard Try and Buy?

A. The API will work with Sage 200 Standard Try and Buy sites, however we will not support the troubleshooting, implementation or debugging of the API and/or connected services that involve the API.

Q. I wish to setup the Sage 200 API, or I am having difficulties setting up the Sage 200 API. Who should I speak to?

A. We have produced the following article, see here, which explains the roles and responsibilities for setting up the Sage 200 API, including those of the Customer (and their IT), Sage Accredited Business Partner, Sage 200 Technical Support and Sage Developer Services.

Generally, all setup queries must first be raised with your relevant support provider, be that Sage or your Accredited Business Partner. Sage 200 Technical Support can then assist with escalated queries regarding setup and configuration whilst Sage Developer Services will assist authentication and formatting of API requests.

Q. The Sage 200 API has been successfully configured for my Sage 200 site; how can I test if this has been successful?

A. You can use our API test tool to log in using your Sage ID to see whether you can return companies you are assigned to.

Q. Can a Sage 200 Business Partner have multiple Office 365 Tenants for demo, testing and development work?

A. You cannot configure the API to use a different URL so it is one API configuration per subscription. You need an Office 365 Tenant per Sage 200 environment you are targeting.

Suggested Workarounds:

1.  Set up a central demo/test system always turned on (perhaps on a machine based in the office) which is set up for API demos and several people share.
2.  The business partner could research themselves or approach Microsoft about providing tenants for demo purposes.

Q. Can I change the email address I used when I installed the Native API tunnel?

A. Yes, you can. We have an article documenting the steps to do this here. These steps must be followed in the order written, otherwise you may end up with the error APISiteAlreadyExists when trying to set up the API.

Common Errors

Q. I try to log into the Sage Business Centre and see the following message - "Subscription not available. The Microsoft 365 subscription you signed in to is not associated with Sage. Contact customer support to determine why". How do I resolve this?

A. You will get this error because you have not yet onboarded your Office 365 tenant with ourselves. You should have received an email from [email protected] that contains a Getting Started link. You need to follow through the steps in this email to onboard.

If you have not received the email, please contact Sage 200 Technical Support (or your Business Partner if applicable) to determine where the email has been sent. The Technical Support team can send the email to an alternate email where required.

Q. When trying to Activate your Microsoft 365 ready for Sage 200 Integration via the invite email received from Sage I get "Subscription not ready. The Microsoft 365 subscription is not ready. You must complete the on-boarding process by going back to your email and clicking Get Started.". How do I resolve this?

A.  This is a relatively uncommon error and could be caused by going part way through the verification process with a different email address. Please ensure prerequisites have been met and if they have, contact Sage 200 Technical Support (or your Business Partner if applicable) to investigate as a new connection may need to be created.  

Q. During the installation, and configuration, of the Azure Application Proxy Installer, I receive the following error "AADSTS650052: The app needs access to a service that your organization has not subscribed to or enabled. Contact your IT Admin to review the configuration or your service subscriptions." What causes this error and how do I resolve it?

A. This error is caused by the Microsoft 365 license not being fully provisioned prior to attempting the install. 

If the tenant was purchased directly from Sage, you should have received an email from [email protected]. This email contains steps to complete the tenant onboarding and must be completed prior to installing the Azure Application Proxy Installer on the Sage 200 server.

You will therefore need to uninstall the Azure Application Proxy from the Sage 200 server, complete the onboarding steps and then select Install and Configure from within the Azure Application Proxy Installer.

Q. During the installation and configuration, of the Azure Application Proxy Installer, I receive the following error: "The type initializer for 'Sage.Graph.ClientFactory threw an exception."

A.This error can be a result of previously installing the Azure Application Proxy using different Microsoft Azure account credentials. To resolve this error remove the TokenCache.dat from the Azure Proxy Installer folder and re-try. 

Q. During the installation and configuration, of the Azure Application Proxy Installer, I receive the following error: "Authorization has been denied for this request"

A.This error can be a result of a previous install where the tblParameters table still has an entry for the old APISiteID, for guidance on removing this along with other data from a previous setup see here.

Q. After entering my Microsoft 365 email address and password a second time during the configuration of the Azure Application Proxy Installer, I receive the following error: Error: APISiteAlreadyExists”. How do I resolve this issue?

A. This issue occurs when the API site credentials have already been used to configure the Native API on another server, either test or production. To resolve this issue please see here.

Q. After entering the site name and site URL in the API tab of Sage 200 System Administration, I receive the following error: “APISiteAlreadyExists”. How do I resolve this issue?

A. As with the previous query, this issue is caused when the API site credentials have already been used on another Sage 200 server, either test or production. The following steps have been produced to advise you how to resolve this issue, however, please be aware that these steps have been created to resolve this issue for externally facing web servers. For the Native API please see the previous question.

1. Open Sage 200 System Administration.
2. Select the API tab and sign in with your Sage ID.
3. Click Edit and untick Enable API.
4. Press OK and this will disable the API for this site.
5. Follow our How to set up the API Service for use with Sage 200 Professional guide to set up the API, see here.

If the original site is no longer accessible, your Sage Accredited Business Partner will need to raise a case via case management to Sage 200 technical support stating the: site name, site URL and email address being used to set up the API.

Once technical support has removed the site information from our internal system, you will be able to complete setup of the Sage 200 API. Please see here for further information.

Q. After granting permission to the Sage Business Center, during the Microsoft 365 onboarding process, I receive the following error: “Cannot setup your integration. We cannot setup your Sage 200 Accounts integration with Microsoft 365 because your Microsoft account does not include the required subscriptions”. What causes this error and how do I resolve it?

A. This issue occurs when the Microsoft 365 user does not have an accepted supported license assigned to their account.

This does not only apply to the licene name (i.e. Microsoft 365 for Business) but also the SKUID of the product. If you encounter this error, first confirm that the Microsoft 365 administrative user, being used to onbaord the Sage 200 Native API, has one of the following supported licenses assigned to them:

• Microsoft 365 Business Standard (formally Office 365 Business Premium)
• Microsoft 365 Enterprise 1 (Microsoft no longer sell this subscription)
• Microsoft 365 E3 (formally Office 365 Enterprise 3)
• Microsoft 365 E5 (formally Office 365 Enterprise 5)
• Microsoft 365 A1 (faculty and student)
• Microsoft 365 A3 (faculty and student)
• Microsoft 365 A5 (faculty and student)

Should one of these license types be assigned to the user, please follow the steps here to determine if the SKUID of your product is supported.

Q. The API connection has been set up and working for some time but suddenly stops working, when Getting Site Status via the API Test Tool you receive a 'Site Cannot be reached' page, and testing the API results in a 404 error (this can be seen as an error in the Sage 200 Secured Services Log).

A. This problem can be caused by the required subscriptions for Microsoft 365 and /or Microsoft Entra ID P1/P2 (formerly Azure AD P1/P2) being disabled, this can be checked via https://admin.microsoft.com/Adminportal/Home#/homepage and clicking on the Subscriptions tab.

Development

Getting Started

Q. Where can I find the API documentation for my Sage 200 application?

A. Documentation for the Sage 200 Standard and Professional API can be found here.

Q. My site has been successfully configured for use with the Sage 200 API, how can I start developing my Sage 200 application?

A. The Getting Started section of our Sage 200 API Developer Website provides a helpful checklist of the steps required to begin developing with the Sage 200 API.

Q. The Getting Started guide advising I “Subscribe to the Sage API of your choice”; which is the correct option for Sage 200 Standard or Sage 200 Professional?

A.  Once you have created your Developer website login, this page will show you a list of available UK API’s. Selecting Subscribe to either the Sage 200 Professional or Sage 200 Standard APIs will add the Sage 200 Unlimited subscription to your developer account. This only needs to be selecting once and will cover both Sage 200 APIs.

Q. I have downloaded the sample application and client library from the Developer website; however, when attempting to authenticate, I encounter an error?

A. The sample application provided on the website, see here, is intended to demonstrate the new method of authentication. The older method is still supported for existing applications, however, will be deprecated 19th February 2021.

If you are developing your application using your old API client credentials, please complete our Sage 200 API Credentials Request Form to recieve compatible client credentials.

Q. I am developing/testing my application and I require demonstration Public/Confidential Client credentials to generate an access token?

A. Please complete our API credentials request form, ensuring to select Development, which will generate, and forward, your request to the Developer Services team.

Q. I have completed development of my application and require live Public/Confidential Client credentials prior to deploying this in a production environment?

A. Please complete our API credentials request form, ensuring to select Production, which will generate, and forward, your request to the Developer Services team.

Q. What is the difference between Development and Production client credentials?

A. Development credentials are intended to allow to you to develop, and test, your Sage 200 API application. To protect our service, we have limited the number of requests from development credentials to 20 per minute.

Production credentials are to be deployed in live production environments and should not be used testing or development purposes. These credentials are limited to approximately 6000 requests per minute. It is therefore suggested that developers who deploy their application on multiple heavy usage sites request multiple client credentials and monitor where these have been deployed. 

Q. When requesting Sage 200 API credentials, I am no longer asked what I would like the access token expiry to be set as. How can I set this?

A. With the migration to the new authentication method the access token expiry is no longer set per client and is instead the same for all Sage 200 API credentials. The access token expiry is set to 8 hours (480 minutes).

Q. What is the maximum value I can set the client credentials refresh token expiry to?

A. The new Sage ID authentication method supports a maximum refresh token expiry of 90 days.

Q. I have received my new client credentials; however, I have not received a Scope. Is this correct?

A. Unlike our previous authentication method, which required a client specific scope, the new authentication method replaces this with a universal scope.

We recommend using “openid profile email offline_access” as this will return a refresh token in the authorization token request response body. 

You can also authorise by using “openid profile email” which will return a access token, however, your response body will not contain a request token.

Q. How do I amend my existing API credentials? i.e. Change the Access Token/Refresh Token expiry, add or remove Redirect URLs, etc.

A. Please contact Sage Developer Services to request changes to your Sage 200 API credentials, ensuring to include your existing credentials Client ID and details of the required change.

Q. Can I use a background service to handle the authentication of my application?

A. No, the initial authentication must be performed by a user. Once this is done the refresh token can be used to keep the application authenticated, up to the expiry lifetime of the refresh token. This can be up to a maximum of 90 days. After this point a user will need to authenticate the application again.

Q. How is the authentication header for Sage 200 API requests formatted?

A. For those who wish to read a detailed breakdown of constructing a Sage 200 API request we have produced the following guide, see here.

Postman

Q. Can I use Postman to query the Sage 200 API?

A. Yes. Due to the simplicity of the Postman application we strongly recommend developers use this application to test their API authentication, request headers and bodies prior to attempting these programmatically.  We have created the following guide to using Postman, see here, specifically for the Sage 200 API which covers all of the required configuration.

Q. When I attempt request an access token via Postman, I receive the following error after entering my Sage ID “Could not complete OAuth 2.0 login. Check Postman Console for more details.” The Postman console shows: Error: [object Object]. How do I resolve this?

A. This issue occurs when your Sage ID has not been registered for use with the Sage 200 API. As part of the setup and configuration process you should receive an email to register for the Sage 200 API, however, should this not occur you can manually register your Sage ID by visiting: https://www.sage200onlineservices.com/register.

You may also encounter this issue if you are using the old Sage ID authentication method, which is not supported for Sage ID’s registered after 1^st September 2020 and will be deprecated 19^th February 2021.

Common Error Codes

Q. What do we mean by the authenticating user?

A. The authenticating user is the user whose Sage ID is used to request an access token which is passed in the API authentication header. The sites, companies and features which this user has access to are then used to determine if the request is valid.

Q. Why does my access request response body not contain a refresh token?

A. This issue occurs when "offline_access" is omitted from the scope value of your access request. To resolve this issue, ensure the following scope is used for all subsequent access requests.

Scope: openid profile email offline_access

Q. When querying the sites endpoint, I receive a HTTP 200 (Successful) response code, however, the response body does not contain any site information?

A.  Please see this article for further troubleshooting steps.

Q. When attempted to query an endpoint I receive a HTTP 401 (Unauthorized) response code?

A. There are numerous causes for a 401 (Unauthorized) error when attempting to make an API request. The most common amongst these are:

• The access token has expired.
• The X-Site and X-Company values are invalid or have been omitted from the request header.

To ensure your access token has not expired, re-attempt your API request immediately after requesting a new token. This issue is more common when querying the API through a 3rd party application, such as Postman, as these do not use the refresh token, unlike application which make use of the authentication method detailed in the sample application.

If you have a valid access token, the issue is then likely due to the X-Site and X-Company values not being present in your API request header or the authenticating user not having access to the relevant Site/Company.

To view the X-Site and X-Company values of all of the companies which the authenticating user has access to a GET request can be ran against the sites endpoint. The site_id and company_id values of the relevant company should then be passed in subsequent, database specific, requests as the X-Site and X-Company values respectively.

Q. When attempted to query an endpoint I receive a HTTP 403 (Forbidden) response code?

A. A 403 (Forbidden) error is usually caused by the role to which the authenticating user belongs not having access to the module the API endpoint surfaces. An example of this would be a user requiring access to the Sales Ledger module in order to run requests against the customers endpoint.

Further information on checking user access rights can be found in the application help files:

• Sage 200 Standard
• Sage 200 Professional

Q. When attempted to query an endpoint I receive a HTTP 404 (Not Found) response code?

A. A 404 (Not Found) error can be returned for a variety of reasons, however, the most common causes are:

• An incorrect endpoint URL being specified.
• An invalid verb being used for your specified endpoint.
• The endpoint is not available in your version of Sage 200.

Please confirm the endpoint URL is identical to that supplied in the API documentation and the verb being used (i.e. POST) is supported by the endpoint you are querying; this is also listed in the API documentation for the endpoint.

Should the endpoint match the API documentation, and the verb be supported by the endpoint, the issue may be due to the endpoint not being available to your version of the Sage 200 application, despite being listed in the API endpoint documentation. For Sage 200 Standard, this is not an issue as all sites are maintained and kept up to date, however, as Sage 200 Professional is an on-premise application client sites may not always be on the most recent version.

To check which version of Sage 200 Professional an endpoint, or field, is available in, browse the What’s New section of the Sage 200 Professional API documentation and locate the endpoint. The section the endpoint is in will be proceeded by a date and year. This date can then be cross-referenced with the release date of the Sage 200 Professional versions, found here, to determine which versions the endpoint is available in.

Q. When attempting to query my data, I receive 'Error 524 - network origin timeout'

A. This has been seen when querying Sage 200 Standard Online. The reason for this is that although the site has been created in the Sage Provisioning Portal, the database has not yet been configured. We would always recommend downloading the application and running through the setup of your database before attempting to query the API. Steps on setting up your database can be found here.

Q. When using the Sage 200 Sample Application and I click on Get Sites, I receive the following error - 'Sequence contains no elements'

A. This error is stating that you have a blank body returned from the Get Sites query. To resolve this issue, please see 'When querying the sites endpoint, I receive a HTTP 200 (Successful) response code, however, the response body does not contain any site information?'

Querying the Sage 200 API

NOTE: Please note, the Sage 200 API does not support the use of the OData "In" filter when querying data. To find the supported filters, please see the API documentation here.

Q. Is it possible to create printable invoices via the Sage 200 API?

A. Unfortunately, at present, the Sage 200 API only supports the creation of transactional sales invoices via the sales_invoices endpoint, not invoices which would be raised via the Invoicing module.

If you require printable invoices you will need to create these invoices as Sales Orders, via the sop_orders endpoint, passing the Sales Order lines as part of the initial Sales Order POST request and then allocate/dispatch/invoice these via the client application.

Please see The data I want to use is not exposed as an endpoint. Can I request new endpoints be added to the application? for further information on what to do if the desired fucntionality is not currently possible via the Sage 200 API.

Q. Is it possible to return all information, from an endpoint, in the response body of my request, rather than the 500 records that are returned by default?

A. Although it is not possible to return all records in the response body, by including the $top query parameter in your request URL, it is possible to increase the number of records returned to 5000.

E.g.  https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers?$top=5000.

Q. When I attempt to use the $skip parameter in my query URL I encounter the following error: “Incorrect syntax near '@__Skip'.\r Invalid usage of the option NEXT in the FETCH statement”. How do I resolve this?

A. To use the $skip parameter you must also specify the field you are ordering your results by, using the $orderby parameter.

E.g. https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers?$skip=10&$orderby=id

Q. When requesting a new token, I get 'Sage Cloud Identity oops something went wrong. Callback URL mismatch'

A. This error is caused by the request token having an incorrect callback URL. Please ensure the callback URL you are passing in the token matches the one you requested when filling out the API Credentials Request form. If you need additional callback URLs added, please get in touch with Developer Services.

Help and Further Support

Q. The data I want to use is not exposed as an endpoint. Can I request new endpoints be added to the application?

A. Yes, you can raise this on the Sage 200 Ideas Portal, as this is routinely monitored by Product Delivery when assessing future changes to the application.

You may also wish to enquire about Sage 200 Software Development Kit (SDK) as the SDK allows: scripting/customisation of desktop forms, integration of external applications and extension of existing data objects/reporting data models (including creation of custom data objects/models).

Unlike the Sage 200 API, however, the Sage 200 SDK does require an active membership to the Sage Developer Programme.

Q. The Sage 200 API has been successfully configured; however, I have some questions regarding the API endpoints or authentication, who is the best person to speak to?

A. For information regarding the available endpoints, supported methods and query parameters, or getting started with the Sage 200 API, we would advise checking the Sage 200 API Developer website. 

If you are encountering issues errors when attempting to query the API, we would recommend reviewing the Common Error Messages section of this FAQ.

For live API credential requests, please complete our online request form.

If you still require assistance, you can raise a case with the Developer Services team via Case Management. Further information on raising a case via Case Management can be found here.

Alternatively, you can email the team at [email protected].

NOTE: Please be aware that although the API is non-language specific the team do not support the implementation, troubleshooting or debugging of applications that make use of it.