Getting started guide

Follow the simple list below to learn about the Connected Cloud API

On-Boarding
Downloading Data
Uploading files
Tracking Progress

To follow this guides we recomment using the Postman desktop app, so you can easily create your first request to the Connected Cloud API. All requests used in this section are available as a Postman collection. Click the button below to download the collection to be used with Postman.

Download Postman collection

On-Boarding

To integrate with Connected Cloud you MUST first acquire an ‘API Key’. An ‘API Key’ can be acquired by completing the following steps of the 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 Connected 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 developers operation.
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, please go for the POST applications operation to receive addition Application ID’s.

The next step to receiving an ‘API Key’ is to consent the integration within the target Connected Cloud application. To achieve this you must generate a ‘passcode’ using the 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 passcodes operation providing 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 Connected Cloud application. This is typically achieved within the target Connected Cloud by selecting the relevant ‘Enable External Integration’ option and entering the ‘passcode’. Typically a consent challenge will then be presented, which when granted will result in an ‘API Key’ being provided via the ‘notificationUrl’ 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 when expired. The implements an ‘API Key’ rotation process, which you MUST implement to ensure continued usage of the . You can detect when an ‘API Key’ expires due to the 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 operation providing 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 Connected Cloud application, Connected Cloud will now upload data (e.g. Products, Customers, …) for the integration at scheduled intervals. On completion of an upload, Connected 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 Connected Cloud, Connected Cloud will then notify you via the ‘notificationUrl’ specified during the application registration.
When you receive notification of new data available, issue a request to the GET file operation to begin downloading that data, providing the desired data domain and scope.
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 the Sage applications always contain the full data of the scope. Two different cases:

First time synchronization: when 3^rd party application is calling the service for the first time, the application could import all data or filter if necessary.
Regular synchronization: 3^rd 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 3^rd 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 applications about new or updated records on the 3^rd 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 file operation 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 cancel file operation
Retry again or cancel the procedure
When file upload has finished, you must notify it to Connected Cloud platform calling POST complete file operation and store ‘trackingUrl’ for future uses.

Tracking Progress

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

Validation

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

Status values could be:

'cancelled' after POST cancel file operation
'quarantine' just after POST complete file operation
'forbidden' if the file is an executable
'unavailable' when file format is not correct
'available' when file is available to be downloaded by the Sage product

Processing

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