enmacc Connect HTTPS API

Version: loading (last updated: May 2020)

Interact with the enmacc trading platform via the modular HTTPS API and automate processes between enmacc and your trading systems.


enmacc CONNECT relies on modern and safe technologies:

Outline


Introduction

This document contains information for developers, on how to use the enmacc CONNECT HTTPS API. With enmacc connect, you can integrate enmacc into your internal workflow allowing you to have a more efficient and quicker trading process. E.g. it enables an information exchange between your Portfolio Management System (PFM), Risk Management Tool, Pricing Tools or similar systems and enmacc to digitize your energy trading processes.

Example use-cases:

Newsletter

To get notified about upcoming changes or updates of the enmacc API, we adivse to subscribe to the enmacc developer newsletter.
* indicates required

Please select all the ways you would like to hear from Enmacc about the Connect API:

You can unsubscribe at any time by clicking the link in the footer of our emails. For information about our privacy practices, please visit our website.

We use Mailchimp as our marketing platform. By clicking below to subscribe, you acknowledge that your information will be transferred to Mailchimp for processing. Learn more about Mailchimp's privacy practices here.

Getting Started

enmacc CONNECT provides simple and secure RESTful HTTPS interfaces for exploring and interacting with the enmacc platform from your own applications.

1. Register

We'll assign an OAuth client_id and client_secret for each of your applications. We additionally give you access to a sandbox environment for development and testing.

Please contact us directly success@enmacc.com

Sign up for enmacc Connect

2. Authenticate

Authenticate your application with enmacc CONNECT. You retrieve an active authorization token with your secure credentials.

Check the POST /authenticate endpoint for more information.

3. Request API

Make requests to our API endpoints with your OAuth credentials.

enmacc CONNECT uses HTTPS over TLS (HyperText Transfer Protocol Secure) as a secured, bidirectional tunnel for communication.

API Keys & Usage Plans

There are measurements in place to protect the API from abuse. This includes a request quota and throttling using the token-bucket pattern. Every client needs to obtain a valid API key to be able to use the API. This key is not used for authentication but to map the requests to a usage plan. Consider this API key a secret! Do not publish the API key. API keys can be revoked to prevent or stop abuse.

Every request is counted against your usage plan. The default usage plan is as follows:

These limits are soft-limits. You can request an increase of these limits. Please contact us directly via success@enmacc.com and describe your use-case.

Authentication

A two-legged OAuth2 approach (using client credentials) is implemented for authentication and results in a JWT access token. OAuth is an open industry-standard protocol to allow secure authorisation in a simple and standardized manner for web, mobile and desktop applications. The necessary credentials are provided by enmacc. Use the POST /authenticate endpoint with your provided credentials to receive a valid JWT token. This token is needed to authenticate you for every subsequent request.

Authentication flow
  1. Request an access token with provided credentials(client-id, client-secret and x-api-key):
    Use the POST /authenticate with your client-id and client-secret as parameters. Don't forget to set the x-api-key HTTP header.
  2. A valid access-token is returned in the response body.
  3. For subsequent request to other endpoints, two HTTP headers have to be set accordingly:
  4. Using the HTTP headers described in the previous step, protected resources can be accessed.
    Note: By default, the access-token expires at midnight of the issued date. Therefore the token can be reused for multiple requests over the day.

Environments

There is a sandbox environment to setup and test the integration of external services without affecting the production trading environment:

Client: https://sandbox.enmacc.com
API: https://connect-sandbox.enmacc.com/

The production environment is available via:

Client: https://trading.enmacc.com
API: https://connect.enmacc.com/

Error Codes and HTTP Status Codes

In general the API response with errors and more specific field-errors if a request was invalid. Field errors occur when the validation of a single property fails. Errors can refer to a more global error or invalid state.

Used HTTP status codes:

Versioning

The API is versioned using a version number in the URL (e.g. /v2.0).

Given a version number MAJOR.MINOR, the:

In order to make sure that your implementation is not affected by minor version changes, please make sure that

Older versions may be marked deprecated and an End-of-life (EOL) will be announced. See previous specifications for more details.

Webhooks

This API uses webhooks to inform external systems (like a portfolio management system) about events (like a traded demand) that occurred on the enmacc system. Therefore, the external system must have an endpoint to digest these incoming events. Provide enmacc the URL to setup the webhook.

Properties:

  1. The requests conform to the HTTP protocol
  2. The endpoint must be secured (https://...)
  3. Throttling on the side of the external user is not considered
  4. Webooks are only executed once per event, there are no retries for failed attempts
  5. Skinny payloads are used. Only minimal information, like eventType and IDs are delivered with the webhook
  6. See the model definition for Event and the /ping endpoint for an payload example

The following event types are currently available:

Release Notes

With this release enmacc announces a major update for enmacc connect API.

Several new endpoints and data models are available to interact with entender via the API:

  • Fetching open and closed entender requests
  • Fetching quotes for entender requests
  • Sending and withdrawing quotes to and from open entender requests
  • Fetching price proposals for open entender requests

Additionally, a new authentication endpoint has been made available which now fully complies with the OAuth 2 standard. The previous authentication endpoint has been marked as deprecated at will be removed at some point.

With this release enmacc announces a new version for enmacc connect HTTPS API.

A new data model and structure of endpoints incorporate:

  • new currencies, units & markets
  • additional trading venues like e.g. engreen (trading of GoO and Elcerts)
  • fast & efficient querying

enmacc HTTPS API V2 starts with focusing a cross-venue trade capturing use case. Therefore /v2.0/trades endpoints will provide an unified access to all trades which are traded via entender, enmarket and engreen. Venue specific endpoints to allow use cases like automatic quoting or deal forwarding will follow shortly.

Additionally, specific enmacc HTTPS API V1 endpoints are marked deprecated. See previous specifications for more details.

Specification enmacc connect v2

Previous Specifications

We are always committed to offer a long lifetime of API endpoints to facilitate the connection to the enmacc platform. Advancing and improving of the enmacc platform sometimes requires an adapation or replacement of existing APIs or the underlying data model. Therefore breaking changes are deployed with an incremented API version. Older versions may be marked deprecated and an End-of-life (EOL) will be announced.

An overview of previous API specifcations including current status can be found in the following paragraphs.


Connect API Version 1

Connect API Version 1 focuses on trade capturing and demand forwarding of entender and enmarket.

State: rework commenced This API is partly replaced by the new v2.0 API (trade capturing use case). Further use cases will be converted in the future.

Limitations

Connect API Version 1 was originally targeted for entender and enmarket for German power and gas trading and therefore shows some limitations in the international context:

Go to Specification Version 1

Migration Guidelines - Use case: Trade capturing

Major changes
Workflow Outline
  1. Authenticate via the POST /v2.0/authenticate endpoint to get an access-token.
  2. Query the GET /v2/trades endpoint to get a list of trade references ordered by tradet-at timestamp. You can restrict or filter trades by commodity, traded-at date and pagination details.
  3. Depending on your use-case, you can get more details about a specifc trade by using the GET trades/{id} endpoint multiple times.

Risk API

Go to Risk API Specification


Renewables API

Go to Renewables API Specification


Pricing API

Go to Pricing API Specification