Information


API Versions

Currently our api supports three different versions.

Incoming requests version is determined by api url (/api/V3/, /api/V2/ or /api/V1/). When just /api/ url is used, then users default api version is used (set in provider API settings GUI), or if that is also not set, then default api version is used (that is currently v1).

On outgoing requests, providers default api version is used (set in provider API settings GUI), or if that is also not set, then default api version is used (that is currently v1).


Changes between API V3 and API V2

Description
Added messages: Added forwardable messages: Added AVP response message that is sent asynchronously in result to forwardable messages that are not sent from the user interface:

Changes between API V2 and API V1

Description Affected xml files
Metering point location data change. StreetAddress and Locality fields were replaced by County, Municipality, Locality, StreetAddress and Postcode.
Metering point metadata change. DeviceIdentification (W-Code) field was added. This field is used in case on production devices otherwise it is empty.
Metering point metadata change. ConsumptionType field was added, with options: CONSUMER GRID_OPERATOR PRODUCER MICRO LINE_OPERATOR
Metering point metadata change. Isolated field was added, with options true and false
Metering point metadata change. ElHeating field was added, with options true / false
NotifySupplyAgreement was updated by field Reason, with options GRID_AGREEMENT_ENDED, GRID_AGREEMENT_RESTORED. GRID_AGREEMENT_ENDED is used when grid agreement is ended and data hub ends automatically the supply agreement. GRID_AGREEMENT_RESTORED is used when the grid agreement is restored (was ended by mistake) and data hub restores the previous supply agreement.

V2 and V1 Metering point location mapping

Api versions v2 and v1 work parallel until v1 support is ended. As v2 is using 5 location fields instead of 2, there is data mapping between two versions. v2 and v1 location data is stored separately. Therefore it is important to understand how the outgoing messages are mapped between two versions.

V1 Outgoing XML

  • If v2 location data is present. Location will be assembled from v2 data.
    • StreetAddress - mapped by v2 StreetAddress
    • Locality - mapped by v2 County, Municipality, Locality, Postcode, separated by commas
  • If v2 location is not present. V1 Location data is used.

V2 Outgoing XML

  • If v2 location data is present. V2 Location data is used.
  • If v2 location is not present.
    • StreetAddress - mapped by v1 StreetAddress
    • Locality - mapped by v1 Locality
    • County - empty
    • Municipality - empty
    • Postcode - empty

Message exchange information

Message exchange is done using HTTP using POST requests. Maximum message size is 100MB.

Security

Basic Authentication is used to identify senders. The sender's EIC code is the username. A password is initially assigned by Elering administrator and can be later changed by the sender. HTTPS is used for transport to guarantee channel security.

Message transfer

The message XML is sent as request body, no special encoding is used. Most of the messages are processed synchronously and the response message (if any) is sent as the response body. Some messages which don't require any specific data in return will only get an OK response with no message body.

Response codes

The HTTP response status code is used to communicate success or failure.

  • Status 200 OK: the message was processed successfully, response body contains the response message.
  • Status 202 ACCEPTED: the message was accepted but processing will happen asynchronously.
  • Status 204 NO CONTENT: the message was processed successfully, there is no response message.
  • Status 400 BAD REQUEST: there was something wrong with the message. The HTTP status text gives more information about the problem. See below for details about the error messages. You should not retry the sending without modifying the message as it will fail again.
  • Status 401 UNAUTHORIZED: authorization failure. Could be invalid username or password or the sender might be disabled by Elering.
  • Status 500 INTERNAL SERVER ERROR: you should retry sending the message after a short delay.

Error messages

When you receive a Status 400 BAD REQUEST response then the text will contain details about what went wrong. See each message for possible errors.
Error messages are usually caused by user input or actions and therefore the data can be modified and retried.
Additionally there are a few errors which mean that the message was composed incorrectly: schema validation failures, invalid sender or receiver codes, etc. These are most likely programmer errors.

Asynchronous responses/events

Some messages require longer processing times and therefore the response is generated asynchronously. Also some events require data to be sent out from AVP without a prior request. For this the same logic is used, only the roles are reversed - the AVP becomes the sender and the provider becomes the receiver. Therefore the provider should implement a server that conforms to the same principles. The URL of the server and the credentials for AVP should be communicated to Elering administrator.

Testing

Current test URL: https://avp-test.elering.ee/api
Current test receiver EIC: ELERINGAVPTEST-W
Simple testing UI