中文简体    English

IVYIOT Cloud Platform WebService API

Version history:

1 Introduction

WebService API: Supports get and post calls. All requests return data in json format.

2.IVY Cloud Platform API General Example and Description

2.1 General examples

WebServiceAPI example:

• https://{HOST}/gateway?service=xxx.xxx?parm1=xxx&parm2=xxx

Note:

• 1.HOST refers to the domain name, and the test environment domain name is sandboxt-ivyiot.io;
• 2.Service=xxx.xx, the interface name is specified here;
• 3.The methods are mainly divided into GET and POST methods;

Returns the result:

{
    "errorCode":"",
    "failureDetails":"",
    "data":""/*if exist*/
}

• a) errorCode is the error code. When an empty string is returned, it
  indicates success. For other values, refer to the corresponding API
  status code table.

• b) failureDetails is the error description. When the
  error code is not empty, this field explains the meaning of the error
  code.

• c) data: return data, when there is return data, the data is in
  this parameter, the specific data data structure see the specific Api
  interface

2.2 Api related configuration information

2.2.1 Api domain name

Test environment:

• sandboxt-api.ivyiot.io (overseas)
• sandboxt-api.ivyiot.cn (China Mainland)

Prd environment:

• api.myfoscam.com(overseas)
• api.myfoscam.cn (domestic)

2.2.2 Important parameters ( important )

Cloud platform internal application identity information

• clientId: oemkey
• clientSecret: 397ff5985bb7437198a9ef51b4815caf

User identity parameters (obtained through the password authorization
login interface)

• openId: user identity Id
• accessToken: user identity

2.3 Common Error Codes ( Important )

2.3.1 System error code

System-level error codes, all interface calls may throw such error codes;

2.3.2 authentication error

The interface that needs to verify identity, the identity information is
incorrect or the identity information expires will throw the following
error

3.Foscam Cloud Platform API List

3.1 Equipment Management

3.1.1 Add Device

Interface description:

• Add device

Request URL:

• https://{HOST}/gateway?service=user_ipc_setting_v2_0.addOemDevice

Request method:

• POST

Request header:

Request parameters:

{
    "errorCode":"",
    "failureDetails":""
}

Return parameter description:

Error code description:

Interface description:

• Delete user device

Request URL:

• https://{HOST}/gateway?service=user_ipc_setting_v2_0.delOemDeviceByMac

Request method:

• POST

Request header:

Request parameters:

Return example:

{
    "errorCode":"",
    "failureDetails":""
}

Return parameter description:

Error code description:

3.1.3 Modify Device

Interface description:

• Modify device

Request URL:

• https://{HOST}/gateway?service=user_ipc_setting_v2_0.updateOemDevice

Request method:

• POST

Request header:

Request parameters:

Return example:

{
    "errorCode":"",
    "failureDetails":""
}

Return parameter description:

Error code description:

3.1.4 Querying User Equipment

Interface description:

• Query information about the device to which the user belongs

Request URL:

• https://{HOST}/gateway?service=user_ipc_setting_v2_0.getOemDeviceByUser

Request method:

• GET

Request header:

• None |

Request parameters:

{
    "errorCode":"",
    "data":[
        {
            "userId":622258,
            "macAddr":"macAddr",
            "deviceName":"deviceName",
            "productName":"productName",
            "username":"asd",
            "password":"password",
            "hasusertag":1,
            "supportStore":1,
            "supportRichMedia":1,
            "oemCode":"7128"
        },
        {
            "userId":622258,
            "macAddr":"macAddr3",
            "deviceName":"deviceName1",
            "productName":"productName",
            "username":"username1",
            "password":"password1",
            "hasusertag":1,
            "supportStore":0,
            "supportRichMedia":0,
            "oemCode":"7128"
        }
    ]
}

Return parameter description:

Error code description:

3.1.5 Query Device Based on Mac

Interface description:

• Query device information by mac address

Request URL:

• https://{HOST}/gateway?service=user_ipc_setting_v2_0.getOemDeviceByUserAndMac

Request method:

• GET

Request header:

• None |

Request parameters:

Return example:

{
    "errorCode":"",
    "data":{
        "userId":622258,
        "macAddr":"macAddr",
        "deviceName":"deviceName",
        "productName":"productName",
        "username":"asd",
        "password":"password",
        "hasusertag":1,
        "supportStore":1,
        "supportRichMedia":1,
        "oemCode":"7128"
    }
}

Return parameter description:

Error code description:

3.1.6 Unbinding Device Interface

Interface description:

• Unbundling the device through mac and signing

Request URL:

• https://{HOST}/gateway?service=user_ipc_setting_v2_0.delOemDeviceForce

Request method:

• POST

Request header:

• None

Request parameters:

Return example:

{
    "errorCode":""
}

Return parameter description:

Error code description:

3.2 Service activation and authorization

3.2.1 Query the user does not activate the authorization record

Interface description:

• Query all inactive authorization records of the user

Request URL:

• https://{HOST}/gateway?service=permission.query_user_not_active

Request method:

• GET

Request header:

• no

Request parameters:

Return example:

{
    "errorCode":"",
    "data":[
        {
            "grantId":222222,
            "ipcMac":"ipcMac",
            "permissionCode":"permissionCode",
            "permissionName":"permissionName",
            "permissionType":1,
            "permissionValue":0,
            "grantStatus":1,
            "userTag":"userTag",
            "streamId":"streamId",
            "belongServer":"belongServer",
            "initTime":1565847960000,
            "channelCount":0
        },
        {
            "grantId":111111,
            "ipcMac":"ipcMac",
            "permissionCode":"permissionCode",
            "permissionName":"permissionName",
            "permissionType":1,
            "permissionValue":0,
            "grantStatus":1,
            "userTag":"userTag",
            "belongServer":"belongServer",
            "initTime":1565847960000,
            "channelCount":0
        }
    ],
    "sysDate":1576289329443
}

Return parameter description:

Error code description:

3.2.2 Activation permissions

Interface description:

• Activate device individual permissions

Request URL:

• https://{HOST}/gateway?service=permission.active

Request method:

• POST

Request header:

Request parameters:

Return example:

{
    "errorCode":"",
    "failureDetails":""
}

Return parameter description:

Error code description:

3.2.3 Obtaining Current Service Information of User Equipment

Interface description:

• Get user device current service information

Request URL:

• https://{HOST}/gateway?service=fcmall.get_current_service

Request method:

• GET

Request header:

• no

Request parameters:

Return example:

{
    "errorCode":"",
    "data":{
        "userId":111111,
        "macAddr":"macAddr",
        "name":"3 days per year",
        "description":"3 Day Cloud Storage",
        "startTime":1521093393000,
        "endTime":1552629393000,
        "validity":"12 Months",
        "status":3,
        "flag":1
    }
}

Return parameter description:

Error code description:

3.2.4 Query the valid authorization records of all users’ devices

Interface description:

• Query valid authorization records of all devices of the user

Request URL:

• https://{HOST}/gateway?service=permission.query_user_ipcs_valid

Request method:

• GET

Request header:

• no

Request parameters:

Return example:

{
    "errorCode":"",
    "data":[
        {
            "grantId":222222,
            "ipcMac":"ipcMac",
            "permissionCode":"permissionCode",
            "permissionName":"permissionName",
            "permissionType":1,
            "permissionValue":0,
            "grantStatus":1,
            "userTag":"userTag",
            "streamId":"streamId",
            "belongServer":"belongServer",
            "initTime":1565847960000,
            "channelCount":0
        },
        {
            "grantId":111111,
            "ipcMac":"ipcMac",
            "permissionCode":"permissionCode",
            "permissionName":"permissionName",
            "permissionType":1,
            "permissionValue":0,
            "grantStatus":1,
            "userTag":"userTag",
            "belongServer":"belongServer",
            "initTime":1565847960000,
            "channelCount":0
        }
    ],
    "sysDate":1576289329443
}

Return parameter description:

Error code description:

3.3 Cloud storage and live streaming

3.3.1 Basic subservice information query

Interface description:

• Query user sub-service information, the data returned by a user is
  fixed, and the user only needs to query once

Request URL:

• https://{HOST}/gateway?service=center.getServerInfo

Request method:

• GET

Request header:

• no

Request parameters:

Return example:

{
    "errorCode":"",
    "data":{
        "userId":111111,
        "subtoken":"subtoken",
        "area":"NA",
        "tag":"tag",
        "storeTag":"storeTag",
        "alexaTag":"alexaTag",
        "sendMsgUrl":"sendMsgUrl",
        "sendMsgUrlSecure":"sendMsgUrlSecure",
        "url":"url",
        "storeUrl":"storeUrl",
        "alexaUrl":"alexaUrl",
        "channelCount":0
    }
}

Return parameter description:

Error code description:

3.3.2 APP Query List of Existing Recording Dates

Interface description:

• The App queries the time when the device has recorded, where HOST
  is the storeUrl address in the result of the basic subservice
  information query interface ;

Request URL:

• https://{HOST}/stream?service=record.date.query

Request method:

• GET

Request header:

• no

Request parameters:

Return example:

{
    "dateList":[
        "20190330T190000",
        "20190331T210000",
        "20190331T190000",
        "20190330T220000",
        "20190331T000000",
        "20190401T180000",
        "20190401T000000"
    ],
    "errorCode":"",
    "failureDetails":""
}

Return parameter description:

3.3.3 APP Get Recording Time

Interface description:

• The App obtains the start and end time of all video clips in the
  time period by the start and end time, where HOST is the storeUrl
  address in the result of the basic subservice information query
  interface ;

Request URL:

• https://{HOST}/stream?service=record.query

Request method:

• GET

Request header:

• no

Request parameters:

Return example:

{
    "errorCode":"",
    "failureDetails":"",
    "recordList":[
        [
            "1554160661",
            "1554160702",
            "2"
        ],
        [
            "1554160794",
            "1554160913",
            "2"
        ],
        [
            "1554161090",
            "1554161145",
            "2"
        ],
        [
            "1554161801",
            "1554161851",
            "2"
        ],
        [
            "1554162015",
            "1554162054",
            "2"
        ],
        [
            "1554162067",
            "1554162129",
            "2"
        ]
    ]
}

Return parameter description:

Error code description:

3.3.4 App Get Play Video Address

Interface description:

• App obtains the recording address, where HOST is the storeUrl
  address in the result of the basic subservice information query
  interface ;

Request URL:

• https://{HOST}/stream?service=record.play

Request method:

• GET

Request header:

• no

Request parameters:

Return example:

{
    "errorCode":"",
    "failureDetails":"",
    "recordUrl":"http://plb-test.myfoscam.com:8100/hls/362d96836ef005eee0460033724fd26c6164406E4B7E409D8E/2019/03/12/718a9039b6b56451_155341.m3u8?timerange=1552377221-1552377230&expires=1552381960&urlVersion=&sign=544ff805a697a373f65c603987db2404&storageType=BPI&oemCode=",
    "secureUrl":"https://plb-test.myfoscam.com:443/hls/362d96836ef005eee0460033724fd26c6164406E4B7E409D8E/2019/03/12/718a9039b6b56451_155341.m3u8?timerange=1552377221-1552377230&expires=1552381960&urlVersion=&sign=544ff805a697a373f65c603987db2404&storageType=BPI&oemCode=&se=1"
}

Return parameter description:

Error code description:

3.4 Tool interface

3.4.1 Server time query

Interface description:

• Love for server time query

Request URL:

• https://{HOST}/gateway?service=cloud_system.current_time

Request method:

• GET

Request header:

• no

Request parameters:

• no

Return example:

{
    "errorCode":"",
    "data":1576481002262
}

Return parameter description:

Error code description:

3.5 Firmware Upgrade

3.5.1 Obtain the latest firmware (IPC) based on the model name

Interface description:

• Get the latest firmware based on the model name

Request URL:

• https://{HOST}/gateway?service=firmware.latest

Request method:

• GET

Request header:

• no

Request parameters:

Return example:

{
    "errorCode":"",
    "firmwareList":[
        {
            "id":135,
            "name":"FosIPC_J_app_ver2.x.2.77MZS4010",
            "desc":"{"zh":"FosIPC_J_app_ver2.x.2.77MZS4010"}",
            "uploadUtilName":"aws-s3",
            "backupUploadUtilName":"local-disk",
            "path":"/firmware/test/FosIPC_J_app_ver2.x.2.77MZS4010--1576569091241.bin",
            "downloadUri":"http://test-download.myfoscam.com:9001/firmware/test/FosIPC_J_app_ver2.x.2.77MZS4010--1576569091241.bin",
            "backupUri":"http://test-download.myfoscam.com:9001/firmware/test/FosIPC_J_app_ver2.x.2.77MZS4010--1576569091241.bin",
            "md5":"24AD9165B11ECB633901BC7F3B412D7F",
            "type":2,
            "interim":false,
            "version1":2,
            "version2":"x",
            "version3":2,
            "version4":77,
            "patchVersion":0,
            "createTime":1576569118000,
            "seqNo":4,
            "newest":true,
            "active":true,
            "remind":1,
            "remindActive":false,
            "firmwarePlatform":"Mstar",
            "productTypeId":1,
            "winPluginId":176,
            "macOsPluginId":177
        }
    ],
    "remind":1
}

Return parameter description:

Error code description: