API SCUTI Documentation-En V 1.0.0

SCUTI API (V.1.0.
0)
The SCUTI API automates the interaction with the SCUTI system. Through the API, independent
processes or applications can be generated with most of the options that can be found in the SCUTI
control panel.
The SCUTI API is RESTFul, which means that the communication is based on HTTP requests. The
documentation details each of the methods developed in the API.
Authentication
To use the SCUTI API an authentication token is required, which is generated by the user. This is
generated once the user has been authenticated with the method: login. The user and the token are
assigned different permissions for each of the operations.
The authentication method is the authentication of each HTTP user, this means that you must provide
the User and its token each time you make a request, since the API does not use sessions.
Server address
The server address is: https://98gjkilko7.execute-api.us-east-1.amazonaws.com/scuti
Remember that HTTPS is required for the connection, otherwise you will not be able to connect via
HTTP.
Note: for this documentation the server address will have the alias: URLServer.
Parameters in requests
The parameters in GET type requests must be provided as a query string in the URL.
The parameters in POST, PUT and DELETE requests must be provided in the body of the request in a
JSON format. Remember to add the appropriate header for the request:
Content-Type: application / json.
- Example Request
{
"user": "userTest",
"pass": "passTest"
}
Remember that attributes are defined in each of the methods listed in the documentation.
Definition of response codes
The HTTP response code returned by a successful request is defined in the documentation. This being
usually the code 200 (OK).
If something goes wrong in the application process, different status codes are returned. The code is
defined in each method.
Answers
The responses are in JSON encoding and the specific response (successful) of each method is described
in its section.
However, if something goes wrong, the standard JSON error message can be in the following format:
{ {
"codeResponse": 120, "codeResponse": 400,
"message": "Model not found." "message": "Bad request."
} }
Note that the attributes in each response, of the respective invoked method, may not always be
present. In each of the responses, the attribute"message" details what happened in the application
process.
A client application should never assume that a certain attribute is present in a response.
Submit your user credentials proactively
Some HTTP clients bypass the authentication header and make a second request on the header when
they get an unauthorized 401 response. Make sure to send the credentials directly, to avoid
unnecessary requests.
Authentication Headers
The authentication headers are requested in each of the methods, and in each of them the headers
that will be required for the request are specified.
The authentication of the methods is by tokens, this means that the headers must be provided every
time you make a request. For this reason, all methods listed in the documentation must have the
following headers.
Name Value Description Kind
Content-Type application/json Data to generate JSON type request string
apiKey scuti_api_dev Data to identify the origin of the request string
idUser 123 User ID int
accessToken token123 User Token string
➢ The headers: idUser and accessToken are obtained from the login method.
➢ The headers: Content-Type and apiKey they will have the values provided in the table above,
for all methods.
Note that, for the login method, only the Content-Type and apiKey headers should be sent.
Unreliable internet
Networks in general are unreliable and particularly one as large and complex as the Internet. Your
application should not assume that you will get a response, it should consider waiting times.
Pagination
Some API methods return a list of data, the list has a preset limit of 10 records, the remaining elements
can be retrieved through multiple requests. In each of the responses, which exceed the range of 10
records, a URL is specified for the next request.
If you need to obtain a greater range of records, the pageSize parameter must be sent with a value no
greater than 100, remember that it can only be sent in those methods that retrieve a list of
information.
Take into account the speed of your application to handle requests.

ACCESS
POST - login
Request Description
URLServer/access/login Login method, returns user information.
Being a POST type request, the parameters must go in the body of the request in type: JSON
format.
- Query parameters in request body

Name Description
username string
required User name
password string
required User password
- Example Request
{
"username": "user.test",
"password": "passTest"
}
- Response example
Code Response example
"codeResponse": 200,
"message": "Login successful",
"data": {
200 OK:
"idUser": 1,
Successful request
"accessToken":
"WPCuEHCCwJKMtMQiPvwxcOVqi9gzpBjkuGyF9mifDxw32"
}
POST - logout
Request Description
URLServer/access/logout User session ends
The method only uses the data sent in the request headers.
- Response example
200 OK: "codeResponse": 200,
Request successful "message": "Logout successful"
DEVICES
GET - getDevices
Request URLServer/devices/getDevices
- Description
The method returns a list of the existing devices in the system.
If a parameter is sent, the method will perform a search filter using the received parameter.
The following example shows a request with the model parameter with value: ST20.
Request with parameter URLServer/devices/getDevices?model=ST20

Description Returns a list of devices that match the parameter sent
If more than one parameter is sent, they will be taken into account in the following order:
group - esn - imei - model - customer - client - profile
Note: if the ESN and PROFILE parameters are received, the method will carry out the process
through the ESN.
- Query parameters
Name Description
group string
optional Group name, field to filter in search
esn string
optional Device serial number, field to filter on search
imei string
optional Device identifier, field to filter in search
model string
optional Model name, field to filter in search
customer string
optional Customer alias, field to filter in search
client string
optional Client alias, field to filter in search
profile string
optional Profile name, field to filter in search
- Response example

"message": "Request successful.",
"data": [
{
"keyDevice": 208,
"ESN": "6009999015",
"imei": "321654987",
"model": "ST20",
"lastComm":
"MNT;6009999015;403;20110101;00:00:30;001;NoData;NA;NC",
"profile": "Brickhouse_Profile",
"customer": "Silent Sensors",
"client": "jux.client",
"firmware": "ST20_SUNTECHUSA_STADV_027",
"firmwareMCU": "ST20_M11"
},
{
"keyDevice": 209,
"ESN": "6009999001",
200 OK: "imei": "353162077274380",
Successful request "model": "ST600",
"lastComm":
"MNT;6009999001;999;20110101;00:00:34;001;NoData;NA;NC",
"profile": null,
"customer": "jux.customer",
"client": "jux.client",
"firmware": "ST600_USA_STADV_405",
"firmwareMCU": null
},
{
…
},
…
],
"first_page_url": "URLServer/devices/getDevices?page=1",
"prev_page_url": null,
"perPage": 10,
"next_page_url": "URLServer/devices/getDevices?page=2",
"last_page_url": "URLServer/devices/getDevices?page=4611",
"total": 46104
GET - getGroupsByDevice
Request URLServer/devices/getGroupsByDevice?esn=123456789
- Description
The method returns a list of the groups assigned to the device.
- Query parameters
Name Description
esn string
required Device serial number
- Response example
"message": "Successful request.",
"data": [
{
"group": "Assured Shipment 1"
},
{
},
{
},
{
"group": "Assured V23 shipment "
},
200 OK: {
Successful request "group": "CAHA TEST Group"
},
{
…
},
…
],
"first_page_url":
"URLServer/devices/getGroupsByDevice?esn=6009999015&page=1",
"perPage": 10,
"next_page_url":
"last_page_url":
"total": 12
GET - getDevicesUpdateStatus
Request URLServer/devices/getDevicesUpdateStatus?updateType=1&model=ST20
- Description
The method returns a list of devices that match the updateType. The updateType parameter
defines the type of update. Only the last record of the update type is displayed.
At least one parameter must be sent to obtain the information: group, esn, model or profile.
The method will filter the search through the received parameter. The following example
shows a request with the model parameter with value: ST20.
Request with
URLServer/devices/getDevicesUpdateStatus?updateType=1&model=ST20
parameter
Description Returns a list of devices that match the parameter sent
group - esn - model - profile
Note: if the ESN and PROFILE parameters are received, the method will carry out the process
through the ESN.
- Query parameters
Name Description
1 = OTA
updateType int
2 = Profile
required Filter for the type of search to perform
3 = MCU
group string
esn string
optional Device serial number
model string
profile string
- Response example

"data": [
{
"ESN": "0460000071",
"imei": "866425037373588",
"model": "ST4500",
"dischargeDate": "2020-04-03 11:51:26",
"comments": "Canceled by the user"
},
{
"ESN": "0460000070",
"imei": "866425037384510",
"model": "ST4500",
"dischargeDate": "2020-03-30 10:12:23",
"comments": null
},
{
"ESN": "0460000073",
"imei": "866425037376862",
"model": "ST4500",
"dischargeDate": "2020-03-30 11:38:13",
"comments": "Incorrect FW"
200 OK: },
Successful request {
"ESN": "0460000055",
"imei": "866425037373471",
"model": "ST4500",
"dischargeDate": "2020-02-05 17:56:00",
"comments": "Canceled by the user"
},
{
…
},
…
],
"first_page_url": "
URLServer/devices/getDevicesUpdateStatus?updateType=1&
model=ST4500&page=1",
"perPage": 10,
"next_page_url": "
"last_page_url": "
"total": 755 "
GET - getDevicesByProfile
Request URLServer/devices/getDevicesByProfile?byStatus=3&profile=profileTest
- Description
The method returns a list with the devices that match the sent profile. The byStatus
parameter defines the status of the profile on the devices.
- Query parameters
Name Description
profile string
required Profile name, field to filter in search
1 = Currently assigned
byStatus int
2 = Currently in process
required Filter for the type of search to perform
3 = Currently in error
- Response example
"data": [
{
"ESN": "0460000054",
"imei": "866425037352335",
"model": "ST4500"
},
{
"ESN": "0460000076",
"imei": "866425037351261",
"model": "ST4500"
},
{
"ESN": "0460000638",
200 OK:
"imei": "862061041450858",
Successful request
"model": "ST4500"
},{
…
},
…
],
"first_page_url": "URLServer/devices/getDevicesByProfile?byStatus=1&
profile=ATT%205sec%20drive&page=1",
"perPage": 10,
"next_page_url": "URLServer/devices/getDevicesByProfile?byStatus=1&
"last_page_url": "URLServer/devices/getDevicesByProfile?byStatus=1&
"total": 41
POST - assignDevicesToGroup
Request URLServer/devices/assignDevicesToGroup
- Description
The method does the mapping of the devices sent in the request. Being a POST type request,
the parameters must go in the body of the request in type: JSON format.
Remember that for this method only one parameter (esn, imei or deviceList) must be sent in
the request. If more than one parameter is sent, they will be taken into account in the
following order: esn - imei - deviceList
Note: if the ESN and DEVICELIST parameters are received, the method will carry out the
process through the ESN.

Name Description
group string
required Name of the group to which the devices will be assigned
esn string
imei string
optional Device identifier
array
deviceList
List of devices to assign. The array must be composed with the ESN of the devices
optional
to be updated.
- Requests examples
Example 1 Example 2
{ "group" : "GROUP_TEST_01",
"group" : "GROUP_TEST_01", "deviceList" : [
"esn" : "210000001" "6009999015","210000002asd",
} "0210000118","6009999001"]
- Response examples
Code: 200 - OK: Successful request
Example 1 Example 2
"data": {
{
"totalDevicesAssigned": 2,
"devicesAssigned": [
"message": "Device correctly assigned to
"6009999015",
group"
"6009999001"],
}
"devicesNotFound": ["210000002asd"],
"devicesAlreadyAssigned": ["0210000118"]
}
POST - unassignDevicesToGroup
Request URLServer/devices/unassignDevicesToGroup
- Description
The method performs unassignment of the devices sent in the request. Being a POST type
request, the parameters must go in the body of the request in type: JSON format.

Name Description
group string
required Name of the group, from which the devices will be unassignment
esn string
imei string
array
deviceList
List of devices to unassignment. The array must be composed with the ESN of the
optional
devices to be updated.
- Requests examples
Example 1 Example 2
{ "group" : "GROUP_TEST_01",
"group" : "GROUP_TEST_01", "deviceList" : [
"esn" : "210000001" "6009999015","210000002asd",
} "0210000118","6009999001"]
- Response examples
Example 1 Example 2
"data": {
{
"totalDevicesUnassigned": 3,
"devicesUnassigned": [
"message": "Device correctly unassigned
"6009999015", "0210000118", "6009999001"
to group"
],
}
"devicesNotFound": ["210000002asd"],
"non-groupDevices": []
}
POST - scheduleFirmwareOtaUpdate
Request URLServer/devices/scheduleFirmwareOtaUpdate
- Description
The method schedules the change of Firmware of the devices sent in the request. Being a
POST type request, the parameters must go in the body of the request in type: JSON format.
Remember that for this method only one parameter (esn or deviceList) must be sent in the
request. If more than one parameter is sent, they will be taken into account in the following
order: esn - deviceList

Name Description
firmware string
required Name of the firmware, to which the device (s) will be updated
esn string
array
deviceList
List of devices for firmware change. The array must be composed with the ESN of
optional
the devices to be updated.
- Requests examples
Example 1 Example 2
"group" : "FIRMWARE_TEST_01",
{
"deviceList" : [
"group" : "FIRMWARE_TEST_01",
"6001111112","210000002asd",
"esn" : "6001111112"
"0210000118","6009999001"
}
]
- Response examples
Example 1 Example 2
"data": {
"totalScheduledDevices": 1,
{
"scheduledDevices": ["6001111112"],
"devicesUpdateProgress": [],
"message": "Update scheduled correctly"
"optionNotFoundForDevices": [
}
"0210000118", "6009999001"
],
"devicesNotFound": ["210000002asd"]
}
POST - scheduleProfileUpdate
Request URLServer/devices/scheduleProfileUpdate
- Description
The method schedules the change of Profile of the devices submitted in the request. Being a
POST type request, the parameters must go in the body of the request in type: JSON format.

Name Description
profile string
required Name of the profile, to which the device (s) will be updated
esn string
imei string
array
deviceList
List of devices for profile change. The array must be composed with the ESN of the
optional
devices to be updated.
- Requests examples
Example 1 Example 2
"group" : "PROFILE_TEST_01",
{
"deviceList" : [
"group" : "PROFILE_TEST_01",
"6001111112","210000002asd",
"esn" : "6001111112"
"0210000118","6009999001"
}
]
- Response examples
Example 1 Example 2
"data": {
{
"totalDevicesUpdated": 3,
"devicesUpdated": [
"message": "Successful update request"
"6001111112", "0210000118", "6009999001"
}
],
}
GROUPS
POST - createGroup
Request URLServer/groups/createGroup
- Description
The method performs group creation on the system. Being a POST type request, the
parameters must go in the body of the request in type: JSON format.

Name Description
name string
required Name of the group to be created
- Example Request
{
"name" : "groupTest"
}
- Response example
{
Successful request "message": "The Group has been added correctly"
}
GET - getGroups
Request URLServer/groups/getGroups
- Description
The method returns a list of the groups belonging to the user.
The following example shows a request with the group parameter with value: groupTest
Request with parameter URLServer/groups/getGroups?group=groupTest

Returns a record of the group that matches the parameter
Description
sent
- Query parameters
Name Description
group string
- Response example
"data": [
{
"name": "4310 Group"
},
{
"name": "4500 Test Group"
},
{
"name": "4940's "
},
200 OK:
{
Successful request
"name": "Actsoft 100 ST4940M 5_28_2020"
},
…
},
…
],
"first_page_url": "URLServer/groups/getGroups?page=1",
"perPage": 10,
"next_page_url": "URLServer/groups/getGroups?page=2",
"last_page_url": "URLServer/groups/getGroups?page=2",
"total": 12
FIRMWARES
GET - getFirmwares
Request URLServer/firmwares/getFirmwares
- Description
The method returns a list of existing firmwares on the system. This method can only be used
by administrator type users.
The following example shows a request with the firmware parameter with value:
firmwareTest
firmware - model
Note: if the FIRMWARE and MODEL parameters are received, the method will carry out the
process through the FIRMWARE.
Request with parameter URLServer/firmwares/getFirmwares?firmware=firmwareTest

Returns a record of the group that matches the parameter
Description
sent
- Query parameters
Name Description
firmware string
optional Firmware name, field to filter in search
model string
- Response example

"data": [
{
"firmwareFactory": "ST4340_USA_STADV_1.0.5",
"firmwareNumber": "1.0.5",
"firmwareReqVer": " ST4340_USA_STADV_1.0.5",
"firmwareMNT": "1.0.5",
"firmwareSTT": "1.0.5",
"model": "ST4340"
},
{
"firmwareFactory": " ST4500_USA_STADV_1.0.3",
"firmwareReqVer": " ST4500_USA_STADV_1.0.3",
"model": "ST4500"
},
{
"firmwareFactory": "1.0.20",
200 OK:
"firmwareReqVer": "STG.52.1.0.20",
Successful request
"firmwareMNT": "STG.52.1.0.20",
"firmwareSTT": "STG.52.1.0.20",
"model": "ST4340LC"
},
{
"firmwareFactory": "1.0.99",
"firmwareReqVer": "1.0.99",
"model": "ST4300"
},
…
},
…
],
"first_page_url": "URLServer/firmwares/getFirmwares?page=1",
"perPage": 10,
"next_page_url": "URLServer/firmwares/getFirmwares?page=2",
"last_page_url": "URLServer/firmwares/getFirmwares?page=31",
"total": 302
PROFILES
POST - createProfile
Request URLServer/profiles/createProfile
- Description
The method performs profiling on the system. As it is a POST request, the parameters must
go in the body of the request in type format: form-data.

Name Description
name string
required Name of the profile to be created
file file
required File that will be assigned to the created profile
- Example Request
{
"name" : "profileTest",
"file" : "file.txt"
}
- Response example
{
Successful request "message": "The Profile has been added correctly"
}
GET - getProfiles
Request URLServer/profiles/getProfiles
- Description
The method returns a list of the profiles belonging to the user. If a parameter is sent, the
method will perform a search filter using the received parameter. In the following example, a
request is shown with the profile parameter with value: profileTest
Request with
URLServer/profiles/getProfiles?profile=profileTest
parameter
Description Returns a record of the group that matches the parameter sent
- Query parameters
Name Description
profile string
- Response example
"data": [
{
"name": "api-prod",
"file": "file.txt",
"owner": "Juan Martinez",
"client": null
},
{
"name": "profile-postman-sftp",
"file": "file.txt",
200 OK: "client": null
Successful request },
{
"name": "profile.jux.admin",
"file": "file.jpg",
"client": null
}
],
"first_page_url": "URLServer/profiles/getProfiles?page=1",
"perPage": 10,
"next_page_url": "URLServer/profiles/getProfiles?page=2",
"last_page_url": "URLServer/profiles/getProfiles?page=2",
"total": 17
POST - cancelProfileUpdates
Request URLServer/profiles/cancelProfileUpdates
- Description
The method performs the cancellation of the last scheduled OTA change of the devices sent
in the request. Being a POST type request, the parameters must go in the body of the request
in type: JSON format.

Name Description
esn string
array
deviceList
List of devices to cancel. The array must be composed with the ESN of the devices
optional
to be updated.
- Requests examples
Example 1 Example 2
{
"deviceList" : [
{
"210000001",
"esn" : "210000001"
"210000002"
}
]
}
- Response examples
Code:200 - OK: Successful request
Example 1 Example 2
"data": {
{ "totalRecordsUpdated": 1,
"codeResponse": 200, "devicesUpdated": ["0210000118"],
"message": "Update successfully canceled" "devicesNoUpdateLogs": [],
} "noUpdatesToCancel": ["6009999001"],
"unabletoCancel": ["6009999015"],
}
OTAS
GET - getOtaUpdatesOptions
Request URLServer/otas/getOtaUpdatesOptions
- Description
The method returns a list of the update options (between firmwares) existing in the system.
If a parameter is sent, the method will perform a filter on the search, using the received
parameter. The following example shows a request with the model parameter with value:
ST600.
Request with
URLServer/otas/getOtaUpdatesOptions?model=ST600
parameter
Description Returns a list of update options that match the parameter sent
esn - model
Note: if the ESN and MODEL parameters are received, the method will carry out the process
through the ESN
- Query parameters
Name Description
esn string
optional Device serial number, field to filter on search
model string
- Response example
"data": [
{
"model": "ST20",
"fwOrigin": "ST20_SUNTECHUSA_STADV_028",
"fwDestiny": "ST20_SUNTECHUSA_STADV_029",
"file": "ST20_STM32__v029_20190909_disADC.hex"
},
{
"model": "ST20",
"file": "ST20_STM32__v030_20190918_1hrDelaySleep.hex"
},
{
"model": "ST20",
"file": "ST20_STM32__v030_20190918_1hrDelaySleep.hex"
},
200 OK: {
Successful request "model": "ST20",
"file": "test.pdf"
},
{
"model": "ST20",
"file": "ST20_STM32__v028_20181217.hex"
},
{
…
},
…
],
"first_page_url": "URLServer/otas/getOtaUpdatesOptions?page=1",
"perPage": 10,
"next_page_url": "URLServer/otas/getOtaUpdatesOptions?page=2",
"last_page_url": "URLServer/otas/getOtaUpdatesOptions?page=31",
"total": 304
POST - cancelOtaUpdates
Request URLServer/otas/cancelOtaUpdates
- Description
The method performs the cancellation of the last scheduled OTA change of the devices sent
in the request. Being a POST type request, the parameters must go in the body of the request
in type: JSON format.
Remember that for this method only one parameter (esn or deviceList) must be sent in the
request. If more than one parameter is sent, they will be taken into account in the following
order: esn - imei - deviceList

Name Description
esn string
array
deviceList
List of devices to cancel. The array must be composed with the ESN of the devices
optional
to be updated.
- Requests examples
Example 1 Example 2
"deviceList" : [
"6001111112",
{
"210000002asd",
"esn" : "6001111112"
"0210000118",
}
"6009999001"
]
- Response examples
Example 1 Example 2
"data": {
"totalRecordsUpdated": 1,
{
"devicesUpdated": ["6001111112"],
"noUpdatesToCancel": [
"message": "Update successfully canceled"
"0210000118", "6009999001"
}
],
"devicesNoUpdateLogs": [],
}
GENERAL
GET - getModels
Request URLServer/general/getModels
- Description
The method returns a list of the existing models in the system.
If the model parameter is sent, the method will search for those models that match the name
of the model received. The following example shows a request with the model parameter
with value: ST600
Request with parameter URLServer/general/getModels?model=ST600

Description Returns a list of the models that match the parameter sent
- Query parameters
Name Description
model string
- Response example
"data": [
{
"model": "ST20"
},
{
"model": "ST25T"
},
{
"model": "ST310U"
200 OK:
},
Successful request
{
…
},
…
],
"first_page_url": "URLServer/general/getModels?page=1",
"perPage": 10,
"next_page_url": "URLServer/general/getModels?page=2",
"last_page_url": "URLServer/general/getModels?page=6",
"total": 57
GET - getVersion
Request URLServer/general/getVersion
- Description
The method returns the current version of the API.
- Response example
{
Successful request "message": "API version: 1.0.0"
}

API SCUTI Documentation-En V 1.0.0

Uploaded by

Copyright:

Available Formats

API SCUTI Documentation-En V 1.0.0

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

API SCUTI Documentation-En V 1.0.0

Uploaded by

Copyright:

Available Formats

SCUTI API (V.1.0.

The server address is: https://98gjkilko7.execute-api.us-east-1.amazonaws.com/scuti

Content-Type: application / json.

Submit your user credentials proactively

Take into account the speed of your application to handle requests.

- Query parameters in request body

Request with parameter URLServer/devices/getDevices?model=ST20

Code Response example

Code Response example

- Query parameters in request body

- Query parameters in request body

- Query parameters in request body

- Query parameters in request body

- Query parameters in request body

Request with parameter URLServer/groups/getGroups?group=groupTest

Request with parameter URLServer/firmwares/getFirmwares?firmware=firmwareTest

Code Response example

- Query parameters in request body

- Query parameters in request body

- Query parameters in request body

Request with parameter URLServer/general/getModels?model=ST600

You might also like