What are web screens?

Sage 200 has been a native desktop application since its creation, and its client requires a Windows operating system. The introduction of web screens for Sage 200 provides a web-based client accessible in your web browser which, for the first time means Sage 200 can be used cross-platform, on any device that has a web browser.

This allows users to do more with Sage 200 such as accessing it remotely whilst in a warehouse performing a stock take or on the road visiting potential customers. The interaction with Sage 200 is more flexible and accessible, with many of the desktop client's screens already available, and more arriving all the time.

The customer list in Sage 200 web screens

How do I access the web screens?

You can access the web screens using several methods:

• In both Sage 200 Standard and Professional, access the cog in the top right of the client application and choose 'Show Web Portal in browser':
  
  
• If you are using Sage 200 Standard, you can go directly to the URL of the web portal https://app.sage200.co.uk/Sage200WebPortal/
• For Sage 200 Professional, your URL is site-specific and can be obtained by accessing the cog in the desktop client and choosing 'Show Web Portal in browser'. This will open a page via your browser and navigate to your site's Web portal website.

What is available?

Currently you can use web screens in the areas listed below, and more are being released all the time.

• Customers
• Suppliers
• Nominal
• Cashbook
• Stock Control
• Sales Orders
• Settings

Check out the video below to hear more about the Web Portal

Now that you have a clearer idea of what the web portal and screens are, we will look at the resources you will have available in your development.

How do you customise screens?

The primary method of customising screens is through the use of a json schema file. We designed this option in order to open up customisation to a wider audience, making development quicker, and easier to understand. This low code method obfuscates the complexity of working with the screens, and provides a simple, yet powerful set of controls and configuration methods.

Let's take a look at a sample schema, and see what it's all about.

• Sage 200 Web screen schema reference
• Guides
• Sample addons
• Step by step walkthroughs
• Developer community forum
• For members of the UK Developer Programme, email support with the team.

The documentation will continue to grow, and evolve over time. Sage are committed to give the best possible experience for developers looking to work with Sage 200 and more specifically the web screens, and are keen to hear your feedback.

If you need to contact the team, email [email protected].

Authentication

All requests made the Sage 200 API must contain a valid access token as part of the authentication header. This section will provide basic information on client credentials as well break down the different methods available to generate an access token. For a more detailed explanation of the Sage 200 API authentication process, see our Authenticate with the Sage 200 API guide, available here.

Client Credentials

The Sage 200 API supports 2 client types for authentication, Confidential Clients (Web) and Public Clients (Desktop). The type of credentials which you use will vary based on your applications construction and will be used, in combination with your Sage ID, to request a valid access/refresh token.

If you require development/production credentials, please return to Obtaining client ID and client secret credentials.

Access & Refresh Tokens

Access tokens are used to authenticate your API request and without one your requests will be denied. Access tokens are set to expire after a specified amount of time, 480 minutes, however, a refresh token can be used to remove the need for the user to sign in each time their access token expires.

Refresh tokens have a much longer expiry time than Access Tokens, with a maximum of 90 days, and can be used to generate a valid Access Token, if the Refresh Token has not expired.

If the Refresh Token has also expired than a user must login with a valid Sage ID to request a new Access Token and Refresh Token.

Please note that the Sage ID, which is used to authenticate the request, authenticating user, determines the operations, including methods and endpoints, available to you. Further information on user roles and features can be found in the relevant application documentation.

• Sage 200 Standard Online
• Sage 200 Professional

Generating an Access Token

There are various methods of generating an Access Token based on your Development needs:

Programmatically

We have created a C# sample application and client library to demonstrate how to programmatically request an access token for a Windows Form Application (Public Client) and a Website (Confidential). These are available for download here. This page also details the changes required to update the Web and Desktop sample solution to use your Sage 200 API client credentials.

NOTE: Please be aware though 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.

Postman

When testing and developing your API application you may wish to use Postman, an open-source API development environment, which allows you to authenticate and run API queries without needing to program an application, or website.

The Get New Access Token option within Postman’s Authorization tab allows you to request an access token for your API request by entering your Confidential client credentials.

Developer Services have also produced a utility which allows you to generate an access token using your Public client credentials, which can be copied into the Postman Authorisation header and used to query the Sage 200 API.

These methods are further explained in our guide to Using Postman with the Sage 200 RESTful API, see here.

NOTE: Postman does not support the use of a refresh token as part of the authentication process and will therefore require a new access token be requested upon expiry of the existing access token.

Site and Company Information

In order to make database specific requests via the Sage 200 API, you need to specify the Site ID (X-Site) and Company ID (X-Company) within your request header. To acquire these, a GET request can be ran to sites endpoint to show information for all sites the authenticating user has access to.

Please see below an example request and response to the sites endpoint for Sage 200 Standard Online:

Request:

Product	Request Type	URL
Sage 200 Standard	GET	https://api.columbus.sage.com/uk/sage200/accounts/v1/sites
Sage 200 Professional	GET	https://api.columbus.sage.com/uk/sage200extra/accounts/v1/sites

Response:

    {
        "company_id": 123,
        "company_name": "APITestCompany",
        "tenant_id": 1234,
        "site_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "site_name": "Demodata",
        "site_short_name": "xxxxxxxxxx"
    }

Querying the Sage 200 API

Supported Methods

The Sage 200 API supports 4 methods, POST, GET, PUT, and DELETE, which correspond to the create, read, update, and delete (CRUD) operations respectively.

Prior to querying a Sage 200 API endpoint, you must first ensure that the method, or verb, you are going to use is supported on this endpoint. This information can be found in the supported verbs section for the endpoint in the relevant Sage 200 API documentation.

For example, the customers endpoint currently supports the GET and POST methods when a record ID is not specified as part of the endpoint URL, and the GET, PUT, and DELETE methods when it is included.

The following sections detail how to use each of these methods, in combination with query parameters and JSON request bodies, where applicable, to query the customers endpoint for Sage 200 Standard Online.

GET Request

A GET request allows you to read information from a specific endpoint, e.g., customers, and return this in the response body of the request.

Example 1

Request:

Product	Request Type	URL
Sage 200 Standard	GET	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers
Sage 200 Professional	GET	https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers

Response:

This request will return information for all customer records in the response body. For performance purposes, this is limited to the first 500 records; we will discuss how to extend this later in this section.

Should you know the ID of the customer record you wish to query, you can append this to the end of your customers endpoint URL and return information for that specific record.

Example 2

Request:

Product	Request Type	URL
Sage 200 Standard	GET	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers/123
Sage 200 Professional	GET	https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers/123

NOTE: The customer ID relates to the unique reference number applied to the record in the Sage 200 database and is therefore not surfaced within the application. We, therefore, suggest that the $filter query parameter is used for a known unique field value, such as the customer reference, see below.

Query Parameters

You can add query parameters to your request URL to influence your API response. The following section will demonstrate how to use, and combine, some of the more common parameters. Please review the full list of the supported query parameters.

$filter

The $filter parameter allows you to return records that match your specified criteria. You can use more than one $filter as part of your request by including the and/or operators.

TIP: This parameter is commonly used to return information for a specific record when the ID is not known.

Example 1

Request:

Product	Request Type	URL
Sage 200 Standard	GET	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers?$filter=reference eq 'A1D001'
Sage 200 Professional	GET	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers?$filter=reference eq 'A1D001'

Response:

This will return record information for the customer record which has a reference of A1D001.

Example 2

Request:

Product	Request Type	URL
Sage 200 Standard	GET	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers?$filter=reference eq 'A1D001' or name eq 'APITest'
Sage 200 Professional	GET	https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers?$filter=reference eq 'A1D001' or name eq 'APITest'

Response:

This will return record information for the customer record which has a reference of A1D001 or a name of APITest.

$select

The $select parameter allows you to limit the fields that are returned in the response of your request. In the following example, we combine this parameter with the $filter parameter to return the ID of one of our customer records.

Example

Request:

Product	Request Type	URL
Sage 200 Standard	GET	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers?$filter=reference eq 'A1D001'&$select=id
Sage 200 Professional	GET	https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers?$filter=reference eq 'A1D001'&$select=id

Response:

    {
        "id": 27825
    }

$top

The $top parameter allows you to limit the number of records returned in your response body. As previously advised, when this value is not specified, the Sage 200 API will limit requests to 500 records. However, for versions of Sage 200 released after February 2019, you can return up to 5000 records, as demonstrated below.

Example

Request:

Product	Request Type	URL
Sage 200 Standard	GET	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers?$top=5000
Sage 200 Professional	GET	https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers?$top=5000

NOTE: If an $orderby parameter is not specified, the endpoint's default will be used.

$orderby

The $orderby parameter allows you to order the results in your API response body, in both ascending and descending order. In this example, we are going to use the $top query parameter to increase the number of records returned to the maximum of 5000 and order the results in descending order by the customer's balance.

Example

Request:</strong>

Product	Request Type	URL
Sage 200 Standard	GET	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers?$top=5000&$orderby=balance desc
Sage 200 Professional	GET	https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers?$top=5000&$orderby=balance desc

$expand

The $expand parameter allows you to include the content of the record's sub-records in your response body.

Example

Request:

Product	Request Type	URL
Sage 200 Standard	GET	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers?$filter=reference eq 'A1D001'&$expand=contacts
Sage 200 Professional	GET	https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers?$filter=reference eq 'A1D001'&$expand=contacts

POST Requests

A POST request allows you to create a record using the Sage 200 API.

As you are creating a new instance of a record, POST requests do not support the inclusion of an existing ID or query parameters in the request URL.

The following example will demonstrate how to create a customer record in Sage 200 Standard Online, with the inclusion of some optional fields. Required fields for a POST request to an endpoint can be found in the Body Fields section of that endpoint's API documentation. For the customers endpoint, the required fields for a POST request are the reference and name fields.

Example

Request:

Product	Request Type	URL
Sage 200 Standard	POST	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers
Sage 200 Professional	POST	https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers

JSON Request Body:

{
    "reference": "APITEST",
    "name": "API Test 02",
    "short_name": "APITEST2",
    "on_hold": false,
    "account_status_type": "AccountStatusActive",
    "currency_id": 2103,
    "telephone_country_code": "00",
    "telephone_area_code": "1234",
    "telephone_subscriber_number": "567 8899",
    "website": "www.apitest01.co.uk",
    "credit_limit": 2500.00,
    "country_code_id": 13,
    "default_tax_code_id": 1729,
    "contacts": [
        {
            "salutation_id": 0,
            "name": "John Smith",
            "first_name": "John",
            "last_name": "Smith",
            "is_default": true
        }
    ]
}

Response:

A successful POST request will return a 200 (OK) HTTP status, and the response body will show the record information for your created record, including fields that were not populated by your initial POST request.

NOTE: The Sage 200 API follows the same rules for record creation as the Sage 200 application. Therefore, if you attempt to re-run your POST request, you will receive a 400 (Bad Request) HTTP status, with the response body advising that "The account reference already exists. You cannot have two accounts with the same account reference."

PUT Requests

A PUT request can be used to update information on an existing record. As such, you must specify your record ID as part of your request URL. Only the information that you intend to update needs to be passed as part of the request body.

TIP: Further information on using the $filter query parameter to find a record's ID can be found in the GET Requests section of this article.

The following example demonstrates how to update the short name of the customer record used in our GET Requests $select example.

Example

Request:

Product	Request Type	URL
Sage 200 Standard	PUT	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers/27825
Sage 200 Professional	PUT	https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers/27825

JSON Request Body:

{
    "short_name": "APIDemo"
}

Response:

A successful PUT request will return a 200 (OK) HTTP status, and the response body will show all record information, including the updated field, for the ID specified in the PUT request URL.

DELETE Requests

The DELETE method can be used to delete a record from Sage 200. You must, therefore, specify the record ID as part of your request URL.

As the Sage 200 API follows the same rules for deletion as the Sage 200 application, you will only be able to delete records that meet the criteria set by your user roles within the application.

Example

Request:

Product	Request Type	URL
Sage 200 Standard	DELETE	https://api.columbus.sage.com/uk/sage200/accounts/v1/customers/27825
Sage 200 Professional	DELETE	https://api.columbus.sage.com/uk/sage200extra/accounts/v1/customers/27825

Response:

A successful DELETE request will return a 200 (OK) HTTP status. If your user roles do not permit the deletion of the record, you will receive a 403 (Forbidden) HTTP status, and the response body will advise that "The requested operation is forbidden for this account."

Next Steps

Learn