Connect-web handles getting authorisation and consent for your application to obtain access to your customer’s energy tariff. Please use your backend systems to make requests to obtain the tariff data. For security reasons, tariff requests should not be made client-side.

​
Setup

1

Clone our repo and install the required dependencies

git clone https://github.com/flat-peak/flatpeak-connect-web.git
cd flatpeak-connect-web
npm install
2

Set the environment variables

export FLATPEAK_CONNECT_URL=https://connect.flatpeak.com
If you are on Windows, ensure you appropriately set env variables for your shell.
3

Run Connect-web locally

npm run dev

A local preview of Connect-Web will be available at http://localhost:7070. The Connect landing page is blank.

​
Obtain a Connect token

You need a connect_token to start a session with Connect. Connect Tokens are single-use objects that identify and secure your customer’s session with Connect. You must create a new connect_token every time you want to start a new Connect session for your customer.

1

Authenticate to FlatPeak API

To create a connect token you need to make a request to create-conect-token API endpoint. Learn how to authenticate to FlatPeak API, follow the authorization-guide.

2

Create a Connect token

Go to create-connect-token API endpoint and create a connect_token.

  • Set connect_web_uri to http://localhost:7070 if you are using the default port.
  • Set callback_uri to any page that can accept callbacks.
Our team likes https://webhook.site for callback tests but you can use something else.
curl --request POST \
--url https://api.flatpeak.com/connect/tariff/token \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"direction": "IMPORT",
"type": "COMMODITY",
"connect_web_uri": "http://localhost:7070",
"callback_uri": "https://webhook.site/4623e56fc5c1",
"postal_address": {
  "country_code": "GB"
}
}'

​
Run Connect Web

1

Open Connect-web in your browser

On your computer, where you already have Connect-web running locally, open to the following URI: http://localhost:7070?fp_cot=cot_***. Replace cot*** with the connect_token. The resulting URI may look similar to this example:

2

Follow the Connect flow

Connect will present you with a set of pages that will let you share your tariff information. It automatically chooses the best route to discover your tariff based on the availability of provider APIs, data-sharing regulations and frequency of provider use within the FlatPeak base.

3

Receive callback

Once click Save button on the Tariff Summary screen, Connect-web will send the following to your callback_uri:

Example callback
https://webhook.site/4623e56fc5c1?fp_cot=cot_6587fa4362341be5b524de3b&fp_status=success

​
Obtain IDs to access customer’s tariff

Using connect_token as a reference, call exchange-connect-token API endpoint to get permanent identifiers that you will use to obtain your customer’s tariff.

location_idIdentifies of the physical location where energy is supplied under an agreement between your customer and their provider.
customer_idIdentifies your customer in FlatPeak systems.

Store both IDs in your application’s database in reference to your customer and the physical location of their property.

​
Make requests to tariff rates API endpoint

1

Requesting tariff rates

You can now make requests to tariff-rates and other API endpoints using location_id as a reference.

curl --request GET \
  --url 'https://api.flatpeak.com/tariffs/rates/{id}?start_time=2023-06-15T09:00:00Z&end_time=2023-06-15T23:00:00Z' \
  --header 'Authorization: Bearer <token>'
2

Handling pending tariff connection

If FlatPeak background service is unable to immediately access your customer’s tariff (for example if energy provider systems are down or if FlatPeak provider integration is unable to parse the tariff) you will receive a 422 error response from the API.

Continue to make the API calls, the error will usually clear itself in minutes. If this does not happen, FlatPeak engineer will resolve the issue behind the scenes; no action is required.

{
  "object": "error",
  "type": "api_error",
  "live_mode": true,
  "time_created": "2022-01-24T14:15:22.003",
  "code": "pending_connect",
  "message": "Connect is processing link to tariff source."
}

Was this page helpful?

Try hosted ConnectNative app or Server-side