API endpoints

Basic info

IS API service

Base URL

https://synerwatt.com

List of all endpoints for Synerwatt API service

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

KASI API service

Base URL

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/telemetry	POST	Submit telemetry
/api/v1/ean/{id}	GET	EAN details
/api/v1/ean/{id}	PATCH	EAN update
/api/v1/ean/{id}/savings	GET	EAN savings

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

Signin user

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

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

cURL

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

Raw body

{
  "username": "test-user",
  "password": "p4ssw0rd",
  "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	p4ssw0rd
remember	Boolean	No	Remember	true

Response

🟢 200 OK

{
    "token": "eyJhbGciOiJSUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "rpt": "eyJhbGciOiJSUzI1NiIs...",
    "type": "Bearer"
}

🔴 401 Unauthorized

{
    "type": "https://sso.synerwatt.com/problems/authentication-error",
    "title": "Authentication Failed",
    "statusCode": 401,
    "detail": {
        "error": "invalid_grant",
        "error_description": "Invalid user credentials"
    },
    "instance": "/auth/signin"
}

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 refreshToken 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

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

cURL

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

Raw body

{
  "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

{
    "token": "eyJhbGciOiJSUzI1NiIs...",
    "type": "Bearer"
}

🔴 401 Unauthorized

{
    "type": "https://sso.synerwatt.com/problems/authentication-error",
    "title": "Authentication Failed",
    "statusCode": 401,
    "detail": {
        "error": "invalid_grant",
        "error_description": "Invalid client credentials"
    },
    "instance": "/auth/token"
}

Notes

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

Signout

This method allows users 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

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

cURL

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

Raw body

/* empty body */

Headers

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

Response

🟢 200 OK

{
    "title": "Signout successful",
    "statusCode": 200,
    "detail": {
        "message": "Token successfully revoked."
    }
}

🟢 200 OK - Soft sign out

/* Cookies cleared without a token revocation */
{
    "title": "Signout successful",
    "statusCode": 200,
    "detail": {
        "error": "invalid_token",
        "error_description": "Invalid token"
    }
}

🔴 400 Bad request

{
    "type": "https://sso.synerwatt.com/problems/authentication-error",
    "title": "Authentication Failed",
    "statusCode": 400,
    "detail": {
        "error": "invalid_request",
        "error_description": "Token not provided"
    },
    "instance": "/auth/signout"
}

Refresh

This method enables users 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

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

cURL

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

Raw body

/* empty body */

Headers

Header	Value	Required
Content-Type	application/json	Yes

Response

🟢 200 OK

{
    "token": "eyJhbGciOiJSUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "rpt": "eyJhbGciOiJSUzI1NiIs...",
    "type": "Bearer"
}

🔴 400 Bad request

{
    "type": "https://sso.synerwatt.com/problems/authentication-error",
    "title": "Token refresh failed",
    "statusCode": 400,
    "detail": {
        "error": "invalid_grant",
        "error_description": "Invalid refresh token"
    },
    "instance": "/auth/refresh"
}

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

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

cURL

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

Raw body

/* empty body */

Headers

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

Response

🟢 200 OK

{
    "success": true,
    "message": "Account retrieved successfully",
    "data": {
        "id": "c8627508-e0ed-4447-95da-8e97046e9b75",
        "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": "af1383ec-b9d5-4d16-941d-1636f14bdf19",
        "info": null
    },
    "timestamp": "2025-06-09T22:55:10.552Z",
    "statusCode": 200
}

🔴 401 Unauthorized

{
    "type": "https://api.synerwatt.com/problems/authentication-error",
    "title": "Authentication Failed",
    "statusCode": 401,
    "detail": {
        "error": "Unauthorized",
        "error_description": "No token provided"
    },
    "instance": "/v1/accounts/me"
}

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

https://api.synerwatt.com/v1/devices

cURL

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

Raw body

/* empty body */

Headers

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

Response

🟢 200 OK

{
    "success": true,
    "message": "Devices retrieved successfully",
    "data": {
        "devices": [
            {
                "id": "53e1987b-2869-4837-89ea-79cba7d82c8d",
                "serial_number": "e43f0690a994",
                "device_type": "gateway",
                "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",
                "billing_point_id": "61c332d4-77b4-4b6d-b5c6-ef51fcd00303",
                "billing_point_code": "CZ-567DEF"
            },
            {
                "id": "7535e02a-79aa-4065-b661-fc2850a54de0",
                "serial_number": "f07e6695b3f1021e",
                "device_type": "gateway",
                "info": {
                    "model": "IS SEC IoT Gateway",
                    "firmware": "1.0.0"
                },
                "status": {
                },
                "location": {
                    "address": "Štefánikovo Nám. 1, 301 33 Plzeň 3, Česko",
                    "coordinates": [
                        49.742,
                        13.3733
                    ]
                },
                "created_at": "2025-05-13T20:24:43.089Z",
                "updated_at": "2025-05-13T20:24:43.089Z",
                "billing_point_id": "8085f471-4dac-409f-9015-584f2c615f62",
                "billing_point_code": "CZ-123ABC"
            }
        ],
        "pagination": {
            "page": 1,
            "limit": 100,
            "offset": 0,
            "total": 2,
            "totalPages": 1,
            "hasNext": false,
            "hasPrev": false
        }
    },
    "timestamp": "2025-06-10T00:01:09.758Z",
    "statusCode": 200
}

🔴 401 Unauthorized

{
    "type": "https://api.synerwatt.com/problems/authentication-error",
    "title": "Authentication Failed",
    "statusCode": 401,
    "detail": {
        "error": "Unauthorized",
        "error_description": "No token provided"
    },
    "instance": "/v1/devices"
}

Customers

List all customers

This method provides a paginated list of all customers associated with the authenticated user's account, including customer information and their associated billing point codes.

Endpoint

Method: GET

https://api.synerwatt.com/v1/customers

cURL

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

Raw body

/* empty body */

Headers

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

Response

🟢 200 OK

{
    "success": true,
    "message": "Customers retrieved successfully",
    "data": {
        "customers": [
            {
              "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",
              "billing_points_codes": ["EAN123CZ"]
              "info": {}
            },
            {
              "id": "c8627508-e0ed-4447-95da-8e97046e9b76",
              "account_type": "customer",
              "name": "Niklas Weber",
              "created_at": "2025-05-13T20:20:25.398Z",
              "updated_at": "2025-05-13T20:20:25.398Z",
              "billing_points_codes": ["EAN456CZ","EAN111CZ"]
              "info": {}
            },

        ],
        "pagination": {
            "page": 1,
            "limit": 100,
            "offset": 0,
            "total": 2,
            "totalPages": 1,
            "hasNext": false,
            "hasPrev": false
        }
    },
    "timestamp": "2025-06-10T00:01:09.758Z",
    "statusCode": 200
}

🔴 401 Unauthorized

{
    "type": "https://api.synerwatt.com/problems/authentication-error",
    "title": "Authentication Failed",
    "statusCode": 401,
    "detail": {
        "error": "Unauthorized",
        "error_description": "No token provided"
    },
    "instance": "/v1/customers"
}

Commands

Submit command

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

Endpoint

Method: POST

https://api.synerwatt.com/v1/commands

cURL

curl -X POST "https://api.synerwatt.com/v1/commands" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-auth-token" \
-H "Accept: */*" \
-d '{
  "command_type": "sell",
  "command_id": "550e8400-e29b-41d4-a716-446655440000",
  "command_expires_at": 1748862696,
  "device_sn": "1234-456ec",
  "billing_point_code": "EAN123CZ",
  "parameters": {
    "use_battery": true,
    "power": 5.6
  }
}
'

Raw body

{
  "command_type": "sell",
  "command_id": "550e8400-e29b-41d4-a716-446655440000",
  "command_expires_at": 1748862696,
  "device_sn": "1234-456ec",
  "billing_point_code": "EAN123CZ",
  "parameters": {
    "use_battery": true,
    "power": 5.6
  }
}

Headers

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

Request Body

Field	Type	Required	Description	Example
command_type	String	Yes	Type of the command	"sell"
command_id	String	No	Reference identifier for the command	"cmd_12345"
command_expires_at	Number	Yes	Unix timestamp when command expires	1748862696
device_sn	String	Yes	Serial number of the device	"1234-456ec"
billing_point_code	String	No	Billing point code / EAN	"EAN123CZ"
parameters	Object	No	Command parameters (varies by action)	"use_battery": true, "power": 5.6

Response

🟢 200 OK

{
    "success": true,
    "message": "Command submitted successfully",
    "request": {
        "command_type": "sell",
        "command_id": "550e8400-e29b-41d4-a716-446655440000",
        "command_expires_at": 1748862696,
        "device_sn": "1234-456ec",
        "billing_point_code": "EAN123CZ",
        "parameters": {
            "use_battery": true,
            "power": 5.6
        }
    },
    "timestamp": "2025-06-09T22:55:10.552Z",
    "statusCode": 200
}

🔴 401 Unauthorized

{
    "type": "https://api.synerwatt.com/problems/authentication-error",
    "title": "Authentication Failed",
    "statusCode": 401,
    "detail": {
        "error": "Unauthorized",
        "error_description": "No token provided"
    },
    "instance": "/v1/commands"
}

Notes

• Commands are executed asynchronously for the target devices. The API accepts the command and returns a success response, but actual execution may take time.
• The command_id is optional but recommended to identify the original command for better tracking.
• The command_expires_at field is a Unix timestamp indicating the command expiration time.
• The parameters object structure depends on the action type
• The billing_point_code is optional but recommended to specify the billing point code / EAN to identify the customer.

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

https://api.synerwatt.com/v1/savings

cURL

curl -X POST "https://api.synerwatt.com/v1/savings" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-auth-token" \
-H "Accept: */*" \
-d '{
    "type": "estimate",
    "savings_date": "2025-06-10",
    "time_slot": 0,
    "device_sn": "1234-456ec",
    "billing_point_code": "EAN123CZ",
    "amount": 20,
    "currency": "CZK"
}
'

Raw body

{
    "type": "estimate",
    "savings_date": "2025-06-10",
    "time_slot": 0,
    "device_sn": "1234-456ec",
    "billing_point_code": "EAN123CZ",
    "amount": 20,
    "currency": "CZK"
}

Headers

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

Request Body

Field	Type	Required	Description	Example
type	String	Yes	Type of the savings	"estimate"
savings_date	String	Yes	Date of the savings	"2025-06-10"
time_slot	Number	Yes	Time slot of the savings	0
device_sn	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

{
    "success": true,
    "message": "Savings submitted successfully",
    "request": {
        "type": "estimate",
        "savings_date": "2025-06-10",
        "time_slot": 0,
        "device_sn": "1234-456ec",
        "billing_point_code": "EAN123CZ",
        "amount": 20,
        "currency": "CZK"
    },
    "timestamp": "2025-06-09T22:55:10.552Z",
    "statusCode": 200
}

🔴 401 Unauthorized

{
    "type": "https://api.synerwatt.com/problems/authentication-error",
    "title": "Authentication Failed",
    "statusCode": 401,
    "detail": {
        "error": "Unauthorized",
        "error_description": "No token provided"
    },
    "instance": "/v1/savings"
}

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

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

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"
}'

Raw body

{
  "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

{
    "token": "eyJhbGciOiJSUzI1NiIs...",
    "type": "Bearer"
}

🔴 401 Unauthorized

{
    "type": "https://sso.synerwatt.com/problems/authentication-error",
    "title": "Authentication Failed",
    "statusCode": 401,
    "detail": {
        "error": "invalid_grant",
        "error_description": "Invalid client credentials"
    },
    "instance": "/auth/token"
}

Notes

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

KASI telemetry

KASI Submit telemetry

This method allows client to submit telemetry data including power measurements, battery status, and inverter state information. It accepts real-time energy data from IoT devices for monitoring and analysis purposes.

Endpoint

Method: POST

https://kasi-provider-domain.cz/api/v1/telemetry

cURL

curl -X POST "https://kasi-provider-domain.cz/api/v1/telemetry" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-auth-token" \
-H "Accept: */*" \
-d '{
  "sn": "1b2a34",
  "ts": 1748862696,
  "quality": 0,
  "d": {
    "is": "normal",
    "pp": "number",
    "gp": "number",
    "bp": "number",
    "cp": "number",
    "bs": "number",
    "gn": "number",
    "up": "number"
  }
}'

Raw body

{
  "sn": "string",           // Required: Unique device identifier
  "ts": "number",           // Required: Unix timestamp (seconds)
  "quality": 0,             // ?
  "d": {                    // Required: Data section
    "is": "string",         // Required: Inverter state
    "pp": "254.0",          // Required: Production power (W)
    "gp": "55.2",           // Required: Grid power (W)
    "bp": "654.5",          // Required: Battery power (W)
    "cp": "92.2",           // Required: Consumption power (W)
    "bs": "75",             // Required: Battery SoC (%)
    "gn": "21.1",           // Required: Generator power (W)
    "up": "0.0"             // Required: UPS power (W)
  }
}

Headers

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

Request Body

Field	Type	Required	Description	Example
sn	String	Yes	Unique device identifier (serial number)	"1b2a34"
ts	Number	Yes	Unix timestamp in seconds	1748862696
quality	Number	No	Data quality indicator	0
d	Object	Yes	Data payload containing measurements	See data fields below
d.is	String	Yes	Inverter state	"normal"
d.pp	String	Yes	Production power in watts	"254.0"
d.gp	String	Yes	Grid power in watts	"55.2"
d.bp	String	Yes	Battery power in watts	"654.5"
d.cp	String	Yes	Consumption power in watts	"92.2"
d.bs	String	Yes	Battery State of Charge (%)	"75"
d.gn	String	Yes	Generator power in watts	"21.1"
d.up	String	Yes	UPS power in watts	"0.0"

Response

🟢 200 OK

{
    "success": true,
    "message": "Telemetry data received successfully",
    "timestamp": "2025-01-20T10:30:00.000Z",
    "statusCode": 200
}

KASI savings

KASI EAN Savings

This method retrieves energy savings data for a specific EAN (billing point). It returns a list of savings entries including both estimated and actual savings with their corresponding time slots, amounts, and associated device information. This is an alternative to the IS API savings endpoint. Data is pulled from the KASI API service instead of being pushed to the IS API service.

Endpoint

Method: GET

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

cURL

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

Raw body

/* 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

{
    "success": true,
    "message": "EAN savings retrieved successfully",
    "data": [
        {
            "type": "estimate",
            "savings_date": "2025-06-10",
            "time_slot": 0,
            "device_sn": "1234-456ec",
            "billing_point_code": "EAN123CZ",
            "amount": 20,
            "currency": "CZK"
        },
        {
            "type": "actual",
            "savings_date": "2025-06-09",
            "time_slot": 2,
            "device_sn": "1234-456ec",
            "billing_point_code": "EAN123CZ",
            "amount": 18.5,
            "currency": "CZK"
        },
        {
            "type": "estimate",
            "savings_date": "2025-06-08",
            "time_slot": 1,
            "device_sn": "1234-456ec",
            "billing_point_code": "EAN123CZ",
            "amount": 25.2,
            "currency": "CZK"
        }
    ],
    "timestamp": "2025-01-20T10:30:00.000Z",
    "statusCode": 200
}

Notes

• The type field indicates the savings entry type: "estimate" for projected savings, "actual" for confirmed savings after measurement.
• The savings_date field is 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 amount field represents the monetary savings value in the specified currency.
• Results are typically ordered by date descending (most recent first).

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

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

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: */*" \

Raw body

/* 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

{
    "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": "e43f0690a994",
            "device_type": "gateway",
            "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",
    "statusCode": 200
}

🔴 404 Not Found

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

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

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

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]
        }
    }
}'

Raw body

{
    "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

{
    "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": "gateway",
            "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",
    "statusCode": 200
}

🔴 404 Not Found

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

🔴 400 Bad Request

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

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.