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:
Trade Capturing
Automatic RFQ creation on entender
Automatic quoting of entender RFQs
Active monitoring of entender RFQs
Newsletter
To get notified about upcoming changes or updates of the enmacc API, we adivse to subscribe to the enmacc developer newsletter.
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.
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 API request has to have a valid x-api-key HTTP request header.
Every request is counted against your usage plan. The default usage plan is as follows:
Throttling (requests per second): 10 req/sec
Burst (bucket size): 100
Quota (requests per day): 5000 req/day
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.
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.
A valid access-token is returned in the response body.
For subsequent request to other endpoints, two HTTP headers have to be set accordingly:
x-api-key: Provided API key for usage plans
Authorization: "Bearer $access-token", where $access-token represent the value of the access-token field of the previous request Note: The HTTP header value has to start with the string "Bearer ".
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.
After authentication, all requests must have a valid x-api-key and Authorization HTTP request header.
Environments
There is a sandbox environment to setup and test the integration of external services without affecting the production trading environment:
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:
200: OK Request was successful
201: Entity Created Request created successfuly a new resource.
400: Bad Request / Limit Exceeded Invalid request. Check for errors or field errors in the body of the response.
401: Unauthorized No valid authorization token exists in the request headers.
403: Forbidden The provided authorization token is not allowed to access the resource.
429: Too Many Requests Exception Usage plan is exceeded.
500: Internal Server Error Server was not able to process the request successfuly.
503: Maintenance Mode Enmacc servers are currently in maintenance mode and unable to serve requests.
Versioning
The API is versioned using a version number in the URL (e.g. /v2.0).
Given a version number MAJOR.MINOR, the:
MAJOR version indicates when incompatible API changes were introduced.
MINOR version indicates when functionality was added in a backwards compatible manner.
In order to make sure that your implementation is not affected by minor version changes, please make sure that
Enumeration values can be added in the future
Additional object properties can be added in the future
Additional polymorphism models can be added in the future (specific discriminator properties can be used for typecasting on API consumer side)
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:
The requests conform to the HTTP protocol
The endpoint must be secured (https://...)
Throttling on the side of the external user is not considered
Webooks are only executed once per event, there are no retries for failed attempts
Skinny payloads are used. Only minimal information, like eventType and IDs are delivered with the webhook
See the model definition for Event and the /ping endpoint for an payload example
The following event types are currently available:
demandTraded Triggered when your company makes a trade on entender
demandCreated Triggered when your company receives a new request on entender
quoteCreated Triggered when your company receives a quote from a recipient for one of your company's open entender requests
priceProposalAdded Triggered when your company receives a price proposal for an entender request that was sent to your company
demandClosed Triggered when a request, which your company received on entender expires, is witdrawn or is traded with someone else
Release Notes
We added the following new features:
Endpoints to access the suggested recipient lists
Support for automatically adding appropriate suggested recipient list (using suggested-recipient-list-enabled flag on request creation)
Support for anonymous trading
Minor update aligning the documentation with the properties already exposed through the API.
With this update we're introducing significant changes to support enmacc’s expanded range of commodities on entender. The API now fully supports all commodities that enmacc offers on the platform, with more to be added in the future.
Action Required:
Please update your API integrations by the end of August 2023 to access the new functionalities and expanded range of commodities without interruption.
If you need any assistance or have questions about the API update or the new commodities, don’t hesitate to contact enmacc’s support team at support@enmacc.com or connect@enmacc.com.
Key Changes:
Enhanced “/trades” endpoints: The /trades endpoints now accommodate the new commodities, and we’ve added an additional property to capture the ID of the entender request that led to the trade.
Deprecated entender “/quotations” endpoints: The old 2.0 entender quoting endpoints are deprecated. Instead, new 2.1 endpoints are introduced to ensure compatibility with the updated entender trading, handling all the new commodities seamlessly.
Documentation for request creation (POST /entender/requests) has already been updated to support all commodities, however they will only be available for creation at the end of August 2023!
Elcerts have been removed from all endpoints:
The offering of elcerts on the enmacc platform has been discontinued
As such all references to elcerts have been removed from the API
A new endpoint was created to retrieve concluded entender
The new endpoint returns all concluded (traded and non-traded) entender requests
Filters can be used in order to narrow down the results
This replaces the concluded filter for the /entender/requests endpoint! This filter is depcreated and will soon be removed!
There are new filters available when querying /entender/requests:
created-at: All entender RFQs created within the specified period, can only be queried for the past 7 days
concluded-at: All entender RFQs concluded (traded or otherwise) within the specified period, can only be queried for the past 7 days
Some changes have been made to reflect an expansion to our clearing capabilities with multiple different exchanges:
Most of the clearing related properties have been deprecated and will be removed in the near future
Clearing related information is now aggregated under a new optional clearing-info property
This property will only be present if the associated RFQ is available for clearing
Some changes have been applied to the documentation:
Balancing zone names have been adjusted and new ones added
An additional disclaimer has been added to the entender/{id} endpoint based on customer feedback to remove ambguity regarding "buy/sell" on RFQs
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 GoOs)
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.
enmacc Connect is migrating to Version 2, Version 1 will be phased out in Q1 2022!
Existing API endpoints will be refactored and replaced with Version 2 endpoints.
Version 1 API endpoints will be set to deprecated and support will continue for a limited time.
Connect API Version 1
Connect API Version 1 focuses on trade capturing and demand forwarding of entender and enmarket.
Trade capturing for entender and enmarket.
Querying and creation of demands for entender.
Creation of quotes for entender.
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:
EUR Currency only Demands with other currency are not accessible and are filtered out
MW and MWh quantity only Demands with other units are not accessible and are filtered out
Gas and power commodities only Demands with other commodities are not accessible and are filtered out
entender and enmarket only Demands from other products (e.g. engreen) are not accessible and are filtered out
No support for spreads, index pricing, or instand entender requests
/trades resource replaces v1 resource /demands for the trade capturing purposes
Authentication works exactly like in v1, but is now available with a v2.0 url prefix. v1 credentials can be reused.
The structure was tailored to better reflect the needs of trade-capturing in contrast to the demand-based v1 -approach. Therefore irrelevant information is excluded in the Trade representation.
v2Trades make use of discriminators to reflect subtypes or compositions to avoid null values. E.g. Instrument shows specific properties depending on the commodity.
The response is always generated from the requester's view to remove ambiguity.
v2 makes use of pagination to improve performance.
Workflow Outline
Authenticate via the POST /v2.0/authenticate endpoint to get an access-token.
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.
Depending on your use-case, you can get more details about a specifc trade by using the GET trades/{id} endpoint multiple times.