API endpoints

Basic info

IS API service

Base URL

http

https://synerwatt.eu

List of all endpoints for Synerwatt API service

Endpoint	Method	Description
https://sso.synerwatt.eu/auth/signin	POST	Signin user
https://sso.synerwatt.eu/auth/token	POST	Service authentication
https://sso.synerwatt.eu/auth/signout	POST	Signout user
https://sso.synerwatt.eu/auth/refresh	GET	Refresh token
https://api.synerwatt.eu/v1/accounts/me	GET	My account details
https://api.synerwatt.eu/v1/traders/me/commands	POST	Submit command
https://api.synerwatt.eu/v1/traders/me/commands	GET	List commands
https://api.synerwatt.eu/v1/traders/me/devices	GET	List all devices
https://api.synerwatt.eu/v1/traders/me/savings	POST	Submit savings entry

KASI API service

Base URL

http

https://kasi-provider-domain.cz

List of all endpoints for KASI API service

Endpoint	Method	Description
/api/v1/auth/token	POST	Service authentication
/api/v1/ean/{id}	GET	EAN details
/api/v1/ean/{id}	PATCH	EAN update

HTTP Status Code Summary

Status Code	Description	Details
200	OK	Everything worked as expected.
400	Bad Request	The request was unacceptable, often due to missing a required parameter.
401	Unauthorized	No valid API key provided.
402	Request Failed	The parameters were valid but the request failed.
403	Forbidden	The API key doesn't have permissions to perform the request.
404	Not Found	The requested resource doesn't exist.
409	Conflict	The request conflicts with another request (perhaps due to using the same idempotent key).
429	Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504	Server Errors	Something went wrong on Stripe's end. (These are rare.)

Authorization

This method provides the standard authentication mechanism for regular users. It utilizes the OAuth 2.0 password grant type, which requires a username and password for user authentication.

Endpoint

Method: POST

http

https://sso.synerwatt.eu/auth/signin

cURLRaw body

cURL

curl -X POST "https://sso.synerwatt.eu/auth/signin" \
-H "Content-Type: application/json" \
-H "Accept: */*" \
-d '{
  "username": "test-user",
  "password": "user-password",
  "remember": true
}'

json

{
  "username": "test-user",
  "password": "user-password",
  "remember": true
}

Headers

Header	Value	Required
Content-Type	application/json	Yes

Request Body

Field	Type	Required	Description	Example
username	String	Yes	Username	test-user
password	String	Yes	Password	user-password
remember	Boolean	No	Remember	true

Response

🟢 200 OK🔴 401 Unauthorized

json

{
    "success": true,
    "message": "Authentication successful",
    "data": {
        "token": "eyJhbGciOiJSUzI1NiIs...",
        "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
        "rpt": "eyJhbGciOiJSUzI1NiIs...",
        "type": "Bearer"
    },
    "timestamp": "2025-08-05T03:27:28.615Z",
    "status_code": 200
}

json

{
    "success": false,
    "message": "Authentication Failed",
    "data": {
        "error": "INVALID_GRANT",
        "error_description": "Invalid user credentials"
    },
    "timestamp": "2025-08-05T03:27:28.615Z",
    "status_code": 401
}

Notes

The remember field serves as a checkbox for "Remember me" on the login form.
Response token is used for authentication in other requests. It contains basic user information and authorization claims.
Response refresh_token is used to obtain a new access token without re-entering the username and password. It is recommended to store it in HTTP-only secure cookie.
Requesting Party Token rpt is a "bigger" token with permissions (fine-grained authorization) to access resources on behalf of the user. It might not be available in every signin response.

Service authentication

This method offers an alternative authentication mechanism tailored for third-party services and integrations. Instead of relying on the OAuth 2.0 password grant type, it utilizes the client_credentials grant, which requires a client_id and client_secret.

Endpoint

Method: POST

http

https://sso.synerwatt.eu/auth/token

cURLRaw body

cURL

curl -X POST "https://sso.synerwatt.eu/auth/token" \
-H "Content-Type: application/json" \
-H "Accept: */*" \
-d '{
  "client_id": "some-client-id",
  "client_secret": "some-passphrase"
}'

json

{
  "client_id": "some-client-id",
  "client_secret": "some-passphrase"
}

Headers

Header	Value	Required
Content-Type	application/json	Yes

Request Body

Field	Type	Required	Description	Example
client_id	String	Yes	Client ID	some-client-id
client_secret	String	Yes	Secret passphrase	some-passphrase

Response

🟢 200 OK🔴 401 Unauthorized

json

{
    "success": true,
    "message": "Service authentication successful",
    "data": {
        "token": "eyJhbGciOiJSUzI1NiIs...",
        "type": "Bearer",
        "expires_in": 900
    },
    "timestamp": "2025-08-05T03:27:28.615Z",
    "status_code": 200
}

json

{
    "success": false,
    "message": "Authentication Failed",
    "data": {
        "error": "UNAUTHORIZED_CLIENT",
        "error_description": "Invalid client or Invalid client credentials"
    },
    "timestamp": "2025-08-05T03:27:28.615Z",
    "status_code": 401
}

Notes

Response token is used for authentication in other requests. It contains basic client information and authorization claims.
The expires_in field indicates the number of seconds until the token expires and must be refreshed.

Signout

This method allows users signed with OAuth 2.0 password grant type to terminate their session by revoking their authentication tokens. It provides a secure way to log out and invalidate the current session tokens.

Endpoint

Method: POST

http

https://sso.synerwatt.eu/auth/signout

cURLRaw body

cURL

curl -X POST "https://sso.synerwatt.eu/auth/signout" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-auth-token" \
-H "Accept: */*" \

json

/* empty body */

Headers

Header	Value	Required
Content-Type	application/json	Yes
Authorization	Bearer your-auth-token	Yes

Response

🟢 200 OK🟢 200 OK - Soft sign out🔴 400 Bad request

json

{
    "success": true,
    "message": "Signout successful",
    "data": {
        "message": "Token successfully revoked"
    },
    "timestamp": "2025-08-05T03:27:28.615Z",
    "status_code": 200
}

json

/* Cookies cleared without a token revocation */
{
    "success": true,
    "message": "Signout successful",
    "data": {
        "error": "INVALID_TOKEN",
        "error_description": "Invalid token"
    },
    "timestamp": "2025-08-05T03:27:28.615Z",
    "status_code": 200
}

json

{
    "success": false,
    "message": "Authentication Failed",
    "data": {
        "error": "INVALID_REQUEST",
        "error_description": "Token not provided"
    },
    "timestamp": "2025-08-05T03:27:28.615Z",
    "status_code": 400
}

Refresh

This method enables users signed with OAuth 2.0 password grant type to obtain new access tokens using their refresh token without requiring re-authentication. It helps maintain session continuity by extending the authentication period seamlessly.

Endpoint

Method: GET

http

https://sso.synerwatt.eu/auth/refresh

cURLRaw body

cURL

curl -X GET "https://sso.synerwatt.eu/auth/refresh" \
-H "Content-Type: application/json" \
-H "Accept: */*" \

json

/* empty body */

Headers

Header	Value	Required
Content-Type	application/json	Yes

Response

🟢 200 OK🔴 400 Bad request

json

{
    "success": true,
    "message": "Token refreshed successfully",
    "data": {
        "token": "eyJhbGciOiJSUzI1NiIs...",
        "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
        "rpt": "eyJhbGciOiJSUzI1NiIs...",
        "type": "Bearer"
    },
    "timestamp": "2025-08-05T03:27:28.615Z",
    "status_code": 200
}

json

{
    "success": false,
    "message": "Token refresh failed",
    "data": {
        "error": "INVALID_GRANT",
        "error_description": "Invalid refresh token"
    },
    "timestamp": "2025-08-05T03:27:28.615Z",
    "status_code": 400
}

Accounts

My account details

This method retrieves detailed information about the currently authenticated user's account, including account type, username, email, and other profile data.

Endpoint

Method: GET

http

https://api.synerwatt.eu/v1/accounts/me

cURLRaw body

cURL

curl -X GET "https://api.synerwatt.eu/v1/accounts/me" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-auth-token" \
-H "Accept: */*" \

json

/* empty body */

Headers

Header	Value	Required
Content-Type	application/json	Yes
Authorization	Bearer your-auth-token	Yes

Response

🟢 200 OK🔴 401 Unauthorized

json

{
    "success": true,
    "message": "Account retrieved successfully",
    "data": {
        "id": "f92a4c31-8d67-4b9e-a15f-3c49d8ae5290",
        "account_type": "trader",
        "username": "my.email@energytrader.sk",
        "email": "my.email@energytrader.sk",
        "name": "Energy Trade s.r.o.",
        "created_at": "2025-05-13T20:20:25.398Z",
        "updated_at": "2025-05-13T20:20:25.398Z",
        "sub": "b47d9c2a-e183-4f95-8d36-9a42c5f0d8e4",
        "info": null
    },
    "timestamp": "2025-06-09T22:55:10.552Z",
    "status_code": 200
}

json

{
    "success": false,
    "message": "Authentication required",
    "data": {
        "error": "UNAUTHORIZED",
        "error_description": "No valid token provided"
    },
    "timestamp": "2025-08-05T03:27:28.615Z",
    "status_code": 401
}

Commands

Submit command

This method allows authenticated users / traders to submit control commands to affect IoT gateway energy controller.

Endpoint

Method: POST

http

https://api.synerwatt.eu/v1/traders/me/commands

cURLRaw body

cURL

curl -X POST "https://api.synerwatt.eu/v1/traders/me/commands" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-auth-token" \
-H "Accept: */*" \
-d '{
  "command": "dPlus1Schedule",
  "command_id": "550e8400-e29b-41d4-a716-446655440000",
  "devices": ["1234-456ec", "4567-890ec"],
  "all_devices": true,
  "parameters": {
    "execute_time": 1752012000,
    "schedule": [
        { "c": "s", "pw": 20.5 },
        { "c": "b", "pw": 16.8 },
        { "c": "b"},
        { "c": "e" },
        { "c": "sb", "pw": 5.4 },
        { "c": "sb"},
        ...
        { "c": "e" }
    ]
  }
}
'

json

{
  "command": "dPlus1Schedule",
  "command_id": "550e8400-e29b-41d4-a716-446655440000",
  "devices": ["1234-456ec", "1234-456ec"],
  "all_devices": true,
  "parameters": {
    "execute_time": 1752012000,
    "schedule": [
        { "c": "s", "pw": 20.5 },
        { "c": "b", "pw": 16.8 },
        { "c": "b"},
        { "c": "e" },
        { "c": "sb", "pw": 5.4 },
        { "c": "sb"},
        { "c": "s", "pw": 1.2 },
        { "c": "e" }
    ]
  }
}

Headers

Header	Value	Required
Content-Type	application/json	Yes
Authorization	Bearer your-auth-token	Yes

Request Body

Field	Type	Required	Description	Example
command	String	Yes	Type of the command	"dPlus1Schedule", "sell", "buy", "disableExport", "stop"
command_id	String	No	Reference identifier for the command (KASI)	"cmd_12345"
devices	Array	No*	Array of device serial numbers (*required when all_devices is not true)	["1234-456ec", "4567-890ec"]
all_devices	Boolean	No	If true, command applies to all trader's devices (devices array ignored)	true
parameters	Object	No	Command parameters (varies by action), for dPlus1Schedule:	"execute_time": 1752012000, "schedule": [{"c": "s", "pw": 20.5}, ... {"c": "e"}]

Response

🟢 201 OK🔴 400 Bad request🔴 401 Unauthorized

json

{
    "success": true,
    "message": "Commands created successfully",
    "data": {
        "master_command_id": "fa5a9e12-2242-453e-b54d-d6f69fa762a2",
        "reference_command_id": "550e8400-e29b-41d4-a716-446655440000",
        "command_type": "dPlus1Schedule",
        "user_id": "23fg91dd-e6f3-47e4-8ae5-22b4607b157f",
        "target_devices_count": 1,
        "created_device_commands_count": 1,
        "device_commands": [
            {
                "id": "56ef7d4a-9b5a-462c-8d42-e415f46b8920",
                "device_id": "c4d8e5f2-9a3b-47c1-8d6e-2f5a9b3c7d1e",
                "device_serial_number": "1234-456ec",
                "status": "pending"
            }
        ],
        "status": "commands_created"
    },
    "timestamp": "2025-08-05T03:24:12.881Z",
    "status_code": 200
}

json

{
    "success": false,
    "message": "Invalid device access: fake-device-serial-number",
    "data": {
        "error": "INVALID_DEVICE_ACCESS",
        "invalid_devices": ["fake-device-serial-number"]
    },
    "timestamp": "2025-08-05T03:27:28.615Z",
    "status_code": 400
}

json

{
    "success": false,
    "message": "Authentication required",
    "data": {
        "error": "UNAUTHORIZED",
        "error_description": "No valid token provided"
    },
    "timestamp": "2025-08-05T03:27:28.615Z",
    "status_code": 401
}

Notes

Command Execution: Commands are executed asynchronously. The API accepts the command and returns a success response, but actual device execution may take time.
Command Tracking: The command_id is optional but recommended for tracking and debugging purposes.
Device Selection:
- Use devices array to target specific devices by their serial numbers
- Use all_devices: true to target all devices associated with the authenticated trader
- If both are provided, all_devices takes precedence and devices array is ignored
Schedule Format dPlus1Schedule:
- Each schedule item represents a 15-minute control interval
- Control commands (c):
  - "b" - buy: Purchase energy from grid
  - "s" - sell: Sell energy to grid (without battery)
  - "sb" - sell with battery: Sell energy to grid using battery
  - "e" - empty/no control: Free 15-minute window with no control (system returns to user's original settings)
- Power (pw) (optional): Desired power in kW
  - If not specified, maximum available power is used
  - Can be specified for "b", "s", or "sb" commands
  - Must be a positive number
Schedule Timing:
- Maximum 96 schedule items (representing 24 hours of 15-minute intervals)
- For full day control (96 items), execute_time should be set to the beginning of the target day
- execute_time uses Unix timestamp in seconds
Trade Format sell, buy, disableExport, stop:
- Trade command that will be executed immediately when received by the device.
- duration (required): Duration of the trade in seconds [s]
- use_battery (optional): battery usage is allowed/not allowed for the trade command [true/false]
- power (optional): Required grid power [kw]
- appliances (optional): List of appliances to be controlled [array of strings]
  - ["all"] - all appliances
  - ["boiler"] - all appliances of type boiler
  - ["boiler[0]","boiler[2]"] - only specific boilers boiler[0] and boiler[2]
Parameter Validation: Different command types may have different parameter requirements and validation rules
For commands targeting specific appliances only sell, buy, stop types are allowed.
Examples of various commands:

json

{
  "command": "dPlus1Schedule",
  "command_id": "550e8400-e29b-41d4-a716-446655440000",
  "devices": ["1234-456ec"],
  "all_devices": false,
  "parameters": {
        "execute_time": 1755640800,
        "schedule": [
            {
                "c": "s",
                "pw": 8.1
            },
            {
                "c": "s",
                "pw": 4.7
            },
            {
                "c": "s",
                "pw": 9.5
            },
            {
                "c": "s",
                "pw": 1.4
            },
            {
                "c": "b",
                "pw": 27.6
            },
            {
                "c": "s",
                "pw": 27.2
            },
            {
                "c": "sb",
                "pw": 25.9
            },
            {
                "c": "sb",
                "pw": 6.2
            },
            {
                "c": "sb",
                "pw": 1.7
            },
            {
                "c": "b",
                "pw": 2.9
            },
            {
                "c": "b",
                "pw": 4.5
            },
            {
                "c": "sb",
                "pw": 29.0
            },
            {
                "c": "b",
                "pw": 6.8
            },
            {
                "c": "sb",
                "pw": 29.9
            },
            {
                "c": "s",
                "pw": 26.5
            },
            {
                "c": "sb",
                "pw": 17.7
            },
            {
                "c": "s",
                "pw": 25.5
            },
            {
                "c": "sb",
                "pw": 13.6
            },
            {
                "c": "s",
                "pw": 8.0
            },
            {
                "c": "b",
                "pw": 27.1
            },
            {
                "c": "s",
                "pw": 23.7
            },
            {
                "c": "b",
                "pw": 26.8
            },
            {
                "c": "sb",
                "pw": 9.4
            },
            {
                "c": "sb",
                "pw": 4.6
            },
            {
                "c": "b",
                "pw": 7.7
            },
            {
                "c": "b",
                "pw": 29.2
            },
            {
                "c": "s",
                "pw": 8.0
            },
            {
                "c": "b",
                "pw": 28.6
            },
            {
                "c": "s",
                "pw": 29.0
            },
            {
                "c": "s",
                "pw": 7.4
            },
            {
                "c": "sb",
                "pw": 5.1
            },
            {
                "c": "b",
                "pw": 1.4
            },
            {
                "c": "b",
                "pw": 7.1
            },
            {
                "c": "sb",
                "pw": 6.6
            },
            {
                "c": "sb",
                "pw": 10.5
            },
            {
                "c": "s",
                "pw": 16.5
            },
            {
                "c": "s",
                "pw": 3.8
            },
            {
                "c": "sb",
                "pw": 23.8
            },
            {
                "c": "sb",
                "pw": 27.2
            },
            {
                "c": "sb",
                "pw": 23.4
            },
            {
                "c": "b",
                "pw": 19.2
            },
            {
                "c": "s",
                "pw": 3.8
            },
            {
                "c": "s",
                "pw": 1.4
            },
            {
                "c": "b",
                "pw": 28.0
            },
            {
                "c": "sb",
                "pw": 7.5
            },
            {
                "c": "b",
                "pw": 22.2
            },
            {
                "c": "s",
                "pw": 7.8
            },
            {
                "c": "sb",
                "pw": 24.5
            },
            {
                "c": "b",
                "pw": 20.8
            },
            {
                "c": "b",
                "pw": 29.0
            },
            {
                "c": "sb",
                "pw": 10.8
            },
            {
                "c": "b",
                "pw": 2.9
            },
            {
                "c": "b",
                "pw": 14.6
            },
            {
                "c": "b",
                "pw": 7.7
            },
            {
                "c": "b",
                "pw": 14.0
            },
            {
                "c": "s",
                "pw": 27.5
            },
            {
                "c": "s",
                "pw": 26.3
            },
            {
                "c": "sb",
                "pw": 5.3
            },
            {
                "c": "s",
                "pw": 26.8
            },
            {
                "c": "s",
                "pw": 24.4
            },
            {
                "c": "b",
                "pw": 29.0
            },
            {
                "c": "b",
                "pw": 7.7
            },
            {
                "c": "s",
                "pw": 26.8
            },
            {
                "c": "s",
                "pw": 2.3
            },
            {
                "c": "s",
                "pw": 14.1
            },
            {
                "c": "b",
                "pw": 8.6
            },
            {
                "c": "b",
                "pw": 29.5
            },
            {
                "c": "b",
                "pw": 3.6
            },
            {
                "c": "b",
                "pw": 18.9
            },
            {
                "c": "s",
                "pw": 28.1
            },
            {
                "c": "s",
                "pw": 19.5
            },
            {
                "c": "b",
                "pw": 24.7
            },
            {
                "c": "s",
                "pw": 11.5
            },
            {
                "c": "sb",
                "pw": 17.7
            },
            {
                "c": "s",
                "pw": 10.8
            },
            {
                "c": "s",
                "pw": 6.5
            },
            {
                "c": "b",
                "pw": 19.5
            },
            {
                "c": "sb",
                "pw": 20.9
            },
            {
                "c": "b",
                "pw": 23.2
            },
            {
                "c": "s",
                "pw": 1.3
            },
            {
                "c": "s",
                "pw": 6.2
            },
            {
                "c": "b",
                "pw": 13.8
            },
            {
                "c": "sb",
                "pw": 26.1
            },
            {
                "c": "s",
                "pw": 15.6
            },
            {
                "c": "s",
                "pw": 29.8
            },
            {
                "c": "s",
                "pw": 24.3
            },
            {
                "c": "sb",
                "pw": 5.8
            },
            {
                "c": "s",
                "pw": 23.0
            },
            {
                "c": "sb",
                "pw": 8.7
            },
            {
                "c": "s",
                "pw": 29.1
            },
            {
                "c": "sb",
                "pw": 2.8
            },
            {
                "c": "sb",
                "pw": 19.0
            },
            {
                "c": "s",
                "pw": 26.4
            },
            {
                "c": "b",
                "pw": 18.0
            },
            {
                "c": "b",
                "pw": 8.6
            },
            {
                "c": "b",
                "pw": 2.9
            }
        ]
    }
}

json

{
    "command": "sell",
    "command_id": "550e8400-e29b-41d4-a716-446655666111",
    "devices": ["1234-456ec"],
    "all_devices": false,
    "parameters": {
        "duration": 60,
        "use_battery": true,
        "power": 5.6
    }
}

json

{
    "command": "buy",
    "command_id": "550e8400-e29b-41d4-a716-446655666112",
    "devices": ["1234-456ec"],
    "all_devices": false,
    "parameters": {
        "duration": 60,
        "use_battery": true,
        "power": 5.6
    }
}

json

{
    "command": "disableExport",
    "command_id": "550e8400-e29b-41d4-a716-446655666113",
    "devices": ["1234-456ec"],
    "all_devices": false,
    "parameters": {
        "duration": 60,
        "use_battery": true,
        "power": 5.6
    }
}

json

{
    "command": "buy",
    "command_id": "550e8400-e29b-41d4-a716-446655666114",
    "devices": ["1234-456ec"],
    "all_devices": false,
    "parameters": {
        "duration": 60,
        "appliances": ["boiler[0]","boiler[2]"],
        "power": 5.6
    }
}

List commands

This method allows authenticated traders to retrieve a paginated list of commands they have submitted, including command details, status information, and device command execution results.

Endpoint

Method: GET

http

https://api.synerwatt.eu/v1/traders/me/commands

cURLRaw body

cURL

curl -X GET "https://api.synerwatt.eu/v1/traders/me/commands?limit=10&offset=0&status=pending" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-auth-token" \
-H "Accept: */*"

json

/* empty body */

Headers

Header	Value	Required
Content-Type	application/json	Yes
Authorization	Bearer your-auth-token	Yes

Query Parameters

Parameter	Type	Required	Description	Example
limit	Number	No	Number of commands to return (max 1000)	10
offset	Number	No	Number of commands to skip	0
page	Number	No	Page number (alternative to offset)	1
per_page	Number	No	Commands per page (alternative to limit)	10
serial_number	String	No	Filter by device serial number	"1234-456ec"
reference_command_id	String	No	Filter by reference command ID	"cmd_12345"
command_id	String	No	Filter by primary command ID (UUID)	"550e8400-e29b-41d4-a716-446655440000"
status	String	No	Filter by device command status	"pending", "sent", "acknowledged", "success", "failed", "timeout", "cancelled"
command_type	String	No	Filter by command type	"dPlus1Schedule", "sell", "buy", "disableExport"
created_from	String	No	Filter commands created from date (ISO format)	"2025-01-01T00:00:00Z"
created_to	String	No	Filter commands created to date (ISO format)	"2025-01-31T23:59:59Z"

Response

🟢 200 OK🔴 401 Unauthorized

json

{
    "success": true,
    "message": "Commands retrieved successfully",
    "data": {
        "commands": [
            {
                "id": "fa5a9e12-2242-453e-b54d-d6f69fa762a2",
                "reference_command_id": "550e8400-e29b-41d4-a716-446655440000",
                "command_type": "dPlus1Schedule",
                "parameters": {
                    "execute_time": 1752012000,
                    "schedule": [
                        { "c": "s", "pw": 20.5 },
                        { "c": "b", "pw": 16.8 },
                        { "c": "e" }
                    ]
                },
                "all_devices": false,
                "trader_id": "f92a4c31-8d67-4b9e-a15f-3c49d8ae5290",
                "created_at": "2025-08-05T03:24:12.881Z",
                "updated_at": "2025-08-05T03:24:12.881Z",
                "trader_sub": "b47d9c2a-e183-4f95-8d36-9a42c5f0d8e4",
                "trader_username": "my.email@energytrader.sk",
                "trader_name": "Energy Trade s.r.o.",
                "device_commands": [
                    {
                        "id": "56ef7d4a-9b5a-462c-8d42-e415f46b8920",
                        "device_id": "c4d8e5f2-9a3b-47c1-8d6e-2f5a9b3c7d1e",
                        "device_serial_number": "1234-456ec",
                        "status": "acknowledged",
                        "mqtt_message_id": "msg_789",
                        "device_response": {
                            "result": "success",
                            "executed_at": "2025-08-05T03:25:30.123Z"
                        },
                        "sent_at": "2025-08-05T03:24:15.456Z",
                        "acknowledged_at": "2025-08-05T03:25:30.123Z",
                        "error_message": null,
                        "created_at": "2025-08-05T03:24:12.881Z",
                        "updated_at": "2025-08-05T03:25:30.123Z"
                    }
                ]
            }
        ],
        "pagination": {
            "page": 1,
            "limit": 10,
            "offset": 0,
            "total": 1,
            "pages": 1,
            "next": false,
            "prev": false
        }
    },
    "timestamp": "2025-08-05T03:27:28.615Z",
    "status_code": 200
}

json

{
    "success": false,
    "message": "Authentication required",
    "data": {
        "error": "UNAUTHORIZED",
        "error_description": "No valid token provided"
    },
    "timestamp": "2025-08-05T03:27:28.615Z",
    "status_code": 401
}

Notes

Pagination: The endpoint supports both limit/offset and page/per_page pagination patterns. If both are provided, page/per_page takes precedence.
Filtering: Multiple filters can be combined to narrow down results. All filters use AND logic.
Command Status: Each command contains an array of device_commands showing the execution status for each target device.
Device Command Status Values:
- pending - Command created but not yet sent to device
- sent - Command scheduled for processing on backend services
- acknowledged - Command sent do device via MQTT and waiting for response
- success - Command executed successfully on device
- failed - Command execution failed on device
- timeout - Device did not respond within expected timeframe
- cancelled - Command was cancelled before execution
Date Filtering: Use ISO 8601 format for created_from and created_to parameters.
Response Structure: Commands are returned in descending order by creation date (newest first).

Devices

List all devices

This method returns a paginated list of all devices associated with the authenticated user's account, including device details, status information, and location data.

Endpoint

Method: GET

http

https://api.synerwatt.eu/v1/traders/me/devices

cURLRaw body

cURL

curl -X GET "https://api.synerwatt.eu/v1/traders/me/devices" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-auth-token" \
-H "Accept: */*" \

json

/* empty body */

Headers

Header	Value	Required
Content-Type	application/json	Yes
Authorization	Bearer your-auth-token	Yes

Response

🟢 200 OK🔴 401 Unauthorized

json

{
    "success": true,
    "message": "Devices retrieved successfully",
    "data": {
        "devices": [
            {
                "id": "5b12141b-6bc2-4454-8f12-519b66545eb2",
                "serial_number": "b8a1f24b3c16",
                "device_type": "controller",
                "info": {
                    "name": "EC Test 2",
                    "model": "EC-v1-HWID0",
                    "firmware": "v0.10.4",
                    "contractual_flow": 9.9,
                    "main_circuit_breaker": 25,
                    "max_battery_capacity": 10,
                    "max_solar_production": 10
                },
                "status": null,
                "location": {
                    "address": ""
                },
                "created_at": "2025-08-13T10:43:14.700Z",
                "updated_at": "2025-08-13T10:43:14.700Z",
                "billing_point_id": "07f22375-dd12-4426-85ff-11fab0f514bc",
                "billing_point_code": "SKb8a1f24b3c16",
                "appliances": []
            },
            {
                "id": "7b23a91d-e4f5-42c8-b5d9-3a8e15f92c40",
                "serial_number": "a7d2f84b3c15",
                "device_type": "controller",
                "info": {
                    "name": "EC Test 1",
                    "port": 502,
                    "model": "EC-v1-HWID0",
                    "baudrate": 9600,
                    "firmware": "v0.10.4",
                    "slave_id": 1,
                    "phase_count": 1,
                    "inverter_type": "Solax",
                    "inverter_power": 3,
                    "contractual_flow": 3,
                    "main_circuit_breaker": 25,
                    "max_battery_capacity": 20,
                    "max_solar_production": 15
                },
                "status": null,
                "location": {
                    "address": "Test address 1"
                },
                "created_at": "2025-08-13T10:36:29.266Z",
                "updated_at": "2025-08-13T10:36:29.266Z",
                "billing_point_id": "b296bdb2-dcb0-445f-8eb7-131e3df1de71",
                "billing_point_code": "SKa7d2f84b3c15",
                "appliances": []
            },
            {
                "id": "7ba15f92-6766-4900-8fc1-ab9cc4596cf5",
                "serial_number": "b8c0d92c01fc",
                "device_type": "controller",
                "info": {
                    "name": "Boiler EC",
                    "port": 502,
                    "model": "EC-v1-HWID1",
                    "baudrate": 9600,
                    "firmware": "v0.10.5",
                    "slave_id": 1,
                    "use_wifi": false,
                    "wifi_ssid": "",
                    "ip_address": "",
                    "phase_count": null,
                    "inverter_type": "",
                    "wifi_password": "",
                    "inverter_power": null,
                    "connection_type": "",
                    "contractual_flow": null,
                    "is_master_device": false,
                    "parent_device_id": "25d1a6b5-2550-4506-b787-3ec37fcd86be",
                    "main_circuit_breaker": 25,
                    "max_battery_capacity": null,
                    "max_solar_production": null
                },
                "status": null,
                "location": {
                    "address": ""
                },
                "created_at": "2025-08-14T08:12:18.355Z",
                "updated_at": "2025-08-26T03:47:47.356Z",
                "billing_point_id": "302d79e7-14a0-498e-b942-df31307ae726",
                "billing_point_code": "",
                "appliances": [
                    {
                        "id": "6ee55eaa-109d-4ec0-a787-395f48deee7a",
                        "appliance_type": "boiler",
                        "name": "Main Boiler",
                        "info": {
                            "power": 1,
                            "volume": 80,
                            "temp_low": 35,
                            "temp_high": 50,
                            "temp_override": 70
                        },
                        "created_at": "2025-08-14T09:11:09.492Z",
                        "updated_at": "2025-08-21T11:36:19.925Z"
                    }
                ]
            }
        ],
        "pagination": {
            "page": 1,
            "limit": 100,
            "offset": 0,
            "total": 2,
            "pages": 1,
            "next": false,
            "prev": false
        }
    },
    "timestamp": "2025-06-10T00:01:09.758Z",
    "status_code": 200
}

json

{
    "success": false,
    "message": "Authentication required",
    "data": {
        "error": "UNAUTHORIZED",
        "error_description": "No token provided"
    },
    "timestamp": "2025-08-05T03:27:28.615Z",
    "status_code": 401
}

Notes

Device Appliances: Each device includes an appliances array containing connected appliances (boilers, wallboxes, ACUs, pool pumps).
Appliance Structure: Each appliance contains:
- id - Unique appliance identifier (UUID)
- appliance_type - Type of appliance (boiler, wallbox, acu, pool_pump)
- name - Human-readable appliance name
- info - Appliance-specific configuration parameters (power, volume, temperature settings, etc.)
- created_at / updated_at - Timestamps for appliance creation and modification
Empty Appliances: Devices without connected appliances will have an empty appliances: [] array.

Savings

Submit savings

This method allows authenticated users to submit energy savings data for specific devices and billing points. It supports both estimated and actual savings entries, enabling traders to report energy conservation achievements and financial benefits for their customers.

Endpoint

Method: POST

http

https://api.synerwatt.eu/v1/traders/me/savings

cURLRaw body

cURL

curl -X POST "https://api.synerwatt.eu/v1/traders/me/savings" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-auth-token" \
-H "Accept: */*" \
-d '{
  "savings": [
    {
      "calculation_method": "estimate",
      "date": "2025-06-01",
      "serial_number": "1234-456ec",
      "billing_point_code": "CZ-123ABC",
      "amount": 20.5,
      "currency": "CZK"
    },
    {
      "calculation_method": "actual",
      "date": "2025-06-01",
      "serial_number": "1234-456ec",
      "billing_point_code": "CZ-123ABC",
      "amount": 15.2,
      "currency": "CZK"
    }
  ]
}
'

json

{
  "savings": [
    {
      "calculation_method": "estimate",
      "date": "2025-06-01",
      "serial_number": "1234-456ec",
      "billing_point_code": "CZ-123ABC",
      "amount": 20.5,
      "currency": "CZK"
    },
    {
      "calculation_method": "actual",
      "date": "2025-06-01",
      "serial_number": "1234-456ec",
      "billing_point_code": "CZ-123ABC",
      "amount": 15.2,
      "currency": "CZK"
    }
  ]
}

Headers

Header	Value	Required
Content-Type	application/json	Yes
Authorization	Bearer your-auth-token	Yes

Request Body

Field	Type	Required	Description	Example
calculation_method	String	Yes	Type of the savings	"estimate","actual"
date	String	Yes	Date of the savings	"2025-06-10"
serial_number	String	Yes	Serial number of the device	"1234-456ec"
billing_point_code	String	No	Billing point code / EAN	"EAN123CZ"
amount	Number	Yes	Amount of the savings	20
currency	String	Yes	Currency of the savings	"CZK"

Response

🟢 200 OK🔴 400 Bad request🔴 401 Unauthorized

json

{
    "success": true,
    "message": "Bulk savings created successfully",
    "data": {
        "processed_ount": 2,
        "created_count": 0,
        "updated_count": 2,
        "entries": [
            {
                "id": "4e89a39a-6557-4844-a3f2-817aa3a5e210",
                "serial_number": "1234-456ec",
                "billing_point_code": "CZ-123ABC",
                "date": "2025-06-01",
                "amount": 20.5,
                "currency": "CZK",
                "calculation_method": "estimate",
                "operation": "updated",
                "account_id": "c8627508-e0ed-4447-95da-8e97046e9b75"
            },
            {
                "id": "001d8b8f-ad56-4a24-9f6b-083dc2608189",
                "serial_number": "1234-456ec",
                "billing_point_code": "CZ-123ABC",
                "date": "2025-06-01",
                "amount": 15.2,
                "currency": "CZK",
                "calculation_method": "actual",
                "operation": "updated",
                "account_id": "c8627508-e0ed-4447-95da-8e97046e9b75"
            }
        ]
    },
    "timestamp": "2025-08-08T04:11:16.560Z",
    "status_code": 200
}

json

{
    "success": false,
    "message": "Invalid ownership: Devices not found or not properly associated",
    "data": {
        "error": "INVALID_DEVICE_OWNERSHIP",
        "invalid_devices": ["fake-device-serial-number"]
    },
    "timestamp": "2025-08-05T03:27:28.615Z",
    "status_code": 400
}

json

{
    "success": false,
    "message": "Authentication required",
    "data": {
        "error": "UNAUTHORIZED",
        "error_description": "No token provided"
    },
    "timestamp": "2025-08-05T03:27:28.615Z",
    "status_code": 401
}

Notes

The type field specifies the savings entry type: "estimate" for projected savings, "actual" for confirmed savings after measurement.
The savings_date field must be in ISO date format "YYYY-MM-DD" representing the date when savings occurred.
The time_slot field represents the specific time slot (0-4) when the savings occurred during the specified date. Use 0 for daily savings.
The device_sn field identifies the IoT gateway device that generated or measured the savings.
The billing_point_code field is optional but recommended to associate savings with a specific customer's EAN code.
The amount field represents the monetary savings value in the specified currency.
Supported currencies include major European currencies (CZK, EUR, etc.). Contact support for additional currency support.

KASI Provider Implementation Notice

The following KASI API service descriptions serve as implementation suggestions for our KASI provider to facilitate cooperation and integration between our systems. These specifications are provided as a reference framework to help establish a common understanding of the expected functionality and data exchange patterns.

Important considerations:

The actual implementation may differ significantly based on the KASI provider's technical infrastructure, business requirements, and preferred implementation methods
Endpoint URLs, request/response formats, authentication mechanisms, and data structures are subject to the provider's internal standards and capabilities
These specifications should be used as a starting point for discussions and negotiations with the KASI provider
Final implementation details must be agreed upon through direct communication and technical coordination with the chosen KASI provider

Please consult with your KASI provider to determine the final API specifications and implementation approach.

KASI Authorization

KASI Service authentication

This method offers an authentication mechanism tailored for third-party services and integrations. It utilizes the client_credentials grant, which requires a client_id and client_secret.

Endpoint

Method: POST

http

https://kasi-provider-domain.cz/api/v1/auth/token

cURLRaw body

cURL

curl -X POST "https://kasi-provider-domain.cz/api/v1/auth/token" \
-H "Content-Type: application/json" \
-H "Accept: */*" \
-d '{
  "client_id": "some-client-id",
  "client_secret": "some-passphrase"
}'

json

{
  "client_id": "some-client-id",
  "client_secret": "some-passphrase"
}

Headers

Header	Value	Required
Content-Type	application/json	Yes

Request Body

Field	Type	Required	Description	Example
client_id	String	Yes	Client ID	some-client-id
client_secret	String	Yes	Secret passphrase	some-passphrase

Response

🟢 200 OK🔴 401 Unauthorized

json

{
    "success": true,
    "message": "KASI authentication successful",
    "data": {
        "token": "eyJhbGciOiJSUzI1NiIs...",
        "type": "Bearer"
    },
    "timestamp": "2025-08-05T03:27:28.615Z",
    "status_code": 200
}

json

{
    "success": false,
    "message": "Authentication Failed",
    "data": {
        "error": "INVALID_GRANT",
        "error_description": "Invalid client credentials"
    },
    "timestamp": "2025-08-05T03:27:28.615Z",
    "status_code": 401
}

Notes

Response token is used for authentication in other requests. It contains basic client information and authorization claims.

KASI EAN Management

KASI EAN

This method retrieves detailed information about a specific EAN (billing point), including associated device data, customer information, and location details. This endpoint serves as the primary way to access combined device and customer data using the billing point code as the main identifier.

Endpoint

Method: GET

http

https://kasi-provider-domain.cz/api/v1/ean/{id}

cURLRaw body

cURL

curl -X GET "https://kasi-provider-domain.cz/api/v1/ean/EAN123CZ" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-auth-token" \
-H "Accept: */*" \

json

/* empty body */

Headers

Header	Value	Required
Content-Type	application/json	Yes
Authorization	Bearer your-auth-token	Yes

Path Parameters

Parameter	Type	Required	Description	Example
id	String	Yes	EAN code / Billing point code	EAN123CZ

Response

🟢 200 OK🔴 404 Not Found

json

{
    "success": true,
    "message": "EAN details retrieved successfully",
    "data": {
        "billing_point_code": "EAN123CZ",
        "billing_point_id": "61c332d4-77b4-4b6d-b5c6-ef51fcd00303",
        "customer": {
            "id": "c8627508-e0ed-4447-95da-8e97046e9b75",
            "account_type": "customer",
            "name": "Adéla Horák",
            "created_at": "2025-05-13T20:20:25.398Z",
            "updated_at": "2025-05-13T20:20:25.398Z",
            "info": {}
        },
        "device": {
            "id": "53e1987b-2869-4837-89ea-79cba7d82c8d",
            "serial_number": "1234-456ec",
            "device_type": "controller",
            "info": {
                "model": "IS SEC IoT Gateway",
                "firmware": "1.0.0"
            },
            "status": {},
            "location": {
                "address": "Skořepka 336/15, 602 00 Brno-střed, Česko",
                "coordinates": [
                    49.1925,
                    16.1833
                ]
            },
            "created_at": "2025-05-13T20:25:14.821Z",
            "updated_at": "2025-05-13T20:25:14.821Z"
        }
    },
    "timestamp": "2025-01-20T10:30:00.000Z",
    "status_code": 200
}

json

{
    "success": false,
    "message": "EAN not found",
    "data": {
        "error": "NOT_FOUND",
        "error_description": "EAN code does not exist or is not accessible"
    },
    "timestamp": "2025-01-20T10:30:00.000Z",
    "status_code": 404
}

Notes

The endpoint returns combined information from both device and customer data associated with the specified EAN code.
The billing_point_code serves as the primary identifier in the KASI service.
Device information includes serial number, type, firmware details, status, and location data.
Customer information includes account details, name, and creation timestamps.
If no device or customer is associated with the EAN, those sections may be null or empty.

KASI EAN Update

This method allows updating information associated with a specific EAN (billing point), including customer details and device configuration. This endpoint enables synchronization of changes from the IS API service to the KASI service.

Endpoint

Method: PATCH

http

https://kasi-provider-domain.cz/api/v1/ean/{id}

cURLRaw body

cURL

curl -X PATCH "https://kasi-provider-domain.cz/api/v1/ean/EAN123CZ" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-auth-token" \
-H "Accept: */*" \
-d '{
    "customer": {
        "name": "Adéla Horáková",
        "info": {
            "phone": "+420 123 456 789"
        }
    },
    "device": {
        "info": {
            "firmware": "1.1.0"
        },
        "status": {
            "last_seen": "2025-01-20T10:25:00.000Z",
            "connection_status": "online"
        },
        "location": {
            "address": "Skořepka 336/15, 602 00 Brno-střed, Česko",
            "coordinates": [49.1925, 16.1833]
        }
    }
}'

json

{
    "customer": {
        "name": "Adéla Horáková",
        "info": {
            "phone": "+420 123 456 789"
        }
    },
    "device": {
        "info": {
            "firmware": "1.1.0"
        },
        "status": {
            "last_seen": "2025-01-20T10:25:00.000Z",
            "connection_status": "online"
        },
        "location": {
            "address": "Skořepka 336/15, 602 00 Brno-střed, Česko",
            "coordinates": [49.1925, 16.1833]
        }
    }
}

Headers

Header	Value	Required
Content-Type	application/json	Yes
Authorization	Bearer your-auth-token	Yes

Path Parameters

Parameter	Type	Required	Description	Example
id	String	Yes	EAN code / Billing point code	EAN123CZ

Request Body

Field	Type	Required	Description	Example
customer	Object	No	Customer information updates	See customer fields below
customer.name	String	No	Customer name	"Adéla Horáková"
customer.info	Object	No	Additional customer information	"phone": "+420 123 456 789"
device	Object	No	Device information updates	See device fields below
device.info	Object	No	Device metadata (model, firmware, etc.)	"firmware": "1.1.0"
device.status	Object	No	Device status information	"connection_status": "online"
device.location	Object	No	Device location data	"address": "...", "coordinates": [...]

Response

🟢 200 OK🔴 404 Not Found🔴 400 Bad Request

json

{
    "success": true,
    "message": "EAN updated successfully",
    "data": {
        "billing_point_code": "EAN123CZ",
        "billing_point_id": "61c332d4-77b4-4b6d-b5c6-ef51fcd00303",
        "customer": {
            "id": "c8627508-e0ed-4447-95da-8e97046e9b75",
            "account_type": "customer",
            "name": "Adéla Horáková",
            "created_at": "2025-05-13T20:20:25.398Z",
            "updated_at": "2025-01-20T10:30:00.000Z",
            "info": {
                "phone": "+420 123 456 789"
            }
        },
        "device": {
            "id": "53e1987b-2869-4837-89ea-79cba7d82c8d",
            "serial_number": "e43f0690a994",
            "device_type": "controller",
            "info": {
                "model": "IS SEC IoT Gateway",
                "firmware": "1.1.0"
            },
            "status": {
                "last_seen": "2025-01-20T10:25:00.000Z",
                "connection_status": "online"
            },
            "location": {
                "address": "Skořepka 336/15, 602 00 Brno-střed, Česko",
                "coordinates": [
                    49.1925,
                    16.1833
                ]
            },
            "created_at": "2025-05-13T20:25:14.821Z",
            "updated_at": "2025-01-20T10:30:00.000Z"
        }
    },
    "timestamp": "2025-01-20T10:30:00.000Z",
    "status_code": 200
}

json

{
    "success": false,
    "message": "EAN not found",
    "data": {
        "error": "NOT_FOUND",
        "error_description": "EAN code does not exist or is not accessible"
    },
    "timestamp": "2025-01-20T10:30:00.000Z",
    "status_code": 404
}

json

{
    "success": false,
    "message": "Invalid update data",
    "data": {
        "error": "VALIDATION_ERROR",
        "error_description": "Invalid field format or value"
    },
    "timestamp": "2025-01-20T10:30:00.000Z",
    "status_code": 400
}

Notes

This endpoint supports partial updates - only provided fields will be updated.
The customer and device objects are optional; you can update either or both.
Nested objects like device.info, device.status, and device.location support partial updates as well.
The response returns the complete updated EAN data including both customer and device information.
The updated_at timestamps are automatically updated for modified entities.
This endpoint is primarily used for synchronization from the IS API service to maintain data consistency.

API endpoints ​

Basic info ​

IS API service ​

KASI API service ​

Authorization ​

Signin user ​

Service authentication ​

Signout ​

Refresh ​

Accounts ​

My account details ​

Commands ​

Submit command ​

List commands ​

Devices ​

List all devices ​

Savings ​

Submit savings ​

KASI Authorization ​

KASI Service authentication ​

KASI EAN Management ​

KASI EAN ​

KASI EAN Update ​

API endpoints

Basic info

IS API service

KASI API service

Authorization

Signin user

Service authentication

Signout

Refresh

Accounts

My account details

Commands

Submit command

List commands

Devices

List all devices

Savings

Submit savings

KASI Authorization

KASI Service authentication

KASI EAN Management

KASI EAN

KASI EAN Update