# Voltra Documentation (Full) ## API Reference URL: https://docs.voltra.com/docs/api-reference # API Reference Interactive documentation for all Voltra APIs. Each page includes endpoint details, request/response schemas, multi-language code samples, and an interactive playground. ## Platform ## EV Charging ## Energy --- ## Access Control API URL: https://docs.voltra.com/docs/api-reference/access-control {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} --- ## Driver Management API URL: https://docs.voltra.com/docs/api-reference/drivers-and-groups {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} --- ## Charging Sessions API URL: https://docs.voltra.com/docs/api-reference/charging-sessions {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} --- ## Data Bridge API URL: https://docs.voltra.com/docs/api-reference/data-bridge {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} --- ## Device Management API URL: https://docs.voltra.com/docs/api-reference/device-management {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} --- ## Load Balancing API URL: https://docs.voltra.com/docs/api-reference/load-balancing {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} --- ## Location API URL: https://docs.voltra.com/docs/api-reference/locations {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} --- ## OCPP 2.0.1 Raw Direct API URL: https://docs.voltra.com/docs/api-reference/ocpp-raw-direct {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} --- ## Organization API URL: https://docs.voltra.com/docs/api-reference/organizations {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} --- ## Billing API URL: https://docs.voltra.com/docs/api-reference/payment-processing {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} --- ## Project API URL: https://docs.voltra.com/docs/api-reference/projects {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} --- ## Proxy Configuration API URL: https://docs.voltra.com/docs/api-reference/proxy-configuration {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} --- ## QR Manager API URL: https://docs.voltra.com/docs/api-reference/qr-manager {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} --- ## Proxy URL: https://docs.voltra.com/docs/Command/proxy Proxy routes OCPP messages between a charger and another charging platform through Voltra. That platform is the **upstream target**, also called a CSMS (Charging Station Management System). In the Console, this service is named **Proxy Controller**. ```mermaid flowchart TB charger[EV charger] <-->|OCPP| proxy[Voltra Proxy] proxy <-->|OCPP over secure WebSocket| target[Upstream CSMS] ``` ## When to Use Proxy - **Keep an existing charging platform connected.** Route a charger's OCPP connection through Voltra while continuing to exchange messages with its upstream CSMS. - **Investigate communication problems.** Inspect proxied traffic in Voltra's Logs and compare it with what the upstream platform receives. - **Use different charger identifiers.** Keep the charger's Voltra ID while connecting to the upstream platform with the ID it expects. Use a single saved upstream target per charger for this workflow. Proxy does not translate between OCPP protocol versions; the charger and upstream platform must use compatible versions. ## Before You Start Have the following ready: - Access to the Console organization and project that contain the charger, with permission to view and create proxy configurations. - An existing charger in [Device Management](/docs/Connect/devices), its Voltra **Charge Box ID**, and its existing Voltra OCPP credentials. - An upstream platform that accepts the charger: its secure WebSocket base URL (`wss://`), charger ID, and Basic authentication password. The upstream username must be the target charger ID. - Access to the charger's connection settings and to the upstream platform's connection or message logs. The Console walkthrough uses **Basic Authentication**. For other authentication modes, see [Managing via API](#managing-via-api). ## Set Up a Proxy in the Console The screenshots below use example charger and platform data. ### Open Proxy Controller Select the charger's organization and project. Open **All Services** and enable **Proxy Controller** if it is not already active, then open it under **Active Services**. The table lists saved configurations by **Charge Box ID**, **Target Platform**, **Target Charge Box ID**, **Authentication**, and **Last Updated**. Check for an existing configuration for your charger before adding one; use its details to edit that target. ![Proxy Controller showing a saved configuration and the Add Proxy Configuration button](/img/screenshots/proxy-controller-page.png) Click **Add Proxy Configuration**. ### Choose the Charger In **Choose Device**, use **Select Device** to pick the charger's Voltra Charge Box ID, then click **Next**. This selects an existing charger; it does not register a new device. ### Configure the Upstream Target In **Configure Proxy Target**, complete these fields: | Field | What to enter | | --- | --- | | **Target Platform Identifier** | A name you recognize, such as `Depot CSMS`. This is a label, not a platform integration selector. | | **Target Charge Box ID** | The charger's ID on the upstream platform, for example `DEPOT_REMOTE_01`. It is also the username for upstream Basic authentication. | | **Authentication Method** | The Console currently fixes this to **Basic Authentication**. | | **WebSocket URL** | The upstream base URL, for example `wss://ocpp.example.com/ocpp16`. Use your platform's actual URL. | | **Authentication Password** | The password issued by the upstream platform for that target charger ID. | ![Configure Proxy Target with an example platform, target charger ID, secure WebSocket URL, and masked password](/img/screenshots/proxy-configure-target.png) Voltra appends the target charger ID to a base URL. With the example values above, it connects to `wss://ocpp.example.com/ocpp16/DEPOT_REMOTE_01`. Do not also append the ID yourself. If your upstream platform needs the charger ID in a different position in its URL, contact Voltra for configuration guidance. Click **Create Proxy**. A successful save opens **OCPP Link Generated** and adds the configuration to the table. ### Connect the Charger Through Proxy Copy the **OCPP URL** from the success dialog. It is the Voltra proxy base URL for the selected charger. Configure it in the charger's connection settings, keeping the charger's existing Voltra Charge Box ID and OCPP credentials. Charger interfaces differ: if yours appends the charger ID automatically, enter only the base URL; if it expects a complete URL, append the Voltra Charge Box ID once. The success dialog also displays an **OCPP Password**. That generated proxy password does not replace the charger's existing Voltra OCPP credentials; keep those credentials on the charger. The **Authentication Password** you entered in the previous step is separate: Voltra uses it to connect to the upstream platform. Reconnect the charger using its connection settings, then complete the checks below. Saving a configuration alone does not move an existing connection onto Proxy. If you need to keep the original connection URL, contact Voltra to coordinate routing activation and reconnection. ## Verify the Connection A saved row and its **Last Updated** value show configuration state, not a live upstream connection. Verify both sides: 1. Confirm the charger has reconnected to the Voltra proxy URL using its existing credentials. 2. Open **Logs** in the Console, set the time range around the reconnect, and use **Charger** → **Select Chargers** to filter to this charger. Proxy entries carry a **Proxied** badge. 3. Look for a successful upstream connection and messages in both directions. A Proxied badge alone does not prove that the upstream platform received or accepted a message. 4. In the upstream platform, confirm the expected **Target Charge Box ID** is connected and receiving fresh messages, such as heartbeats. Check a request and its corresponding response across both systems. These checks establish the message path. Validate any charging workflows you depend on with the upstream platform before relying on this setup for a site. ## Change or Remove a Configuration Click a configuration's row to open **Proxy Details**, then click **Edit** to change its target platform label, target charger ID, URL, or password. Leaving the password blank preserves the stored upstream password. The selected Voltra charger cannot be changed through this editor. ![Proxy Details in edit mode, with target settings, the option to keep the stored password, and Save Changes](/img/screenshots/proxy-details-sidebar.png) Click **Save Changes**. This does not reconfigure an already connected proxy session. Reconnect the charger and repeat the connection checks to verify the new target settings. Deleting a configuration removes the saved target; it does not disconnect an active session or switch the charger back to a direct connection. Before removing Proxy, configure the charger's intended direct OCPP connection and verify it. If Voltra activated routing for the original URL, coordinate its removal with Voltra as well. ## Troubleshooting | What you see | What to check | | --- | --- | | The charger is missing from **Select Device** | Select the organization and project where it is registered. Register the charger in Device Management first if it does not exist. | | The charger fails to connect after setup | Use its existing Voltra OCPP credentials, not the password generated by the Proxy dialog. Check that the connection URL contains the Voltra Charge Box ID exactly once. | | The upstream platform rejects the connection | Check the target charger ID, its Basic password, the `wss://` URL, and protocol compatibility. Basic authentication uses the target charger ID as its username. | | The upstream URL ends with the charger ID twice | Enter the base URL in **WebSocket URL**; Voltra appends the target ID. | | The row exists, but there is no upstream traffic | Reconnect through the proxy URL and check both Voltra and upstream logs. Saving the row does not activate a connection. | | Edits do not appear to take effect | Reconnect the charger. An existing session retains the settings it started with. | ## Managing via API The [Proxy Configuration API Reference](/docs/api-reference/proxy-configuration) lists the configuration endpoints. For API-key requests, send `x-api-key`, `x-organization-id`, and `x-project-id` headers. Authenticated session requests also need organization and project context. The API supports these upstream authentication modes: | Mode | Behavior | | --- | --- | | `Basic` | Uses the target charger ID as the username and the configured upstream password. This is the Console workflow above. | | `None` | Adds no configured upstream credential, but forwards an incoming `Authorization` header if present. It does not strip charger credentials. | | `ClientCertificate` | Uses a separately provisioned client certificate. Certificate provisioning is a prerequisite; creating the configuration does not issue a certificate. | ## Next Steps - [Device Management](/docs/Connect/devices) — Register chargers and manage their connection details. - [Proxy Configuration API Reference](/docs/api-reference/proxy-configuration) — Automate configuration management. --- ## EV Charging — Getting Started URL: https://docs.voltra.com/docs/Command # EV Charging Voltra's EV charging platform handles the rules, policies, and financial operations that govern how charging stations are used. ## Core Features | Feature | What It Does | |-|-| | [Remote Operations](/docs/Command/remote-operations) | Start/stop sessions, reboot chargers, update firmware | | [Proxy](/docs/Command/proxy) | Connect chargers to an existing charging platform through Voltra | | [OCPI](/docs/Command/ocpi) | Publish chargers to EV roaming networks | | [Charge Authorization](/docs/Command/authorization) | Controls who can start a charging session and under what rules | | [Charging Sessions](/docs/Command/sessions) | Tracks session lifecycle from plug-in to billing | | [Pricing Engine](/docs/Command/pricing) | Applies dynamic pricing policies to charging sessions | | [Payment Processing](/docs/Command/payments) | Processes transactions through your payment provider | | [Load Management](/docs/Command/load-management) | Distributes available power across chargers at a site | | [Grid Services](/docs/Command/grid-services) | Enrolls devices in demand response and VPP programs | | [QR Codes](/docs/Command/qr-codes) | Generate shortcodes for driver-initiated sessions | ## How It Works When a driver plugs in, Command evaluates an authorization policy to decide whether to allow the session. If approved, it resolves the applicable pricing policy, monitors the session, and settles the transaction through your connected payment provider. In parallel, load management enforces site-level power constraints, and grid services can curtail or shift charging in response to demand response signals. ```mermaid graph LR A[Driver plugs in] --> B[Authorization] B --> C[Session starts] C --> D[Pricing resolved] C --> E[Load limits applied] D --> F[Session completes] F --> G[Payment settled] E -.-> H[Grid services] ``` ## Managing QR Codes Voltra supports linking physical QR codes on charging stations to your chargers via [shortcodes](/docs/Command/qr-codes). Drivers scan the code to initiate a session without needing an RFID card or app credential. ## Next Steps - [Authorization](/docs/Command/authorization) — Set up driver credentials and policies - [Sessions](/docs/Command/sessions) — Understand the charging session lifecycle - [Pricing](/docs/Command/pricing) — Configure pricing for your chargers - [Grid Services](/docs/Command/grid-services) — Enroll devices in demand response programs --- ## Authorization URL: https://docs.voltra.com/docs/Command/authorization # Authorization Authorization determines who is allowed to start a charging session and under what conditions. You register drivers, assign them credentials (RFID cards, PIN codes, or app-based tokens), and write authorization policies that evaluate each charge request in real time. ## How It Works When a charger receives a start request, the authorization service evaluates the request against the active policy for that charger. The policy is written in [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/) (the Open Policy Agent language) and can inspect the driver's identity, credential type, time of day, charger location, and any custom metadata you attach to drivers or groups. The policy returns three outputs: | Output | Purpose | |-|-| | `allow` | Whether to permit the session (boolean) | | `billing_strategy` | How to bill: `bypass` (free), `driver_pays`, or `organization_account` | | `denial_reason` | Human-readable explanation when `allow` is false | ## Drivers and Credentials A **driver** represents an individual who can charge at your stations. Each driver belongs to an organization and can hold one or more credentials: - **RFID** — Physical card tapped at the charger - **PIN Code** — Unique code entered on the charger display - **Guest Authorization** — Visitors charge without an account, typically billed at the charger Drivers can be organized into **driver groups** for bulk policy assignment (e.g., "Employees", "Residents", "VIP Fleet"). ## Use Cases - **Fleets** — Authorize vehicles by vehicle ID where the charger supports it - **Residential complexes** — Grant residents free charging tied to their occupancy - **Commercial offices** — Free charging for employees, paid for guests after hours ## Create an Authorization Policy **Why Rego?** Rego lets you express complex, composable rules without custom code. Policies are versioned, auditable, and hot-reloadable. Visit the [Charge Authentication page](https://console.voltra.com/dashboard/charge-authentication) in the Voltra Console and click **+ Add Authentication Policy**. ### Employee and Guest Policy This policy grants free charging to employees and paid charging to guests: ```hcl import future.keywords.if default allow = false allow if { input.user.type == "employee" } allow if { input.user.type == "guest" } billing_strategy := "bypass" if { input.user.type == "employee" } override_per_unit_price := 0 if { input.user.type == "employee" } billing_strategy := "driver_pays" if { input.user.type == "guest" } denial_reason := "Access denied: Only employees and guests are permitted" if { not allow } ``` ### Spending Limit Policy Enforce different pre-authorization limits by user type: ```hcl package authorization.spending_limits import future.keywords.if default allow = false allow if { input.user.type == "guest" input.pre_auth_amount <= 5000 } allow if { input.user.type == "registered_customer" input.pre_auth_amount <= 20000 } allow if { input.user.type == "employee" } billing_strategy := "driver_pays" if { allow input.user.type == "guest" } billing_strategy := "driver_pays" if { allow input.user.type == "registered_customer" } billing_strategy := "bypass" if { allow input.user.type == "employee" } override_per_unit_price := 0 if { allow input.user.type == "employee" } denial_reason := sprintf( "Pre-authorization amount $%.2f exceeds limit for %s users", [input.pre_auth_amount / 100, input.user.type] ) if { not allow } ``` ### VIP Charger Access Restrict specific chargers to employees only: ```hcl package authorization.vip_chargers import future.keywords.if default allow = false vip_chargers := { "charger-vip-001", "charger-vip-002", "charger-executive-parking" } is_vip_charger if { vip_chargers[input.charger.charge_box_id] } allow if { is_vip_charger input.user.type == "employee" } allow if { not is_vip_charger } billing_strategy := "bypass" if { allow is_vip_charger input.user.type == "employee" } override_per_unit_price := 0 if { allow is_vip_charger input.user.type == "employee" } billing_strategy := "driver_pays" if { allow not is_vip_charger } denial_reason := "Access denied: VIP chargers are reserved for employees only" if { not allow is_vip_charger } ``` ## Managing Authorization via API ```bash # List drivers curl -X GET https://api.voltra.com/authorization/api/v1/drivers \ -H "Authorization: Bearer $VOLTRA_API_KEY" # Evaluate an authorization request curl -X POST https://api.voltra.com/authorization/api/v1/auth \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "charge_box_id": "CHARGER-001", "id_tag": "RFID-ABC123" }' ``` ```javascript // List drivers const drivers = await fetch( "https://api.voltra.com/authorization/api/v1/drivers", { headers: { Authorization: `Bearer ${apiKey}` } } ) // Evaluate an authorization request const result = await fetch( "https://api.voltra.com/authorization/api/v1/auth", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ charge_box_id: "CHARGER-001", id_tag: "RFID-ABC123", }), } ) ``` ```python import requests # List drivers drivers = requests.get( "https://api.voltra.com/authorization/api/v1/drivers", headers={"Authorization": f"Bearer {api_key}"}, ) # Evaluate an authorization request result = requests.post( "https://api.voltra.com/authorization/api/v1/auth", headers={"Authorization": f"Bearer {api_key}"}, json={ "charge_box_id": "CHARGER-001", "id_tag": "RFID-ABC123", }, ) ``` > **See also:** [Drivers and Groups API Reference](/docs/api-reference/drivers-and-groups) for the full endpoint documentation. ## Best Practices - Start with a restrictive default (`default allow = false`) and explicitly allow known user types - Use driver groups to manage authorization at scale rather than per-driver rules - Test policies with the Rego playground before deploying to production - Include a `denial_reason` in every policy so drivers see a meaningful message when rejected - Use `context` blocks to attach audit metadata (policy name, timestamp) to each decision ## Next Steps - [Sessions](/docs/Command/sessions) — Understand what happens after authorization succeeds - [Pricing](/docs/Command/pricing) — Configure how authorized sessions are priced - [Payments](/docs/Command/payments) — Set up payment collection for driver-pays sessions --- ## Grid Services URL: https://docs.voltra.com/docs/Command/grid-services # Grid Services Grid services let you enroll your charging infrastructure in demand response (DR) programs and participate as a virtual power plant (VPP). When grid operators or aggregators send signals to reduce or shift load, Voltra automatically dispatches the appropriate commands to your enrolled devices. ## How It Works Voltra's demand response service acts as a protocol-agnostic orchestrator. It connects to upstream DR program sources (OpenADR VTNs, IEEE 2030.5 servers, Leap), translates their signals into a common event model, and dispatches power adjustments to your devices through the appropriate protocol (OCPP, Modbus, etc.). ```mermaid graph LR VTN[OpenADR VTN] --> DR[Demand Response Service] IEEE[IEEE 2030.5] --> DR Leap[Leap] --> DR DR --> D1[OCPP Chargers] DR --> D2[Modbus Devices] DR --> D3[Other Protocols] ``` ## Core Concepts ### Programs A DR **program** represents an offering from a grid operator or aggregator. Programs specify eligibility rules, compensation structures, and the types of events you can expect. Voltra syncs available programs from connected sources automatically. | Property | Description | |-|-| | `program_id` | Unique identifier from the source | | `program_name` | Human-readable name | | `program_type` | Category (e.g., capacity, energy, ancillary) | | `region` | Geographic area the program covers | | `enrollment_method` | How devices join (automatic, external authorization) | ### Enrollments An **enrollment** connects a specific device to a DR program. When you create an enrollment, the service registers the device with the upstream source and verifies its eligibility. Enrollments support three target types: | Target Type | Description | |-|-| | Charger | An individual OCPP charger by charge box ID | | Device | A generic device by device ID | | Load Group | A group of chargers managed together (coming soon) | Enrollments track status (`active`, `pending`, `suspended`) and can have pending actions such as external authorization URLs that the user must visit to complete enrollment. ### Events A DR **event** is a signal from the grid to adjust power consumption. Events contain one or more time intervals, each with a payload describing what to do: | Payload Type | What It Means | |-|-| | `PowerFraction` | Reduce consumption to a fraction of capacity (0.0 to 1.0) | | `DispatchSetpoint` | Target a specific aggregate kW across enrolled devices | Events carry a priority (lower number = higher urgency) and are dispatched to enrolled devices according to the conflict resolution strategy (first-come-first-served by default). ## Enroll a Device 1. List available programs to find one in your region 2. Check enrollment requirements for the program 3. Create an enrollment with the device's charge box ID and program ID 4. If the program uses external authorization (e.g., Leap Connect), complete the authorization flow at the returned URL ## Managing Grid Services via API ```bash # List available DR programs curl -X GET https://api.voltra.com/demand-response/programs \ -H "Authorization: Bearer $VOLTRA_API_KEY" # Enroll a device in a program curl -X POST https://api.voltra.com/demand-response/enrollments \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "program_id": "caiso-pdp-2026", "enrollment_target": "CHARGER-001" }' # List enrollments curl -X GET https://api.voltra.com/demand-response/enrollments \ -H "Authorization: Bearer $VOLTRA_API_KEY" # List DR events curl -X GET https://api.voltra.com/demand-response/events \ -H "Authorization: Bearer $VOLTRA_API_KEY" # Remove an enrollment curl -X DELETE "https://api.voltra.com/demand-response/enrollments/caiso-pdp-2026:CHARGER-001" \ -H "Authorization: Bearer $VOLTRA_API_KEY" ``` ```javascript const headers = { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", } // List available DR programs const programs = await fetch( "https://api.voltra.com/demand-response/programs", { headers } ) // Enroll a device const enrollment = await fetch( "https://api.voltra.com/demand-response/enrollments", { method: "POST", headers, body: JSON.stringify({ program_id: "caiso-pdp-2026", enrollment_target: "CHARGER-001", }), } ) // List DR events const events = await fetch( "https://api.voltra.com/demand-response/events", { headers } ) ``` ```python import requests headers = {"Authorization": f"Bearer {api_key}"} # List available DR programs programs = requests.get( "https://api.voltra.com/demand-response/programs", headers=headers, ) # Enroll a device enrollment = requests.post( "https://api.voltra.com/demand-response/enrollments", headers=headers, json={ "program_id": "caiso-pdp-2026", "enrollment_target": "CHARGER-001", }, ) # List DR events events = requests.get( "https://api.voltra.com/demand-response/events", headers=headers, ) ``` ## Supported Protocols Voltra connects to DR programs through three upstream protocols: | Protocol | Description | |-|-| | **OpenADR** | Industry-standard for utility-to-aggregator DR signaling. Voltra acts as a VEN (Virtual End Node). | | **IEEE 2030.5** | Smart grid protocol for DER management with certificate-based identity. | | **Leap** | Commercial DR aggregator with webhook-based event delivery. | The demand response service abstracts these protocols so your enrollment and monitoring experience is identical regardless of source. ## Best Practices - Start by enrolling a small number of chargers in a program to validate event dispatch before scaling - Monitor participation records after events to verify successful device response - Use the enrollment requirements endpoint to check what metadata a program needs before enrolling - Set appropriate device capacity in `source_metadata` for programs that distribute power setpoints ## Next Steps - [Load Management](/docs/Command/load-management) — Understand how site-level power limits interact with DR events - [Sessions](/docs/Command/sessions) — See how DR curtailment affects active sessions - [Authorization](/docs/Command/authorization) — Configure policies that account for DR participation --- ## Load Management URL: https://docs.voltra.com/docs/Command/load-management # Load Management Load management distributes available electrical capacity across your charging infrastructure. You define sites (physical locations), organize chargers into groups, and set power limits at each level. The load balancing engine dynamically adjusts charging rates to keep total draw within your site's capacity. ## How It Works Load management uses a three-level hierarchy: ```mermaid graph TD Site[Site] --> CG1[Charger Group A] Site --> CG2[Charger Group B] CG1 --> C1[Charger 1] CG1 --> C2[Charger 2] CG2 --> C3[Charger 3] CG2 --> C4[Charger 4] ``` - **Sites** are physical locations within your facility. Each site has an address and a total power limit. - **Charger Groups** organize chargers within a site. Each group can have its own load management strategy and power limit. - **Chargers** are assigned to groups and receive dynamic power limits from the load balancing engine. ## Key Features - **Dynamic load balancing** — Automatically distribute available power across active sessions - **Power limits** — Set constraints at the site level and the charger group level - **Real-time power distribution** — View power allocation across active sessions as it changes ## Create a Load Configuration ### Prerequisites - At least two [connected devices](/docs/Connect/devices) on the device management page - A physical address for each site (used for OCPI charger location publishing) ### Create a Site 1. Visit the [Load Balancing page](https://console.voltra.com/dashboard/load-balancing) in the Voltra Console 2. Click **+ Create Site** 3. Enter the location and site-specific information (address, power limit) 4. Save the site ### Add a Charger Group 1. On the Load Balancing page, click **+ Add Charger Group** under your site 2. Name the group and configure its power limit ### Assign Chargers to a Group 1. Click on a charger group to open the sidebar 2. Click **+ Add Charger** to assign chargers to the group 3. Configure the load strategy and any strategy-specific parameters from the sidebar ## Load Group Strategies Each charger group can use a different load management strategy to control how power is distributed among its chargers. Contact [hello@voltra.com](mailto:hello@voltra.com) to learn about available strategies and which one is right for your deployment. ## Managing Load Management via API ```bash # List sites curl -X GET https://api.voltra.com/csms/v2/sites \ -H "Authorization: Bearer $VOLTRA_API_KEY" # Create a site curl -X POST https://api.voltra.com/csms/v2/sites \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Main Parking Garage", "address": "123 Energy Blvd, San Francisco, CA 94105", "power_limit_kw": 150 }' # List charger groups for a site curl -X GET https://api.voltra.com/csms/v2/sites/{site_id}/charger-groups \ -H "Authorization: Bearer $VOLTRA_API_KEY" ``` ```javascript // List sites const sites = await fetch( "https://api.voltra.com/csms/v2/sites", { headers: { Authorization: `Bearer ${apiKey}` } } ) // Create a site const newSite = await fetch( "https://api.voltra.com/csms/v2/sites", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ name: "Main Parking Garage", address: "123 Energy Blvd, San Francisco, CA 94105", power_limit_kw: 150, }), } ) ``` ```python import requests # List sites sites = requests.get( "https://api.voltra.com/csms/v2/sites", headers={"Authorization": f"Bearer {api_key}"}, ) # Create a site new_site = requests.post( "https://api.voltra.com/csms/v2/sites", headers={"Authorization": f"Bearer {api_key}"}, json={ "name": "Main Parking Garage", "address": "123 Energy Blvd, San Francisco, CA 94105", "power_limit_kw": 150, }, ) ``` > **See also:** [Load Balancing API Reference](/docs/api-reference/load-balancing) for the full endpoint documentation. ## Best Practices - Set conservative site-level power limits first, then fine-tune at the charger group level - Group chargers by physical circuit or breaker panel to match electrical reality - Monitor real-time power distribution during peak hours to validate your limits - Use separate charger groups for different use cases (e.g., employee vs. visitor parking) ## Next Steps - [Grid Services](/docs/Command/grid-services) — Participate in demand response programs with your load-managed fleet - [Sessions](/docs/Command/sessions) — See how load limits affect active sessions - [Pricing](/docs/Command/pricing) — Adjust pricing based on peak vs. off-peak load --- ## Payments URL: https://docs.voltra.com/docs/Command/payments # Payments Payment processing handles the financial side of charging sessions. Voltra connects to your payment provider (currently Stripe) to collect payments from drivers, track transactions, and manage customer records. The system is designed to be payment-provider agnostic, so you can use your preferred platform. ## How It Works When a session with a `driver_pays` billing strategy completes, the payment processing service settles the transaction through your connected payment provider. The flow is: 1. Driver completes a charging session 2. The [pricing engine](/docs/Command/pricing) calculates the total cost 3. Payment processing charges the driver's saved payment method 4. A transaction record is created for auditing Voltra provides a white-labelled payment portal where drivers can add and manage their payment methods. All sensitive payment data is handled by the payment provider and never stored on Voltra's servers. ## Use Cases - **EV charging payments** — Accept payments from drivers using a branded payment portal - **Transaction analytics** — Track payment patterns to inform pricing decisions ## Connect a Payment Provider Self-service payment provider setup is coming soon. For now, contact [hello@voltra.com](mailto:hello@voltra.com) to connect your Stripe account. Voltra will facilitate creating your payment account and providing your payment account ID. Once connected, you can view the connection status on the [Payment Processing page](https://console.voltra.com/dashboard/payment-processing) in the Voltra Console. ## Managing Payments via API ```bash # List customers curl -X GET https://api.voltra.com/payment-processing/v2/customers \ -H "Authorization: Bearer $VOLTRA_API_KEY" # List transactions curl -X GET https://api.voltra.com/payment-processing/v2/transactions \ -H "Authorization: Bearer $VOLTRA_API_KEY" ``` ```javascript // List customers const customers = await fetch( "https://api.voltra.com/payment-processing/v2/customers", { headers: { Authorization: `Bearer ${apiKey}` } } ) // List transactions const transactions = await fetch( "https://api.voltra.com/payment-processing/v2/transactions", { headers: { Authorization: `Bearer ${apiKey}` } } ) ``` ```python import requests # List customers customers = requests.get( "https://api.voltra.com/payment-processing/v2/customers", headers={"Authorization": f"Bearer {api_key}"}, ) # List transactions transactions = requests.get( "https://api.voltra.com/payment-processing/v2/transactions", headers={"Authorization": f"Bearer {api_key}"}, ) ``` > **See also:** [Payment Processing API Reference](/docs/api-reference/payment-processing) for the full endpoint documentation. ## Best Practices - Connect your payment provider before assigning `driver_pays` authorization policies - Use transaction data to monitor revenue and identify underperforming chargers - Keep payment provider credentials secure and rotate them according to your provider's recommendations ## Next Steps - [Pricing](/docs/Command/pricing) — Configure what drivers are charged - [Sessions](/docs/Command/sessions) — Understand when payments are triggered - [Authorization](/docs/Command/authorization) — Set billing strategies per driver type --- ## Pricing URL: https://docs.voltra.com/docs/Command/pricing # Pricing The pricing engine resolves what a driver pays for a charging session. You define pricing policies — flat fees, per-kWh rates, per-minute rates, or scheduled combinations — and assign them to individual chargers. When a session completes, the engine calculates the total cost by applying the active policy to the session's metered energy and duration. ## How It Works A pricing policy is a JSON document that describes one or more pricing components. When a charger has an assigned policy, every session on that charger uses it to compute the final cost. Policies support four component types: | Component | Charges Based On | |-|-| | `FLAT` | Fixed fee per session | | `RATE` (KWH) | Energy delivered in kWh | | `RATE` (MINUTE) | Duration plugged in | | Schedule | Time-of-day and day-of-week rules with a fallback | ## Create a Pricing Policy Visit the [Pricing Engine page](https://console.voltra.com/dashboard/pricing-engine) in the Voltra Console and click **+ Add Pricing Policy**. ### Flat Fee Charge a fixed amount per session regardless of energy or time: ```json { "currency": "USD", "component": { "type": "FLAT", "amount": 5, "description": "Base fee" }, "taxIncluded": false } ``` ### Per-kWh Rate Bill drivers based on the energy they consume: ```json { "currency": "USD", "component": { "type": "RATE", "perUnitRate": 0.1, "unit": "KWH" }, "taxIncluded": false } ``` ### Per-Minute Rate Bill drivers based on how long they are plugged in: ```json { "currency": "USD", "component": { "type": "RATE", "unit": "MINUTE", "perUnitRate": 0.1 }, "taxIncluded": true } ``` ### Schedule-Based Policy Combine components with time-of-day and day-of-week rules. Sessions outside any schedule window use the `fallback` component: ```json { "currency": "USD", "fallback": { "type": "FLAT", "amount": 3, "description": "Default fallback fee" }, "timezone": "America/Los_Angeles", "schedules": [ { "startTime": "09:00", "endTime": "17:00", "daysOfWeek": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"], "component": { "type": "RATE", "unit": "KWH", "perUnitRate": 1.5, "description": "Rate per KWH" } }, { "startTime": "06:00", "endTime": "18:00", "daysOfWeek": ["SATURDAY", "SUNDAY"], "component": { "type": "FLAT", "amount": 5, "description": "Base fee" } } ], "taxIncluded": true } ``` Schedule time ranges cannot span past midnight. Split overnight ranges into two entries (e.g., 18:00-23:59 and 00:00-06:00). ## Assign a Policy to a Charger 1. Visit the [Device Management page](https://console.voltra.com/dashboard/device-management) 2. Click the charger you want to configure 3. Select a pricing policy from the **Pricing** dropdown in the device details sidebar 4. Click **Save Policies** ## Managing Pricing via API ```bash # List pricing policies curl -X GET https://api.voltra.com/pricing/v2/pricing-policies \ -H "Authorization: Bearer $VOLTRA_API_KEY" # Create a pricing policy curl -X POST https://api.voltra.com/pricing/v2/pricing-policies \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Standard kWh Rate", "currency": "USD", "component": { "type": "RATE", "unit": "KWH", "perUnitRate": 0.25 }, "taxIncluded": false }' ``` ```javascript // List pricing policies const policies = await fetch( "https://api.voltra.com/pricing/v2/pricing-policies", { headers: { Authorization: `Bearer ${apiKey}` } } ) // Create a pricing policy const newPolicy = await fetch( "https://api.voltra.com/pricing/v2/pricing-policies", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ name: "Standard kWh Rate", currency: "USD", component: { type: "RATE", unit: "KWH", perUnitRate: 0.25 }, taxIncluded: false, }), } ) ``` ```python import requests # List pricing policies policies = requests.get( "https://api.voltra.com/pricing/v2/pricing-policies", headers={"Authorization": f"Bearer {api_key}"}, ) # Create a pricing policy new_policy = requests.post( "https://api.voltra.com/pricing/v2/pricing-policies", headers={"Authorization": f"Bearer {api_key}"}, json={ "name": "Standard kWh Rate", "currency": "USD", "component": {"type": "RATE", "unit": "KWH", "perUnitRate": 0.25}, "taxIncluded": False, }, ) ``` The pricing API reference page is temporarily excluded from the generated docs due to a circular schema issue. Use the examples above or contact support for full endpoint details. ## Best Practices - Use schedule-based policies for sites with peak/off-peak pricing rather than swapping policies manually - Always set a `fallback` component on scheduled policies to avoid unpriceable sessions - Test policies in a staging project before assigning them to production chargers - Include `taxIncluded: true` when your displayed prices should be inclusive of tax ## Next Steps - [Payments](/docs/Command/payments) — Collect payments for priced sessions - [Sessions](/docs/Command/sessions) — See how pricing is applied during the session lifecycle - [Authorization](/docs/Command/authorization) — Control billing strategy per driver type --- ## QR Codes URL: https://docs.voltra.com/docs/Command/qr-codes # QR Codes QR codes let drivers start a charging session by scanning a code on the physical charger, without needing an RFID card, PIN, or app login. Voltra manages this through **shortcodes** — unique identifiers printed on QR stickers that map to specific chargers and connectors. ## How It Works Each QR code encodes a shortcode URL. When a driver scans it, the URL resolves to the assigned charger and connector, launching the payment portal or session initiation flow. You generate shortcodes in Voltra, print them as QR stickers, and assign them to chargers. ## Assign a Shortcode 1. Visit the [QR Code Manager](https://console.voltra.com/dashboard/qr-manager) in the Voltra Console 2. Generate a new shortcode or select an existing unassigned one 3. Assign it to a specific charger and connector 4. Print and affix the QR sticker to the physical charger ## Managing QR Codes via API ```bash # List shortcodes curl -X GET https://api.voltra.com/csms/v2/shortcodes \ -H "Authorization: Bearer $VOLTRA_API_KEY" # Assign a shortcode to a charger curl -X POST https://api.voltra.com/csms/v2/shortcodes/assign \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "shortcode": "ABC123", "charge_box_id": "CHARGER-001", "connector_id": 1 }' ``` ```javascript // List shortcodes const shortcodes = await fetch( "https://api.voltra.com/csms/v2/shortcodes", { headers: { Authorization: `Bearer ${apiKey}` } } ) // Assign a shortcode to a charger const assignment = await fetch( "https://api.voltra.com/csms/v2/shortcodes/assign", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ shortcode: "ABC123", charge_box_id: "CHARGER-001", connector_id: 1, }), } ) ``` ```python import requests # List shortcodes shortcodes = requests.get( "https://api.voltra.com/csms/v2/shortcodes", headers={"Authorization": f"Bearer {api_key}"}, ) # Assign a shortcode to a charger assignment = requests.post( "https://api.voltra.com/csms/v2/shortcodes/assign", headers={"Authorization": f"Bearer {api_key}"}, json={ "shortcode": "ABC123", "charge_box_id": "CHARGER-001", "connector_id": 1, }, ) ``` > **See also:** [QR Manager API Reference](/docs/api-reference/qr-manager) for the full endpoint documentation. ## Best Practices - Use a consistent shortcode naming convention that maps to your physical site layout - Print QR codes with UV-resistant materials for outdoor installations - Keep a mapping spreadsheet of shortcodes to charger locations for field technicians - Test each QR code after installation to verify it resolves to the correct charger ## Next Steps - [Authorization](/docs/Command/authorization) — Configure guest authorization for QR-initiated sessions - [Payments](/docs/Command/payments) — Set up payment collection for guest drivers - [Sessions](/docs/Command/sessions) — Monitor sessions started via QR scan --- ## Charging Sessions URL: https://docs.voltra.com/docs/Command/sessions # Charging Sessions A charging session represents the full lifecycle of a single charge event, from the moment a driver plugs in until the session is billed. Sessions tie together authorization decisions, energy delivery, and payment transactions into a single auditable record. ## How It Works When a charger reports a start transaction, Voltra creates a session record and begins tracking energy delivery and duration. The session moves through a state machine until it completes or fails, at which point billing is finalized. ```mermaid stateDiagram-v2 [*] --> pending pending --> active: Charger starts active --> completed: Charger stops active --> failed: Error pending --> cancelled: Timeout / rejected completed --> [*] failed --> [*] cancelled --> [*] ``` ## Session States | State | Description | |-|-| | `pending` | Authorization granted, waiting for the charger to begin | | `active` | Energy is being delivered | | `completed` | Charging finished normally, billing settled | | `failed` | An error interrupted the session | | `cancelled` | Session was cancelled before energy delivery started | ## Key Properties | Property | Type | Description | |-|-|-| | `id` | uuid | Unique session identifier | | `charge_box_id` | string | Charger that hosted the session | | `status` | enum | Current session state | | `energy_delivered` | float | Energy delivered in kWh | | `total_cost` | float | Calculated cost after pricing is applied | | `billing_strategy` | enum | `bypass`, `driver_pays`, or `organization_account` | | `start_time` | datetime | When charging began | | `stop_time` | datetime | When charging ended | | `driver_id` | uuid | Driver associated with the session | | `currency` | string | ISO 4217 currency code | ## Monitoring Sessions The sessions API provides several analytics endpoints to help you understand charging patterns across your fleet: | Endpoint | What It Returns | |-|-| | List sessions | Paginated session records with filtering by status, date range, and charger | | Total sessions | Aggregate count of all sessions | | Total energy dispatch | Cumulative kWh delivered across all sessions | | Average session length | Mean session duration in minutes | | Chargers with sessions | List of chargers ranked by session count | ## Billing Each session carries a `billing_strategy` determined by the [authorization policy](/docs/Command/authorization): - **bypass** — No charge to the driver (e.g., employee free charging) - **driver_pays** — The driver is billed based on the active [pricing policy](/docs/Command/pricing) - **organization_account** — The organization absorbs the cost The `total_cost` is resolved when the session completes by applying the charger's pricing policy to the metered energy and duration. ## Managing Sessions via API ```bash # List sessions with filters curl -X GET "https://api.voltra.com/authorization/api/v1/charging-sessions/?status=active&limit=50" \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "x-organization-id: $ORG_ID" \ -H "x-project-id: $PROJECT_ID" # Get total energy delivered curl -X GET "https://api.voltra.com/authorization/api/v1/charging-sessions/dispatch" \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "x-organization-id: $ORG_ID" \ -H "x-project-id: $PROJECT_ID" # Get average session length curl -X GET "https://api.voltra.com/authorization/api/v1/charging-sessions/length" \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "x-organization-id: $ORG_ID" \ -H "x-project-id: $PROJECT_ID" ``` ```javascript const headers = { Authorization: `Bearer ${apiKey}`, "x-organization-id": orgId, "x-project-id": projectId, } // List active sessions const sessions = await fetch( "https://api.voltra.com/authorization/api/v1/charging-sessions/?status=active&limit=50", { headers } ) // Get total energy delivered const energy = await fetch( "https://api.voltra.com/authorization/api/v1/charging-sessions/dispatch", { headers } ) // Get average session length const avgLength = await fetch( "https://api.voltra.com/authorization/api/v1/charging-sessions/length", { headers } ) ``` ```python import requests headers = { "Authorization": f"Bearer {api_key}", "x-organization-id": org_id, "x-project-id": project_id, } # List active sessions sessions = requests.get( "https://api.voltra.com/authorization/api/v1/charging-sessions/", headers=headers, params={"status": "active", "limit": 50}, ) # Get total energy delivered energy = requests.get( "https://api.voltra.com/authorization/api/v1/charging-sessions/dispatch", headers=headers, ) # Get average session length avg_length = requests.get( "https://api.voltra.com/authorization/api/v1/charging-sessions/length", headers=headers, ) ``` > **See also:** [Charging Sessions API Reference](/docs/api-reference/charging-sessions) for the full endpoint documentation. ## Best Practices - Use `from_date` and `to_date` filters to scope session queries to relevant time windows - Monitor the `failed` state to detect charger hardware issues early - Use the energy dispatch endpoint for fleet-wide energy reporting rather than summing individual sessions client-side - Set up [webhooks](/docs/Platform/data-bridge) to receive real-time notifications when sessions complete ## Next Steps - [Pricing](/docs/Command/pricing) — Configure how session costs are calculated - [Payments](/docs/Command/payments) — Process transactions for completed sessions - [Authorization](/docs/Command/authorization) — Control who can start sessions --- ## Data Bridge URL: https://docs.voltra.com/docs/Platform/data-bridge # Data Bridge Data Bridge connects your charger data to external data sources so you can seamlessly operate on, analyze, and export your charger data. Configure a connector once, and Data Bridge streams events from the platform to your destination in real time. ## How It Works 1. **Configure a connector** with your destination credentials and preferences 2. **Select which events** to stream (sessions, status changes, meter values) 3. **Data Bridge delivers** events in real time with at-least-once guarantees 4. **Monitor delivery** status, error rates, and latency from the console ## Connection Compatibility Data Bridge supports the following destination types: | Destination | Use Case | |-|-| | **AWS S3** | Data lake ingestion, long-term archival | | **Google Cloud Storage** | Analytics pipelines, BigQuery staging | | **Azure Storage** | Azure-native data workflows | | **DigitalOcean Spaces** | S3-compatible object storage | | **Webhook** | Real-time HTTP callbacks to your backend | | **MQTT** | Publish events to IoT message brokers | Need a destination type not listed here? Contact [hello@voltra.com](mailto:hello@voltra.com) and we will add it. ## Event Filtering Filter which events are delivered to each connector: - **By event type** -- session events, status changes, meter values - **By device or location** -- limit to specific chargers or sites - **By project** -- scope to a single project boundary ## Delivery Guarantees - **At-least-once delivery** -- events may be delivered more than once, so design consumers to be idempotent - **Retry with backoff** -- failed deliveries are retried with exponential backoff - **Dead-letter queue** -- persistently failed events are stored for later inspection and replay ## Creating a Connector ### From the Console 1. Visit the [Data Bridge page](https://console.voltra.com/dashboard/data-bridge) in the Voltra Console 2. Click **+ Add Connector** or click **Connect** on the destination card you want 3. Fill in the configuration for your connector (bucket name, credentials, endpoint URL) 4. Click **Create Connector** to start streaming ![Data Bridge page](/img/screenshots/data-bridge-page.png) ![Connector Configuration modal](/img/screenshots/connector-configuration-modal.png) ### Via API Use the connector configurations endpoints to manage connectors programmatically. ## Managing Data Bridge via API ```bash # List all connector configurations curl -X GET https://api.voltra.com/csms/v2/connector-configurations \ -H "Authorization: Bearer $VOLTRA_API_KEY" # Create a new connector configuration curl -X POST https://api.voltra.com/csms/v2/connector-configurations \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "s3", "bucket": "your-bucket", "prefix": "charging-data/", "region": "us-east-1" }' ``` ```javascript // List all connector configurations const response = await fetch( "https://api.voltra.com/csms/v2/connector-configurations", { headers: { Authorization: `Bearer ${apiKey}` }, } ) const connectors = await response.json() // Create a new connector configuration const created = await fetch( "https://api.voltra.com/csms/v2/connector-configurations", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "s3", bucket: "your-bucket", prefix: "charging-data/", region: "us-east-1", }), } ) ``` ```python import requests headers = {"Authorization": f"Bearer {api_key}"} # List all connector configurations response = requests.get( "https://api.voltra.com/csms/v2/connector-configurations", headers=headers, ) connectors = response.json() # Create a new connector configuration created = requests.post( "https://api.voltra.com/csms/v2/connector-configurations", headers=headers, json={ "type": "s3", "bucket": "your-bucket", "prefix": "charging-data/", "region": "us-east-1", }, ) ``` > **See also:** [Data Bridge API Reference](/docs/api-reference/data-bridge) for the full endpoint documentation. ## Monitoring Track connector health from the console or API: | Metric | Description | |-|-| | Delivery success rate | Percentage of events delivered on first attempt | | Error count | Number of failed deliveries in the current window | | Latency | Time from event emission to delivery confirmation | | Last delivery | Timestamp of the most recent successful delivery | ## Best Practices - Use event filtering to send only the events each destination needs, reducing cost and noise - Store connector credentials securely -- Data Bridge encrypts them at rest - Monitor the dead-letter queue and set up alerts for persistent failures - Design downstream consumers to handle duplicates since delivery is at-least-once ## Next Steps - [Integrations](/docs/Integrations) -- Browse pre-built third-party integrations - [API Reference](/docs/api-reference/data-bridge) -- Full Data Bridge endpoint documentation --- ## Energy URL: https://docs.voltra.com/docs/Connect # Energy Connect batteries, solar inverters, meters, and other energy assets to Voltra. Manage device profiles, firmware, connectivity, and tunnels. ## Core Concepts ### [Devices](/docs/Connect/devices) The core domain object. A device is any physical energy asset — meter, inverter, or controller — connected to Voltra. Each device maintains a persistent connection, reports status and meter values, and receives remote commands. ### [Device Model](/docs/Connect/device-model) VRN identity, types, and relationships for energy devices. ### [Protocols](/docs/Connect/protocols) The communication standards devices use to talk to Voltra: Modbus, DNP3, BACnet, MQTT, IEEE 2030.5. ### [Tunnels](/docs/Connect/tunnels) Secure device connectivity tunnels for remote access. ## Next Steps - [Devices](/docs/Connect/devices) — Register and manage physical hardware - [Protocols](/docs/Connect/protocols) — Learn about supported protocols - [EV Charging](/docs/Command) — Charging station operations and business logic --- ## Remote Operations URL: https://docs.voltra.com/docs/Command/remote-operations # Remote Operations Actions are remote commands sent to connected devices. You use actions to control device behavior -- setting a thermostat setpoint, resetting a charger, unlocking a connector, or updating firmware. Actions support both single-device and batch execution, with full lifecycle tracking from submission to completion. ## How It Works When you execute an action, Voltra routes the command to the target device through its active protocol connection. The platform tracks the execution through a lifecycle and returns results asynchronously. Each action has: - A **target device** identified by device ID - An **action name** matching a capability the device supports (e.g., `setSetpoint`, `reset`) - Optional **parameters** specific to the action - A **status** that progresses through the execution lifecycle ### Action Lifecycle Every action execution moves through these states: ```mermaid stateDiagram-v2 [*] --> pending pending --> running : Device accepts running --> completed : Success running --> failed : Error running --> cancelled : User cancels pending --> cancelled : User cancels ``` | Status | Description | |-|-| | `pending` | Action queued, waiting for device | | `running` | Device acknowledged, executing | | `completed` | Action finished successfully | | `failed` | Action encountered an error | | `cancelled` | Action was cancelled before completion | ## Single Actions To execute an action on a single device, send the device ID, action name, and any required parameters. Voltra returns an execution ID you can use to poll for status. **Example request body:** ```json { "device_id": "dev-001", "action": "setSetpoint", "params": { "value": 72.5, "unit": "F" } } ``` ## Batch Actions Batch execution sends commands to multiple devices in a single request. Each device/action pair is executed independently -- a failure on one device does not block the others. **Example request body:** ```json { "actions": [ { "device_id": "dev-001", "action": "setSetpoint", "params": { "value": 72 } }, { "device_id": "dev-002", "action": "setSetpoint", "params": { "value": 68 } } ] } ``` The response includes per-device results with individual success/failure status. ## Available Actions Each device exposes a set of available actions based on its type and protocol. You can list what actions a device supports before executing. Each action definition includes: | Property | Type | Description | |-|-|-| | `name` | string | Action identifier | | `description` | string | What the action does | | `params` | array | Parameter definitions with types and constraints | | `preconditions` | array | Conditions that must be met | | `timeout` | integer | Timeout in milliseconds | | `idempotent` | boolean | Whether repeated calls are safe | ## Managing Actions via API ### Execute an Action ```bash curl -X POST https://api.voltra.sh/csms/v2/actions/execute \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "device_id": "dev-001", "action": "setSetpoint", "params": { "value": 72.5, "unit": "F" } }' ``` ```javascript const response = await fetch("https://api.voltra.sh/csms/v2/actions/execute", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ device_id: "dev-001", action: "setSetpoint", params: { value: 72.5, unit: "F" }, }), }) const { data } = await response.json() console.log(data.execution_id) ``` ```python response = requests.post( "https://api.voltra.sh/csms/v2/actions/execute", headers={ "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", }, json={ "device_id": "dev-001", "action": "setSetpoint", "params": {"value": 72.5, "unit": "F"}, }, ) execution_id = response.json()["data"]["execution_id"] ``` ### Check Action Status ```bash curl -X GET "https://api.voltra.sh/csms/v2/actions/$EXECUTION_ID" \ -H "Authorization: Bearer $VOLTRA_API_KEY" ``` ```javascript const response = await fetch( `https://api.voltra.sh/csms/v2/actions/${executionId}`, { headers: { Authorization: `Bearer ${apiKey}` }, } ) const { data } = await response.json() console.log(data.status, data.progress) ``` ```python response = requests.get( f"https://api.voltra.sh/csms/v2/actions/{execution_id}", headers={"Authorization": f"Bearer {api_key}"}, ) status = response.json()["data"]["status"] ``` ### List Available Actions for a Device ```bash curl -X GET "https://api.voltra.sh/csms/v2/actions/device/$DEVICE_ID" \ -H "Authorization: Bearer $VOLTRA_API_KEY" ``` ```javascript const response = await fetch( `https://api.voltra.sh/csms/v2/actions/device/${deviceId}`, { headers: { Authorization: `Bearer ${apiKey}` }, } ) const { data } = await response.json() ``` ```python response = requests.get( f"https://api.voltra.sh/csms/v2/actions/device/{device_id}", headers={"Authorization": f"Bearer {api_key}"}, ) actions = response.json()["data"] ``` ## Best Practices - **Check available actions first** before executing. Not all devices support all actions. - **Use batch execution** for fleet-wide operations instead of looping single calls. - **Poll with backoff** when waiting for action completion. Start with 1-second intervals and increase. - **Handle `failed` status gracefully.** Check the `result.message` field for error details. ## Next Steps - [Devices](/docs/Connect/devices) -- Understand the devices you control - [Workflows](/docs/Connect/workflows) -- Automate multi-step action sequences - [Telemetry](/docs/Platform/telemetry) -- Monitor device data after actions - [Device Model](/docs/Connect/device-model) -- Understand device types and capabilities --- ## Device Model URL: https://docs.voltra.com/docs/Connect/device-model # Device Model The device model is Voltra's knowledge graph for energy assets. It defines what kinds of devices exist (types and interfaces), tracks individual instances (objects), and organizes them into containment hierarchies so you can query an entire site, building, or fleet from a single root. **Why:** The OntologyService API is not yet in the public API reference. The endpoints shown below are stable but may change before GA. ## How It Works The device model is built on four primitives that work together: - **Types** define a category of device (e.g., "EV Charger", "Battery Inverter"). Each type declares what properties and capabilities its instances support. - **Interfaces** define reusable capability contracts (e.g., "Metered", "Switchable"). Types implement one or more interfaces, and interfaces can inherit from other interfaces. - **Objects** are individual device instances. Every object has a type and a set of property values. - **Containment** organizes objects into parent/child trees. A "Site" object contains "Building" objects, which contain "Panel" objects, which contain "Charger" objects. ```mermaid graph TD A[Type: EV Charger] -->|implements| B[Interface: Metered] A -->|implements| C[Interface: Switchable] D[Object: charger-001] -->|instance of| A E[Object: site-hq] -->|contains| F[Object: building-a] F -->|contains| D ``` ## Types and Interfaces Types are the device registry. Each type has a lifecycle (`draft`, `active`, `deprecated`) and can implement multiple interfaces. | Property | Type | Description | |-|-|-| | `vrn` | string | Voltra Resource Name (unique ID) | | `name` | string | Human-readable type name | | `lifecycle` | enum | `draft`, `active`, `deprecated` | | `tenant_id` | string | Organization scope | Interfaces define reusable property and capability contracts. A "Metered" interface might declare that any implementing type must report `energy_kwh` and `power_kw` properties. Interfaces support inheritance -- a "BidirectionalMeter" interface can extend "Metered". ## Objects and Properties Objects are concrete instances of a type. When you register a physical device, Voltra creates an object linked to its type. Properties are key-value pairs defined by the object's type and interfaces. Property definitions specify the data type, unit, and constraints. Each object carries its own property values. | Property | Type | Description | |-|-|-| | `vrn` | string | Unique object identifier | | `type_vrn` | string | VRN of the object's type | | `name` | string | Human-readable instance name | | `tenant_id` | string | Organization scope | ## Containment Hierarchy Containment models the physical or logical nesting of objects. A site contains buildings, buildings contain panels, panels contain chargers. The hierarchy is stored as a closure table, enabling efficient queries at any depth. You can traverse the hierarchy in several ways: - **Ancestors** -- walk up from a charger to its site - **Descendants** -- walk down from a site to all nested devices - **Siblings** -- find other objects under the same parent - **Roots** -- find top-level objects with no parent - **Direct parent** -- find the immediate container ## Graph Relationships and Traversal Beyond containment, the device model supports arbitrary graph relationships between objects. You can query neighbors, find shortest paths between two objects, or extract subgraphs rooted at a given node. Graph queries support direction filtering (`IN`, `OUT`, `BOTH`) and relationship type filtering to narrow results. ## Managing the Device Model via API The OntologyService uses the `X-Organization-Id` header for tenant scoping. All endpoints require this header. ### List Types ```bash curl -X GET "https://api.voltra.sh/ontology/types?limit=20" \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "X-Organization-Id: $ORG_ID" ``` ```javascript const response = await fetch("https://api.voltra.sh/ontology/types?limit=20", { headers: { Authorization: `Bearer ${apiKey}`, "X-Organization-Id": orgId, }, }) const { data } = await response.json() ``` ```python response = requests.get( "https://api.voltra.sh/ontology/types", params={"limit": 20}, headers={ "Authorization": f"Bearer {api_key}", "X-Organization-Id": org_id, }, ) data = response.json()["data"] ``` ### Get an Object ```bash curl -X GET "https://api.voltra.sh/ontology/objects/$OBJECT_VRN" \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "X-Organization-Id: $ORG_ID" ``` ```javascript const response = await fetch(`https://api.voltra.sh/ontology/objects/${objectVrn}`, { headers: { Authorization: `Bearer ${apiKey}`, "X-Organization-Id": orgId, }, }) const { data } = await response.json() ``` ```python response = requests.get( f"https://api.voltra.sh/ontology/objects/{object_vrn}", headers={ "Authorization": f"Bearer {api_key}", "X-Organization-Id": org_id, }, ) data = response.json()["data"] ``` ### Query Containment Ancestors ```bash curl -X GET "https://api.voltra.sh/ontology/containment/ancestors?vrn=$DEVICE_VRN" \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "X-Organization-Id: $ORG_ID" ``` ```javascript const response = await fetch( `https://api.voltra.sh/ontology/containment/ancestors?vrn=${deviceVrn}`, { headers: { Authorization: `Bearer ${apiKey}`, "X-Organization-Id": orgId, }, } ) const { data } = await response.json() ``` ```python response = requests.get( "https://api.voltra.sh/ontology/containment/ancestors", params={"vrn": device_vrn}, headers={ "Authorization": f"Bearer {api_key}", "X-Organization-Id": org_id, }, ) data = response.json()["data"] ``` ## Next Steps - [Devices](/docs/Connect/devices) -- Learn about physical device management - [Actions](/docs/Command/remote-operations) -- Send commands to device objects - [Telemetry](/docs/Platform/telemetry) -- Query device measurements and events - [Device Profiles](/docs/Connect/device-profile) -- Configure device templates --- ## Devices URL: https://docs.voltra.com/docs/Connect/devices # Devices Devices are the physical chargers and energy assets connected to the Voltra platform. Every device maintains a persistent connection to Voltra, reports its status and meter values in real time, and can receive remote commands. ## How It Works ### Charger A charger (or charge box) is the physical charging station. Each charger: - Has a unique identifier (charge box ID) - Connects via WebSocket to Voltra - Contains one or more connectors - Reports status and meter values ### Connector A connector is an individual charging port on a charger. Each connector: - Has a connector ID (1, 2, etc.) - Has a type (CCS, CHAdeMO, Type 2, etc.) - Has its own status (Available, Charging, Faulted) - Can have different power ratings ### EVSE In OCPP 2.0.1, an EVSE (Electric Vehicle Supply Equipment) groups connectors that share hardware: - One EVSE typically equals one parking space - An EVSE may have multiple connector types - Only one connector per EVSE can charge at a time ## Device States | Status | Description | |-|-| | Available | Ready to charge | | Preparing | Cable connected, waiting to start | | Charging | Active charging session | | Finishing | Session complete, cable still connected | | Reserved | Reserved for a specific driver | | Unavailable | Temporarily out of service | | Faulted | Error condition | ## Adding a Device There are two ways to register a device with Voltra: through the Console or via the API. ### Via the Console 1. Navigate to the [Device Management page](https://console.voltra.com/dashboard/device-management) in the Voltra Console. 2. Click **+ Connect New Device** to open the connection modal. 3. Fill in the required information for your device (name, model, location). 4. For EV chargers, the modal generates an OCPP link and password. Enter these into your charger's configuration software. 5. The charger connects and sends a `BootNotification`. Voltra accepts the connection and syncs state automatically. ### Via the API Register a device programmatically by calling `POST /chargers/`: ```bash curl -X POST https://api.voltra.sh/csms/v2/chargers/ \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Lobby Charger 1", "charge_box_id": "CHARGER-001", "location_id": "loc_abc123" }' ``` ```javascript const response = await fetch("https://api.voltra.sh/csms/v2/chargers/", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ name: "Lobby Charger 1", charge_box_id: "CHARGER-001", location_id: "loc_abc123", }), }) const charger = await response.json() ``` ```python response = requests.post( "https://api.voltra.sh/csms/v2/chargers/", headers={"Authorization": f"Bearer {api_key}"}, json={ "name": "Lobby Charger 1", "charge_box_id": "CHARGER-001", "location_id": "loc_abc123", }, ) charger = response.json() ``` ## Remote Operations You can control devices remotely through Voltra: - **Start/stop** charging sessions - **Reset** the charger (soft or hard) - **Unlock** connectors - **Update firmware** over the air - **Change configuration** keys ## Managing Devices via API ```bash # List all chargers curl -X GET https://api.voltra.sh/csms/v2/chargers/ \ -H "Authorization: Bearer $VOLTRA_API_KEY" # Get a specific charger curl -X GET https://api.voltra.sh/csms/v2/chargers/CHARGER-001 \ -H "Authorization: Bearer $VOLTRA_API_KEY" ``` ```javascript // List all chargers const chargers = await fetch("https://api.voltra.sh/csms/v2/chargers/", { headers: { Authorization: `Bearer ${apiKey}` }, }).then((r) => r.json()) // Get a specific charger const charger = await fetch("https://api.voltra.sh/csms/v2/chargers/CHARGER-001", { headers: { Authorization: `Bearer ${apiKey}` }, }).then((r) => r.json()) ``` ```python # List all chargers chargers = requests.get( "https://api.voltra.sh/csms/v2/chargers/", headers={"Authorization": f"Bearer {api_key}"}, ).json() # Get a specific charger charger = requests.get( "https://api.voltra.sh/csms/v2/chargers/CHARGER-001", headers={"Authorization": f"Bearer {api_key}"}, ).json() ``` > **See also:** [Device Management API Reference](/docs/api-reference/device-management) for the full endpoint documentation. ## Next Steps - [Profiles](/docs/Connect/profiles) — Configure device capabilities and settings - [Protocols](/docs/Connect/protocols) — Learn about OCPP and other supported protocols - [Locations](/docs/Platform/locations) — Organize devices by physical site --- ## Locations URL: https://docs.voltra.com/docs/Platform/locations # Locations Locations represent the physical sites where your devices are deployed. A location has an address and groups one or more chargers that share a physical space. Locations are used throughout the platform for load management, OCPI roaming, and displaying chargers on maps. ## How It Works A location is the physical container for devices. When you create a location, you define: - **Name** — A human-readable label for the site (e.g., "Downtown Parking Garage") - **Address** — The street address used for mapping and OCPI publishing - **Coordinates** — Latitude and longitude for precise positioning - **Metadata** — Custom key-value pairs for your own tracking (building codes, zones, etc.) Devices are assigned to a location during registration or updated afterward. A single location can contain multiple chargers of different types and protocols. ## Key Properties | Property | Type | Description | |-|-|-| | `id` | string | Unique location identifier | | `name` | string | Human-readable site name | | `address` | object | Street address with city, state, postal code, country | | `coordinates` | object | Latitude and longitude | | `chargers` | array | Devices assigned to this location | ## Managing Locations via API ### Create a Location ```bash curl -X POST https://api.voltra.sh/csms/v2/locations/ \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Downtown Parking Garage", "address": { "street": "123 Main St", "city": "Austin", "state": "TX", "postal_code": "78701", "country": "US" }, "coordinates": { "latitude": 30.2672, "longitude": -97.7431 } }' ``` ```javascript const response = await fetch("https://api.voltra.sh/csms/v2/locations/", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ name: "Downtown Parking Garage", address: { street: "123 Main St", city: "Austin", state: "TX", postal_code: "78701", country: "US", }, coordinates: { latitude: 30.2672, longitude: -97.7431, }, }), }) const location = await response.json() ``` ```python response = requests.post( "https://api.voltra.sh/csms/v2/locations/", headers={"Authorization": f"Bearer {api_key}"}, json={ "name": "Downtown Parking Garage", "address": { "street": "123 Main St", "city": "Austin", "state": "TX", "postal_code": "78701", "country": "US", }, "coordinates": { "latitude": 30.2672, "longitude": -97.7431, }, }, ) location = response.json() ``` ### List Locations ```bash curl -X GET https://api.voltra.sh/csms/v2/locations/ \ -H "Authorization: Bearer $VOLTRA_API_KEY" ``` ```javascript const locations = await fetch("https://api.voltra.sh/csms/v2/locations/", { headers: { Authorization: `Bearer ${apiKey}` }, }).then((r) => r.json()) ``` ```python locations = requests.get( "https://api.voltra.sh/csms/v2/locations/", headers={"Authorization": f"Bearer {api_key}"}, ).json() ``` > **See also:** [Locations API Reference](/docs/api-reference/locations) for the full endpoint documentation. ## Next Steps - [Devices](/docs/Connect/devices) — Register chargers and assign them to locations - [Protocols](/docs/Connect/protocols) — Learn about the communication protocols your devices use --- ## Profiles URL: https://docs.voltra.com/docs/Connect/profiles # Profiles Device profiles define the capabilities and configuration of a charger. Voltra auto-discovers profile data during the device handshake, or you can create and manage profiles manually through the Console or API. ## How It Works When a charger first connects, Voltra queries its configuration keys and stores the results as a device profile. This profile captures everything the platform needs to understand what the device can do and how it behaves. ### Basic Information - **Vendor** — Manufacturer name - **Model** — Model identifier - **Serial Number** — Unique device serial - **Firmware Version** — Current firmware ### Connectors Each connector on the device is described by: | Property | Description | |-|-| | `connector_id` | Numeric identifier (1, 2, etc.) | | `type` | CCS1, CCS2, CHAdeMO, Type 2, etc. | | `power_rating` | Maximum kW output | | `voltage` | Operating voltage | | `current` | Maximum amperage | ### Capabilities Profiles indicate which OCPP features the charger supports: | Capability | Description | |-|-| | Smart Charging | Charging profile support | | Reservations | Can reserve connectors | | Remote Start | Start sessions via API | | Local Auth | RFID authorization | | Firmware Update | Over-the-air updates | ## Configuration Chargers have configurable settings accessed via OCPP `GetConfiguration` / `ChangeConfiguration`: ### Common Settings | Key | Description | |-|-| | `HeartbeatInterval` | How often charger sends heartbeat | | `ConnectionTimeout` | Time before dropping idle connection | | `MeterValueSampleInterval` | Frequency of meter readings | | `AuthorizeRemoteTxRequests` | Whether remote starts need auth | ### Auto-Discovery Voltra automatically discovers charger configuration during connection: 1. Charger connects and sends `BootNotification` 2. Voltra queries all configuration keys 3. Settings are stored in the device profile 4. Configuration becomes available via the API ## Managing Profiles via API ```bash # Get a charger's profile curl -X GET https://api.voltra.sh/csms/v2/chargers/CHARGER-001 \ -H "Authorization: Bearer $VOLTRA_API_KEY" # Update a charger's profile curl -X PATCH https://api.voltra.sh/csms/v2/chargers/CHARGER-001 \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Updated Charger Name", "metadata": { "floor": "2", "zone": "A" } }' ``` ```javascript // Get a charger's profile const profile = await fetch("https://api.voltra.sh/csms/v2/chargers/CHARGER-001", { headers: { Authorization: `Bearer ${apiKey}` }, }).then((r) => r.json()) // Update a charger's profile const updated = await fetch("https://api.voltra.sh/csms/v2/chargers/CHARGER-001", { method: "PATCH", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ name: "Updated Charger Name", metadata: { floor: "2", zone: "A" }, }), }).then((r) => r.json()) ``` ```python # Get a charger's profile profile = requests.get( "https://api.voltra.sh/csms/v2/chargers/CHARGER-001", headers={"Authorization": f"Bearer {api_key}"}, ).json() # Update a charger's profile updated = requests.patch( "https://api.voltra.sh/csms/v2/chargers/CHARGER-001", headers={"Authorization": f"Bearer {api_key}"}, json={ "name": "Updated Charger Name", "metadata": {"floor": "2", "zone": "A"}, }, ).json() ``` > **See also:** [Device Management API Reference](/docs/api-reference/device-management) for the full endpoint documentation. ## Next Steps - [Devices](/docs/Connect/devices) — Register and manage chargers - [Protocols](/docs/Connect/protocols) — Learn about OCPP configuration and features --- ## Protocols URL: https://docs.voltra.com/docs/Connect/protocols # Protocols Voltra supports industry-standard protocols for device communication. Connect translates each protocol into a unified device model, so the rest of the platform works the same regardless of how the physical device communicates. ## OCPP (Open Charge Point Protocol) OCPP is the open standard for communication between charging stations and central systems. It is the primary protocol for EV charger connectivity. ### OCPP 1.6 The most widely deployed version. **Supported Profiles:** | Profile | Description | |-|-| | Core | Basic charging operations | | Smart Charging | Charging profiles and power limits | | Remote Trigger | Trigger status updates | | Reservation | Reserve connectors | | Local Auth List | Offline authorization | | Firmware Management | OTA updates | **Transport:** WebSocket with JSON payloads **Connection URL Format:** ``` wss://ocpp.voltra.sh/ocpp/1.6/{chargeBoxId} ``` ### OCPP 2.0.1 The latest version with enhanced features. **Key Improvements:** - Device model with EVSE concept - ISO 15118 support (Plug & Charge) - Enhanced security (security profiles) - Improved smart charging - Better error reporting **Functional Blocks:** - Core - Advanced Security - Local Authorization - Smart Charging - Reservation - Remote Control - Availability - Transactions - Tariff & Cost - Diagnostics - Display Message - Firmware Management - ISO 15118 **Connection URL Format:** ``` wss://ocpp.voltra.sh/ocpp/2.0.1/{chargingStationId} ``` ## Protocol Selection | Factor | OCPP 1.6 | OCPP 2.0.1 | |-|-|-| | Device Support | Most chargers | Newer chargers | | Features | Standard | Advanced | | Security | Basic auth, TLS | Security profiles, certificates | | Complexity | Lower | Higher | ## Security ### TLS All connections use TLS encryption: - TLS 1.2 minimum - Certificate validation - Secure WebSocket (wss://) ### Authentication - **OCPP 1.6** — HTTP Basic Auth or TLS client certificates - **OCPP 2.0.1** — Security profiles with certificate-based auth ## Using OCPP via API Send raw OCPP messages to devices through the OCPP Raw Direct endpoints. This is useful for sending custom OCPP commands that are not covered by the higher-level device management API. ```bash # Send a raw OCPP message to a charger curl -X POST https://api.voltra.sh/csms/v2/chargers/CHARGER-001/ocpp/raw \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "action": "GetConfiguration", "payload": { "key": ["HeartbeatInterval", "MeterValueSampleInterval"] } }' # Trigger a remote status notification curl -X POST https://api.voltra.sh/csms/v2/chargers/CHARGER-001/ocpp/raw \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "action": "TriggerMessage", "payload": { "requestedMessage": "StatusNotification" } }' ``` ```javascript // Send a raw OCPP message to a charger const response = await fetch( "https://api.voltra.sh/csms/v2/chargers/CHARGER-001/ocpp/raw", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ action: "GetConfiguration", payload: { key: ["HeartbeatInterval", "MeterValueSampleInterval"], }, }), } ) const result = await response.json() ``` ```python # Send a raw OCPP message to a charger response = requests.post( "https://api.voltra.sh/csms/v2/chargers/CHARGER-001/ocpp/raw", headers={"Authorization": f"Bearer {api_key}"}, json={ "action": "GetConfiguration", "payload": { "key": ["HeartbeatInterval", "MeterValueSampleInterval"], }, }, ) result = response.json() ``` > **See also:** [OCPP Raw Direct API Reference](/docs/api-reference/ocpp-raw-direct) for the full endpoint documentation. ## Next Steps - [Devices](/docs/Connect/devices) — Register and manage chargers - [Profiles](/docs/Connect/profiles) — Understand device capabilities and configuration --- ## Telemetry URL: https://docs.voltra.com/docs/Platform/telemetry # Telemetry Telemetry is the time-series data flowing from connected devices -- power readings, energy measurements, temperature values, status events, and any other data point a device reports. Voltra ingests, stores, and indexes telemetry so you can query the latest values, analyze historical trends, and export data for external systems. ## How It Works Every data point in Voltra is identified by a **Voltra Resource Name (VRN)** that encodes the device and measurement path: ``` vrn:device:dev-001/data/power vrn:device:dev-001/data/energy vrn:device:dev-002/data/temperature ``` Each data point carries: | Property | Type | Description | |-|-|-| | `vrn` | string | Unique identifier for the measurement | | `timestamp` | datetime | When the value was recorded | | `value` | number, string, or boolean | The measurement value | | `quality` | enum | `good`, `uncertain`, or `bad` | ### Data Quality The `quality` field indicates how reliable a data point is: - **`good`** -- Value is within normal range and was received on time - **`uncertain`** -- Value may be stale or outside expected bounds - **`bad`** -- Value is known to be invalid (sensor fault, communication error) ## Querying Latest Values The most common query is "what is this device reading right now?" The latest-value endpoint returns the most recent data point for one or more VRNs in a single request. ## Querying Historical Data For trend analysis, query a time range with optional aggregation. You can: - Specify **start** and **end** times (ISO 8601) - Choose an **aggregation interval** (`1min`, `5min`, `15min`, `1h`, `1d`) - Apply an **aggregation function** (`avg`, `min`, `max`, `sum`, `count`, `first`, `last`) - Query **multiple VRNs** in a single request ## Exporting Data For bulk analysis or integration with external tools, export data as JSON or CSV. The export endpoint accepts the same query parameters as the history endpoint but returns a downloadable file. ## Managing Telemetry via API ### Get Latest Values ```bash curl -X POST https://api.voltra.sh/csms/v2/data/latest \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "vrns": [ "vrn:device:dev-001/data/power", "vrn:device:dev-001/data/energy" ] }' ``` ```javascript const response = await fetch("https://api.voltra.sh/csms/v2/data/latest", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ vrns: [ "vrn:device:dev-001/data/power", "vrn:device:dev-001/data/energy", ], }), }) const { data } = await response.json() data.forEach((point) => console.log(point.vrn, point.data.value)) ``` ```python response = requests.post( "https://api.voltra.sh/csms/v2/data/latest", headers={ "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", }, json={ "vrns": [ "vrn:device:dev-001/data/power", "vrn:device:dev-001/data/energy", ] }, ) for point in response.json()["data"]: print(point["vrn"], point["data"]["value"]) ``` ### Query Historical Data ```bash curl -X POST https://api.voltra.sh/csms/v2/data/query \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "vrns": ["vrn:device:dev-001/data/power"], "start": "2026-01-15T00:00:00Z", "end": "2026-01-15T12:00:00Z", "interval": "15min", "aggregation": "avg" }' ``` ```javascript const response = await fetch("https://api.voltra.sh/csms/v2/data/query", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ vrns: ["vrn:device:dev-001/data/power"], start: "2026-01-15T00:00:00Z", end: "2026-01-15T12:00:00Z", interval: "15min", aggregation: "avg", }), }) const { data } = await response.json() console.log(`${data.points.length} points returned`) ``` ```python response = requests.post( "https://api.voltra.sh/csms/v2/data/query", headers={ "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", }, json={ "vrns": ["vrn:device:dev-001/data/power"], "start": "2026-01-15T00:00:00Z", "end": "2026-01-15T12:00:00Z", "interval": "15min", "aggregation": "avg", }, ) result = response.json()["data"] print(f"{len(result['points'])} points returned") ``` ### Export Data as CSV ```bash curl -X POST https://api.voltra.sh/csms/v2/data/export \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "vrns": ["vrn:device:dev-001/data/power"], "start": "2026-01-14T00:00:00Z", "end": "2026-01-15T00:00:00Z", "format": "csv" }' \ -o power_data.csv ``` ```javascript const response = await fetch("https://api.voltra.sh/csms/v2/data/export", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ vrns: ["vrn:device:dev-001/data/power"], start: "2026-01-14T00:00:00Z", end: "2026-01-15T00:00:00Z", format: "csv", }), }) const csv = await response.text() ``` ```python response = requests.post( "https://api.voltra.sh/csms/v2/data/export", headers={ "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", }, json={ "vrns": ["vrn:device:dev-001/data/power"], "start": "2026-01-14T00:00:00Z", "end": "2026-01-15T00:00:00Z", "format": "csv", }, ) with open("power_data.csv", "w") as f: f.write(response.text) ``` ## Best Practices - **Use aggregation for large time ranges.** Querying raw data over days or weeks can return millions of points. Use `interval` and `aggregation` to downsample. - **Query multiple VRNs together** instead of making separate requests for each measurement. - **Check the `quality` field.** Uncertain or bad data points should be flagged in dashboards and excluded from calculations. - **Use CSV export** for integration with spreadsheets, data warehouses, and BI tools. ## Next Steps - [Devices](/docs/Connect/devices) -- Understand the devices producing telemetry - [Device Model](/docs/Connect/device-model) -- See how data points map to device properties - [Actions](/docs/Command/remote-operations) -- React to telemetry by sending device commands - [Workflows](/docs/Connect/workflows) -- Automate responses to telemetry events --- ## Tunnels URL: https://docs.voltra.com/docs/Connect/tunnels # Tunnels Tunnels provide secure VPN access to devices that sit behind firewalls, NAT, or private networks. When you need to remotely diagnose a device, access its local web interface, or perform firmware updates that require a direct connection, tunnels create a WireGuard VPN link between your machine and the device's network. ## How It Works Voltra provisions a WireGuard VPN tunnel between your client and a gateway co-located with the target device. The tunnel: 1. **Provisions** a VPN endpoint on Voltra's gateway infrastructure 2. **Generates** a WireGuard configuration file you download to your client 3. **Establishes** an encrypted point-to-point connection to the device network 4. **Routes** traffic so you can reach the device as if you were on its local network Once connected, you can SSH into the device, open its web UI in a browser, or run any IP-based tool directly. ### Tunnel Lifecycle ```mermaid stateDiagram-v2 [*] --> provisioning : POST /tunnels provisioning --> active : Gateway ready active --> active : Download config, connect active --> deprovisioning : DELETE /tunnels/:id deprovisioning --> [*] : Resources released ``` | State | Description | |-|-| | `provisioning` | Gateway is allocating VPN resources | | `active` | Tunnel is ready for connections | | `deprovisioning` | Tunnel is being torn down | ## Provisioning a Tunnel To create a tunnel, specify the target device or network segment. Voltra provisions the VPN endpoint and returns a tunnel ID. ## Downloading the VPN Config After provisioning, download the WireGuard configuration file. This file contains the private key, endpoint address, and allowed IPs needed to connect. The config file contains a private key. Treat it like a credential -- do not commit it to version control or share it over unencrypted channels. ## Listing Tunnel Devices Each tunnel can reach one or more devices on the target network. Use the devices endpoint to see which devices are accessible through a given tunnel. ## Managing Tunnels via API ### Provision a Tunnel ```bash curl -X POST https://api.voltra.sh/csms/v2/tunnels \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "device_id": "dev-001", "name": "Maintenance tunnel" }' ``` ```javascript const response = await fetch("https://api.voltra.sh/csms/v2/tunnels", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ device_id: "dev-001", name: "Maintenance tunnel", }), }) const { data } = await response.json() console.log(data.id) ``` ```python response = requests.post( "https://api.voltra.sh/csms/v2/tunnels", headers={ "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", }, json={"device_id": "dev-001", "name": "Maintenance tunnel"}, ) tunnel_id = response.json()["data"]["id"] ``` ### Download WireGuard Config ```bash curl -X GET "https://api.voltra.sh/csms/v2/tunnels/$TUNNEL_ID/config" \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -o tunnel.conf ``` ```javascript const response = await fetch( `https://api.voltra.sh/csms/v2/tunnels/${tunnelId}/config`, { headers: { Authorization: `Bearer ${apiKey}` }, } ) const config = await response.text() // Save to tunnel.conf ``` ```python response = requests.get( f"https://api.voltra.sh/csms/v2/tunnels/{tunnel_id}/config", headers={"Authorization": f"Bearer {api_key}"}, ) with open("tunnel.conf", "w") as f: f.write(response.text) ``` ### Deprovision a Tunnel ```bash curl -X DELETE "https://api.voltra.sh/csms/v2/tunnels/$TUNNEL_ID" \ -H "Authorization: Bearer $VOLTRA_API_KEY" ``` ```javascript const response = await fetch( `https://api.voltra.sh/csms/v2/tunnels/${tunnelId}`, { method: "DELETE", headers: { Authorization: `Bearer ${apiKey}` }, } ) ``` ```python response = requests.delete( f"https://api.voltra.sh/csms/v2/tunnels/{tunnel_id}", headers={"Authorization": f"Bearer {api_key}"}, ) ``` ## Best Practices - **Deprovision tunnels when done.** Active tunnels consume gateway resources. Clean up after maintenance sessions. - **Rotate tunnel credentials** for long-lived tunnels by deprovisioning and re-provisioning periodically. - **Restrict tunnel access** to operators who need direct device connectivity. Most operations are better served by the Actions API. ## Next Steps - [Devices](/docs/Connect/devices) -- Understand the devices you connect to - [Actions](/docs/Command/remote-operations) -- Send remote commands without a VPN - [Protocols](/docs/Connect/protocols) -- Learn about device communication protocols --- ## Workflows URL: https://docs.voltra.com/docs/Connect/workflows # Workflows Workflows are automated sequences that orchestrate device actions, conditional logic, and integrations. You define a trigger, a series of steps, and an error strategy -- Voltra executes the workflow whenever the trigger fires. Workflows eliminate manual coordination across devices and let you build reliable automation for energy operations. ## How It Works A workflow consists of three parts: 1. **Trigger** -- what starts the workflow (an event, a schedule, a webhook, or manual invocation) 2. **Steps** -- the ordered sequence of operations to perform 3. **Error strategy** -- what happens when a step fails (`rollback`, `continue`, or `stop`) When a trigger fires, Voltra creates a **workflow run** that tracks the execution of each step. You can monitor runs in real time and cancel them if needed. ### Trigger Types | Trigger | Description | Example | |-|-|-| | `event` | Fires when a matching device event occurs | `device:*/alerts/high_temp` | | `schedule` | Fires on a cron schedule | `0 */6 * * *` (every 6 hours) | | `webhook` | Fires when an external system calls a URL | Third-party integration callbacks | | `manual` | Fires only when explicitly invoked via API | On-demand maintenance tasks | ### Step Types Workflows support these step types: | Step | Description | |-|-| | `device_action` | Execute an action on a device | | `conditional` | Branch based on a condition expression | | `delay` | Wait for a specified duration | | `webhook` | Call an external HTTP endpoint | | `set_variable` | Set a variable for use in later steps | | `parallel` | Execute multiple steps concurrently | | `log` | Write a message to the workflow run log | ### Workflow Run Lifecycle ```mermaid stateDiagram-v2 [*] --> pending pending --> running : Execution starts running --> completed : All steps succeed running --> failed : Step fails (stop/rollback) running --> cancelled : User cancels ``` | Status | Description | |-|-| | `pending` | Run created, waiting to start | | `running` | Steps are executing | | `completed` | All steps finished successfully | | `failed` | A step failed and error strategy applied | | `cancelled` | Run was cancelled by a user | ## Creating a Workflow Define a workflow with a trigger, steps, and error handling: ```json { "id": "wf-temp-response", "name": "Temperature Response", "trigger": { "type": "event", "source": "device:*/alerts/high_temp" }, "steps": [ { "type": "log", "message": "High temperature alert received" }, { "type": "device_action", "device_id": "hvac-001", "action": "setCooling", "params": { "level": "high" } } ], "timeout": 300000, "on_error": "rollback" } ``` ## Monitoring Workflow Runs Each workflow run records: - The trigger that started it - Input and output data - Per-step execution results - Duration and timestamps - Error details if the run failed ## Managing Workflows via API ### Create a Workflow ```bash curl -X POST https://api.voltra.sh/csms/v2/workflows \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "id": "wf-temp-response", "name": "Temperature Response", "trigger": { "type": "event", "source": "device:*/alerts/high_temp" }, "steps": [ { "type": "log", "message": "High temp alert" }, { "type": "device_action", "device_id": "hvac-001", "action": "setCooling", "params": { "level": "high" } } ], "on_error": "rollback" }' ``` ```javascript const response = await fetch("https://api.voltra.sh/csms/v2/workflows", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ id: "wf-temp-response", name: "Temperature Response", trigger: { type: "event", source: "device:*/alerts/high_temp" }, steps: [ { type: "log", message: "High temp alert" }, { type: "device_action", device_id: "hvac-001", action: "setCooling", params: { level: "high" } }, ], on_error: "rollback", }), }) const { data } = await response.json() ``` ```python response = requests.post( "https://api.voltra.sh/csms/v2/workflows", headers={ "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", }, json={ "id": "wf-temp-response", "name": "Temperature Response", "trigger": {"type": "event", "source": "device:*/alerts/high_temp"}, "steps": [ {"type": "log", "message": "High temp alert"}, {"type": "device_action", "device_id": "hvac-001", "action": "setCooling", "params": {"level": "high"}}, ], "on_error": "rollback", }, ) workflow = response.json()["data"] ``` ### List Workflow Runs ```bash curl -X GET "https://api.voltra.sh/csms/v2/workflows/$WORKFLOW_ID/runs?status=running" \ -H "Authorization: Bearer $VOLTRA_API_KEY" ``` ```javascript const response = await fetch( `https://api.voltra.sh/csms/v2/workflows/${workflowId}/runs?status=running`, { headers: { Authorization: `Bearer ${apiKey}` }, } ) const { data } = await response.json() ``` ```python response = requests.get( f"https://api.voltra.sh/csms/v2/workflows/{workflow_id}/runs", params={"status": "running"}, headers={"Authorization": f"Bearer {api_key}"}, ) runs = response.json()["data"] ``` ### Execute a Workflow Manually ```bash curl -X POST "https://api.voltra.sh/csms/v2/workflows/$WORKFLOW_ID/execute" \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "inputs": { "device_id": "dev-001", "target_temp": 72 } }' ``` ```javascript const response = await fetch( `https://api.voltra.sh/csms/v2/workflows/${workflowId}/execute`, { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ inputs: { device_id: "dev-001", target_temp: 72 }, }), } ) const { data } = await response.json() console.log(data.execution_id, data.status) ``` ```python response = requests.post( f"https://api.voltra.sh/csms/v2/workflows/{workflow_id}/execute", headers={ "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", }, json={"inputs": {"device_id": "dev-001", "target_temp": 72}}, ) run = response.json()["data"] ``` ## Best Practices - **Start with `on_error: "stop"`** during development so failures are immediately visible. - **Use `conditional` steps** to guard destructive actions with safety checks. - **Set reasonable timeouts.** The default is 5 minutes (300000 ms). Long-running workflows should use higher values. - **Monitor runs** for failed status and set up alerts for production workflows. ## Next Steps - [Actions](/docs/Command/remote-operations) -- Understand the commands workflows execute - [Telemetry](/docs/Platform/telemetry) -- Use telemetry events as workflow triggers - [Devices](/docs/Connect/devices) -- Learn about the devices workflows control - [Protocols](/docs/Connect/protocols) -- Understand how commands reach devices --- ## Developer Resources URL: https://docs.voltra.com/docs/Developer # Developer Resources Resources for developers building on the Voltra platform. ## Getting Started - [API Overview](/docs/Platform/api) - REST API patterns and authentication - [API Keys](/docs/Developer/api-keys) - Creating and managing API credentials - [Quickstart](/docs/Overview/quickstart) - Get up and running quickly ## Reference - [API Reference](/api) - Complete API documentation - [Versioning](/docs/Developer/versioning) - API versioning and deprecation policy - [Changelog](/docs/Developer/changelog) - Release notes and updates ## Support - [Help Center](/docs/Developer/help-center) - FAQs and support resources - [Legal](/docs/Developer/legal) - Terms, privacy, and compliance ## SDKs & Tools Official SDKs are in development. Current API Reference includes samples for: - Python - Node.js - cURL - Java ## Community - GitHub: [github.com/voltra-energy](https://github.com/voltra-energy) - Contact: [developer@voltra.com](mailto:developer@voltra.com) --- ## API Keys URL: https://docs.voltra.com/docs/Developer/api-keys # API Keys API keys provide programmatic access to the Voltra platform. ## Key Types ### Project API Keys Scoped to a single project. Use for: - Application integrations - Automated scripts - CI/CD pipelines ### Organization API Keys Access across all projects in an organization. Use for: - Cross-project reporting - Organization-wide automation - Admin tools ## Creating API Keys 1. Navigate to **Project Settings** > **API Keys** 2. Click **Create API Key** 3. Enter a descriptive name 4. Select permissions/scopes 5. Click **Create** 6. **Copy the key immediately** - it won't be shown again ## Using API Keys Include the key in the Authorization header: ```bash curl -X GET "https://api.voltra.sh/csms/chargers" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## Key Permissions Assign minimum necessary permissions: | Scope | Access | |-------|--------| | `read:devices` | View chargers and status | | `write:devices` | Modify charger configuration | | `read:sessions` | View charging sessions | | `write:sessions` | Start/stop sessions | | `read:billing` | View pricing and transactions | | `write:billing` | Modify pricing policies | ## Key Management ### Rotating Keys 1. Create a new key with same permissions 2. Update your applications to use the new key 3. Verify new key works correctly 4. Delete the old key ### Revoking Keys 1. Navigate to **API Keys** 2. Find the key to revoke 3. Click **Delete** 4. Confirm deletion Revoked keys stop working immediately. ## Security Best Practices - **Never commit keys to version control** - Use environment variables for key storage - Rotate keys periodically - Use minimum necessary permissions - Monitor key usage for anomalies - Delete unused keys ## Rate Limiting API keys are subject to rate limits: - Default: 1000 requests per minute - Rate limit headers in responses - Contact support for higher limits ## Learn More - [API Overview](../Platform/api) - Using the API - [Security](../Platform/security) - Security practices --- ## Changelog URL: https://docs.voltra.com/docs/Developer/changelog # Changelog Recent updates and changes to the Voltra platform. ## 2024 ### January 2024 #### New Features - **Load Management**: New site and charger group management APIs - **Pricing Engine**: Support for time-of-use pricing schedules - **Data Bridge**: Added MQTT connector type #### Improvements - Improved WebSocket connection stability - Enhanced error messages across all APIs - Better pagination support for list endpoints #### Bug Fixes - Fixed meter value timestamp handling in OCPP 2.0.1 - Corrected rate limiting behavior for batch operations --- ## API Changes ### Breaking Changes *No breaking changes in the current version.* ### Deprecations *No current deprecations.* ### New Endpoints Recent endpoint additions: | Endpoint | Service | Description | |----------|---------|-------------| | `GET /sites` | Load Management | List sites | | `POST /charger-groups` | Load Management | Create charger group | | `GET /resolved-prices` | Pricing Engine | Get calculated prices | ## Subscribe to Updates - Watch our [GitHub repository](https://github.com/voltra-energy) for releases - Contact [developer@voltra.com](mailto:developer@voltra.com) for the developer newsletter --- ## Help Center URL: https://docs.voltra.com/docs/Developer/help-center # Help Center Resources and support for Voltra developers. ## Frequently Asked Questions ### Getting Started **How do I get API access?** 1. Create a Voltra account 2. Set up an organization and project 3. Generate API keys in project settings 4. Start making API calls **Which OCPP versions are supported?** Voltra supports OCPP 1.6 JSON and OCPP 2.0.1. See [Protocols](../Connect/protocols) for details. **How do I connect a charger?** Follow our [Quickstart Guide](../Overview/quickstart) for step-by-step instructions. ### API & Integration **What are the rate limits?** Default rate limit is 1000 requests per minute. Contact support for higher limits. **How do I handle API errors?** All errors return standard JSON format with error code and message. See [API Overview](../Platform/api) for error handling patterns. **Can I test in a sandbox environment?** Create a separate project for testing. Contact support for sandbox credentials if needed. ### Billing & Account **How is usage billed?** Contact [sales@voltra.com](mailto:sales@voltra.com) for pricing information. **How do I upgrade my plan?** Contact your account representative or [sales@voltra.com](mailto:sales@voltra.com). ## Contact Support ### Developer Support For API and integration questions: - Email: [developer@voltra.com](mailto:developer@voltra.com) - GitHub Issues: [github.com/voltra-energy](https://github.com/voltra-energy) ### General Support For account and billing questions: - Email: [support@voltra.com](mailto:support@voltra.com) ### Security Issues Report security vulnerabilities: - Email: [security@voltra.com](mailto:security@voltra.com) ## Status Check platform status at [status.voltra.com](https://status.voltra.com). --- ## Legal & Compliance URL: https://docs.voltra.com/docs/Developer/legal # Legal & Compliance Legal documentation and compliance information for the Voltra platform. ## Terms of Service The Voltra Terms of Service govern your use of the platform. - [Terms of Service](https://voltra.com/terms) - [API Terms of Use](https://voltra.com/api-terms) ## Privacy Policy How we collect, use, and protect your data. - [Privacy Policy](https://voltra.com/privacy) - [Cookie Policy](https://voltra.com/cookies) ## Data Processing ### Data Processing Agreement (DPA) For customers requiring a DPA: - Contact [legal@voltra.com](mailto:legal@voltra.com) - Available for enterprise customers - GDPR-compliant terms ### Data Residency - Primary processing in US - EU data residency available on request - Data export capabilities for portability ## Compliance Certifications | Certification | Status | Documentation | |--------------|--------|---------------| | SOC 2 Type II | Certified | Available on request | | GDPR | Compliant | DPA available | | PCI DSS | Compliant | For payment processing | ### Requesting Compliance Documents Contact [security@voltra.com](mailto:security@voltra.com) for: - SOC 2 reports - Penetration test summaries - Security questionnaire responses ## Acceptable Use The platform may not be used for: - Illegal activities - Circumventing security measures - Unauthorized data access - Service disruption attempts See Terms of Service for complete acceptable use policy. ## Contact ### Legal Questions - Email: [legal@voltra.com](mailto:legal@voltra.com) ### Security & Compliance - Email: [security@voltra.com](mailto:security@voltra.com) ### Data Protection Officer - Email: [dpo@voltra.com](mailto:dpo@voltra.com) --- ## Versioning URL: https://docs.voltra.com/docs/Developer/versioning # Versioning Voltra's API versioning policy ensures stability while allowing continued improvement. ## Current Version The current API version is **v1** (implied, not in URL path). ## Versioning Strategy ### URL Versioning Major version changes will be reflected in the URL path: ``` https://api.voltra.sh/v1/chargers (current) https://api.voltra.sh/v2/chargers (future major version) ``` ### Backward Compatibility Within a major version, we maintain backward compatibility: - New fields may be added to responses - New optional parameters may be added to requests - New endpoints may be added - Existing fields and endpoints will not be removed ## Deprecation Policy When breaking changes are necessary: 1. **Announcement**: Changes announced at least 6 months in advance 2. **Deprecation Period**: Old version remains available during transition 3. **Migration Guide**: Documentation provided for upgrading 4. **Sunset**: Old version retired after deprecation period ## Deprecation Notices Deprecated features are indicated in: - API responses (via headers) - API Reference documentation - Changelog announcements - Email notifications (for major changes) ## Checking API Version Response headers include version information: ``` X-API-Version: 1.0 X-Deprecation-Warning: This endpoint is deprecated. Use /v2/... instead. ``` ## Learn More - [Changelog](./changelog) - Recent changes - [API Reference](/api) - Current API documentation --- ## Welcome to Voltra URL: https://docs.voltra.com/docs/index # Welcome to Voltra Voltra is a comprehensive energy platform for managing devices, processing payments, balancing loads, and more. ## Getting Started - [Quickstart](/docs/Overview/quickstart) — Get up and running in minutes - [Account Setup](/docs/Overview/account-setup) — Create your organization and project - [API Reference](/api-reference) — Interactive API documentation ## Products - **Voltra Charge** — EV charging management and payment processing - **Voltra Grid** — Load management and VPP participation - **Voltra Otto** — Automated device operations - **Voltra EMS** — Energy management system - **Voltra Vantage** — Analytics and insights ## Platform - [Organizations](/docs/Platform/organizations) — Multi-tenant organization management - [Projects](/docs/Platform/projects) — Project-level resource isolation - [Access Control](/docs/Platform/access-control) — Role-based permissions - [EV Charging](/docs/Command) — Charging station operations and business logic - [Energy](/docs/Connect) — Connect energy assets to Voltra --- ## Integrations URL: https://docs.voltra.com/docs/Integrations # Integrations Voltra integrates with third-party systems to extend your charging infrastructure. Browse the catalog below to find the integration you need. ## Custom Integrations Build your own integrations using Voltra's platform APIs: - **REST API** -- Full programmatic access to all platform functionality - **Data Bridge** -- Configurable connectors for streaming events to external systems - **Webhooks** -- Real-time event notifications pushed to your endpoints ## Next Steps - [Data Bridge](/docs/Platform/data-bridge) -- Stream charging data to external systems - [API Keys](/docs/Getting-Started/api-keys) -- Set up authentication for API access - [Data Bridge](/docs/Platform/data-bridge) -- Stream data to external systems --- ## Available Integrations URL: https://docs.voltra.com/docs/Integrations/available-integrations # Available Integrations A catalog of pre-built integrations available in Voltra. ## Payment Providers ### Stripe Accept payments through Stripe. - **Status**: Available - **Category**: Payments - **Setup**: Connect your Stripe account in Payment Processing settings ## Carbon & Sustainability ### FuSE Earn carbon credits for EV charging. - **Status**: Available - **Category**: Carbon Credits - **Setup**: Enable in Integration Store, configure FuSE credentials ## Roaming Networks ### OCPI Hub Connections Connect to OCPI-compatible roaming networks. - **Status**: Available - **Category**: Roaming - **eMSPs**: See [eMSP Authentication](./OCPI/emsp-authentication) to get started - **CPOs**: See [Connect OCPI](../Connect/ocpi) to get started ## Coming Soon The following integrations are in development: | Integration | Category | Status | |-------------|----------|--------| | Additional payment providers | Payments | Planned | | Utility rate APIs | Energy | Planned | | Fleet management systems | Fleet | Planned | | Building management systems | Energy | Planned | ## Request an Integration Need an integration we don't have? Contact [developer@voltra.com](mailto:developer@voltra.com) with your requirements. ## Build Custom Integrations Use Voltra's APIs to build custom integrations: - [REST API Overview](../Platform/api) - [Data Bridge](../Services/DataBridge/) for data streaming - [Webhooks](#) for event notifications --- ## OCPI Integration URL: https://docs.voltra.com/docs/Integrations/OCPI # OCPI Integration Connect chargers to roaming networks. Display chargers on Apple and Google Maps. ## Getting Started To integrate with Voltra as an eMSP, you need to complete a one-time authentication process to establish credentials between your platform and ours. - [eMSP Authentication](./OCPI/emsp-authentication) - How to register and authenticate your eMSP platform - [CPO Authentication](../Connect/ocpi) - How to register and onboard your chargers onto roaming networks --- ## eMSP Authentication URL: https://docs.voltra.com/docs/Integrations/OCPI/emsp-authentication # eMSP Authentication Authenticate your eMSP platform with Voltra to access chargers on our network. This is a one-time registration process that follows the [OCPI credentials specification](https://github.com/ocpi/ocpi/blob/master/credentials.asciidoc). ## How It Works Authentication is a two-step process: you receive a **registration token** from Voltra, then exchange it for **permanent credentials**. | Step | Who | Action | |------|-----|--------| | 1 | Voltra | Creates a registration token and sends it to you | | 2 | You | Exchange the registration token for permanent credentials | After step 2, you use the permanent credentials for all future requests. ## Step 1: Receive Your Registration Token A Voltra team member creates a registration token and sends it to you directly (via email or another agreed channel). This is a manual, out-of-band step — there is no self-service registration. The registration token is a one-time use token. It may have an expiration date. If your token expires before you complete registration, contact Voltra to receive a new one. ## Step 2: Exchange Credentials Use your registration token to call the credentials endpoint. This exchanges the one-time token for permanent credentials. **Request:** ```http POST https://api.voltra.sh/ocpi/cpo/2.2.1/credentials Authorization: Token Content-Type: application/json { "token": "", "url": "https://your-platform.com/ocpi/versions", "roles": [ { "role": "EMSP", "business_details": { "name": "Your Company Name" }, "party_id": "YPC", "country_code": "US" } ] } ``` | Field | Description | |-------|-------------| | `token` | A token you generate for Voltra to authenticate with your platform | | `url` | Your OCPI versions endpoint URL | | `roles[].role` | Must be `EMSP` | | `roles[].business_details.name` | Your company name | | `roles[].party_id` | Your 3-character OCPI party ID | | `roles[].country_code` | Your 2-character ISO 3166-1 country code | **Response:** ```json { "status_code": 1000, "status_message": "Success", "data": { "token": "", "url": "https://api.voltra.sh/ocpi/versions", "roles": [ { "role": "CPO", "business_details": { "name": "Voltra" }, "party_id": "VOL", "country_code": "CA" } ] } } ``` Save the `token` from the response. This is your **permanent credential** for all future requests to Voltra. > **Important:** The permanent token is only returned once. Store it securely — Voltra cannot retrieve it later. ## Making Authenticated Requests Use the permanent token from step 2 in the `Authorization` header for all subsequent requests. ```http GET https://api.voltra.sh/ocpi/cpo/2.2.1/locations Authorization: Token ``` ## Troubleshooting | Problem | Cause | Solution | |---------|-------|----------| | `401 Unauthorized` on credential exchange | Registration token expired or already used | Contact Voltra for a new registration token | | `401 Unauthorized` on subsequent requests | Incorrect or missing token | Verify you are using the token from the credential exchange response, not the registration token | --- ## Welcome to Voltra URL: https://docs.voltra.com/docs/Overview # Welcome to Voltra Voltra is a cloud-native platform for connecting, managing, and monetizing EV charging infrastructure. Whether you are deploying a single charger or operating a fleet of thousands, Voltra gives you the connectivity, data, and business logic to run your network. ## What is Voltra? Voltra is organized into three areas: - **Platform** — Organizations, projects, access control, locations, security, telemetry, and data bridge. - **EV Charging** — Charge authorization, pricing, sessions, payments, load management, demand response, OCPI. - **Energy** — Device connectivity for batteries, solar inverters, meters. Modbus, DNP3, BACnet, MQTT, IEEE 2030.5. ## Next Steps - Follow the [Quickstart](/docs/Overview/quickstart) to connect your first device - Read about [Organizations and Projects](/docs/Platform/organizations) for multi-tenant setup - Explore the [Reference Architecture](/docs/Platform/reference-architecture) for a deeper look at the platform --- ## Account Setup URL: https://docs.voltra.com/docs/Overview/account-setup # Account Setup This guide walks you through setting up your Voltra account, creating your organization, and configuring your first project. ## Creating Your Account 1. Visit [voltra.com](https://voltra.com) and click **Get Started** 2. Enter your email address and create a password 3. Verify your email address 4. Complete your profile information ## Creating an Organization Organizations are the top-level container for all your Voltra resources. 1. After logging in, click **Create Organization** 2. Enter your organization name 3. Add organization details (address, contact info) 4. Click **Create** ## Setting Up Your First Project Projects help you organize resources within your organization. Common project structures include: - By location (e.g., "Downtown Garage", "Airport Terminal") - By customer (for CPO/eMSP setups) - By environment (e.g., "Production", "Staging") To create a project: 1. Navigate to **Projects** 2. Click **Create Project** 3. Enter the project name and description 4. Select which services to enable ## Enabling Services Voltra services can be enabled per-project. Common services include: | Service | Description | |---------|-------------| | Device Management | Core charger connectivity | | Payment Processing | Accept payments for charging | | Pricing Engine | Configure charging rates | | Load Management | Balance power across chargers | ## Inviting Team Members 1. Go to **Organization Settings** > **Members** 2. Click **Invite User** 3. Enter the user's email address 4. Select their role and permissions 5. Click **Send Invite** ## Managing Organizations and Projects via API You can also create organizations and projects programmatically. ### Create an Organization ```bash curl -X POST https://api.voltra.com/csms/v2/organization/ \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Acme Charging"}' ``` ```javascript const response = await fetch("https://api.voltra.com/csms/v2/organization/", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ name: "Acme Charging" }), }) const data = await response.json() console.log(data) ``` ```python import requests response = requests.post( "https://api.voltra.com/csms/v2/organization/", headers={"Authorization": f"Bearer {api_key}"}, json={"name": "Acme Charging"}, ) print(response.json()) ``` ### Create a Project ```bash curl -X POST https://api.voltra.com/csms/v2/projects/ \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Downtown Garage"}' ``` ```javascript const response = await fetch("https://api.voltra.com/csms/v2/projects/", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ name: "Downtown Garage" }), }) const data = await response.json() console.log(data) ``` ```python import requests response = requests.post( "https://api.voltra.com/csms/v2/projects/", headers={"Authorization": f"Bearer {api_key}"}, json={"name": "Downtown Garage"}, ) print(response.json()) ``` > **See also:** [Organizations API Reference](/api/Organizations) and [Projects API Reference](/api/Projects) for full endpoint documentation. ## Next Steps - Add your first charger with the [Quickstart](/docs/Overview/quickstart) - Configure [Access Control](/docs/Platform/access-control) for your team - Set up [API Keys](/docs/Getting-Started/api-keys) for programmatic access --- ## Quickstart URL: https://docs.voltra.com/docs/Overview/quickstart # Quickstart **What you'll do:** Connect a charger to Voltra and query its status via API. **Time:** 10 minutes. ## Prerequisites - A Voltra account ([sign up](https://console.voltra.com)) - An API key ([create one](/docs/Getting-Started/api-keys)) ## Step 1: Get Your API Key Open the [Voltra Console](https://console.voltra.com) and navigate to **Settings > API Keys**. Click **Create API Key**, give it a name, and copy the generated key. ![API key created successfully](/img/screenshots/api-key-created-successfully-modal.png) Copy your API key now. You will not be able to see it again after closing the modal. All API requests use the same authorization header: ``` Authorization: Bearer $VOLTRA_API_KEY ``` ## Step 2: List Your Devices Check what chargers already exist in your organization. ```bash curl -X GET https://api.voltra.com/csms/v2/chargers/ \ -H "Authorization: Bearer $VOLTRA_API_KEY" ``` ```javascript const response = await fetch("https://api.voltra.com/csms/v2/chargers/", { headers: { Authorization: `Bearer ${apiKey}` }, }) const data = await response.json() console.log(data) ``` ```python import requests response = requests.get( "https://api.voltra.com/csms/v2/chargers/", headers={"Authorization": f"Bearer {api_key}"}, ) print(response.json()) ``` **Expected response:** ```json { "success": true, "message": "Charge boxes retrieved successfully", "charge_boxes": [ { "charge_box_id": "CP001", "charger_name": "Main Parking Lot Charger", "status": "Available", "ocpp_protocol": "ocpp1.6J", "registration_status": "Accepted" } ] } ``` ## Step 3: Add a Device You can add a charger through the Console or the API. ### Using the Console 1. Navigate to **Devices** and click **Add Device** 2. Enter your charger's identifier (the `charge_box_id` printed on the device) ![Connect a new device modal](/img/screenshots/connect-a-new-device-modal.png) 3. Copy the generated OCPP WebSocket URL and password. Configure your charger to connect to this URL. ![OCPP link generated modal](/img/screenshots/ocpp-link-generated-modal.png) ### Using the API ```bash curl -X POST https://api.voltra.com/csms/v2/chargers/ \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "charge_box_id": "CP001", "charge_point_vendor": "EVBox", "charge_point_model": "Elvi" }' ``` ```javascript const response = await fetch("https://api.voltra.com/csms/v2/chargers/", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ charge_box_id: "CP001", charge_point_vendor: "EVBox", charge_point_model: "Elvi", }), }) const data = await response.json() console.log(data) ``` ```python import requests response = requests.post( "https://api.voltra.com/csms/v2/chargers/", headers={"Authorization": f"Bearer {api_key}"}, json={ "charge_box_id": "CP001", "charge_point_vendor": "EVBox", "charge_point_model": "Elvi", }, ) print(response.json()) ``` **Expected response:** ```json { "success": true, "message": "Successfully added charger(s)", "charger": { "charge_box_id": "CP001", "charge_point_vendor": "EVBox", "charge_point_model": "Elvi", "registration_status": "Pending", "organization_id": "123e4567-e89b-12d3-a456-426614174000" }, "password": "abc123def456" } ``` The `password` field is the OCPP security credential for the charger. Configure it in your charger's central system settings along with the WebSocket URL. ## Step 4: Monitor Device Status Once your charger connects, query its status by shortcode. ```bash curl -X GET https://api.voltra.com/csms/v2/chargers/C7LVNSNL \ -H "Authorization: Bearer $VOLTRA_API_KEY" ``` ```javascript const shortcode = "C7LVNSNL" const response = await fetch( `https://api.voltra.com/csms/v2/chargers/${shortcode}`, { headers: { Authorization: `Bearer ${apiKey}` }, } ) const data = await response.json() console.log(data) ``` ```python import requests shortcode = "C7LVNSNL" response = requests.get( f"https://api.voltra.com/csms/v2/chargers/{shortcode}", headers={"Authorization": f"Bearer {api_key}"}, ) print(response.json()) ``` **Expected response:** ```json { "success": true, "charger": { "charge_box_id": "CP001", "charger_name": "Main Parking Lot Charger", "status": "Available", "ocpp_protocol": "ocpp1.6J", "registration_status": "Accepted" } } ``` A `status` of `Available` means the charger is online and ready for a charging session. ## What You Built In this quickstart you: - Authenticated with the Voltra API using an API key - Listed all chargers in your organization - Registered a new charger via Console or API - Queried a specific charger's real-time status Your charger is now connected to Voltra's **Connect** layer and reporting its status in real time. ## Next Steps - [Devices](/docs/Connect/devices) — Learn how device registration, protocols, and status reporting work - [Organizations](/docs/Platform/organizations) — Set up multi-tenant access for your team - [API Reference](/api) — Full endpoint documentation for every Voltra API --- ## Platform Overview URL: https://docs.voltra.com/docs/Platform # Platform Overview The Platform layer is the foundation beneath every Voltra capability. It owns the tenancy boundary, identity model, and permission system that all other layers depend on. Whether you are connecting devices, routing data, or executing business logic, the Platform layer determines **who** can act and **where** those actions take effect. ## What the Platform Provides - **Multi-tenancy** -- every API call is scoped to an organization, ensuring complete data isolation between business entities. - **Identity** -- users, API keys, and service accounts are first-class objects with auditable lifecycles. - **Access control** -- role-based policies govern what each identity can read, write, or execute at the organization, project, or resource level. ## Resource Hierarchy All resources in Voltra live inside a two-level ownership hierarchy: ``` Organization (tenant boundary) └── Project (resource isolation) ├── Devices ├── Locations ├── Configurations └── API Keys (project-scoped) ``` **Organizations** represent a business entity -- a charge point operator, fleet manager, or managed-service provider. They are the billing boundary and the outermost security perimeter. **Projects** subdivide an organization into logical groups. Common patterns include one project per physical site, one per environment (production / staging), or one per end customer in a white-label deployment. ## Key Concepts | Concept | Purpose | |-|-| | [Organizations](/docs/Platform/organizations) | Tenant boundary, billing, and member management | | [Projects](/docs/Platform/projects) | Resource grouping and service enablement | | [Access Control](/docs/Platform/access-control) | Roles, policies, and granular permissions | | [Reference Architecture](/docs/Platform/reference-architecture) | System design and deployment patterns | | [Security](/docs/Platform/security) | Authentication, encryption, and compliance | ## Next Steps - [Organizations](/docs/Platform/organizations) -- understand the top-level tenant model - [Projects](/docs/Platform/projects) -- learn how to isolate resources within an org - [Access Control](/docs/Platform/access-control) -- configure who can do what --- ## Access Control URL: https://docs.voltra.com/docs/Platform/access-control # Access Control Voltra provides role-based access control (RBAC) to manage who can do what within your organization and projects. ## Core Concepts ### Roles Roles are named collections of permissions. Common roles include: | Role | Description | |-|-| | Owner | Full access to organization and all projects | | Accountant | Access to billing, invoices, and financial reports | | Charge Point Operator | Day-to-day operations (manage chargers, view status, start sessions) | ### Policies Policies define specific permissions that can be: - Assigned directly to users - Grouped into roles - Scoped to specific resources ### Permissions Granular actions users can perform: - `devices:read` - View charger information - `devices:write` - Modify charger configuration - `sessions:start` - Initiate charging sessions - `billing:manage` - Access billing settings ## Permission Scopes Permissions can be scoped at different levels: ``` Organization Level └── Applies to all projects Project Level └── Applies to specific project only Resource Level └── Applies to specific resources (chargers, locations) ``` ## Managing Access ### Assigning Roles 1. Go to **Organization Settings** > **Members** 2. Select a user 3. Click **Assign Role** 4. Choose the role and scope 5. Save changes ### Creating Custom Roles 1. Go to **Organization Settings** > **Roles** 2. Click **Create Role** 3. Name the role and add description 4. Select permissions to include 5. Save the role ### Auditing Access - View all role assignments in **Access Control** settings - Check user permissions with the validation API - Review audit logs for permission-related events ## Best Practices - **Principle of Least Privilege**: Grant minimum necessary permissions - **Use Roles**: Prefer roles over individual permission assignments - **Regular Review**: Audit access periodically - **Document Custom Roles**: Keep records of what custom roles are for ## Managing Access Control via API ```bash # List permissions for the current user curl -X GET https://api.voltra.com/csms/v2/access-control/permission \ -H "Authorization: Bearer $VOLTRA_API_KEY" # Create an access control policy curl -X POST https://api.voltra.com/csms/v2/access-control/policy \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Site Operator", "permissions": ["devices:read", "devices:write", "sessions:start"] }' ``` ```javascript const headers = { Authorization: `Bearer ${apiKey}` } // List permissions for the current user const permissions = await fetch( "https://api.voltra.com/csms/v2/access-control/permission", { headers } ) // Create an access control policy const policy = await fetch( "https://api.voltra.com/csms/v2/access-control/policy", { method: "POST", headers: { ...headers, "Content-Type": "application/json" }, body: JSON.stringify({ name: "Site Operator", permissions: ["devices:read", "devices:write", "sessions:start"], }), } ) ``` ```python import requests headers = {"Authorization": f"Bearer {api_key}"} # List permissions for the current user permissions = requests.get( "https://api.voltra.com/csms/v2/access-control/permission", headers=headers, ) # Create an access control policy policy = requests.post( "https://api.voltra.com/csms/v2/access-control/policy", headers=headers, json={ "name": "Site Operator", "permissions": ["devices:read", "devices:write", "sessions:start"], }, ) ``` > **See also:** [Access Control API Reference](/docs/api-reference/access-control) for the full endpoint documentation. ## Next Steps - [Organizations](/docs/Platform/organizations) -- organization-level access boundaries - [Projects](/docs/Platform/projects) -- project-level access scoping - [Security](/docs/Platform/security) -- authentication, encryption, and compliance --- ## Organizations URL: https://docs.voltra.com/docs/Platform/organizations # Organizations Organizations are the top-level container in Voltra's multi-tenant architecture. They represent a business entity such as a charge point operator, fleet manager, or property owner. ## Organization Structure ``` Organization ├── Organization Details (address, contact info) ├── Members (users with access) ├── Projects │ ├── Project A (Production) │ │ ├── Services │ │ └── Resources (chargers, locations, etc.) │ └── Project B (Staging) │ ├── Services │ └── Resources └── Billing & Subscription ``` ## Key Concepts ### Multi-tenancy Each organization is fully isolated: - Separate data storage - Independent configuration - Dedicated API credentials - Isolated user access ### Organization Details Organizations can store: - Legal business name - Billing and mailing addresses - Contact information - Tax identifiers ### Member Management Control who has access to your organization: - Invite users by email - Assign roles and permissions - Remove access when needed - Track member activity ## Common Patterns ### Single Organization Most operators use a single organization with multiple projects: - One project per site or region - Shared team access across projects - Centralized billing ### Multiple Organizations Managed service providers may use multiple organizations: - One organization per end customer - Separate billing per organization - White-label deployments ## Managing Organizations via API ```bash # List all organizations curl -X GET https://api.voltra.com/csms/v2/organization/ \ -H "Authorization: Bearer $VOLTRA_API_KEY" # Create an organization curl -X POST https://api.voltra.com/csms/v2/organization/ \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "ACME Charging", "country": "US" }' ``` ```javascript const headers = { Authorization: `Bearer ${apiKey}` } // List all organizations const orgs = await fetch("https://api.voltra.com/csms/v2/organization/", { headers, }) // Create an organization const newOrg = await fetch("https://api.voltra.com/csms/v2/organization/", { method: "POST", headers: { ...headers, "Content-Type": "application/json" }, body: JSON.stringify({ name: "ACME Charging", country: "US", }), }) ``` ```python import requests headers = {"Authorization": f"Bearer {api_key}"} # List all organizations orgs = requests.get( "https://api.voltra.com/csms/v2/organization/", headers=headers, ) # Create an organization new_org = requests.post( "https://api.voltra.com/csms/v2/organization/", headers=headers, json={ "name": "ACME Charging", "country": "US", }, ) ``` > **See also:** [Organizations API Reference](/docs/api-reference/organizations) for the full endpoint documentation. ## Next Steps - [Projects](/docs/Platform/projects) -- organize resources within an organization - [Access Control](/docs/Platform/access-control) -- manage member permissions - [Security](/docs/Platform/security) -- authentication and encryption --- ## Projects URL: https://docs.voltra.com/docs/Platform/projects # Projects Projects are containers within an organization that group related resources and services. They provide logical separation for different sites, environments, or use cases. ## What Projects Contain - **Devices**: Chargers registered to the project - **Locations**: Physical sites with chargers - **Services**: Enabled capabilities (pricing, payments, etc.) - **Configuration**: Project-specific settings ## Common Project Structures ### By Location ``` Organization: ACME Charging ├── Project: Downtown Garage ├── Project: Airport Terminal A └── Project: Corporate Campus ``` ### By Environment ``` Organization: ACME Charging ├── Project: Production ├── Project: Staging └── Project: Development ``` ### By Customer (for MSPs) ``` Organization: Managed Services Co ├── Project: Customer A - Sites ├── Project: Customer B - Sites └── Project: Customer C - Sites ``` ## Services Each project can enable different services based on needs: | Service | Description | |-|-| | Device Management | Core charger connectivity | | Locations | Site and location management | | Charge Authorization | Driver and RFID management | | Payment Processing | Payment collection | | Pricing Engine | Rate configuration | | Load Management | Site power balancing | | Data Bridge | External integrations | ### Enabling Services 1. Navigate to **Project Settings** > **Services** 2. Click **Enable** on the desired service 3. Accept any terms of service if required 4. Configure service-specific settings ## Project Settings - **Name and Description**: Identify the project - **Default Configuration**: Default settings for new resources - **Webhooks**: Project-level event notifications - **API Keys**: Project-scoped credentials ## Managing Projects via API ```bash # List all projects curl -X GET https://api.voltra.com/csms/v2/projects/ \ -H "Authorization: Bearer $VOLTRA_API_KEY" # Create a project curl -X POST https://api.voltra.com/csms/v2/projects/ \ -H "Authorization: Bearer $VOLTRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Downtown Garage", "description": "Production site for downtown parking structure" }' ``` ```javascript const headers = { Authorization: `Bearer ${apiKey}` } // List all projects const projects = await fetch("https://api.voltra.com/csms/v2/projects/", { headers, }) // Create a project const newProject = await fetch("https://api.voltra.com/csms/v2/projects/", { method: "POST", headers: { ...headers, "Content-Type": "application/json" }, body: JSON.stringify({ name: "Downtown Garage", description: "Production site for downtown parking structure", }), }) ``` ```python import requests headers = {"Authorization": f"Bearer {api_key}"} # List all projects projects = requests.get( "https://api.voltra.com/csms/v2/projects/", headers=headers, ) # Create a project new_project = requests.post( "https://api.voltra.com/csms/v2/projects/", headers=headers, json={ "name": "Downtown Garage", "description": "Production site for downtown parking structure", }, ) ``` > **See also:** [Projects API Reference](/docs/api-reference/projects) for the full endpoint documentation. ## Next Steps - [Organizations](/docs/Platform/organizations) -- parent container for projects - [Access Control](/docs/Platform/access-control) -- control who can access project resources - [Security](/docs/Platform/security) -- authentication and encryption --- ## Reference Architecture URL: https://docs.voltra.com/docs/Platform/reference-architecture # Reference Architecture The Voltra platform is built on a layered architecture designed for scalability, reliability, and flexibility. This page explains how the platform is structured and how data flows through the system. ## Architecture Overview Voltra consists of three interconnected layers, each with distinct responsibilities:
```mermaid flowchart TB subgraph CMD["COMMAND — Business Logic"] direction LR C1["Pricing"] C2["Payments"] C3["Authorization"] C4["Load Management"] end subgraph CDT["CONDUIT — Data Routing"] direction LR B1["Event Router"] B2["Data Bridge"] B3["Webhooks"] end subgraph CNT["CONNECT — Device Communication"] direction LR A1["Device Gateway"] A2["Protocol Handlers"] A3["Device Registry"] end EXT["Your Applications & Integrations"] <--> CMD CMD <--> CDT CDT <--> CNT CDT <-.->|"Data Streaming"| EXT CNT <--> DEV["EV Chargers & Devices"] ```
## The Three Layers ### Connect Connect is the foundation of the platform. It maintains persistent connections with your charging devices, translates protocols (OCPP 1.6 and 2.0.1), and manages device identity and configuration. All device communication flows through Connect, which handles reliability concerns like reconnection and message queuing automatically. ### Conduit Conduit sits in the middle, routing data where it needs to go. It distributes events between platform components, streams data to external systems via configurable connectors, and delivers webhooks for event-driven integrations. Use Conduit's Data Bridge to push charging data to your analytics platforms or custom applications. ### Command Command is where business logic lives. It provides the services that power your charging operations: authorizing drivers, processing payments, calculating prices, and balancing load across chargers. Command services are organized into product families—Volta Charge for charging operations and Volta Grid for energy optimization. ## Multi-Tenancy Your data is isolated at every layer. Organizations have completely separate data storage, API credentials are scoped to organizations and projects, and resources belong to exactly one project. See [Organizations](./organizations) and [Projects](./projects) for details. ## Next Steps - [Connect](./connect) — Device connectivity details - [Conduit](./conduit) — Data routing and integrations - [Command](./command) — Business logic services --- ## Security URL: https://docs.voltra.com/docs/Platform/security # Security Voltra is built with security as a core principle. This page outlines our security practices and compliance certifications. ## Authentication ### API Authentication - **API Keys**: Project-scoped credentials for programmatic access - **Bearer Tokens**: JWT-based authentication for user sessions - **OAuth 2.0**: Third-party application authorization ### Device Authentication - **OCPP Basic Auth**: Username/password for charger connections - **Certificate-based**: TLS client certificates for enhanced security - **Credential Rotation**: Automated and manual credential refresh ## Authorization ### Role-Based Access Control - Granular permissions system - Custom role creation - Resource-level access control - See [Access Control](./access-control) for details ### API Scopes - Fine-grained API permissions - Least-privilege key creation - Scope validation on every request ## Data Protection ### Encryption in Transit - TLS 1.2+ for all connections - OCPP over Secure WebSocket (wss://) - Certificate validation enforced ### Encryption at Rest - AES-256 encryption for stored data - Encrypted database storage - Secure key management ### Data Isolation - Tenant data isolation - Logical separation between organizations - No cross-tenant data access ## Compliance ### Certifications | Certification | Status | |--------------|--------| | SOC 2 Type II | Certified | | GDPR | Compliant | | PCI DSS | Compliant (for payment processing) | ### Data Residency - Data processing region selection - EU data residency options - Data export capabilities ## Security Practices - Regular security audits - Penetration testing - Vulnerability scanning - Incident response procedures - Security awareness training ## Reporting Security Issues Report security vulnerabilities to [security@voltra.com](mailto:security@voltra.com). ## Learn More - [Access Control](./access-control) - Permission management - [API Keys](../Developer/api-keys) - Credential management - [Legal](../Developer/legal) - Compliance documentation --- ## Products Overview URL: https://docs.voltra.com/docs/Products # Products Overview Voltra's platform capabilities are packaged into products designed for specific use cases. Each product combines multiple services to deliver complete solutions. ## Our Products | Product | Description | |---------|-------------| | [Charge](./charge) | Complete EV charging station management | | [Otto](./otto) | Driver-facing mobile experience | | [Grid](./grid) | Energy and load optimization | | [EMS](./ems) | Enterprise Energy Management System | | [Vantage](./vantage) | AI-powered operations platform | ## How Products and Services Relate Products are built on top of platform services: ``` ┌─────────────────────────────────────────────────┐ │ PRODUCTS │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌────────┐│ │ │ Charge │ │ Otto │ │ Grid │ │ EMS ││ │ └─────────┘ └─────────┘ └─────────┘ └────────┘│ ├─────────────────────────────────────────────────┤ │ SERVICES │ │ Device Mgmt │ Pricing │ Payments │ Load Mgmt │ │ Auth │ Locations │ Data Bridge │ QR Manager │ ├─────────────────────────────────────────────────┤ │ PLATFORM │ │ Connect │ Conduit │ Command │ └─────────────────────────────────────────────────┘ ``` ## Choosing a Product - **Charge Point Operators**: Start with Charge for station management - **Fleet Managers**: Combine Charge with Grid for depot charging - **Energy Providers**: Use Grid and EMS for energy optimization - **Developers**: Use individual services via API for custom solutions --- ## Charge URL: https://docs.voltra.com/docs/Products/charge # Charge Volta Charge is Voltra's complete EV charging station management product. It provides everything you need to deploy, operate, and monetize a charging network. ## Key Features ### Station Management - Connect chargers from any OCPP-compatible vendor - Real-time monitoring and status updates - Remote operations (start/stop, reset, unlock) - Firmware management and diagnostics ### Driver Experience - Mobile app and RFID authorization - Reservation system - Session history and receipts - Multiple payment options ### Pricing & Payments - Flexible pricing models (per-kWh, per-minute, flat rate) - Time-of-use pricing - Payment processing integration - Invoicing and billing ### Operations - Dashboard for network overview - Alerts and notifications - Maintenance scheduling - Usage analytics and reporting ## Powered By Charge combines these platform services: - [Device Management](../Services/DeviceManagement/) - [Locations](../Services/Locations/) - [Charge Authorization](../Services/ChargeAuthorization/) - [Payment Processing](../Services/PaymentProcessing/) - [Pricing Engine](../Services/PricingEngine/) - [QR Code Manager](../Services/QRCodeManager/) ## Who Uses Charge - Charge Point Operators (CPOs) - Property owners with EV charging - Workplace charging programs - Retail and hospitality venues - Fleet operators ## Getting Started 1. [Set up your account](../Overview/account-setup) 2. [Add your first charger](../Overview/quickstart) 3. Configure [pricing policies](../Services/PricingEngine/) 4. Enable [payment processing](../Services/PaymentProcessing/) --- ## EMS URL: https://docs.voltra.com/docs/Products/ems # EMS The Voltra Energy Management System (EMS) provides enterprise-level energy optimization across your entire facility, integrating EV charging with building loads, solar, storage, and grid connections. ## Key Features ### Holistic Energy Management - Unified view of all energy assets - EV charging integrated with building systems - Solar and storage coordination - Grid interconnection management ### Optimization Engine - Cost minimization algorithms - Peak demand reduction - Renewable energy maximization - Carbon footprint optimization ### Utility Integration - Rate schedule management - Demand response automation - Grid signal processing - Utility API connections ### Enterprise Controls - Multi-site management - Centralized policy configuration - Role-based access across facilities - Enterprise-wide reporting ## Architecture ``` ┌─────────────────────────────────────────────────┐ │ EMS │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │Optimizer│ │ Monitor │ │ Control │ │ │ └─────────┘ └─────────┘ └─────────┘ │ ├─────────────────────────────────────────────────┤ │ Connected Assets │ │ EV Chargers │ Solar │ Battery │ Building │ Grid│ └─────────────────────────────────────────────────┘ ``` ## Use Cases - Large commercial properties - Industrial facilities - University campuses - Hospital systems - Corporate headquarters ## Private Preview EMS is currently in private preview. Contact [sales@voltra.com](mailto:sales@voltra.com) to learn more about early access. --- ## Grid URL: https://docs.voltra.com/docs/Products/grid # Grid Volta Grid is Voltra's energy and load optimization product. It helps you manage power consumption across your charging infrastructure while maintaining driver satisfaction. ## Key Features ### Load Management - Site-level power limits - Dynamic load balancing across chargers - Priority-based charging allocation - Real-time power monitoring ### Smart Charging - Time-of-use optimization - Grid signal response - Demand charge management - Off-peak charging incentives ### VPP Participation - Virtual Power Plant integration - Demand response programs - Grid services revenue - Automated dispatch ### Energy Analytics - Consumption dashboards - Peak demand tracking - Cost optimization reports - Carbon impact metrics ## Powered By Grid combines these platform services: - [Load Management](../Services/LoadManagement/) - [Device Management](../Services/DeviceManagement/) ## Use Cases ### Fleet Depot Charging - Charge entire fleet within power limits - Optimize for departure schedules - Minimize demand charges - Track energy costs per vehicle ### Commercial Sites - Share power with building loads - Avoid infrastructure upgrades - Participate in utility programs - Reduce operating costs ### Grid Services - Provide grid balancing services - Earn demand response revenue - Support renewable integration - Meet sustainability goals ## Getting Started 1. [Add your chargers](../Overview/quickstart) 2. Configure [sites and load groups](../Services/LoadManagement/) 3. Set power limits and priorities 4. Monitor and optimize ## Learn More - [Load Management Service](../Services/LoadManagement/) - [Load Management API](/api/Command/VoltaGrid/LoadManagement) --- ## Otto URL: https://docs.voltra.com/docs/Products/otto # Otto Otto is Voltra's driver-facing mobile experience. It provides EV drivers with a seamless way to find, use, and pay for charging. ## Key Features ### Find Charging - Map-based charger discovery - Real-time availability status - Charger details and amenities - Navigation integration ### Start Charging - QR code scanning - Mobile app authorization - RFID card support - Plug and charge ### Pay for Charging - Stored payment methods - Pay-per-use options - Session receipts - Charging history ### Manage Account - Profile management - Payment method management - Notification preferences - Support access ## Integration with Charge Otto integrates seamlessly with Volta Charge: - Operators configure stations in Charge - Drivers access stations through Otto - Payments flow through Payment Processing - Authorization via Charge Authorization ## White-Label Options Otto can be white-labeled for: - Custom branding - Operator-specific apps - Fleet driver portals - Enterprise deployments ## For Developers Build custom driver experiences using our APIs: - [Device Management API](/api/DeviceConnectivity/DeviceManagement) - Station information - [Charging Sessions API](/api/Command/VoltaCharge/ChargingSessions) - Session data - [Payment Processing API](/api/Command/VoltaCharge/PaymentProcessing) - Payment handling ## Learn More Contact [sales@voltra.com](mailto:sales@voltra.com) for Otto availability and white-label options. --- ## Vantage URL: https://docs.voltra.com/docs/Products/vantage # Vantage Vantage is Voltra's AI-powered operations platform. It brings generative AI capabilities to your charging infrastructure, helping you work smarter and faster. ## Key Features ### Generative UI - AI-generated dashboards and reports - Natural language queries - Custom visualizations on demand - Automated insights ### Logging Analysis - AI-powered log parsing - Anomaly detection - Root cause analysis - Predictive maintenance alerts ### Code Generation - Integration code assistance - API usage examples - Configuration generation - Troubleshooting scripts ## How Vantage Works Vantage runs across the entire Voltra stack, providing AI assistance for: - **Operations**: "Show me chargers with connection issues this week" - **Analysis**: "Why did sessions drop at Site A yesterday?" - **Development**: "Generate Python code to fetch all offline chargers" - **Reporting**: "Create a monthly utilization report for stakeholders" ## Integration Vantage integrates with all Voltra services: - Device Management data - Charging session analytics - Load management metrics - Payment and revenue data ## Private Preview Vantage is currently in private preview as we continue to refine and expand its capabilities. If you're interested in early access or would like to learn more about how Vantage can enhance your operations, please reach out to [developer@voltra.com](mailto:developer@voltra.com). ## Learn More - [Vantage API Reference](/api/Vantage) - API documentation (coming soon) --- ## Services Overview URL: https://docs.voltra.com/docs/Services # Services Overview Services are the modular building blocks of the Voltra platform. Each service provides specific functionality that can be enabled per-project. ## Available Services ### Connect Layer | Service | Description | |---------|-------------| | [Device Management](./DeviceManagement/index) | Register, monitor, and control chargers | | [Locations](./Locations/index) | Manage physical sites and locations | ### Conduit Layer | Service | Description | |---------|-------------| | [Data Bridge](./DataBridge/index) | Stream data to external systems | ### Command Layer | Service | Description | |---------|-------------| | [Charge Authorization](./ChargeAuthorization/index) | Manage drivers and credentials | | [Payment Processing](./PaymentProcessing/index) | Accept and process payments | | [Pricing Engine](./PricingEngine/index) | Configure charging rates | | [Load Management](./LoadManagement/index) | Balance power across chargers | | [QR Code Manager](./QRCodeManager/index) | Generate and manage QR codes | | [Proxy](./Proxy/index) | Route OCPP messages | ## Enabling Services Services are enabled at the project level: 1. Navigate to your project 2. Go to **Settings** > **Services** 3. Click **Enable** on the desired service 4. Accept terms if prompted 5. Configure service settings ## Service Dependencies Some services require others: - Payment Processing requires Pricing Engine - Load Management requires Device Management - Charge Authorization requires Device Management Voltra automatically enables required dependencies. ## API Access Each service has its own API. See the [API Reference](/api) for complete documentation. --- ## About URL: https://docs.voltra.com/docs/Services/ChargeAuthorization # About Charger authentication gives you fine grained control over authorization methods for EV charging. ## Use Cases - **Fleets**: Vehicles can be granted charge authorization based on their vehicle ID (where compatible) - **Residential Complexes**: Residents can be granted free charging with their occupancy agreements. - **Commercial Offices**: Give your employees free charging. Offer your chargers up to visitors for paid charging after hours. ## Authorization Types - **Pin Code**: Offer unique pin codes for specific users to grant specific authorization. - **RFID**: Use RFID cards to authenticate users and authorize their charger. - **Guest Authorization**: Give visitors the option to charge their EV without an organization account. ## Try it Out Get started by [Creating an Authorization Policy](./creating-an-authorization-policy). --- ## Creating an Authorization Policy URL: https://docs.voltra.com/docs/Services/ChargeAuthorization/creating-an-authorization-policy # Creating an Authorization Policy Start by visiting the [Charge Authentication Page](https://console.voltra.com/dashboard/charge-authentication). ![Charge Authentication page](/img/screenshots/charge-authentication-page.png) Click on the "+ Add Authentication Policy" to open the "Add Authentication Policy" modal. Here is where you can fill out any complex pricing policies. ![Add Authentcation Policy modal](/img/screenshots/add-authentication-policy-modal.png) ## Pricing Policy Examples ### Employee / Guest Pricing Policies ```hcl import future.keywords.if # Default to deny unless explicitly allowed default allow = false # Allow employees - they get free charging allow if { input.user.type == "employee" } # Allow guests - they will be charged allow if { input.user.type == "guest" } # Billing strategy: free for employees, driver pays for guests billing_strategy := "bypass" if { input.user.type == "employee" } override_per_unit_price := 0 if { input.user.type == "employee" } billing_strategy := "driver_pays" if { input.user.type == "guest" } # Contextual metadata about the decision context := { "policy": "employee_guest", "user_type": input.user.type, "payment_method": input.user.payment_method, "timestamp": input.timestamp } # Denial reason for registered customers or other user types denial_reason := "Access denied: Only employees and guests are permitted" if { not allow } ``` ### Enforce Preauthorization Limits for Different Users ```hcl package authorization.spending_limits import future.keywords.if default allow = false # Guests have a lower pre-auth limit ($50) allow if { input.user.type == "guest" input.pre_auth_amount <= 5000 # Assuming cents } # Registered customers have medium limit ($200) allow if { input.user.type == "registered_customer" input.pre_auth_amount <= 20000 } # Employees have no limit allow if { input.user.type == "employee" } billing_strategy := "driver_pays" if { allow input.user.type == "guest" } billing_strategy := "driver_pays" if { allow input.user.type == "registered_customer" } billing_strategy := "bypass" if { allow input.user.type == "employee" } override_per_unit_price := 0 if { allow input.user.type == "employee" } denial_reason := sprintf("Pre-authorization amount $%.2f exceeds limit for %s users", [input.pre_auth_amount / 100, input.user.type]) if { not allow } ``` ### Charger Specific VIP Access ```hcl package authorization.vip_chargers import future.keywords.if default allow = false vip_chargers := { "charger-vip-001", "charger-vip-002", "charger-executive-parking" } is_vip_charger if { vip_chargers[input.charger.charge_box_id] } # Only employees can use VIP chargers allow if { is_vip_charger input.user.type == "employee" } # Everyone can use regular chargers allow if { not is_vip_charger } billing_strategy := "bypass" if { allow is_vip_charger input.user.type == "employee" } override_per_unit_price := 0 if { allow is_vip_charger input.user.type == "employee" } billing_strategy := "driver_pays" if { allow not is_vip_charger } context := { "policy": "vip_chargers", "is_vip_charger": is_vip_charger, "charger_id": input.charger.charge_box_id } denial_reason := "Access denied: VIP chargers are reserved for employees only" if { not allow is_vip_charger } ``` ## Need Support? Let us help you. Send enquiries to [hello@voltra.com](emailto:hello@voltra.com) --- ## About URL: https://docs.voltra.com/docs/Services/DataBridge # About ![Data Bridge page](/img/screenshots/data-bridge-page.png) Data Bridge connects your charger data to external data sources so you can seamlessly operate on, analyze and export your charger data. ## Connection Compatibility We offer data connectors for: - **DigitalOcean Spaces** - **AWS S3** - **Google Cloud Storage** - **Azure Storage** ## Custom Connections Need to export your data into a different data source? Email [hello@voltra.com](emailto:hello@voltra.com) and we'll be happy to add a new data connection. ## Ready to try it out? Try [Creating a Connector](./creating-a-connector) --- ## Creating a Connector URL: https://docs.voltra.com/docs/Services/DataBridge/creating-a-connector # Creating a Connector ## Data Bridge Page Start by visiting the [Data Bridge page](https://console.voltra.com/dashboard/data-bridge). ![Data Bridge page](/img/screenshots/data-bridge-page.png) ## Adding a Connector Click on "+ Add Connector" to open up the add connector modal. Alternatively click on the "Connect" button in the data bridge card that you want to connect to. Fill in the configuration for your connector and hit "Create Connector" to start streaming your logs into the data source. ![Connector Configuration modal](/img/screenshots/connector-configuration-modal.png) ## Need Support? Contact [hello@voltra.com](emailto:hello@voltra.com) to get help. --- ## About URL: https://docs.voltra.com/docs/Services/DeviceManagement # About ![Device Management page](/img/screenshots/device-management-page.png) Voltra's Device Management platform provides charging tools, monitoring, and maintenance capabilities for EV Chargers. Device Management enables operators to remotely manage their entire charging network, from individual chargers to large-scale deployments, ensuring optimal performance, reliability, and uptime. ## Key Features ### Charger Management Create, update, and delete chargers within your project. ### Remote Control Send remote commands to chargers including reset operations (soft and hard resets). Troubleshoot and manage chargers remotely without on-site visits. ### API Native Use our API tools to integrate with your existing management software. --- ## Common Use Cases ### Consulting & Engineering Firms Power your infrastructure projects with modular APIs or white-labeled software built for custom implementations. Remove the need to reinvent the wheel for every project. ### CPOs/Charge Networks Manage, track, and monitor all connected devices. Configure device settings, track performance, and ensure optimal operation across both OCPP and non-OCPP chargers. ### Multi-family Residential & Commercial Properties Add support for shared public or private chargers with the flexibility to adapt to any building setup. Integrate with your Building Management System, sub-metering platform, and more to create a seamless ecosystem for your tenants. ### Fleet Management/TMS Providers Extend your fleet software to support Electric Vehicles by adding simple modular services for payments, scheduling, and more. Sync directly with your TMS to make sure your fleet never misses a beat. ### Installers & Electricians Bundle software with every charger you install, with access to an installer portal to manage uptime and be alerted the second that a device goes offline. --- ## Supported Protocols & Standards ### Protocol Compatibility - OCPP 1.6 - OCPP 2.0.1 - **Custom Extensions**: Support for vendor-specific OCPP extensions and features --- ## Try it out Begin by [adding a device](./adding-a-device). --- ## Adding a Device URL: https://docs.voltra.com/docs/Services/DeviceManagement/adding-a-device # Adding a Device The first step to using Voltra's Connected Energy Cloud is to add a device. **Device Management Page** The [Device Management page](https://console.voltra.com/dashboard/device-management) is the home of adding any device. ![Device Management Page](/img/screenshots/device-management-page.png) **Add Your Device** Click on the "+ Connect New Device" button to open up the "Connect New Device" modal. Fill in the required information associated with your device. ![Connect a New Device modal](/img/screenshots/connect-a-new-device-modal.png) **EV Chargers** When connecting an EV Charger, the "Connect New Device" modal will generate an OCPP link and password for you to enter into your EV's software. ![OCPP Link Generated modal](/img/screenshots/ocpp-link-generated-modal.png) ## More Resources Once you've added a device consider: - [Connecting a payment provider to your project](../PaymentProcessing/) and [assigning a pricing policy to a charger](../PricingEngine/creating-a-pricing-policy) to begin accepting payments on your charger. - [Assigning a QR Code](/api/Command/VoltaCharge/QRCodeManager) to get started with our white-labeled payment portal. - [Adding authorization policies](../ChargeAuthorization/creating-an-authorization-policy) to authorize or deny vehicles in your fleet, residents of your complex or employees at your office. --- ## About URL: https://docs.voltra.com/docs/Services/LoadManagement # About The Load Balancing API provides load management capabilities for physical locations within your EV charging infrastructure enabling you to organize, and control charging equipment while implementing sophisticated load management strategies. ## Site Hierarchy ```mermaid graph TD; Org[Organization]; Proj[Project]; Loc[Location]; Site[Site]; Group[ChargerGroup]; Charger[Charger]; Org --> Proj; Org --> Charger; Proj --> Site[**Site**]; Loc --> Site; Site --> Group; Group --> Charger; ``` **Sites**: Sites are physical locations at your facility. Sites can have many groups of chargers. \ **Charger Groups**: Each charger group can have a different load management configuration. ## Key Features - **Dynamic Load Balancing**: Automatically distribute available power across charging sessions - **Power Limits**: Configure site-level and load group-level power constraints - **Power Distribution**: View real-time power allocation across active sessions ## Try it out Begin by [Creating a Load Configuration](./creating-a-load-configuration). --- ## Creating a Load Configuration URL: https://docs.voltra.com/docs/Services/LoadManagement/creating-a-load-configuration # Creating a Load Configuration ## Prerequisites You'll need to start by [adding at least two devices](../DeviceManagement/adding-a-device) on the device management page. You will also need an **address for each site** within your facility. If you only have one site on your facility, then your site's address is your facilities address. If you enable charger location publishing via OCPI, your chargers will show up at this address. ## Load Configuration ### Load Balancing Page Begin by visiting the Load Balancing page. ![Empty Load Balancing Page](/img/screenshots/load-balancing-page.png) ### Create a Site Sites are physical locations within your facility. You will have a chance later to group chargers in each site. Click on "+ Create Site" to open the site modal and fill in the location and site specific information ![Configure site modal](/img/screenshots/configure-site-modal.png) When complete, your site will appear on the Load Balancing page ![Load Balancing page with outside garate site shown](/img/screenshots/load-balancing-page-empty-site.png) ### Add a Charger Group to a Site Click on "+ Add Charger Group" to create a charger group that you want to load balance. ![Create charger group modal](/img/screenshots/create-charger-group-modal.png) ### Assign Chargers to Charger Group After creating a charger group, click on the charger group and a sidebar will open. Click on "+ Add Charger" in the side bar to add chargers to the group. ![Charger group sidebar with add charger button](/img/screenshots/charger-group-add-charger.png) The load strategy and any load strategy parameters can be configured from this sidebar. ## Next Steps Investigate the load management strategy that is right for you and your fleet at [Load Group Strategies](./load-group-strategies). --- ## Load Group Strategies URL: https://docs.voltra.com/docs/Services/LoadManagement/load-group-strategies # Load Group Strategies Documentation coming soon. ## Have Questions? Contact [hello@voltra.com](emailto:hello@voltra.com) to get answers. --- ## Locations URL: https://docs.voltra.com/docs/Services/Locations # Locations The location data model is used by various services like Load Management and OCPI in Voltra's CEC. The API's in this documentation are provided for your utility. --- ## Payment Processing URL: https://docs.voltra.com/docs/Services/PaymentProcessing # Payment Processing ![Payment Processing page](/img/screenshots/payment-processing-page.png) Use your choice of payment providers for collecting payments from your users. Payment Processing is a payment provider agnostic solution so you can use your preferred payment platform with our software. ## Use Cases - **EV Charging Payments**: Use our white-labelled payment portal to accept payments from EVs charging on your chargers. - **Track Transactions**: Use the transaction data and uncover payment patterns to set competitive prices. --- ## Connecting a Payment Provider URL: https://docs.voltra.com/docs/Services/PaymentProcessing/connecting-a-payment-provider # Connecting a Payment Provider ![Connected Payment Provider page with Stipe connected](/img/screenshots/stripe-connected-payment-provider.png) To connect a payment provider, contact [hello@voltra.com](mailto:hello@voltra.com). We will facilitate creating your payment account and giving your payment account ID. **Coming Soon** We're adding the capability to enter the payment account information yourself. --- ## About URL: https://docs.voltra.com/docs/Services/PricingEngine # About Voltra's Pricing Engine is real-time pricing platform that. This sophisticated system enables sophisticated pricing strategies. ## Key Features - **Schedule Pricing Poilicies**: Want to charge EV users for using your chargers from 9-5 but make charging free otherwise? Set schedules based on time of day and day of the week. - **kWh Based Pricing Policies**: Charge your users based on their usage. - **Time Based Pricing Policies**: Charge your users based on how long they are plugged in to your charger. - **Flat Fees**: Charge a flat fee for using your charger. ## Try it Out Start by [Creating a Pricing Policy](./creating-a-pricing-policy). --- ## Creating A Pricing Policy URL: https://docs.voltra.com/docs/Services/PricingEngine/creating-a-pricing-policy # Creating A Pricing Policy Pricing policies are the fundamental data model for setting users the price. Begin by visiting the [Pricing Engine page](https://console.voltra.com/dashboard/pricing-engine). ![Pricing Engine page](/img/screenshots/pricing-engine-page.png) Click on the "+ Add Pricing Policy" button to open the "Create New Pricing Policy Modal". You can create complex policies to suit your pricing needs. ![Create new pricing policy modal](/img/screenshots/create-new-pricing-policy-modal.png) Below are some example pricing policies you can create: ### Flat Pricing Policy ```json { "currency": "USD", "component": { "type": "FLAT", "amount": 5, "description": "Base fee" }, "taxIncluded": false } ``` ### KWh Rate Pricing Policy ```json { "taxIncluded": false, "currency": "USD", "component": { "type": "RATE", "perUnitRate": 0.1, "unit": "KWH" } } ``` ### Minute Rate Pricing Policy ```json { "currency": "USD", "component": { "type": "RATE", "unit": "MINUTE", "perUnitRate": 0.1 }, "taxIncluded": true } ``` ## Schedule Based Pricing Policies Use each of the components listed above to create a schedule based pricing policy. Use the below as a references for what you can create: ```json { "currency": "USD", "fallback": { "type": "FLAT", "amount": 3, "description": "Default fallback fee" }, "timezone": "America/Los_Angeles", "schedules": [ { "endTime": "17:00", "component": { "type": "RATE", "unit": "KWH", "description": "Rate per KWH", "perUnitRate": 1.5 }, "startTime": "09:00", "daysOfWeek": [ "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY" ] }, { "endTime": "18:00", "component": { "type": "FLAT", "amount": 5, "description": "Base fee" }, "startTime": "06:00", "daysOfWeek": [ "SATURDAY", "SUNDAY" ] } ], "taxIncluded": true } ``` ### Caveats #### Time Ranges Each time range of a pricing policy cannot span past midnight. This is so that we can be consistent and clear for not only creating pricing policies, but displaying prices to your users. ## Assigning a Pricing Policy to a Charger Visit the [Device Management Page](https://console.voltra.com/dashboard/device-management). ![Device Management page with chargers](/img/screenshots/device-management-with-chargers.png) Click on the charger you want to assign the pricing policy to. There is a "Pricing" dropdown where you can select the pricing policy you created. After selecting the pricing policy, click on "Save Policies" to save the pricing policy. ![Device details sidebar](/img/screenshots/device-details-sidebar.png) ## Further Customization Need a different pricing strategy? Trying to pull in data like energy prices into your pricing policy? Contact [hello@voltra.com](emailto:hello@voltra.com) for special inquiries. --- ## Proxy Configuration URL: https://docs.voltra.com/docs/Services/Proxy # Proxy Configuration Configure proxy settings for device communication in Voltra. --- ## QR Code Manager URL: https://docs.voltra.com/docs/Services/QRCodeManager # QR Code Manager Manage QR codes for your charging stations in Voltra. --- ## Vantage Overview URL: https://docs.voltra.com/docs/Vantage # Vantage Overview Vantage is Voltra's AI services platform designed to run seamlessly across the entire Voltra stack. Vantage brings generative AI capabilities to your charging infrastructure operations. ## Capabilities ### Generative UI Dynamically generate user interfaces and dashboards based on natural language queries. - Ask questions in plain English - Get instant visualizations - Create custom reports on demand ### Logging Analysis AI-powered log parsing, anomaly detection, and insights. - Automatic issue detection - Root cause analysis - Predictive maintenance alerts ### Code Generation Accelerate integration development with intelligent code assistance. - API usage examples - Integration boilerplate - Troubleshooting scripts ## Private Preview Vantage is currently in private preview as we continue to refine and expand its capabilities. If you're interested in early access or would like to learn more about how Vantage can enhance your operations, please reach out to [developer@voltra.com](mailto:developer@voltra.com). ## Learn More - [Vantage Product Overview](../Products/vantage) - Product capabilities - [Vantage API Reference](/api/Vantage) - API documentation (coming soon) --- ## API Reference URL: https://docs.voltra.com/docs/Vantage/api-reference # API Reference Vantage API documentation. ## Status Vantage APIs are currently in private preview. Full API documentation will be available when Vantage reaches general availability. ## Preview Access If you're participating in the Vantage private preview, API documentation is available through your preview access portal. ## Learn More - [Vantage Overview](./) - Platform capabilities - [Request Access](mailto:developer@voltra.com) - Join the preview program ---