​
Introduction

This document explains how to develop a third-party integration with an energy provider that will be pluggable into FlatPeak backend systems. To make it easier to follow the steps below, we presume you are developing an integration with a provider that supplies your home or business and will refer to it as “your provider.”

The integration scope is designed to be light and only implements the functionality necessary to obtain access to your account with your energy provider and read your tariff.

​
Prepare the project

1

Obtain FlatPeak IDs

Before you can start working on the integration, you need to obtain a FlatPeak ID for your provider. If you cannot find your provider in the list, complete this form.

  1. Login to Dashboard and go to Integrations > Energy Providers.
  2. Find your provider in the list, and check that it does not have the Direct label.
  3. Make note of its FlatPeak ID and Name.
We will use FLATPEAK_ID prv_63a6087272941ef077a8fd3e and PROVIDER_NAME LunarEnergy in this guide.
2

Clone FlatPeak starter package

Clone provider integration starter template from FlatPeak repository on GitHub:

git clone https://github.com/flat-peak/flatpeak-provider-integration-template.git
3

Prepare your project

Run the following commands to detach your code from the FlatPeak repository, set the required environment variables and install dependencies:

cd flatpeak-provider-integration-template
git remote remove origin # unlink local repo from starter project
cp .env.blank .env # copy vars for your local environment
npm i # install dependencies
4

Apply FlatPeak IDs

Search project and replace text placeholders:

<PROVIDER_NAME> -> LunarEnergy

<FLATPEAK_ID> -> prv_63a6087272941ef077a8fd3e

​
Implement integration functions

The scope of FlatPeak provider integration is comprised of three main functions:

  1. Obtain authorisation to access your account with your energy support (authorise).
  2. Locate your tariff inside your energy provider’s dashboard and (capture) it.
  3. Converting this tariff into FlatPeak format (convert).

Typical energy provider integration architecture

You will implement functions in ./modules/provider/index.js:

FunctionDescription
authoriseValidates the username and password that you have captured on views/auth_metadata_capture.hbs page where the login form is located. It shall return the status, error message if it occurred and all additional data required to request the tariff, such as access_token or cookies.
captureFetches tariff object from the user account with the provider using values returned by the authorise function. The output of this function shall be a tariff object with a unique reference_id for which you can use anything that uniquely identifies the tariff, such as user account identification with the provider.
convertTransforms the tariff object received from the capture function into a FlatPeak tariff object, as defined in Tariff element model.
You can find an example implementation (non-OAUTH2, GraphQL) in: https://github.com/flat-peak/provider-octopus-energy-uk/blob/main/modules/provider/index.js

​
Console testing

You may find it helpful to run e2e tests as defined in e2e.test.js:

  1. Insert credentials for your energy provider dashboard to .env file:
TEST_CUSTOMER_USER=user@email.com
TEST_CUSTOMER_PASSWORD=password
  1. Run tests: npm test

​
Browser testing

Once integration functions are implemented and you can pass console tests, you shall test user flow in the browser. You will need to obtain a valid token to run FlatPeak Connect. Here is how to do it:

1

Obtain a token to start Connect session

  1. Grab account_id and any api_key from API keys page in the Dashboard
  1. Create a bearer_token (read more about FlatPeak API authorization here
  1. Use bearer_token to create a connect_token
Set callback_uri to any page accepting callbacks. Our team likes https://webhook.site, but you can choose any other service.
2

Bind your provider to Connect session

curl --request POST \
  --url https://connect.flatpeak.com \
  --header 'Content-Type: application/json' \
  --data '{
  "connect_token": "cot_6587fa4362341be5b524de3b",
  "route": "provider_select",
  "data": {
    "provider": {
      "id": "prv_63a6087272941ef077a8fd3e"
    }
  }
}'
3

Run your application

  1. Run npm start

  2. In a browser, open: http://localhost:8080/?fp_cot= and append the Connect token you created earlier, i.e.:

  3. A Login form should be displayed. Submit username and password for your account with your provider.

  1. After you submit the correct login credentials, the Sharing consent form should be displayed.

You have now completed the development of FlatPeak third-party provider integration. For the next steps, contact FlatPeak support at support@flatpeak.com.

Was this page helpful?