Overview

SmartSuite Integration API consists of a RESTful web API which provides the means of extracting bulk data and specific data from SmartSuite. It it intended to be used by SmartSuite customers to integrate in-house systems with the SmartSuite solution.

Routes and Resources

Version 1 supports the Reporting route with the following bulk resources:

• Service Point reports
• Route Segment reports
• Service Point actions
• Service Point serviced events
• Route details

In addition it supports the IntegrationAPI route with the following resource:

• Status
• GetApiKeyDetails

Base URL

[In progress] The developer will be provided with two URLs. One for development and testing purposes, and the other for access to the live SmartSuite service.

Development Environment

The development service has the facility to invoke specific repeatable responses and also to use example data relevant to the local situation. Note that the data may be cleared/reset at certain intervals.

Authentication

Authentication is required (apart for status routes) and uses HTTP Basic Authentication.

More Information

Request and Response format

Get requests will usually take a Guid as a parameter and return a JSON encoded resource. More complex Post requests will make use of a JSON encoded Request Data Transfer Object (DTO) and similarly return the data in a JSON encoded Response DTO.

Errors

The API will use the following standard HTTP Status Codes:

• OK 200
• Accepted 202
• Bad Request 400
• Unauthorized 401
• Forbidden 403
• Internal Server Error 500

In addition all Response DTOs derive from a base DTO which includes a list of Messages which may include information about warnings and errors.

{
  "message": [
    {
      "itemId": "abcd-1234",
      "message": "Not found"
    }
  ],
  "responseDateTime": "2022-04-04T20:16:58.0126585Z"
  "version": "1.0"
}

Endpoints

• GET /IntegrationAPI/Status – returns SeviceStatus

Bulk Data Fetches

The bulk data to be fetched is limited to a maximum time span (24hrs) by means of the 'From' and 'To' parameters. Where no time span is set then the last 24 hours is assumed. Where only one of 'From' or 'To' is set then the time span of 24 hours relative to that is assumed. Where both are set but the time span is greater than 24 hours then the 'From' setting will be used and a time span of 24 hours relative to that is assumed.

• /Reporting/FetchServicePointReports
• /Reporting/FetchRouteSegmentReports
• /Reporting/FetchServicePointActions
• /Reporting/FetchServicePointServicedEvents

Entity Fetches

• /RouteServicePoint/... [In progress]

DataModel

The data model is provided as part of the SDK as 'SmartSuite Integration API Data Model.dll'. This .net dll class library contains the definitions of all resources, classes and DTOs.

Request and Response DTOs

• Reporting.DTO.FetchServicePointReports and Reporting.DTO.FetchAdhocReports_Response
• FetchRouteSegmentReports_Request and FetchRouteSegmentReports_Response
• FetchServicePointActions_Request and FetchServicePointActions_Response
• FetchServicePointServicedEvents_Request and FetchServicePointServicedEvents_Response

Resources

• ServicePointReport
• RouteSegmentReport
• ServicePointAction
• ServicePointServicedEvent
• ServiceStatus

Constants

[DataModel.Common.Constants] (../datamodel/ISL.SmartSuite.Integration.DataModel.Common.Constants.html) contains a number of Guids that can be used as User IDs in the basic authentication of the development Integration API. These will invoke specific error responses like invalid parameter, server error, or return specific resources as defined in Constants.

For example posting to /Reporting/FetchServicePointReports on the development server with User Id set as MockProviderSimpleResponse will result in a response containing SampleServicePointReport.

Swagger

The 'Swagger UI' is available on the development and testing environment at the Base URL appended with the path '/swagger'. This enables visualizing and interacting with the Integration API using a browser.