Skip to content

Latest commit

 

History

History
395 lines (375 loc) · 11.5 KB

README.md

File metadata and controls

395 lines (375 loc) · 11.5 KB
Raw

Wallbox.com API

How to interact with the API?

In this document, i will give you a short overview, how to proceed.

Please note:
This procedure only works, if you have registered an account at wallbox.com with your own email address. Google SSO (Single-Sign-on) will not work!

Basic informations

/* Basic Variables used */
let password = 'YourPassword';
let email = '[email protected]';
let charger_id = 'idOfTheCharger';
let wallbox_token = '';
let conn_timeout = 3000;

const BASEURL = 'https://api.wall-box.com/';
const URL_AUTHENTICATION = 'auth/token/user';
const URL_CHARGER = 'v2/charger/';
const URL_CHARGER_CONTROL = 'v3/chargers/';
const URL_CHARGER_MODES = 'v4/chargers/';
const URL_CHARGER_ACTION = '/remote-action';
const URL_STATUS = 'chargers/status/';
const URL_CONFIG = 'chargers/config/';
const URL_REMOTE_ACTION = '/remote-action/';
const URL_ECO_SMART = '/eco-smart/';

Token

For every request to the Wallbox.com API you need a request token. With this token, you can control the Wallbox or request data from it.

/* Send a POST request to the API */
const options = {
    url: BASEURL + URL_AUTHENTICATION,
    timeout: conn_timeout,
    method: 'POST',
    headers: {
        'Authorization': 'Basic ' + Buffer.from(email + ":" + password).toString('base64'),
        'Accept': 'application/json, text/plain, */*',
        'Content-Type': 'application/json;charset=utf-8',
    }
};

The token will be returned in jwt Block of the return from the server. Create the function, to store this token inside a variable. E.g. wallbox_token as mentioned above.

With the new received token, which is valid for around 60 seconds, you can now control the Wallbox.

Control the Wallbox

/* Send a PUT request to the API */
const options = {
    url: BASEURL + URL_CHARGER + charger_id,
    timeout: conn_timeout,
    method: 'PUT',
    headers: {
        'Authorization': 'Bearer ' + wallbox_token,
        'Accept': 'application/json, text/plain, */*',
        'Content-Type': 'application/json;charset=utf-8',
    },
    data: JSON.stringify({
        [key]: value
    })
}

Variables for key and value

Key Value Explanation
locked 0 or 1 Unlock/Lock the Wallbox
maxChargingCurrent 6 to 32 Set the current charge speed

Alternative with configs:

/* Send a POST request to the API */
const options = {
    url: BASEURL + URL_CONFIG + charger_id,
    timeout: conn_timeout,
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + wallbox_token,
        'Accept': 'application/json, text/plain, */*',
        'Content-Type': 'application/json;charset=utf-8',
    },
    data: JSON.stringify({
        [key_1]: value,
        [key_2]: value
    })
}

Variables for key and value

Key 1 Value Explanation Key 2 Value Explanation
energy_price float number price per kWh currency_id idx 1 to n Optional the currency index, 1 for euro
max_charging_current 6 to 32 Set the current charge speed NO KEY2
home_sharing 0 or 1 disable or enable power boost icp_max_current 1 to 64 or -1 to -64 set the max power per phase use positive if home_sharing is 1 , negative if 0 
/* Send a POST request to the API */
const options = {
    url: BASEURL + URL_CHARGER_CONTROL + charger_id + URL_REMOTE_ACTION,
    timeout: conn_timeout,
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + wallbox_token,
        'Accept': 'application/json, text/plain, */*',
        'Content-Type': 'application/json;charset=utf-8',
    },
    body: JSON.stringify({
        'action': value
    })
}

Variables for action value

Value Explanation
1 Resume - Mode
2 Pause - Mode
3 Reboot the Wallbox
4 Factory - Rest the Wallbox. ! Be careful !
5 Install Software Update if available
9 After a manual stop: resume schedule and ecosmart mode

Control Wallbox Modes

/* Send a PUT request to the API */
const options = {
    url: BASEURL + URL_CHARGER_MODES + charger_id + URL_ECO_SMART,
    timeout: conn_timeout,
    method: 'PUT',
    headers: {
        'Authorization': 'Bearer ' + wallbox_token,
        'Accept': 'application/json, text/plain, */*',
        'Content-Type': 'application/json;charset=utf-8',
    },
    data: JSON.stringify({
        "data" : {
             "attributes": {
                    "percentage": 100,
                    "enabled": 0,
                     "mode": 0
            },
            "type": "eco_smart"
        }
    })
}
Key Value Explanation
enabled 0 or 1 enable or disable eco smart
mode 0 or 1 0 is Eco Mode, 1 is Full Green

Receive Data from the Wallbox - API

There are 2 information adresses, which provide informations. One is "basic" information about the Wallbox itself and some diagnosis. The other one - i call it "extended", delivers informations about about charging and past sessions.

Basic information

/* Send a PUT request to the API */
const options = {
    url: BASEURL + URL_CHARGER + charger_id,
    timeout: conn_timeout,
    method: 'PUT',
    headers: {
        'Authorization': 'Bearer ' + token,
        'Accept': 'application/json, text/plain, */*',
        'Content-Type': 'application/json;charset=utf-8',
    }
}

You will receive a json, with basic informations and the current state of the Wallbox inside status.

{
    "data": {
        "chargerData": {
            "id": 00000,
            "uid": "xyz",
            "uniqueIdentifier": "wsUnanQQ",
            "serialNumber": "xxwweerrr",
            "name": "PulsarPlus SN 00000",
            "group": 289814,
            "groupUid": "xyz",
            "chargerType": "PulsarPlus",
            "softwareVersion": "5.17.59",
            "softwareUpdatedAt": 1689715588,
            "status": 210,
            "ocppConnectionStatus": 4,
            "ocppReady": "ocpp_1.6j",
            "stateOfCharge": null,
            "maxChgCurrent": null,
            "maxAvailableCurrent": 32,
            "maxChargingCurrent": 32,
            "locked": 1,
            "lastConnection": 1692341408,
            "lastSync": {
                "date": "2023-08-17 20:01:46.000000",
                "timezone_type": 3,
                "timezone": "UTC"
            },
            ...
            "resume": {
                "totalUsers": 1,
                ...
            }
        },
        "users": [
            {
                "id": 286113,
                ...
            }
        ]
    }
}

Extended Information

/* Send a GET request to the API */
const options = {
    url: BASEURL + URL_STATUS + charger_id,
    timeout: conn_timeout,
    method: 'GET',
    headers: {
        'Authorization': 'Bearer ' + token,
        'Accept': 'application/json, text/plain, */*',
        'Content-Type': 'application/json;charset=utf-8',
    }
}

You will receive a json, with extended and more informations, which is around 200 lines long. The most interesting JSON property here would be charging_power and status_id - explained below.

{
    "user_id": 286113,
    "user_name": "Stephan",
    "car_id": 1,
    "car_plate": "",
    "depot_price": 0.2,
    "last_sync": "2023-08-18 06:50:26",
    "power_sharing_status": 0,
    "mid_status": 1,
    "status_id": 210,
    "name": "PulsarPlus SN 9988552",
    "charging_power": 0,
    "max_available_power": 32,
    "depot_name": "Kreyenborg.koeln",
    "charging_speed": 0,
    "added_range": 4,
    "added_energy": 0.546,
    "added_green_energy": 0,
    "added_discharged_energy": 0,
    "added_grid_energy": 0,
    "charging_time": 585,
    "finished": true,
    "cost": 0,
    "current_mode": 3,
    "preventive_discharge": false,
    "state_of_charge": null,
    "ocpp_status": 4,
    "config_data": {
        "charger_id": 9988552,
        "uid": "xys",
        "serial_number": "9988552",
        "name": "PulsarPlus SN 9988552",
        "locked": 1,
        "auto_lock": 1,
        "auto_lock_time": 300,
        "multiuser": 0,
        "max_charging_current": 32,
        "language": "EN",
        "icp_max_current": 0,
        "grid_type": 1,
        "energy_price": 0.24,
        "energyCost": {
            "value": 0.24,
            "inheritedGroupId": null
        },
        "unlock_user_id": 286113,
        "power_sharing_config": 256,
        "purchased_power": 0,
        "show_name": 1,
        "show_lastname": 1,
        "show_email": 1,
        "show_profile": 1,
        "show_default_user": 1,
        "gesture_status": 7,
        "home_sharing": 0,
        "dca_status": 0,
        "connection_type": 1,
        "max_available_current": 32,
        "live_refresh_time": 30,
        "update_refresh_time": 300,
        "owner_id": 286113,
        "remote_action": 0,
        "rfid_type": null,
        "charger_has_image": 0,
        "sha256_charger_image": null,
        "plan": {
            "plan_name": "Business",
            "features": [
                "DEFAULT_FEATURE",
                "POWER_BOOST",
                "MOBILE_CONNECTIVITY",
                "CHARGER_SUBGROUPS",
                "USER_SUBGROUPS",
                "DYNAMIC_POWER_SHARING",
                "PAYMENTS",
                "SET_UP_INCLUDED",
                "BULK_ACTIONS",
                "AUTOMATIC_REPORTING",
                "BILLING",
                "STATISTICS"
            ]
        },
        "sync_timestamp": 1692301922,
        "currency": {
            "id": 1,
            "name": "Euro Member Countries",
            "symbol": "€",
            "code": "EUR"
        },
        "charger_load_type": "Private",
        "contract_charging_available": false,
        "country": {
            "id": 4,
            "code": "DEU",
            "iso2": "DE",
            "name": "ALEMANIA",
            "phone_code": "49"
        },
        "state": null,
        "timezone": "Europe/Berlin",
        "part_number": "PLP1-M-2-4-9-002-F",
        "software": {
            "updateAvailable": false,
            "currentVersion": "5.17.59",
            "latestVersion": "5.17.59",
            "fileName": "plp1_5.17.59.tar"
        },
        "available": 1,
        "operation_mode": "ocpp",
        "ocpp_ready": "ocpp_1.6j",
        "tariffs": [],
        "mid_enabled": 0,
        "mid_margin": 1,
        "mid_margin_unit": 1,
        "mid_serial_number": "",
        "mid_status": 1,
        "session_segment_length": 0,
        "group_id": 289814,
        "user_socket_locking": 0,
        "sim_iccid": null,
        "ecosmart": {
            "enabled": false,
            "mode": 0,
            "percentage": 100
        }
    }
}

Status Informations inside both JSON properties status

Status Code Explanation
0 Disconnected
14 Error
15 Error
161 Ready
162 Ready
163 Disconnected
164 Waiting
165 Locked
166 Updating
177 Scheduled
178 Paused
179 Scheduled
180 Waiting for car demand
181 Waiting for car demand
182 Paused
183 Waiting in queue by Power Sharing
184 Waiting in queue by Power Sharing
185 Waiting in queue by Power Boost
186 Waiting in queue by Power Boost
187 Waiting MID failed
188 Waiting MID safety margin exceeded
189 Waiting in queue by Eco-Smart
193 Charging
194 Charging
195 Charging
196 Discharging
209 Locked
210 Locked - Car connected