Summary
Description
NOTE: As per our communication sent to you, this method of setting up the API will no longer be supported as of 19th Febuary 2021.Please ensure you follow this article on how to set up the Native API Tunnel for future API set ups.
This article explains the process for installing and enabling the API on a customer site. If you are using Sage 200 Extra, you'll need to purchase a digital certificate from a third-party provider so that the server can accept secure external connections.
The API installer used should be the one held in the installers folder of 200 which will ensure you always use the correct version. If for any reason you do not have the installers folder, or access to it you are able to download one from our support website.
NOTE: You must ensure you have consent from your customer to enable the API within their software. As part of the setup process, you will be required to contact Business Partner Services to confirm they wish to enable the functionality. The customer will receive notification of this upon completion.
Resolution
Setting up the API service for Sage 200
Important pre-requisites to note
Topology – Sage support the setup and use of the on-premise API in the following configuration.
- Sage 200 Server and SQL setup and working.
- Installation of the 200 API must be on a separate externally facing web server on the same domain / network as your Sage 200 / SQL server. This is a vital for authentication with Sage ID to work and the subsequent redirect to your server to be accepted by the API.
- You must ensure that the certificate you use when setting up the site bindings (explained in a later part) is bought from an authorised secure certificate issuing authority. The default Sage 200 API SSL Certificate will not work.
NOTE: For further details please see the Deployment and Installation guide relevant to your version of Sage 200.
Install the API service
- When using Sage 200 it is recommended to use the API installer that is added to your system as part of the main 200 install to ensure the correct version is used.
This is vital to a working setup, if you use the wrong version of the API installer it will not work, or will produce inconsistencies in the data.
You can however, download the API Installer for your version of Sage 200 by going to Ask Sage article .
- Ensure this is installed on an externally facing web server on the same domain as your Sage 200 Server and SQL database.
- Right-click on Sage200API.exe and run as Administrator.
- Follow the steps within the Sage 200 API installer. You must ensure you carry out the following as part of the installation process:
- Change the Logon directory path to the location of your Sage 200 Server machine. Don't leave this as the default value.
- Enter the correct password for the Server Identity Username that has been detected on the subsequent screen.
- Change the Logon directory path to the location of your Sage 200 Server machine. Don't leave this as the default value.
- Once the installation has completed, proceed to the next section below.
Apply your SSL certificate to the API website
Once you have installed the API website on your external server machine, you need to amend the website bindings in IIS to use the external SSL certificate and set up firewall rules on both your Sage servers.
NOTE: If you require any assistance with setting up bindings, you should contact your IT support team.
- Open Internet Information Services (IIS) Manager.
- Expand the list of websites and choose Sage 200 API.
- Right-click on the Sage 200 API website and choose Edit Bindings.
- Choose Add.
- Change the type to https.
- Set the port number to a port that's not currently in use.
- From the SSL certificate drop-down menu, choose your external SSL certificate.
NOTE: This is not the Sage 200 API SSL Certificate.
- Click OK.
NOTE: You may see a message informing you that another site is using the same HTTPS binding. Click Yes to apply the binding to this site.
Click OK to close the Add Bindings window. - Click Close to close the Site Bindings window. The Sage 200 API web site is now using your external SSL certificate.
Set up firewall rules
NOTE: If you require any assistance with amending firewall settings, you should contact your IT support team.
To increase the security of your deployment, you must configure the Windows firewall on both of your Sage servers. The following table details the ports that need to be opened for Sage 200 to function correctly.
Sage 200 Server (Inbound Rules) | TCP Port Sage 200 App Services (Default 10443) | |
SQL Server (Inbound Rules) | TCP Port SQL Server (Default 1433) | |
Sage 200 API Service Server (Inbound Rules) | TCP Port specified during the assignment of the binding to the Sage 200 API website |
Check API service can be accessed
NOTE: Carry out step 1 of the below steps on a machine outside of the server/API network.
- Enter the following location in your browser:
https://HostName/sage200api/internal/api_status.
The HostName is the name specified when you created a binding for the API site. - If the page returned has a value of 1, then the API can be accessed externally. If this is not returned, then please contact your IT support for further assistance.
- Check the Web.Config file, on the server go to c:\inetpub\sage 200 api\Sage200API and using notepad edit the Web.Config file in this folder.
Find the line which relates to the credentials.xml file and ensure it has the correct path to the Sage 200 credentials file.
For example:
If the API is returning no companies check that the site URL in System Administration is correct and begins with https://.
Also ensure that you can access the path \\ServerName\Sage\.
Activate the API in Sage 200 System Administration
Once you've installed the API Service, it needs to be activated in Sage 200 System Administration.
Register your Sage ID for the Sage 200 API
A Sage ID is used to give your company access to the Sage 200 API and to log on to your apps. If you don't have a Sage ID already, you'll be asked to create one.
- Open System Administration, click API.
- Click Edit.
- Click Get Sage ID.
- Follow the instructions to complete the registration.
- If you are encountering issues when configuring the API Settings or with your Sage ID registration, you can manually register your ID by browsing to www.sage200onlineservices.com/register
You may encounter an error message:
If this is the case, then your ID is already registered for use with Sage 200 Extra.
Activate the API in System Administration
You need to enter the URL for the public endpoint of the API. This will be your domain name and end in /Sage200API, such as https://your domain name/Sage200API:
- Open System Administration, click API.
- Click Edit.
- Select API Enabled.
- Enter a name for your site, this can be anything of your choice.
- Enter your Site URL.
- Click OK. You'll be prompted to log in with your Sage ID. The site status will show as Pending until your licence has been updated.
Contact Sage to update the Sage 200 licence and enable the API.
In the setup of the API, the API tab will show your site as ‘PendingAuthorisation’. To enable this you will need to speak to technical support. Before calling through, ensure you have the Site Name, Site URL & email address which was used to set the API up. Once the details have been confirmed and they have advised the API is now enabled, in System Administration select ‘Actions’ from the top, and then ‘Refresh’. The API status should have changed from ‘PendingAuthorisation’ to ‘Enabled’.
Set up API users
Every user who will access an app via the API will require their own Sage ID. You will also need to specify which users have access to the API on their User Properties:
- Open System Administration, click Users, User Name.
- On the General tab, select Is API User.
- On the User details tab, enter an email address for this user. This is the email address they'll use for their Sage ID to access the app.
- On the Company Access tab, check the companies the user can access. Users will only be able to access companies via the app that they have access to here.
- Click OK.
The user will receive an email asking them to complete the registration process to create a Sage ID.
To test the API has been successfully configured
NOTE: The following steps will require you to grant web user access to the user you have configured the API and Sage ID for. To do this, ensure the Is Web User box is ticked under the General tab for that user. This is for testing purposes only. To use the API you do not have to be a web user. If you do not have any web user licenses, you can use an application such as Postman and our help files to send a GetSites request to return all the company information assigned to that user.
Once you’ve set the API up and installed the Native API proxy installer you can test to see whether the API successfully returns any information.
- Go to the following address - onlineservices.sage200.co.uk.
- Choose Sage 200 Professional & Sage 200 Extra Online.
- This will ask you to log in to Sage 200 Online
TIP: This will be the Sage ID that you entered in System Administration
- Grant permission for 18 hours.
- If this is successful, then you should see a “company selection” window with a list of companies that the user is associated with in System Administration.
- There is also a Sales Order form you can use. We recommend testing that you can access the correct company records in this form.
Now that the API is enabled successfully, you may wish to look at further documentation:
- API endpoint documentation can be found here.
- How to make an API request via Postman can be found here.
Upgrading your licence
Need a little more room? To add extra companies, users, employees or more to your software licence, leave your details and we'll be in touch.