Ask Flux
Help Center
How can we help?
All Categories
APIs
APIs Onboarding and Troubleshooting

APIs Onboarding and Troubleshooting

Last updated on November 11, 2024

Introduction

API stands for Application Programming Interface. GreenFlux makes available to its customers several APIs, which allow to automate data exchange between GreenFlux platform and external system/components.

 

Please note that the full documentation regarding APIs is at developer.greenflux.com

 

GreenFlux supports two type of APIs:

  1. "Normal" APIs: It is the customer (application) who initiates a request, e.g. make a GET call request, to obtain CDRs between date A and B
  1. Webhooks (also referred to as reverse-APIs), whereby it is GreenFlux who initiates the requests, by invoking a certain endpoint of the customer, to pass along a certain set of information. This is event driven, e.g. when a CDR webhook is configured for a certain customer, then every time a CDR is generated, this is a trigger that initiates the webhook to send the CDR to the customer's application.
 

GreenFlux, due to its nature as a SaaS provider, makes extensive use of APIs. This article will only focus on those that are customer facing.

Infrastructure and provisioning

GreenFlux divides its product in two main categories of APIs:

  1. Platform API
  1. Charge Assist (CA) API
 

Charge Assist API is meant specifically to target app development, that is meant to be used by EV Drivers, whereas Platform API covers all the remaining functionalities from GreenFlux platform, in its several modules, as presented below. It is worthwhile to mention that platform APIs are only meant to manage data that directly involves assets managed by GreenFlux backend (tokens and/or charge stations).

 
Category
Group
Module
Default Configurations*
Push available?**
Remarks
Platform API
CPO data
CDR
Read
NA
NA
Yes
By default small CDRs (not meetingeViolin criteria: <0.2 kWh and 2 min)are not published. All CDRs are populated/pushed when configurationitem 'PUBLISH_ALL_CDRS' is set to true.
Charge Station Notifications
Read
NA
NA
Yes
For push Info / Warning / Error can be configured via configuration item (ChargeStationNotificationsOcpiEventLevel), Info is default and pushes all. Warning only warnings and errors.
Locations v1
Read
NA
NA
Yes
Only one version of Locations module per subscription
Meter Values
Read
NA
NA
No
Sessions
Read
NA
NA
Yes
Charge-location management
Charge Stations
Read
Write
NA
No
Locations v2
Read
Write
NA
No
Only one version of Locations module per subscription
Remote commands
Remote Commands
Read
Write
NA
No
EMSP
CRM
Read
Write
NA
No
Smart Charging
Smart Charging
Read
Write
Delete
No
Charge Assist API
Charge assist
Charge Assist
Read
Write
Delete
Yes
Push available for sessions
  • Default configurations contain all available permissions. If less should be granted, this should be explicitly requested
  • *When push/webhook is required, customer must provide endpoint and token key for authorization

Can't make the API working? Check FAQ and troubleshooting guidelines on the bottom of the page

Platform API

Platform API Design

It is worthwhile to dig deeper into how the platform API is designed. APIs are setup by creating an API subscription. A customer can have one or more API subscriptions. From the customer perspective, each API subscription is characterized by the following elements:

  1. API token key: This is what allows the customer to make API calls and request information from the API subscription
  1. CPOs and/or EMSPs linked: Each subscription must have at least one CPO and/or EMSP linked to it. Linking a CPO/EMSP essentially means that the subscription has control over the assets beloning to that CPO/EMSP.
  1. Module(s) enabled: This will determine the endpoints that the customer is able to invoke; e.g. customer is only abel to make a GET CDR call, when the CDR module has been enabled. By default all permissions available (Read/Write/Delete, as applicable dependeing on the module) are enabled.
  1. (optional) webhooks enabled: when customer requires so we may configure webhooks for the API subscription, which will push information about the linked CPO(s)/EMSP(s) to the API subscriber.
  1. Special configurations:
    1. CDR Cost Breakdown - True/False: when this is enabled, the total costs breakdown will be available in the CDR, as applicable according to the scenario. For more info check the properties total_wholesale, total_retail and total_reimbursement in this page: CDR API (greenflux.com). This detail is only available for assets in our platform (e.g. reimbursement total only when this is configured in a charger in GreenFlux platform).

Very important aspects to retain on API infrastructure provisioning as well:

  1. Each platform API subscription is completely independent from one another.
  1. There are independent API subscriptions between PRODuction and ACCeptance environment.

Currently, none of the above aspects are visible to the customer, and these need to be communicated by your CSM/support. It is in the roadmap to improve this.

Onboarding Procedures

1. Step 1: Assess your needs with your CSM, for both ACC and PROD: 1. which modules, and whether any "special" requirements are needed, check introduction above 2. Which webhooks are to be configured, in this case, we need the endpoints and token keys from the customer - more info here 3. Which CPOs and/or EMSPs are to be linked to the API subscriptions  2. Step 2: CSM handles the request for the API subscriptions in ACC and PROD 3. Step 3: CSM shares the API token key with customer 4. Step 4: Customer tests in ACC, before going live to PROD.

  1. 1. Step 1: Assess your needs with your CSM, for both ACC and PROD:
    1. 1. which modules, and whether any "special" requirements are needed, check introduction above
    2. 2. Which webhooks are to be configured, in this case, we need the endpoints and token keys from the customer - more info here
    3. 3. Which CPOs and/or EMSPs are to be linked to the API subscriptions
  1. 2. Step 2: CSM handles the request for the API subscriptions in ACC and PROD
  1. 3. Step 3: CSM shares the API token key with customer
  1. 4. Step 4: Customer tests in ACC, before going live to PROD.

Charge Assist (CA) API

CA API Design

Similarly to the description we did above, so the CA API has a certain design. A customer can have more than one CA API subscription, but only when they develope more than one app.

From the customer perspective, each API subscription is characterized by the following elements:

  1. E-mail address linked to the subscription: This is links the API subscription with the customer. From the reserved page of contoso, the user will be able to check the API keys and test the API endpoints.
  1. CPOs and/or EMSPs linked: Each subscription must have at least one CPO and/or EMSP linked to it. Linking a CPO/EMSP essentially means that the subscription has control over the assets beloning to that CPO/EMSP.
  1. Module(s) enabled: All endpoints are enabled by default, except for PUT External Payment Method, which needs to be activated upon request.
  1. (optional) webhooks enabled: when customer requires so we may configure webhooks for the API subscription, which will push information to the API subscriber.

Contoso links:

  1. ACC: APIs: ACC CA API - Microsoft Azure API Management - developer portal (chargeassist.app)
  1. PROD: APIs: PROD CA API - Microsoft Azure API Management - developer portal (chargeassist.app)

Very important aspects to retain on API infrastructure provisioning as well:

  1. Each CA API subscription is completely independent from one another.
  1. There are independent API subscriptions between PRODuction and ACCeptance environment.

Currently, none of the above aspects are visible to the customer, and these need to be communicated by your CSM/support.

Onboarding Procedures

  1. Step 1: Assess your needs with your CSM, for both ACC and PROD:
    1. Inform when PUT External Payment Method needs to be activated
    2. Which CPOs and/or EMSPs are to be linked to the API subscriptions
    3. Which chargers should be made available through CA API. In ACC, only the chargers from the customer ACC tenant are displayed. In PROD, customer may choose one of the three, as applicable:
      1. Option 1: Only display in the app, charge stations from the customer in GreenFlux platform (applicable only if customer acts as CPO)
      2. Option 2: Display all charge stations that GFX has in its database (this is the setup for GFX charge assist app, and it cover nearly 100% of all chargers in europe, for instance)
      3. Option 3: (Option only possible for customers in self managed roaming) Customer can choose its charge stations, if applicable, plus the charge stations related to its agreements with roaming CPOs.
  1. On top of that, the customer provides the e-mail address of the account whose subscriptions (ACC and PROD) will be linked to. Customer needs to sign-up in contoso (see links above)
  1. Step 2: CSM handles the request for the API subscriptions in ACC and PROD
  1. Step 3: After request has been completed, CSM informs customer, who can check the API token keys by accessing the contoso pages (see links above):
  1. Step 4: Customer tests in ACC, before going live to PROD.

FAQs

Did this answer your question?
😞
😐
🤩
Submit a ticket