Documentation

Copy page

Connect API - OCPP Wallbox Onboarding

TL;DR

• POST /vendors/{id}/connections with type: "ocpp" → read flowOptions[name="ocppUrl"] from the response → display the wss:// URL to the user → user enters it in their wallbox config
• Do not use the URL from GET /connection-options; it is a randomized preview. The URL to configure is always the one in flowOptions[name="ocppUrl"]
• Only one open connection allowed per user — if you need a new one, DELETE the old connection first (devices must be unlinked first)
• Any wallbox that connects to the user's OCPP endpoint is attached to that one open connection — even if its configured URL still carries the device tag of an earlier, deleted connection (see URL adoption). The connection's ocppUrl then reflects the identity the wallbox actually connected with
• The wallbox won't show up in GET /vendors/{id}/devices until it actually connects to the OCPP endpoint — tell users to save & restart
• Plugging in does not start charging by itself — see Charging Behaviour After Plug-in

Complete flow for connecting OCPP wallboxes via the Connect API.

---

Notes

• Vendor/Model is a 1 to 1 relation (one Vendor per Model)
• Only one pending connection at a time (this constraint might be removed in future)
• Similar to form flow

---

Step 1: List Vendors

Code
GET /v1/users/{userId}/vendors?category=wallbox

Response:

Code
{
  "data": [
    {
      "id": "{vendorId}",
      "name": "go-e V3/Gemini/Pro via OCPP"
    }
  ]
}

---

Step 2: Get Connection Options

Code
GET /v1/users/{userId}/vendors/{vendorId}/connection-options

Response:

Code
{
  "flow": "ocpp",
  "formOptions": [
    {
      "type": "text",
      "data": {
        "value": "wss://ocpp.clever-pv.com/<OCPP-HOME-ID>/<DEVICE-TAG>",
        "readonly": true,
        "label": "OCPP Connection URL",
        "description": "Enter this URL in your wallbox configuration"
      }
    }
  ],
  "docUrl": null
}

• OCPP-HOME-ID: unique OCPP identifier per home/user, automatically created by the Connect API
• DEVICE-TAG: Some devices require this id, but it's optional for others. In case the device requires the ID, it will be added by the Connect API. If not required, this part of the URL will not be provided

Warning — do not display this URL to the user. The DEVICE-TAG segment in this pre-creation response is freshly randomized on every read and is never persisted. Use this endpoint only to discover the flow type and field layout. The URL to give to the user is the one returned as flowOptions[name="ocppUrl"] after you create the connection in Step 3 — that one is stable.

---

Step 3: Create Connection

Code
POST /v1/users/{userId}/vendors/{vendorId}/connections

Request:

Code
{
  "type": "ocpp",
  "data": {}
}

Response:

Code
{
  "connectionId": "2c659624-ea66-49db-ae98-716b2e73fb0d",
  "vendorId": "{vendorId}",
  "flowOptions": [
    {
      "name": "ocppUrl",
      "data": "wss://ocpp.clever-pv.com/<OCPP-HOME-ID>/<DEVICE-TAG>"
    }
  ]
}

Note: Read the URL from flowOptions[name="ocppUrl"].data. Match by name, not by index — order is not guaranteed. The device tag in the URL is minted and persisted when the connection is created; the URL does not re-roll on reads. The same array is re-surfaced on every GET /v1/users/{userId}/vendors/connections?vendorId=... call, so you can recover the URL later without re-creating the connection.

There is one case where the URL legitimately changes after creation: if a wallbox that is still configured with an older OCPP URL connects, it is adopted into this connection and the ocppUrl switches to the identity the wallbox actually uses — see URL adoption. Always re-read flowOptions before configuring a wallbox rather than relying on a URL you stored earlier.

---

Step 4: User Interaction required: Enter OCPP URL in Wallbox

Ask the wallbox owner to:

1. Open the configuration interface of their wallbox (web UI or app).
2. Locate the setting for the OCPP server URL (sometimes called backend URL or charge point management URL).
3. Use the ocppUrl value from the flowOptions array returned in Step 3: Create Connection (or re-fetched via GET /v1/users/{userId}/vendors/connections?vendorId={vendorId}) in the wallbox device.
4. Save/apply the configuration and, if required by the device, restart the wallbox.

As soon as the wallbox connects to the OCPP endpoint, it will appear in Step 6: List Devices from Vendor.

---

URL Adoption (Lenient Matching)

Since there is only one open connection per user at a time, matching is deliberately lenient: every wallbox that connects to the user's OCPP endpoint is attached to that one open connection — the device tag in its configured URL does not have to match the tag minted at creation. A wallbox still configured with the URL of an earlier, deleted connection is therefore adopted just the same. After adoption, the connection's ocppUrl in flowOptions reflects the identity the wallbox actually connected with, which may differ from the URL returned when the connection was created.

This makes re-onboarding simple — do not reconfigure the wallbox:

1. Delete the device (DELETE /v1/users/{userId}/devices/{deviceId}), then the connection.
2. Create a new connection. The wallbox — still configured with its previous URL — is adopted automatically, typically within ~10 seconds and without a restart.
3. It appears in GET …/vendors/{vendorId}/devices?connectionId={newConnectionId} — create the device from there.

Two rules follow from this behavior:

• flowOptions[name="ocppUrl"] is the single source of truth. Re-read it via GET /v1/users/{userId}/vendors/connections?vendorId={vendorId} before configuring anything in the wallbox; never reuse a URL you stored earlier.
• Never reconfigure the wallbox after it has been adopted. Switching it to the freshly minted URL at that point creates a second identity: the connection is already bound to the old one, no status messages match the device you created, and it stays in waitingForStatus indefinitely.

If you explicitly want a fresh identity, remove the OCPP URL from the wallbox (or take it offline) before creating the new connection. With nothing connecting, no adoption happens, and the minted URL from flowOptions is the one to configure.

---

Step 5: Delete Connection (Optional)

In case the connection is not established, the connection should be deleted as there may only be one connection with unassigned OCPP devices at a time per userId.

Code
DELETE /v1/users/{userId}/vendors/{vendorId}/connections/cfb0103c-a6be-4673-b926-f6dcb718a0a0

Response: 204 on success

Important: All devices attached to the connection must be deleted first (via DELETE /v1/users/{userId}/devices/{deviceId}). If you attempt to delete a connection with linked devices, the endpoint will return an error.

---

Step 6: List Devices from Vendor

Code
GET /v1/users/{userId}/vendors/{vendorId}/devices?connectionId=2c659624-ea66-49db-ae98-716b2e73fb0d

Response:

Code
{
  "data": [
    {
      "name": "go-e V3/Gemini via OCPP",
      "text": "OCPP Wallbox - 85034558CP001 - Connector 1",
      "model": {
        "id": "0b1c2d3e-4f5a-4b6c-7d8e-9f0a1b2c3d4e",
        "name": "goe-v3-ocpp",
        "category": "wallbox"
      },
      "externalId": "EXTERNAL_ID_OF_DEVICE",
      "available": true,
      "connectionId": "76979136-08ea-41e3-9aa3-1ec6fe162bd4"
    }
  ]
}

---

Step 7: Create Device in Connect API

Code
POST /v1/users/{userId}/devices

Request:

Code
{
  "name": "Arbitrary display name for wallbox",
  "externalId": "EXTERNAL_ID_OF_DEVICE",
  "modelId": "0b1c2d3e-4f5a-4b6c-7d8e-9f0a1b2c3d4e",
  "connectionId": "2c659624-ea66-49db-ae98-716b2e73fb0d"
}

Response:

Code
{
  "data": [
    {
      "id": "d43129c3-84f1-484d-b2a4-ef60d6a3b485",
      "name": "Arbitrary display name for wallbox",
      "externalId": "EXTERNAL_ID_OF_DEVICE",
      "model": {
        "id": "e9a3d7c4-2b8f-4a6d-c5f1-7b3e9a2d8c4f",
        "name": "go-e V3/Gemini via OCPP",
        "category": "wallbox",
        "vendor": {
          "id": "{vendorId}",
          "name": "go-e OCPP"
        }
      },
      "capabilities": [
        {
          "name": "core",
          "data": {
            "name": "Arbitrary display name for wallbox",
            "connectivityStatus": "connecting"
          },
          "options": null,
          "interventions": []
        },
        {
          "name": "on-off",
          "data": {
            "state": "off"
          },
          "options": null,
          "interventions": []
        },
        {
          "name": "display-power",
          "data": {
            "power": 0,
            "lastUpdate": null
          },
          "options": null,
          "interventions": []
        },
        {
          "name": "display-charging-state",
          "data": {
            "chargingState": "waitingForStatus"
          },
          "options": {
            "chargingState": [
              "noCarConnected",
              "charging",
              "waitingOnCar",
              "completed",
              "error",
              "awaitingStart",
              "waitingForStatus"
            ]
          },
          "interventions": []
        },
        {
          "name": "display-charging-current",
          "data": {
            "amperage": 0
          },
          "options": null,
          "interventions": []
        },
        {
          "name": "display-charging-phases",
          "data": {
            "phases": 0
          },
          "options": null,
          "interventions": []
        },
        {
          "name": "set-charging-power",
          "data": {
            "desiredAmperage": 6
          },
          "options": {
            "minAmperage": 6,
            "maxAmperage": 32
          },
          "interventions": []
        },
        {
          "name": "min-max-amperage",
          "data": {
            "minAmperage": 6,
            "maxAmperage": 32
          },
          "options": {
            "absoluteMinAmperage": 6,
            "absoluteMaxAmperage": 32
          },
          "interventions": []
        },
        {
          "name": "phase-mode",
          "data": {
            "phaseMode": "automatic3Phases"
          },
          "options": {
            "availablePhaseModes": [
              "singlePhase",
              "twoPhases",
              "threePhases",
              "automatic2Phases",
              "automatic3Phases"
            ]
          },
          "interventions": []
        },
        {
          "name": "phase-switching",
          "data": {
            "supported": true
          },
          "options": null,
          "interventions": []
        },
        {
          "name": "charging-mode",
          "data": {
            "chargingMode": "clever"
          },
          "options": {
            "chargingMode": [
              "clever",
              "casual",
              "chargeAlways"
            ]
          },
          "interventions": []
        },
        {
          "name": "boost",
          "data": {
            "enabled": false
          },
          "options": null,
          "interventions": []
        },
        {
          "name": "smart-mode",
          "data": {
            "enabled": false
          },
          "options": null,
          "interventions": []
        },
        {
          "name": "solar-optimization",
          "data": {
            "enabled": true,
            "ratedCapacity": 1380,
            "sunShare": 100
          },
          "options": null,
          "interventions": []
        },
        {
          "name": "priority",
          "data": {
            "priority": 1
          },
          "options": null,
          "interventions": []
        },
        {
          "name": "rated-capacity",
          "data": {
            "ratedCapacity": 1380
          },
          "options": null,
          "interventions": []
        },
        {
          "name": "target-charging",
          "data": {
            "enabled": false,
            "targetControlLock": null,
            "currentRuntime": 0,
            "hasReachedTarget": false,
            "lastTargetControl": null,
            "executionTime": null,
            "targetWh": null,
            "targetSoC": null,
            "unitType": null,
            "targetDate": null,
            "weekDays": null,
            "type": null,
            "useSmartChargePlan": null,
            "sendPushNotification": null,
            "enableTargetControlLimit": null,
            "chargedWh": 0,
            "consumption": null,
            "batteryCapacity": null,
            "currentSoC": null,
            "socLimit": null,
            "lastUpdate": null
          },
          "options": null,
          "interventions": []
        },
        {
          "name": "price-control",
          "data": {
            "enabled": false,
            "threshold": 25
          },
          "options": null,
          "interventions": []
        },
        {
          "name": "time-control",
          "data": {
            "nextSchedule": null
          },
          "options": null,
          "interventions": []
        }
      ]
    }
  ]
}

---

Charging Behaviour After Plug-in

clever-PV does not start a charging session just because a cable was plugged in. What happens next depends on two things:

1. The charger's own authorization setting — a setting on the wallbox itself, not controlled by the Connect API. clever-PV never rejects an authorization the charger requests, so:

• Free charging / plug-and-charge / local RFID: the charger starts on its own; clever-PV observes it (display-charging-state becomes charging).
• Wait for the backend: the charger stays in awaitingStart until a start is sent.

2. Whether an optimization is enabled in clever-PV

• smart-mode true plus an active feature (solar-optimization, price-control, soc-plan, target-charging, time-control): clever-PV starts the session itself once the feature's condition is met — no per-session trigger. A self-started session is regulated or stopped by the surplus loop unless charging-mode is chargeAlways.
• smart-mode false: clever-PV stays passive. A backend-gated charger has to be triggered every session via on-off or boost.

on-off is not a stored preference — its state mirrors the live charging state, so an on does not carry over to the next plug-in. boost is per session as well and is cleared on unplug.

Track the session via display-charging-state: noCarConnected → awaitingStart → charging. Writes return 202; re-fetch the device afterwards.