Guide to constructing an API request

This document is a step by step guide to building an application utilising the RESTful API for Sage 200 Standard and Sage 200 Professional.

Overview

The API is a RESTful data service which provides programmatic access to read and write data, allowing developers to make HTTP requests and receive responses. The API uses the OAuth 2.0 standard for authentication. OAuth 2.0 is a widely recognised framework for authentication and is globally used in APIs. This is a process of exchanges that allow a user to grant access for an application to access their data set. You can read more about OAuth 2.0 here.

These requests use the following HTTP verbs to determine the request functionality:

OAuth flow

The client requests authorization from the resource owner. The authorization request can be made directly to the resource owner, or, preferably, indirectly via the authorization server, which acts as an intermediary.

The client receives an authorization grant, which are credentials representing the resource owner’s authorization. These are expressed using one of four grant types and are defined in this specification or using an extension grant type. The authorization grant type depends on the method used by the client to request authorization and the types supported by the authorization server:

• The client requests an access token by authenticating with the authorization server and presenting the authorization grant.
• The authorization server authenticates the client and validates the authorization grant, and if valid, issues an access token.
• The client requests the protected resource from the resource server and authenticates by presenting the access token.
• The resource server validates the access token, and if valid, serves the request.

Confidential or Public Client

There are 2 ways to access the Sage 200 API, via a Confidential Client or a Public Client.

Public Client:

Mobile and Desktop applications are classed as a public client types as they would need to store the client and secret locally, and securely, which are then used as part of the Sage ID user authentication process. This is potentially less secure as the client and secret would need to be distributed with the compiled applications. To improve security, a temporary certificate is issued by Sage ID to secure any communication between the application and Sage ID

Confidential Client:

Web based applications that store the Client and Secret keys on a server are classed as Confidential Clients. They are more secure because only the server has access to these keys; they are not distributed to end users

Credentials

When you register your application for the Sage 200 API, you are provided with:

• A Client_ID
• A Scope

If you are using a confidential client, you will also be provided with:

• A Secret Key

For confidential client, you will register one or more redirect URLs with Sage that will be used during the OAuth process to redirect the user back to your application. For testing and development purposes you do not need to register your application and can instead use our demonstration credentials. Please contact Sage Developer Services there contact details can be found here if you require these. To register your API application, for a production environment, and receive your API Credentials, please complete our request form.

Access and refresh tokens

Access tokens are used to authenticate API requests. Without a valid access token any request will be denied. Access tokens are set to expire after a specified amount of time, for a maximum of 60 minutes for the access token and 180 days for the refresh token. When a successful request is made to generate a new access token a refresh token is also generated. When an access token expires, your application can be configured to either have the user login to requests another access token, or the refresh token can be used to generate a new access token without user interaction up to the lifetime of the refresh token.

Access tokens are specific to the Sage ID used to request the token and therefore share the same level of authorization and permission within the Sage 200, as the user who made the request.

Base URLs

The Base URL for your request will differ based on the Sage 200 application.

For Sage 200 Professional/Extra Online you need to ensure the following Base URL being used is:

https://api.columbus.sage.com/uk/sage200extra/accounts/

For Sage 200 Standard this would be:

https://api.columbus.sage.com/uk/sage200/accounts/

The following demonstrations will assume you are using a confidential client.

Authorization Request

You will need to start by authenticating your application. This is achieved by sending a request to the Sage 200 Authorization Server with the following information:

Request URL:

https://eu-oauth.sso.services.sage.com/SSO/OAuthService/WebStartAuthorisationAttempt

OAuth requires all parameters to be URL encoded and concatenated with an ‘&’.

Example Request:

https://eu-oauth.sso.services.sage.com/SSO/OAuthService/WebStartAuthorisationAttempt?response_type=code&client_id=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&redirect_uri=http%3a%2f%2flocalhost%3a56953%2fAccount%2fAuthorise&state=Th15IsAT35t5tat3T0Demo5trat3AnAP1Auth3nt1cat1onR3qu35t&scope=XXXXXXXX()%3b

Response:

When this endpoint is queried, the user is prompted to sign into with their Sage ID and asked if they want to authorise the application. If the user allows access to your application, they are redirected to the redirect URL along specified in the request with an authorization code which can be read from the response.

Example Response:

http://localhost:56953/Account/Authorise?code=DZjSeplzqsdfXam%2bisdf3z%2bVbyxI%2bS19%2bpu0vOAs%3d&state=Th15IsAT35t5tat3T0Demo5trat3AnAP1Auth3nt1cat1onR3qu35t

Access token

Once your application has been authenticated you will then need to request an access token in exchange for the authorization code.

To do this, you will need to send a POST request to the following URL:

Required header parameters:

Required request body parameters:

Example request body:

grant_type=authorization_code&code=DZjSeplzqsdfXam%2bisdf3z%2bVbyxI%2bS19%2bpu0vOAs%3dredirect_uri=http%3a%2f%2flocalhost%3a56953%2fAccount%2fAuthorise

Example Response:

"{\"access_token\":\"fkFjvLZ\\/hKSueaLh7pRQDQ8cXzxbWp7QvXldoa+IszfZXAqSagAxW5eFS1Hqa2TjTi7C5qTgIJlf60qhd4gs7\\/nxoRyJPx6LXZHG7COfeQxQmmhzVvevZXq8WhEIkTIR8aDa3OtDKITWC6Lhyk5cFBeUviGPdu\\/yutux0TEKzRc4RVZRET6Fshl3zCN65U\\/HlGCrelVe8odz\\/GXiEFDziIN4KgmN7TCMIIqIA4qDifgaBiD4sFsLKo77vI14yoOFUXA9RmE0+Fa0V2eGN3vZyFCeZH0\\/+x4b60MCvydIaDKWK6eCwynCNtJJqkxSH1Aa7fIvmUFNnt6JZi7BMGSujjhXMrto1F3ObdCDZ+H0qUn0TwHwwmccuKlTKoSqdqF4NKd38qxYbkOruOIrTrWPE959tntz\\/SawM+jp5F4zgoswvxREI9xtBq2ZMWPsFC+0H001FLcf+t3E+cR\\/PvxzweIlqaBeUwbZj1IIEYxrwZCUe2pPuaVJFlNR82PAANKBko1B47+zy7fLkJGQZYhMcLI82Eq6KBzzCBF\\/NKn5XfyCUJhiveWWFEiHuMMsrqTCYkGwy7mA+ohzE6BE4j+jWom5RI04cUcisPBMQTeXAvesFtWvkEiI7eFqE3jHRusdUyMd4STFuMf3TY\\/hAk6Z4LHPbHLGQu6b6rioSUgfEQ8v1M2tHRKQ9chOwWM3YHhZgZHq9A8x8EEmzG3gj46rGyTCLmCG0qt1j67zYzOXVYnOKc28aDLhSFV0qHLeQG5xfK\\/u7Yq\\/WgKuRb8w11umLV7yx0oR+TRVUjQBZJqwWxABfoqP6cV6WbUQNPalUa2NQuvZ+o0gdfa034Jq3PjmFwp690IE6FUCPsT0+\",\"expires_in\":1200,\"refresh_token\":\"6Z3IFJE80HAG9R633ICV8EC64B401P28B6ER2D1E2O754QAA312D476ABR1W5Z4L5K0EEZ767BAXEV6D344SA5CB4F4N39E6ATCTEF983J4KBL9U9N45CQ4KCJ0K1K5Z\",\"scope\":null,\"token_type\":\"bearer\"}"

Using the refresh token

During the authorization exchange, you are issued with an access token and a refresh token. You must include the access token in each API call.

You can use a valid refresh token to obtain a new access token without requiring the user to sign in again, up to the expiry of the refresh token. To do this, you will need to send a POST request to the following URL:

https://eu-oauth.sso.services.sage.com/SSO/OAuthService/WebGetAccessToken

Required header parameters:

Required request body parameters:

TIP: All parameters need to be URL encoded and concatenated with an ‘&’.

Example request body:

grant_type=refresh_token&refresh_token= 6Z3IFJE80HAG9R633ICV8EC64B401P28B6ER2D1E2O754QAA312D476ABR1W5Z4L5K0EEZ767BAXEV6D344SA5CB4F4N39E6ATCTEF983J4KBL9U9N45CQ4KCJ0K1K5Z

Example Response:

"{\"access_token\":\"fkFjvLZ\\/hKSueaLh7pRQDQ8cXzxbWp7QvXldoa+IszfZXAqSagAxW5eFS1Hqa2TjqloTl\\/FtxOp9NvqUN2YNsULkCS0CE5aDssKzpARvSQN7LhGnIU2DlJTWmwGAVc4q5D6WBwAbrOM2jiaiQUP4KQagEKOXLCjbJkX6TSQy+\\/DGQ0gobe0Ybg\\/2WIxt45+XZ8ngQht6QYDaCTEFt76hUHfd+pzG5U8NX4kjyzLzvXkNPs63qgoqbmlaeFSbSSwRfi4qa+GTP+\\/yQVxuj55gRsO++F4mCysc18+E1bG7\\/MREKVf\\/4iarkI+ydc1Uq7lwLFbpWTll7nk9GuFLBA52cAFo+AjPj1zJzb+NF5\\/TmIPBvInFsFTE9Ckr2xHq5DyrCpU7XgAyi+AD7q\\/MnK+kT5cb0nVzRqFxBXdvfYkPlDMupTEMKfLKqYWqWPZUseAPuVGdTup4k87JJNwHuunzIXmTmC7avVlbHGdDyU4+5jzUUWZjT\\/iDZ3DWFhBmSM5uUp8dpRdXxV8kUg4H8izfYsBuDOVH1KZtxiVYWPLpIcBFTlufdWIA0da4k2bIwH40Zo\\/yHqzkfRXGUKquJoGaXAksRkdZ+ffJJz3PsSUrF\",\"expires_in\":1200,\"refresh_token\":\"673NFZES0RAJ9Z6L3VCI8UCU4W4B1A2UBBEJ2U1F257D4UAS3B2K4I6RBH1N5X4D4GAP3P3W4HD48A1XDA42AJEN444FEY7MBO4JFR1W2L10EK3HBE8A1S3M3I1B6X2N\",\"scope\":\"6bektnhq();\",\"token_type\":\"bearer\"}"

Making a Request

With a valid access token, you are now authorised to make API requests. A request consists of various attributes which must be built up prior to sending the request.The API has several endpoints and operations available. These are essentially URLs available to make requests to.

For example, a GET request to the customer’s endpoint will return all customers, whereas, a POST request to the same endpoint will create a new customer.

All the available endpoints and operation can be found here. The documentation for each operation provides information on available/required fields and OData query parameters.

Once you have determined which HTTP method (operation) and endpoint you wish to use you will need to construct the request header and body.

Header parameters:

Headers include information about the HTTP request and about the data that is sent with the request body.

As part of your header you will need to supply the following values for each HTTP request:

CAUTION: If you omit to add to a space you will the following error in your response body when you attempt to make an API request: “Message”: “Authorization has been denied for this request.”

Example:

Bearer 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

Request Body Example: This is an example of a JSON request body for a POST request to the customers endpoint.

{
    "reference": "APITEST",
    "name": "API Test",
    "short_name": "APITEST",
    "on_hold": false,
    "account_status_type": "AccountStatusActive",
    //Currencies endpoint
    "currency_id": 63956,
    "exchange_rate_type": "ExchangeRateSingle",
    "telephone_country_code": "00",
    "telephone_area_code": "1234",
    "telephone_subscriber_number": "567 8899",
    "fax_country_code": "00",
    "fax_area_code": "1234",
    "fax_subscriber_number": "567 9988",
    "website": "www.apitest01.co.uk",
    "credit_limit": 2500.00,
    //Country_codes endpoint
    "country_code_id": 63946,
    //Tax_codes endpoint
    "default_tax_code_id": 1287,
    "duns_code": "000000001",
    "contacts": [
        {
            "salutation_id": 0,
            "name": "Api Test",
            "first_name": "Api",
            "middle_name": "",
            "last_name": "Test",
            "is_default": true
        }
    ]
}

Further Information:

Setup and Configuration: Information on setup and configuration of the Native API, using Microsoft Azure Active Directory tunnelling, can be found here.

API Setup and Responsibilities: Information on who responsible for each area of a Sage API deployment can be found here.

FAQ: For a list of frequently asked question regarding the Sage 200 API, please see here.

Getting Started with Postman: This guide provides steps to making API request to the Sage 200 RESTful API via Postman, and can be found here.