General Information
General Information#
DepotFinity APIs#
DepotFinity API documentation aims to describe the specifications, conventions, steps to get started, and how to use DepotFinity APIs.
The DepotFinity APIs are based on the JSON:API specification with some customizations. You must be authorized to use the DepotFinity APIs. For more information on authorization, see Authorization. Access to API's will be available only when subscribed to the relevant packages, see DepotFinity Packages
The sample requests and responses within this document use the following configuration.
-
Linux/MacOS shell in which environmental variables are set using the
export-command. Other environments may require a different setup. For example, Windows uses theset-command. -
Example API calls are demonstrated using "curl" command line utility. However, the APIs can be used in any programming language with an HTTP client such as Go, Python, NodeJS, Javascript, and Java.
DepotFinity APIs allow you to perform the following functions.
- Manage tokens
- Manage transactions
- Control charging power limits
- Generate session reports
- Get energy prices and power consumption
- Manage RFIDs
- Send remote commands to the charger
- Manage Reservations
- Terminate an active charger connection
- Interface with EV using VDV-261 parameters (The Authorization procedure for VDV-261 API is different from other DepotFinity APIs. For more information see VDV-261)
DepotFinity Packages#
Note
Access to API's will be available only when subscribed to the relevant packages.
| API | Basic | Advanced | Premium |
|---|---|---|---|
| Charger Status API | ✅ | ✅ | ✅ |
| Transactions API | ✅ | ✅ | ✅ |
| Session Reports API (applicable to only HPC chargers) | ✅ | ✅ | ✅ |
| Time Series API | ✅ | ✅ | ✅ |
| Force Termination API | ✅ | ✅ | ✅ |
| RFID Management API | ✅ | ✅ | |
| Remote Commands API | ✅ | ✅ | |
| Reservations API | ✅ | ✅ | |
| Charger Control API | ✅ | ||
| Virtual Power Plant API | ✅ | ||
| VDV-261 API | ✅ |
HTTP Status Codes#
HTTP response status codes indicate if a specific HTTP request is successful or not.
| Term | Description |
|---|---|
| 200 | Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action. |
| 201 | The request has been fulfilled, resulting in the creation of a new resource. |
| 202 | The request has been accepted for processing, but the processing has not been completed. The request might or might not be eventually acted upon, and may be disallowed when processing occurs. |
| 204 | The server successfully processed the request and is not returning any content. |
| 400 | The server cannot or will not process the request due to an apparent client error. For example, malformed request syntax, size too large, invalid request message framing, or deceptive request routing. |
| 401 | Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided. |
| 403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource, or may need an account of some sort. This code is also typically used if the request provided authentication via the WWW-Authenticate header field, but the server did not accept that authentication. |
| 404 | The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible. |
| 405 | A request method is not supported for the requested resource. For example, a GET request on a form that requires data to be presented via POST, or a PUT request on a read-only resource. |
| 406 | The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request. |
| 409 | Indicates that the request could not be processed because of conflict in the current state of the resource, such as an edit conflict between multiple simultaneous updates. |
| 429 | The user has sent too many requests in a given amount of time. Intended for use with rate-limiting schemes. Note: Allows 100 queries per five minutes per IP address |
| 500 | A generic error message, given when an unexpected condition was encountered and no more specific message is suitable. |
| 503 | The server cannot handle the request (because it is overloaded or down for maintenance). Generally, this is a temporary state. Note: Approximately 90 seconds |
| 504 | The server was acting as a gateway or proxy and did not receive a timely response from the upstream server. |
Concepts & Glossary#
The following table lists the terms, concepts, and glossary of different parameters used in DepotFinity APIs.
| Term | Description |
|---|---|
| Charger ID | A unique identifier that represents a charger in the network of chargers. |
| Connector ID | A unique identifier that represents a connector in the charger. There may be more than one Connector ID's linked to a charger. |
| Driver ID | A unique identifier that represents a driver linked to an EV participating in the charging activity. |
| Energy Delivered | Total energy delivered by the charger to increase the vehicle SoC. |
| EV | Electric Vehicle |
| JWT | JSON Web Token |
| MAC ID | A media access control address is a hexadecimal identifier assigned to each device connected to the network. |
| RFID | Radio frequency identifier is used in devices called RFID tags. The RFID tag can be used for the purposes of identification, authorizing charging activity, and so on. |
| SoC | State of charge of electric vehicle's battery. |
| Transaction ID | A unique identifier that represents a specific charging event at a specific time. |
| Vehicle ID | A unique identifier that represents the electric vehicle participating in the charging activity. |
| VIN | Vehicle Identification Number |
| HPC | High Power Charging |