Getting started

Easy PV and Heatpünk have a number of API endpoints that can be used to integrate CRMs, job management platforms and other applications. ThisWe isvery anmuch areawelcome thatconnections isto underour activedesign developmenttools, and if you have ana application thatplatform you would like to integrate with Easy PV or Heatpünk and need supportconnect please letgive us knowa shout - we'd be veryreally happy to help.

GETTING STARTED

Sandbox access

If you are developing an integration with another application we can give you access to our sandbox environment. Please ask for details. In all the examples we give here we use the live api at the https://easy-pv.co.uk/ domain; to use the Easy PV sandbox usesimply change this to https://sandbox.easy-pv.co.uk.

If

We youuse arethe integratingsame withunderlying platform for Heatpünk, and almost all the endpoints we refer to here will also work for Heatpünk (we'll make clear if not). For Heatpünk, use https://heatpunk.co.uk for the live environment, and https://sandbox.heatpunk.co.uk for the sandbox.

Documentation and testing

Documentation for the API is at https://easy-pv.co.uk/api/about/ and https://heatpunk/api/about/. Most calls are identical for Easy PV and for Heatpünk.

You can test calls from the documentation itself. It will also give example CURL calls which you can test from a command line. Platforms such as postman or hoppscotch are also very useful for development of an API integration.

Generating an API key

Most API endpoints that we make publicly available can only be accessed through a 'pro' team API key. For 'Pro' team owners and admins please login and go to your 'Pro account settings' dashboard, then click on the 'CRM connections' tab. Click on the 'Generate key' button to create an API key.

It is very important that you keep the API key secure. Anyone who gains access to it will be able to access and change all data for the users in your team, including customer names and addresses. We recommend it is only used for server-server requests, and stored as an environment variable and kept out of git repositories. If you wish to keep a backup of the key, use a secure password manager.

Note that we don't keep a record of the key. If you lose it, you will need to generate a new one.one for your application.

Documentation

If you are developing an application just for one company, you will only need to generate one key. If you have a platform that many companies use, every company will need to generate their own key and testing

save

Documentationit forto thetheir APIaccount ison atyour https://easy-pv.co.uk/api/about/ and https://heatpunk/api/about/. Most calls are identical for Easy PV and for Heatpünk.

You can test calls from the documentation itself. It will also give example CURL calls which you can test from a command line. Platforms such as postman or hoppscotch are also very useful for development of an API integration.platform.

PROJECT ENDPOINTS

/projects/create

A common requirement is to create a new Easy PV project from meta data that you already hold, such as a customer name, address and postcode.

You can create projects using the https://easy-pv.co.uk/api/v1/projects/create endpoint.

Projects must have an "owner", which must be specified in the request POST. The owner email must be a member of the pro team that owns the API key.

The fields you can pass across in the 'meta' object are: projectName customerName customerEmail customerPhone address postcode crmReference

crmReference can be used for your internal reference - it's likely that you will have a unique database ID that you want to be associated with the project. All fields are optional.

curl -X 'POST'   'https://easy-pv.co.uk/api/v1/projects/create'  -H 'accept: application/json' -H 'X-API-KEY: **********KEY***********' -H 'Content-Type: application/json' -d '{
  "owner": "sales@midsummerenergy.co.uk",  
  "meta": {
      "customerName": "Joe Bloggs"
  }
}'

The endpoint will return a JSON object with a projectId property. You will almost certainly want to save this projectId within your own database.

You can link directly to a project with a link of the following form:

https://easy-pv.co.uk/?project=872019

FORMS AND FILES Within Easy PV and Heatpünk, users complete forms and generate PDF reports. In your application you may want to view the completed files and forms associated with a project, and fetch completed form data and PDF documents.

To list forms for a project:

To get a list completed forms for a project, use /api/v1/projects/forms/list. Provide the projectId and ownerEmail in the GET parameters.

curl -X 'GET'
'https://sandbox.easy-pv.co.uk/api/v1/projects/forms/list?projectId=872034&ownerEmail=andy%40midsummerenergy.co.uk'
-H 'accept: application/json'
-H 'X-API-KEY: ---KEY---'

This should return an object with completed forms and surveys.

To retrieve form fields:

Use /api/v1/projects/forms/form.

You will need to provide the ID of the project, ID of the form (from the response above), and the ownerEmail.

curl -X 'GET' \

'https://sandbox.easy-pv.co.uk/api/v1/projects/forms/form?projectId=872034&form=letterOfConsent&ownerEmail=andy%40midsummerenergy.co.uk&formCategory=forms'
-H 'accept: application/json'
-H 'X-API-KEY: ---KEY---'

To list files saved to a project: Use /api/v1/projects/files/list. Set the type property to projects Provide the ID of the project and the ownerEmail Files saved within Easy-PV are listed within the fileRegistry.uploads array of the response.

curl -X 'GET'
'https://sandbox.easy-pv.co.uk/api/v1/files/list?type=projects&id=872034&ownerEmail=andy%40midsummerenergy.co.uk'
-H 'accept: application/json'
-H 'X-API-KEY: ---KEY---'

To download a file:

use /api/v1/files/file.

Provide the same details as the previous request, plus the file category (uploads) and the file name.

curl -X 'GET'
'https://sandbox.easy-pv.co.uk/api/v1/files/file?type=projects&id=872034&ownerEmail=andy%2Bjumptech%40midsummerenergy.co.uk&fileCategory=uploads&file=test%20project%20%20letter%20of%20consent~Letter%20of%20Consent.pdf&responseFormat=b64'
-H 'accept: application/json'
-H 'X-API-KEY: ---KEY---'

Setting responseFormat to either b64 or meta will include a meta object in the response. This includes a datetime string for when the file was created and last updated. b64 will also return the document as a base64-encoded string in the response. raw will just return the file as stored.

PROJECT DATA, CART AND ORDER LINKS

Easy PV and Heatpünk generate a full bill of materials for a project, and for our UK and Ireland sites you can very quickly place an order for the components from Midsummer. You may like to import the shopping cart into your application and display an ordering link. Users love the ease of ordering all the kit for an installation.

Please note - the cart is refreshed every time you visit the overview page of a project.

To fetch project data, including the cart and order link, use the api/v1/projects/data endpoint. You need to pass in the project ID, and the user you are acting as. The user must have view rights to the project. You will get back an object which includes a 'cart' array and a 'midsummerOrderLink' string. Both should be self explanatory.

The order link is an easy way to order everything needed for a project. However, if you offer the ability to edit the cart, you may like to generate your own order link. If you do this, you can also add some additional parameters such as a delivery address or order reference to the order.

In its simplest form, an order can be just an object with an 'items' property. For each item, specify the property.

const order = { "items": { "2586": { "qty": 99 }, "4258": { "qty": 99 } } }

Here is a more complex order, with a shipping address, despatch date and reference:

const order = { "items": { "2586": { "qty": 99 } }, "deliveryOption": "standard", "shippingAddress": { "postcode": "CB24 6AZ", "add1": "Midsummer Energy", "add2": "Cambridge Road Industrial Estate", "add3": "Milton", "add4": "", "email": " andy@midsummerenergy.co.uk ", "phone": "01223 858414", "firstname": "Andy", "lastname": "Rankin" }, "despatchDate": "2023-02-08", "reference": "trial order" }

Once you have created your order, simply create an order string by stringifying the object then Base64 encoding the result then URL encoding the result Then goto https://midsummerwholesale.co.uk/upload?order=[string]

In javascript: function createOrderLink(order) { return "https://midsummerwholesale.co.uk/upload?order="+encodeURIComponent(btoa(JSON.stringify(order))) }