How to guides
Follow the simple list below to learn about the Sage 50 Cloud API
On-Boarding
Sage 50 Cloud platform requires a registration of Developer and 3rd party applications to take advantage of integration services, and get credentials to use it.
Developer onboarding
Required a Developer ID and an Application ID for each application consuming Sage 50 Cloud. Follow next steps:
-
Creating a new developer account and application account through POST: /api/developers and get
'registrationUrl'. -
Developer has to open this url in any web browser to complete the registration process. A captcha is presented, and after completion developer receives an e-mail with
'developerId'and'applicationId'.
Note: You need a unique application accounts for each 3rd party application. If you need to register new applications call POST: developers/{developerId}/applications
Integration onboarding
For each Sage 50 application integrated with the 3rd party application you need a unique API Key to access the data. The API Key is achieved when administrator user consents to 3rd party Application, the access to a specific domain, on Sage 50 application.
Get Passcode
The consent process starts getting a Passcode on 3rdparty application.
Call POST: /api/developers/{developerId}/applications/{applicationId}/passcodes giving a ‘secret’ to get a temporary ‘passcode’.
Get API Key
-
On Sage 50 application user invokes some option and enter the passcode.
-
The user is presented with a message to grant (or deny) access to the domain (e.g. e-Commerce) requested by the 3rd party app.
-
Once granted, the 3rd party app is notified on
‘approvalUrl’ with the API key'apikey'by Sage 50 Cloud in order to start working. -
You must store
'apikey'and'secret'safely, and if possible in different places to improve security.
API Key Rotation
When an API key has expired, Sage 50 Cloud returns a 401-http error in ALL operations, except those operations included in API rotation process, to inform the API key must be refreshed.
In the case of expiration 3rd party application has to refresh API key:
- Call the method PATCH: ApiKey informing the requested parameters:
'initialApikey'and'secret', and get the new API Key
3rd party developer is responsible to rotate Api keys on any circumstance. This means 3rd party Application has to be prepared to re-act when receive this type of errors without impacting on customer experience.
Downloading files
Once a user of Sage 50 application has consented a 3rd party application on a domain (e.g. e-Commerce), Sage 50 will upload files for each scope (e.g. Products, Customers, …) with the frequency configured on the application.
Sage 50 Cloud platform will keep the last version file of the scope (uploaded file from Sage 50 installation), and 3rd party application will be notified every time a file is updated.
How does notification work?
- When a file from a scope is uploaded from Sage50 application, the Sage 50 Cloud platform sends a notification (POST: uploadedUrl) to all 3rdparties that have linked to that Sage 50 installation on that specific scope.
- Getting the
'passcode'will help to identify the Sage 50 installation that is sending the data.
Once notification is received, 3rd party application can call a method to get the download required urls of the file: GET: /api/files/{domain}/{scope}, and get download the file from the ‘downloadUrl’ address executing any http file download method.
Downloaded scope file content is a Json format with the schema published on Solutions section.
Managing downloaded File
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.
Status values could be:
'processing'file is processing by Sage 50, and'progress'attribute will show the percentage of work done'failed'when errors on process'badRequest'when errors on request'accepted'when processing has finished successfully
When 'accepted', 'failed', or 'badRequest' Sage 50 could upload a file with the results of processing. Download results (e.g. Order result) from 'downloadResultUrl'