How to guides

Follow the simple list below to learn about the Sage 50 Cloud API

On-Boarding
Downloading Data
Uploading files
Tracking Progress

On-Boarding

To integrate with Sage 50 Cloud you MUST first acquire an ‘API Key’. An ‘API Key’ can be acquired by completing the following steps of the Sage 50 Cloud API On-Boarding Process.

Developer and Application Registration

The first step to receiving an ‘API Key’ is to register your details, including the details of the application you wish to integrate with Sage 50 Cloud. On completion of this step you will be assigned a personal ‘Developer ID’ and Application ID’.

Follow the steps below to receive your ‘Developer ID’ and ‘Application ID’

First register your Developer and Application details by issuing a request against the POST: /API/DEVELOPERS end point.
Next retrieve the value of the 'registrationUrl' property from the response.
Next open up a Web Browser and navigate to the value retrieved from the 'registrationUrl' property.
Finally, to complete the registration process, complete the captcha challenge.
You will now receive an e-mail with your personal ‘Developer ID’ and ‘Application ID’. NOTE: You MUST store your ‘Developer ID’ and ‘Application ID’ securely.

NOTE: To register additional applications issue further requests against the POST: developers/{developerId}/applications end point to receive addition Application ID’s.

The next step to receiving an ‘API Key’ is to consent the integration within the target Sage 50 Cloud application. To achieve this you must generate a ‘passcode’ using the Sage 50 Cloud API and present the ‘passcode’ to the user.

Generating a Passcode

Follow the steps below to generate a ‘passcode’.

First issue a request against the POST: /api/developers/{developerId}/applications/{applicationId}/passcodes end point passing a ‘secret’
Finally, retrieve the value of the ‘passcode’ property from the response.
NOTE: You should also take note of the value of the ‘expires’ property in the response as this specifies how long the ‘passcode’ will remain valid.
Typically the ‘passcode’ will now be displayed to the user.

Receiving an API Key

The final step to receiving an ‘API Key’ is to consent the integration within the target Sage 50 Cloud application. This is typically achieved within the target Sage 50 Cloud by selecting the relevant ‘Enable External Integration’ option and entering the ‘passcode’. Typically a constent challenge will then be presented, which when granted will result in an ‘API Key’ being provided via the ‘approvalUrl’ specified during the Application registration.

NOTE: You MUST securely store your 'apiKey' and 'secret'

API Key Rotation

API Keys have an associated expiry value, which will result in the ‘API Key’ being denied access to the Sage 50 Cloud API when expired. The Sage 50 Cloud API implements an ‘API Key’ rotation process, which you MUST implement to ensure continued usage of the Sage 50 Cloud API. You can detect when an ‘API Key’ expires due to the Sage 50 Cloud API responding with a 401 HTTP Status Code as a result of an API request.

To ensure that you always have a valid ‘API Key’, follow the ‘API Key’ Rotation steps below

First, issue a request against the PATCH: ApiKey end point passing the 'initialApikey' and 'secret' parameters.
Finally, retrieve your new ‘API Key’ from the value of the ‘apikey’ property in the response

Downloading Data

Once an integration is consented within the target Sage 50 Cloud application, Sage 50 Cloud will now upload data (e.g. Products, Customers, …) for the integration at scheduled intervals. On completion of an upload Sage 50 Cloud will notify your application of the existence of the new data.

How does the new data notification work?

Once the data for your integration is successfully uploaded from Sage 50 Cloud, Sage 50 Cloud will then notify you via the ‘uploadUrl’ specified during the Application registration
When you receive notification of the new data, issue a request to the GET: /api/files/{domain}/{scope} end point to begin the downloading of that data.
The ‘downloadUrl’ property in the response contains the URL to use to download the data.

The contents of the download will be formatted using the ‘application/json’ mime type and the structure will conform to the definition as published for your integration in the Solutions section.

Managing the Downloaded Data

Scope files uploaded from Sage 50 applications always contain the full data of the scope. Two different cases:

First time synchronization: when 3rdparty application is calling the service for the first time, the application could import all data or filter if necessary.
Regular synchronization: 3rd party application will have to compare data on file with local version to detect new records, updates and deleted records.

Uploading files

It is the responsibility of the 3r party application to decide when and how often is required to upload files on the platform. Recommendations will depend on the integration use case, and business requirements.

Uploading a file is the mechanism to inform Sage 50 application about new or updated records on the 3rd party application.

The process has the following steps:

Compose the file following the schema of the scope (See Api Reference a Solution sections)
Call POST: /api/files/{domain}/{scope} and get 'uploadUrl', 'uploadVerb', 'uploadHeaders', 'completeUrl' and ‘cancelUrl'.
Upload file as an http call to the url 'uploadUrl' with the verb 'uploadVerb', and the headers 'uploadHeaders'
If the upload fails you have to notify the platform calling POST: cancelUrl
Retry again or cancel the procedure
When file upload has finished, you must notify it to Sage 50 Cloud platform calling POST: completeUrl and and store ‘trackingUrl’ for future uses

Tracking Progress

Once the file is uploaded you can get status information calling GET: trackingUrl and get 'status', 'progress' and 'downloadResultUrl':

Validation

When a file is uploaded to Sage 50 Cloud platform, there is a validation process on the platform before file is available to be downloaded by the Sage 50 application.

Status values could be:

'cancelled' after POST: /api/files/{fileKey}/cancel
'quarantine' just after POST: /api/files/{fileKey}/complete
'forbidden' if the file is an executable
'unavailable' when file format is not correct
'available' when file is available to be downloaded by Sage 50

Processing

Once file is available then Sage 50 downloads it and process file data.