Skip to content

Retailer API

Introduction

Emulate's Retailer API allows electricity retailers to access all the customers, facilities, and devices associated with a retailer. Such access is granted via a cryptographically signed JSON Web Token used in the Authorization header of the Retailer API requests.

The integration between the Emulate service and the Retailer API occurs primarily at the backend level. There may be the following integration scenarios:

  • Integration with a retailer's support tools by being able to query the customer's SPO settings or to access logs of potential problems with a device.
  • Integration with a retailer's customer management system, so that when a customer leaves the retailer, their devices are automatically removed from Emulate's system.
  • Integration with a retailer's backend customer-facing web application. For example, if a retailer maintains a server-side web application for the customer portal, then it should be possible to add a page to let the user set up their SPO settings for a device.

Integration with the Emulate service via the Retailer API

Tokens for the retailer API grant access to the information of all customers of the retailer. The only time the token should be exposed to a frontend application is when it is a tool that should access all customer devices and settings, such as a customer support tool. If you need to build customer-facing frontend or mobile applications, use the Single Customer API instead.

Make a request to the Emulate Retailer API

Before querying the Emulate Retailer API, generate a JSON Web Token. For details on JWT generation, see Authorization.

The Emulate API supports the following environments:

Staging https://api.stage.emulate.network/
Productionhttps://api.emulate.network/

To make a request to the Retailer API, set up the HTTP Authorization header using the Bearer mechanism as follows. The token variable contains the JSON Web Token:

npm i axios
let res = await axios.get(
'https://api.emulate.network/v1/retailer/manufacturers',
{
headers: {
Authorization: 'Bearer ' + token
}
});
console.log(res.status);
console.log(res.data);

For testing purposes, you can use the Emulate staging environment with test data to configure your application:

let res = await axios.get(
'https://api.stage.emulate.network/v1/retailer/manufacturers',
{
headers: {
Authorization: 'Bearer ' + token
}
});
console.log(res.status);
console.log(res.data);

Troubleshooting

If you get a 403 (access denied) error in the response to your Retailer API request, check the following:

  • The JWT is syntactically valid. Validate your token by pasting it in the JWT tool.
  • The signing algorithm is RS256.
  • The key corresponds to the environment you are using.
  • The key is generated for the Retailer API, not the Single Customer API.
  • The correct retailer ID is used.
  • The token has not expired

What To Read Next

→

For a full description of requests, responses, and parameters, see the Retailer API Reference . To download the complete API Reference, navigate to the Retailer API Reference page and click Download OpenAPI