Virta Partner API

https://docs.virta.global
Admin
Virta Partner API is a comprehensive charging infrastructure platform providing APIs for EV charging...
Tokens:91,158
Snippets:414
Trust Score:9.9
Update:7 months ago
Show doc for...
Tokens:
Raw
### Example Charging Session Response (Ongoing)

Source: https://docs.virta.global/docs/onboarding-guide/enterprise/charging/get-charge-session-details

An example response for an ongoing charging session, containing detailed information such as balance, duration, pricing, and station details. The status 'ONGOING' signifies that the charge start has been received.

```JSON
{
  "details": {
    "balance": -5070,
    "cdrId": 57431234,
    "cdrReceivedAt": null,
    "connectorId": 1,
    "currency": "RON",
    "durationSeconds": 22,
    "eichrechtLink": null,
    "freeMinutes": 0,
    "inProgress": true,
    "isNonDecimalCurrency": false,
    "isV2GCharge": false,
    "notes": [],
    "priceCents": 100,
    "pricingScheme": "normal",
    "provider": "Virta",
    "signedMetervalueBegin": null,
    "signedMetervalueEnd": null,
    "startTime": "2024-03-04T15:45:53+02:00",
    "station": {
      "address": "Perämiehenkatu 12 e",
      "city": "Helsinki",
      "coordinates":
      {
        "lat": 60.15928514067767,
        "lng": 24.93480279953453
      },
      "eichrechtType": "None",
      "evseId": 226123,
      "isV2G": false,
      "locationId": 226123,
      "name": "Charger Name",
      "publicKey": null
    },
    "stopTime": null,
    "v2gSetting": null,
    "wattHour": 8
  },
  "sessionId": "ea3acd66-30aa-4005-a03c-bccff28c2f78",
  "status": "ONGOING"
}
```

--------------------------------

### Install Kafka Client and Avro Libraries (Node.js)

Source: https://docs.virta.global/docs/onboarding-guide/data-streaming/consuming

Installs the necessary npm packages for creating a Kafka consumer client and decoding Avro data. This includes `kafka-js` for Kafka interaction and `avsc` for Avro decoding.

```bash
mkdir my-kafka-client && cd my-kafka-client
npm install kafka-js avsc
```

--------------------------------

### Example Charging Session Response (Pending)

Source: https://docs.virta.global/docs/onboarding-guide/enterprise/charging/get-charge-session-details

An example response for a charging session that is in the 'PENDING' state. This indicates that the station has not yet received or authorized the charging.

```JSON
{
    "sessionId": "ea3acd66-30aa-4005-a03c-bccff28c2f78",
    "status": "PENDING",
    "details": null
}
```

--------------------------------

### GET /2.2.1

Source: https://docs.virta.global/docs/ocpi-roaming/handshake

Retrieve module endpoint URLs for a specific OCPI version (e.g., 2.2.1). This allows the EMSP to discover the locations of other necessary modules.

```APIDOC
## GET /2.2.1

### Description
Retrieve module endpoint URLs for a specific OCPI version (e.g., 2.2.1). This allows the EMSP to discover the locations of other necessary modules.

### Method
GET

### Endpoint
/2.2.1

### Parameters
None

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **endpoints** (object) - A mapping of module names to their respective URLs.
  - **locations** (string) - URL for the Locations module.
  - **tariffs** (string) - URL for the Tariffs module.
  - **tokens** (string) - URL for the Tokens module.
  - **commands** (string) - URL for the Commands module.
  - **sessions** (string) - URL for the Sessions module.
  - **cdrs** (string) - URL for the CDRs module.

#### Response Example
```json
{
  "endpoints": {
    "locations": "/2.2.1/locations",
    "tariffs": "/2.2.1/tariffs",
    "tokens": "/2.2.1/tokens",
    "commands": "/2.2.1/commands",
    "sessions": "/2.2.1/sessions",
    "cdrs": "/2.2.1/cdrs"
  }
}
```
```

--------------------------------

### Latest Charging Session Response Example (JSON)

Source: https://docs.virta.global/docs/onboarding-guide/enterprise/charging/get-charge-session-details

An example JSON response for the `GET /customer/me/charges/latest` endpoint. This payload includes comprehensive details about the customer's latest charging session, such as financial information, session duration, and associated station data. It is important to note the absence of a specific charging session ID in this response.

```JSON
{
    "balance": -484386,
    "billingMinutes": 2,
    "city": "",
    "connectorId": 1,
    "currency": "RON",
    "durationSeconds": 101,
    "eichrechtLink": null,
    "evseId": 4563892,
    "freeMinutes": 0,
    "id": 990794,
    "inProgress": true,
    "isNonDecimalCurrency": false,
    "isV2GCharge": false,
    "notes": [],
    "priceCents": 0,
    "pricingDetails": [],
    "pricingScheme": "advanced",
    "provider": "Virta",
    "signedMetervalueBegin": null,
    "signedMetervalueEnd": null,
    "startTime": "2024-06-18T17:32:42+03:00",
    "station":
    {
        "address": "",
        "city": "",
        "eichrechtType": "None",
        "id": 4563892,
        "isV2G": false,
        "location":
        {
            "coordinates":
            {
                "lat": 44.46513275,
                "lng": 26.10156984
            }
        },
        "name": "First station from ONE",
        "publicKey": null
    },
    "stationId": 4563892,
    "stationName": "ONE Tower",
    "stopTime": null,
    "v2gSetting": null,
    "virtaImpactEnabled": false,
    "wattHour": 0
}
```

--------------------------------

### Tariff with peak and off-peak pricing

Source: https://docs.virta.global/docs/ocpi-roaming/module/tariffs

This example demonstrates a tariff structure that includes peak and off-peak pricing components, along with parking fees and a flat rate.

```APIDOC
## GET /websites/virta_global/tariffs

### Description
Retrieves a list of available tariffs, including detailed pricing information for different time periods and services.

### Method
GET

### Endpoint
/websites/virta_global/tariffs

### Parameters
#### Query Parameters
- **country_code** (string) - Optional - Filter tariffs by country code.
- **party_id** (string) - Optional - Filter tariffs by party ID.

### Request Example
```
GET /websites/virta_global/tariffs?country_code=FI&party_id=VIR
```

### Response
#### Success Response (200)
- **status_code** (integer) - The status code of the response.
- **data** (array) - An array of tariff objects.
  - **country_code** (string) - The country code associated with the tariff.
  - **party_id** (string) - The party ID associated with the tariff.
  - **id** (string) - The unique identifier for the tariff.
  - **currency** (string) - The currency used for pricing.
  - **type** (string) - The type of tariff (e.g., REGULAR).
  - **elements** (array) - An array of tariff elements, defining different pricing rules.
    - **price_components** (array) - Components of the price, such as energy, parking, or flat fees.
      - **type** (string) - The type of price component (e.g., ENERGY, PARKING_TIME, FLAT).
      - **price** (number) - The price per unit.
      - **vat** (number) - The VAT percentage.
      - **step_size** (integer) - The increment for billing.
    - **restrictions** (object) - Time-based restrictions for the tariff element.
      - **start_time** (string) - The start time for the restriction (HH:MM).
      - **end_time** (string) - The end time for the restriction (HH:MM).
      - **day_of_week** (array) - An array of days of the week the restriction applies to.
  - **min_price** (object) - The minimum charge for the tariff.
    - **excl_vat** (number) - The minimum price excluding VAT.
    - **incl_vat** (number) - The minimum price including VAT.
  - **last_updated** (string) - The timestamp when the tariff was last updated.
- **timestamp** (string) - The timestamp when the response was generated.

#### Response Example
```json
{
  "status_code": 1000,
  "data": [
    {
      "country_code": "FI",
      "party_id": "VIR",
      "id": "TARIFF01",
      "currency": "EUR",
      "type": "REGULAR",
      "elements": [
        {
          "price_components": [
            {
              "type": "ENERGY",
              "price": 0.35,
              "vat": 24.0,
              "step_size": 1
            },
            {
              "type": "PARKING_TIME",
              "price": 5.0,
              "vat": 24.0,
              "step_size": 300
            }
          ],
          "restrictions": {
            "start_time": "08:00",
            "end_time": "18:00",
            "day_of_week": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"]
          }
        },
        {
          "price_components": [
            {
              "type": "ENERGY",
              "price": 0.25,
              "vat": 24.0,
              "step_size": 1
            },
            {
              "type": "FLAT",
              "price": 0.5,
              "vat": 24.0,
              "step_size": 1
            }
          ]
        }
      ],
      "min_price": {
        "excl_vat": 1.0,
        "incl_vat": 1.24
      },
      "last_updated": "2024-01-15T10:00:00Z"
    }
  ],
  "timestamp": "2024-01-15T10:00:00Z"
}
```
```

--------------------------------

### GET /versions

Source: https://docs.virta.global/docs/ocpi-roaming/handshake

Discover the supported OCPI versions that Virta's API supports. This is a crucial step in the handshake process to determine compatibility.

```APIDOC
## GET /versions

### Description
Discover the supported OCPI versions that Virta's API supports. This is a crucial step in the handshake process to determine compatibility.

### Method
GET

### Endpoint
/versions

### Parameters
None

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **versions** (array) - A list of supported OCPI versions.
  - **version** (string) - The OCPI version number (e.g., "2.2.1").
  - **url** (string) - The URL for the module endpoint corresponding to this version.

#### Response Example
```json
{
  "versions": [
    {
      "version": "2.2.1",
      "url": "/2.2.1"
    }
  ]
}
```
```

--------------------------------

### Station Start API

Source: https://docs.virta.global/docs/onboarding-guide/ptc/intro

Initiates the charging process at a station after a payment session has been established. The station will enter a 'preparing' status, and if a successful handshake with the EV is achieved, the charge will begin.

```APIDOC
## POST /station/start

### Description
Initiates the charging process at a station. This endpoint is called after a payment session is authorized and the EV driver is ready to charge.

### Method
POST

### Endpoint
/station/start

### Parameters
#### Query Parameters
- **sessionId** (string) - Required - The identifier of the payment session.

### Request Example
```json
{
  "sessionId": "sess_12345abcde"
}
```

### Response
#### Success Response (200)
- **stationId** (string) - The identifier of the station where charging is initiated.
- **status** (string) - The status of the station start request (e.g., 'preparing').

#### Response Example
```json
{
  "stationId": "stn_fgh67890ij",
  "status": "preparing"
}
```
```

--------------------------------

### CDR POST Response Example (HTTP)

Source: https://docs.virta.global/docs/ocpi-roaming/module/cdrs

This is a sample HTTP response for a successful CDR POST request. It indicates a '201 Created' status and provides a 'Location' header pointing to the newly created CDR resource.

```http
HTTP/1.1 201 Created
Location: https://your-emsp.com/ocpi/2.2.1/emsp/cdrs/CDR001
```

--------------------------------

### Start Charging Session

Source: https://docs.virta.global/docs/onboarding-guide/ptc/intro

Initiates a charging session for a payment terminal customer using their device ID, EVSE ID, and connector ID.

```APIDOC
## POST station/start

### Description
The API is used to start a charging session for a payment terminal customer, requires the deviceId from the POST PaymentTerminalCustomer API, evseId and connectorId. This API only sends to command to the station to start the charging session, it's possible that the station is not able to start the charging session. See section Charge state handling for more information.

### Method
POST

### Endpoint
`/station/start`

### Parameters
#### Request Body
- **deviceId** (string) - Required - The unique identifier of the payment terminal customer.
- **evseId** (string) - Required - The unique identifier of the charging station's EVSE.
- **connectorId** (string) - Required - The identifier of the connector on the EVSE.

### Request Example
```json
{
  "deviceId": "ptc_abc123xyz789",
  "evseId": "EVSE001",
  "connectorId": "connector1"
}
```

### Response
#### Success Response (200)
- **chargeSessionId** (string) - The unique identifier for the initiated charging session.
- **status** (string) - The status of the charging session initiation (e.g., "Pending", "Started").

#### Response Example
```json
{
  "chargeSessionId": "cs_session456",
  "status": "Started"
}
```
```

--------------------------------

### Start Charging Session

Source: https://docs.virta.global/docs/onboarding-guide/enterprise/charging/intro

Initiates a charging session for an EV driver using the provided evseId (stationId) and connector id. Requires an access token.

```APIDOC
## POST /customer/charge-session/start

### Description
Starts a charging session on behalf of an EV driver. Requires the `evseId` (stationId) and `connectorId`.

### Method
POST

### Endpoint
/customer/charge-session/start

### Parameters
#### Query Parameters
- **evseId** (string) - Required - The ID of the charging station.
- **connectorId** (string) - Required - The ID of the connector on the charging station.

### Request Body
(No explicit request body described, but authentication token is required)

### Request Example
(Authentication token should be included in the headers)

### Response
#### Success Response (200)
- **sessionId** (string) - The unique identifier for the initiated charging session.

#### Response Example
```json
{
  "sessionId": "6c174117-8926-49ba-b2fb-5609bc84df39"
}
```
```

--------------------------------

### Consuming OCPP Raw Logs - Example Output

Source: https://docs.virta.global/docs/onboarding-guide/data-streaming/ocpp-raw-logs/intro

An example of a raw log message received from a station, demonstrating the structure and content. This output is parsed based on the detected `StationProtocol` (e.g., OCPP 1.6) to interpret the message type, unique ID, action, and payload.

```json
{
    "EventPublishedAtUtc": "2025-02-10T13:57:52.270Z",
    "StationId": "352964057755515",
    "StationIdNormalized": "352964057755515",
    "StationProtocol": "ocpp-j-1-6",
    "LoggedAtUtc": "2025-02-10T13:57:49.579Z",
    "MessageDirectionEnumId": "read_from_station",
    "MessageInStationProtocolStandard": "[2, \"38914293\", \"MeterValues\", {\"connectorId\": 1, \"transactionId\": 77941074, \"meterValue\": [{\"sampledValue\": [{\"value\": \"66026400\", \"context\": \"Sample.Periodic\", \"format\": \"Raw\", \"measurand\": \"Energy.Active.Import.Register\", \"location\": \"Outlet\", \"unit\": \"Wh\"}], \"timestamp\": \"2025-02-10T13:57:48Z\"}]}"
  }
```

--------------------------------

### Node.js CLI Execution Command

Source: https://docs.virta.global/docs/onboarding-guide/data-streaming/consuming

This command demonstrates how to execute the Node.js Kafka client script from the command line. Ensure you have Node.js installed and the script is saved as './src/client.js'.

```bash
node ./src/client.js
```

--------------------------------

### POST /2.2.1/credentials

Source: https://docs.virta.global/docs/ocpi-roaming/handshake

Initiates the initial registration process with Virta. This endpoint is used by the EMSP to register with Virta, typically involving the exchange of tokens.

```APIDOC
## POST /2.2.1/credentials

### Description
Initiates the initial registration process with Virta. This endpoint is used by the EMSP to register with Virta, typically involving the exchange of tokens.

### Method
POST

### Endpoint
/2.2.1/credentials

### Parameters
#### Query Parameters
- **token** (string) - Required - The token provided by Virta (TOKEN_A) for initial registration.

#### Request Body
This endpoint does not typically require a request body for the initial registration POST, as authentication is handled via query parameters and headers.

### Request Example
(No request body example provided for this specific POST action, as it's primarily token-driven)

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the registration attempt.
- **data** (object) - Contains details about the registration, potentially including TOKEN_C.
  - **token** (string) - The token provided by Virta (TOKEN_C) for subsequent communication.

#### Response Example
```json
{
  "status": "success",
  "data": {
    "token": "TOKEN_C_EXAMPLE"
  }
}
```

### Common Issues
- **"Invalid token" error**: Ensure you are using the correct, single-use TOKEN_A and that the Authorization header is formatted correctly as `Token {TOKEN_A}`.
```

--------------------------------

### START_SESSION Command Example

Source: https://docs.virta.global/docs/ocpi-roaming/module/commands

This snippet demonstrates the HTTP request to initiate a charging session remotely. It includes the endpoint, authorization, and content type headers, along with the JSON payload specifying the callback URL and driver token.

```http
POST /2.2.1/cpo/commands/START_SESSION
Authorization: Token dG9rZW5fY19leGFtcGxl
Content-Type: application/json
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000
X-Correlation-ID: 6ba7b810-9dad-11d1-80b4-00c04fd430c8

{
  "response_url": "https://your-emsp.com/ocpi/2.2.1/commands/callback/CMD001",
  "token": "YOUR_PRE_AUTHORIZED_TOKEN",
  "location_id": "YOUR_LOCATION_ID",
  "evse_uid": "YOUR_EVSE_UID",
  "connector_id": "YOUR_CONNECTOR_ID",
  "authorization_reference": "YOUR_AUTHORIZATION_REFERENCE"
}
```

--------------------------------

### GET /2.2.1/credentials

Source: https://docs.virta.global/docs/ocpi-roaming/handshake

Retrieve the current credentials associated with the EMSP. This can be used to check the status or obtain the active token.

```APIDOC
## GET /2.2.1/credentials

### Description
Retrieve the current credentials associated with the EMSP. This can be used to check the status or obtain the active token.

### Method
GET

### Endpoint
/2.2.1/credentials

### Parameters
#### Query Parameters
- **token** (string) - Required - The authorization token (TOKEN_C) for accessing credentials.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **status** (string) - The current status of the credential (e.g., INITIAL, ACTIVE, SUSPENDED, DELETED).
- **token** (string) - The active authorization token.

#### Response Example
```json
{
  "status": "ACTIVE",
  "token": "CURRENT_ACTIVE_TOKEN"
}
```
```

--------------------------------

### Transition to API v4.1 from API v4.0

Source: https://docs.virta.global/docs/4-1-admin/41a5a6150369a-transition-instructions

Instructions for migrating from API v4.0 to API v4.1, focusing on authentication and base URL changes.

```APIDOC
## Transition to API v4.1 from API v4.0

### Description
If you are using API v 4.0, you need to make two primary changes to transition to API v 4.1:
1. Add a new authorization header `x-api-key` to all requests. Obtain your personal API key by submitting a request through the 'Request API Key' form.
2. Update the base URL according to the environment you are using.

The request and response parameters remain the same between API v 4.0 and v 4.1.

### Method
N/A (Configuration change)

### Endpoint
N/A (Base URL change)

### Parameters
#### Request Headers
- **x-api-key** (string) - Required - Your personal API key for authentication.

#### Base URL Changes
**Environment** | **API v 4.0 URL** | **API v 4.1 URL**
---|---|---
Production | `api.virta.fi/v4/admin` or `api.virta-ev.com/v4/admin` | `api.virta.global/admin`
Test | `api.virta.fi/v4/admin` or `api.test.virta-ev.com/v4/admin` | `api.test.virta.global/admin`

### Request Example
```http
GET /some/endpoint HTTP/1.1
Host: api.virta.global
X-Api-Key: YOUR_API_KEY
```

### Response
N/A (This section describes configuration changes, not specific endpoint responses.)
```

--------------------------------

### OCPI API Pagination Example

Source: https://docs.virta.global/docs/ocpi-roaming/protocol-basics

Illustrates how to paginate responses for lists of objects using query parameters like `date_from` and `limit`, and how to interpret response headers like `Link`, `X-Total-Count`, and `X-Limit`.

```http
GET /2.2.1/cpo/locations?date_from=2024-01-01T00:00:00Z&limit=50
```

--------------------------------

### Successful Registration Response from Virta

Source: https://docs.virta.global/docs/ocpi-roaming/handshake

This is an example of a successful registration response from Virta Global. It contains the permanent access token (TOKEN_C) that your system will use for all subsequent API calls to Virta.

```json
{
  "status_code": 1000,
  "data": {
    "token": "{TOKEN_C}",
    "url": "https://ocpi.virta.global/versions",
    "roles": [
      {
        "role": "CPO",
        "party_id": "VIR",
        "country_code": "FI",
        "business_details": {
          "name": "Virta"
        }
      }
    ]
  }
}
```

--------------------------------

### Example Tariff with Peak and Off-Peak Pricing (JSON)

Source: https://docs.virta.global/docs/ocpi-roaming/module/tariffs

This JSON object represents a tariff structure that includes different pricing elements for peak and off-peak hours. It details energy prices, parking fees, and restrictions like time of day and day of week. The structure also includes currency, country code, and minimum charge information.

```json
{
  "status_code": 1000,
  "data": [
    {
      "country_code": "FI",
      "party_id": "VIR",
      "id": "TARIFF01",
      "currency": "EUR",
      "type": "REGULAR",
      "elements": [
        {
          "price_components": [
            {
              "type": "ENERGY",
              "price": 0.35,
              "vat": 24.0,
              "step_size": 1
            },
            {
              "type": "PARKING_TIME",
              "price": 5.0,
              "vat": 24.0,
              "step_size": 300
            }
          ],
          "restrictions": {
            "start_time": "08:00",
            "end_time": "18:00",
            "day_of_week": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"]
          }
        },
        {
          "price_components": [
            {
              "type": "ENERGY",
              "price": 0.25,
              "vat": 24.0,
              "step_size": 1
            },
            {
              "type": "FLAT",
              "price": 0.5,
              "vat": 24.0,
              "step_size": 1
            }
          ]
        }
      ],
      "min_price": {
        "excl_vat": 1.0,
        "incl_vat": 1.24
      },
      "last_updated": "2024-01-15T10:00:00Z"
    }
  ],
  "timestamp": "2024-01-15T10:00:00Z"
}
```

--------------------------------

### List CPO CDRs - GET Request Example

Source: https://docs.virta.global/docs/onboarding-guide/enterprise/cdr-reports/list-cpo-cdrs

Demonstrates how to retrieve a list of CDRs (Call Detail Records) for a specific CPO seller. This API requires an admin token for authorization and supports pagination with a limit of 10 records per page.

```http
GET /admin/cpo/cdrs?cpoSellerId=12345 HTTP/1.1
Host: api.test.virta.global
Content-Type: application/json
x-api-key: {{X_API_KEY}}
Authorization: Bearer {{ADMIN_TOKEN}}
```

--------------------------------

### START_SESSION Synchronous Response Example

Source: https://docs.virta.global/docs/ocpi-roaming/module/commands

This snippet shows the immediate response from Virta after a START_SESSION command is sent. It indicates whether the command was accepted for processing and provides a timeout value for the asynchronous result.

```json
{
  "status_code": 1000,
  "data": {
    "result": "ACCEPTED",
    "timeout": 30
  },
  "timestamp": "2024-01-15T14:00:00Z"
}
```

--------------------------------

### Example Avro Schema Structure

Source: https://docs.virta.global/docs/onboarding-guide/data-streaming/consuming

This is an example of a JSON schema used for Avro serialization/deserialization. It defines the structure and data types for messages, such as 'StationId' and 'MessageInStationProtocolStandard' for station messages.

```json
{
  "doc": "Station message.",
  "fields": [
    {
      "doc": "Station identity as reported by the station",
      "name": "StationId",
      "type": "string"
    },
    {
      "doc": "The actual message sent to or received from the station. ",
      "name": "MessageInStationProtocolStandard",
      "type": "string"
    }
  ],
  "name": "StationMessageTopicValue",
  "type": "record"
}
```

--------------------------------

### Update Session to ACTIVE (PATCH)

Source: https://docs.virta.global/docs/ocpi-roaming/module/sessions

Updates an existing EV charging session to the ACTIVE state using a PATCH request. This typically signifies the start of charging and includes the actual start time and last updated timestamp.

```json
{
  "status": "ACTIVE",
  "start_date_time": "2024-01-15T14:02:00Z",
  "last_updated": "2024-01-15T14:02:00Z"
}
```

--------------------------------

### Transition to API v4.1 from API v2.0

Source: https://docs.virta.global/docs/4-1-admin/41a5a6150369a-transition-instructions

Guidance for users migrating from API v2.0 to the latest API v4.1, including contact information for support.

```APIDOC
## Transition to API v4.1 from API v2.0

### Description
If you are still using API v 2.0, please contact support@virta.global for detailed instructions on migrating to the newest API version (v 4.1). The base URLs for API v 2.0 and API v 4.1 are provided below for identification purposes.

### Method
N/A (Contact support for migration details)

### Endpoint
N/A (Contact support for migration details)

### Parameters
N/A (Contact support for migration details)

### Base URL Identification
**Environment** | **API v 2.0 URL** | **API v 4.1 URL**
---|---|---
Production | `apiv2.virta.fi` | `api.virta.global/admin`
Test | `apiv2.test.virta.fi` | `api.test.virta.global/admin`

### Request Example
N/A

### Response
N/A
```

--------------------------------

### External Service API - Overview

Source: https://docs.virta.global/docs/external-service-api/1cb1ba507abf8-custom-integrations

This section provides an overview of the Virta Global External Service API, including base URLs for production and test environments, and a link to a mock server.

```APIDOC
## Virta Global External Service API

### Description
This API provides access to custom services supported by Virta, enabling integration with various aspects of their platform.

### API Base URLs
- **Production:** `https://api.virta.global/external-service`
- **Test:** `https://api.test.virta.global/external-service`

### Mock Server
- **URL:** `https://stoplight.io/mocks/virta/external-service-api/631493878`

### Key Areas Covered
- Authentication
- Cross Organisation Links
- Energy Management
- EV Drivers
- EV Drivers Groups
- EVSEs Discovery
- Pool
- RFIDs
- Station Management
- Tariffs
- CDR
- Custom integrations
- Payment terminal operations
- Data Push
- Virtual Power Plant
```

--------------------------------

### Get Latest Charges

Source: https://docs.virta.global/docs/onboarding-guide/enterprise/charging/intro

Retrieves the latest charging sessions associated with the authenticated EV driver.

```APIDOC
## GET /customer/me/charges/latest

### Description
Fetches the latest charging sessions for the currently authenticated EV driver.

### Method
GET

### Endpoint
/customer/me/charges/latest

### Parameters
(None)

### Request Body
(None)

### Request Example
(No request body needed)

### Response
#### Success Response (200)
- (Array of latest charge session objects, details not specified)

#### Response Example
```json
[
  {
    "sessionId": "abc123def456",
    "startTime": "2023-10-27T10:00:00Z",
    "endTime": "2023-10-27T11:00:00Z",
    "totalCostCents": 750
  }
]
```
```

--------------------------------

### CDR POST Request Body Example (JSON)

Source: https://docs.virta.global/docs/ocpi-roaming/module/cdrs

This JSON object represents a sample Charge Detail Record (CDR) payload that can be sent via a POST request. It includes details about the charging session, location, costs, and energy consumption, structured with charging periods.

```json
{
  "status_code": 1000,
  "data": {
    "country_code": "FI",
    "party_id": "VIR",
    "id": "CDR001",
    "start_date_time": "2024-01-15T14:02:00Z",
    "end_date_time": "2024-01-15T15:30:00Z",
    "session_id": "SES001",
    "cdr_token": {
      "country_code": "NL",
      "party_id": "EMS",
      "uid": "TOKEN001",
      "type": "RFID",
      "contract_id": "NL-EMS-C001"
    },
    "auth_method": "AUTH_REQUEST",
    "cdr_location": {
      "id": "LOC001",
      "name": "Helsinki Charging Hub",
      "address": "Mannerheimintie 1",
      "city": "Helsinki",
      "country": "FIN",
      "coordinates": {
        "latitude": "60.17045",
        "longitude": "24.94147"
      },
      "evse_uid": "EVSE001",
      "evse_id": "FI*VIR*E001",
      "connector_id": "1",
      "connector_standard": "IEC_62196_T2_COMBO",
      "connector_format": "CABLE",
      "connector_power_type": "DC"
    },
    "currency": "EUR",
    "charging_periods": [
      {
        "start_date_time": "2024-01-15T14:02:00Z",
        "dimensions": [
          { "type": "ENERGY", "volume": 42.5 },
          { "type": "TIME", "volume": 1.467 }
        ],
        "tariff_id": "TARIFF01"
      },
      {
        "start_date_time": "2024-01-15T15:25:00Z",
        "dimensions": [{ "type": "PARKING_TIME", "volume": 0.083 }],
        "tariff_id": "TARIFF01"
      }
    ],
    "total_cost": {
      "excl_vat": 13.5,
      "incl_vat": 16.74
    },
    "total_energy": 42.5,
    "total_time": 1.467,
    "total_parking_time": 0.083,
    "last_updated": "2024-01-15T15:35:00Z"
  },
  "timestamp": "2024-01-15T15:35:00Z"
}
```

--------------------------------

### Charging API

Source: https://docs.virta.global/docs/onboarding-guide/api-reference

Endpoints for managing charging sessions, including starting, stopping, and retrieving session progress.

```APIDOC
## POST /customer/charge-session/start

### Description
Starts a charging session.

### Method
POST

### Endpoint
https://api.virta.global/customer/charge-session/start

### Parameters
#### Request Body
- **evse_id** (string) - Required - The ID of the EVSE to start charging on.
- **vehicle_id** (string) - Optional - The ID of the vehicle being charged.

### Response
#### Success Response (200)
- **session_id** (string) - The ID of the newly started charging session.

## POST /customer/charge-session/stop

### Description
Stops a charging session.

### Method
POST

### Endpoint
https://api.virta.global/customer/charge-session/stop

### Parameters
#### Request Body
- **session_id** (string) - Required - The ID of the charging session to stop.

## GET /customer/charge-session/:id

### Description
Retrieves the progress of a charging session.

### Method
GET

### Endpoint
https://api.virta.global/customer/charge-session/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the charging session.

### Response
#### Success Response (200)
- **session_progress** (object) - The progress details of the charging session.

## GET /admin/cpo/sessions

### Description
Retrieves a list of CPO charging sessions.

### Method
GET

### Endpoint
https://api.virta.global/admin/cpo/sessions
```

--------------------------------

### Get EV Driver Details via External Service API

Source: https://docs.virta.global/docs/onboarding-guide/enterprise/user-management/get-ev-driver

This snippet demonstrates how to retrieve the full details of an EV Driver using their unique ID. It requires the EV driver's ID and authentication credentials (API key and service token) to make a GET request to the external service endpoint.

```http
GET /external-service/ev-drivers/{{EV_DRIVER_ID}} HTTP/1.1
Host: api.test.virta.global
x-api-key: {{X_API_KEY}}
Authorization: Bearer {{SERVICE_TOKEN}}
```

--------------------------------

### Get Station Information

Source: https://docs.virta.global/docs/onboarding-guide/ptc/intro

Used to retrieve details about a specific charging station, including tariffs, connectors, and location information.

```APIDOC
## GET station/{id}

### Description
Used to get the station information for the station where the charging session is going to be started. Contains tariffs, connectors, location information etc.

### Method
GET

### Endpoint
`/station/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the station.

### Response
#### Success Response (200)
- **stationInfo** (object) - Detailed information about the station.
  - **tariffs** (array) - List of available tariffs.
  - **connectors** (array) - List of available connectors.
  - **location** (object) - Location details of the station.

#### Response Example
```json
{
  "stationInfo": {
    "tariffs": [
      {
        "id": "tariff123",
        "name": "Standard Rate",
        "price": 0.20
      }
    ],
    "connectors": [
      {
        "id": "connector1",
        "type": "Type2",
        "status": "Available"
      }
    ],
    "location": {
      "address": "123 Charging Street",
      "city": "Chargeville",
      "country": "Electroland"
    }
  }
}
```
```

--------------------------------

### Versions API

Source: https://docs.virta.global/docs/ocpi-roaming/welcome

Discover supported OCPI versions and available modules for integration.

```APIDOC
## GET /versions

### Description
Your system queries Virta to discover supported OCPI versions and available modules, or Virta queries your system to discover your supported versions during registration.

### Method
GET

### Endpoint
`/versions`

### Parameters
#### Query Parameters
- **token** (string) - Required - Authentication token (TOKEN_A for EMSP to Virta, TOKEN_B for Virta to EMSP).

### Response
#### Success Response (200)
- **versions** (array) - A list of supported OCPI versions and their capabilities.

#### Response Example
```json
{
  "versions": [
    {
      "version": "2.2.1",
      "url": "/2.2.1"
    }
  ]
}
```
```

```APIDOC
## GET /{version}

### Description
Your system retrieves the list of module endpoints for a specific OCPI version from Virta, or Virta retrieves your module endpoints for a specific version.

### Method
GET

### Endpoint
`/{version}`

### Parameters
#### Path Parameters
- **version** (string) - Required - The OCPI version to retrieve details for (e.g., "2.2.1").
#### Query Parameters
- **token** (string) - Required - Authentication token (TOKEN_A for EMSP to Virta, TOKEN_B for Virta to EMSP).

### Response
#### Success Response (200)
- **modules** (array) - A list of supported modules and their corresponding endpoints for the specified version.

#### Response Example
```json
{
  "modules": [
    {
      "name": "locations",
      "endpoints": {
        "get": "/2.2.1/cpo/locations"
      }
    },
    {
      "name": "sessions",
      "endpoints": {
        "get": "/2.2.1/cpo/sessions"
      }
    }
  ]
}
```
```

--------------------------------

### GET /customer/me/charges/latest

Source: https://docs.virta.global/docs/onboarding-guide/enterprise/charging/get-charge-session-details

Retrieves details about the latest or ongoing charging session for the current EV driver.

```APIDOC
## GET /customer/me/charges/latest

### Description
Use this API if you want to know if there is an ongoing charging session for the current EV Driver or just extract details about the last charging session.

### Method
GET

### Endpoint
`/customer/me/charges/latest`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **evseId** (string) - Optional - The ID of the EVSE (Electric Vehicle Supply Equipment) to filter the latest charge session by.

#### Request Body
None

### Request Example
```
GET /customer/me/charges/latest?evseId=YOUR_EVSE_ID HTTP/1.1
Host: api.test.virta.global
Content-Type: application/json
Authorization: Bearer {{ACCESS_TOKEN}}
```

### Response
#### Success Response (200)
- **sessionId** (string) - The unique identifier for the charging session.
- **status** (string) - The current status of the charging session (e.g., PENDING, ONGOING, COMPLETED).
- **details** (object | null) - An object containing detailed information about the charging session if available, otherwise null.

#### Response Example
```json
{
  "sessionId": "ea3acd66-30aa-4005-a03c-bccff28c2f78",
  "status": "ONGOING",
  "details": {
    "balance": -5070,
    "cdrId": 57431234,
    "cdrReceivedAt": null,
    "connectorId": 1,
    "currency": "RON",
    "durationSeconds": 22,
    "eichrechtLink": null,
    "freeMinutes": 0,
    "inProgress": true,
    "isNonDecimalCurrency": false,
    "isV2GCharge": false,
    "notes": [],
    "priceCents": 100,
    "pricingScheme": "normal",
    "provider": "Virta",
    "signedMetervalueBegin": null,
    "signedMetervalueEnd": null,
    "startTime": "2024-03-04T15:45:53+02:00",
    "station": {
      "address": "Perämiehenkatu 12 e",
      "city": "Helsinki",
      "coordinates": {
        "lat": 60.15928514067767,
        "lng": 24.93480279953453
      },
      "eichrechtType": "None",
      "evseId": 226123,
      "isV2G": false,
      "locationId": 226123,
      "name": "Charger Name",
      "publicKey": null
    },
    "stopTime": null,
    "v2GSetting": null,
    "wattHour": 8
  }
}
```
```

--------------------------------

### Get CPO Ongoing Charging Sessions

Source: https://docs.virta.global/docs/onboarding-guide/enterprise/charging/intro

Retrieves a list of ongoing charging sessions managed by a CPO (Charge Point Operator).

```APIDOC
## GET /admin/cpo/sessions

### Description
Retrieves a list of all ongoing charging sessions managed by the CPO (Charge Point Operator).

### Method
GET

### Endpoint
/admin/cpo/sessions

### Parameters
(None)

### Request Body
(None)

### Request Example
(No request body needed)

### Response
#### Success Response (200)
- (Array of ongoing charging session objects managed by the CPO. Specific fields not detailed.)

#### Response Example
```json
[
  {
    "sessionId": "xyz789abc123",
    "evseId": "station-001",
    "startTime": "2023-10-27T09:30:00Z",
    "status": "CHARGING"
  }
]
```
```

--------------------------------

### Real-time Token Authorization (HTTP POST)

Source: https://docs.virta.global/docs/ocpi-roaming/module/tokens

This HTTP POST request illustrates the real-time authorization flow for a specific token. It includes the token UID and type in the URL path and requires an Authorization header. The response contains authorization details in JSON format.

```http
POST /2.2.1/emsp/tokens/TOKEN001/authorize?type=RFID
Authorization: Token dG9rZW5fYl9leGFtcGxl
```

--------------------------------

### GET /2.2.1/emsp/tokens

Source: https://docs.virta.global/docs/ocpi-roaming/module/tokens

Virta pulls tokens from your system periodically to build a local cache. This endpoint lists tokens in a paginated format.

```APIDOC
## GET /2.2.1/emsp/tokens

### Description
Virta pulls tokens from your system periodically to build a local cache. This endpoint lists tokens in a paginated format.

### Method
GET

### Endpoint
/2.2.1/emsp/tokens

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of tokens to return per page.
- **offset** (integer) - Optional - Number of tokens to skip before starting to collect the result set.

### Request Example
```
GET /2.2.1/emsp/tokens?limit=10&offset=0
```

### Response
#### Success Response (200)
- **tokens** (array) - An array of Token objects.
- **total** (integer) - The total number of tokens available.

#### Response Example
```json
{
  "tokens": [
    {
      "country_code": "NL",
      "party_id": "NL-E01",
      "uid": "ABC123XYZ",
      "type": "RFID",
      "contract_id": "CON-456",
      "issuer": "EMSP Name",
      "valid": true,
      "whitelist": "ALWAYS",
      "visual_number": "12345",
      "group_id": "GRP-789",
      "language": "en",
      "default_profile_type": "REGULAR",
      "energy_contract": {
        "supplier_name": "Energy Co.",
        "contract_id": "EN-CON-001"
      },
      "last_updated": "2023-10-27T10:00:00Z"
    }
  ],
  "total": 100
}
```
```
Tokens:
Raw