guide d'utilisation-api comptage brute rest...guide d’utilisation api speed balancing version...

Guide d’Utilisation API Speed Balancing View Version 1.0

1

GUIDE D’UTILISATION

API SPEED BALANCING

Version 1.0

Date d’entrée en vigueur : 17 Décembre 2018

Guide d’Utilisation API Speed Balancing Version 1.0

2

SOMMAIRE

1 INTRODUCTION ________________________________________ 4

1.1 Définitions ........................................................................................... 4

1.2 Assistance technique ............................................................................ 5

2 DESCRIPTION FONCTIONNELLE DE L’API SPEED BALANCING ___________ 6

2.1 Description générale ............................................................................. 6

2.2 Pré-requis à l’utilisation des API ............................................................. 6 2.2.1 Confidentialité des données ...................................................................... 6 2.2.2 Résiliation ................................................................................................ 6

2.3 Ressource « balancing_per_brp » .......................................................... 6

2.4 Ressource « balancing_per_entity » ....................................................... 6

2.5 Ressource « reserves_per_brp » ............................................................ 6

2.6 Ressource « reserves_per_entity »......................................................... 6

2.7 Agrégation des données ........................................................................ 7

3 ACCES A L’API ________________________________________ 8

4 RESSOURCES EXPOSEES PAR L’API « SPEED BALANCING » ____________ 9

4.1 Ressource /balancing_per_brp ............................................................... 9 4.1.1 GET /balancing_per_brp ........................................................................... 9

4.1.1.1 Modalités d’appel ............................................................................ 9

4.1.1.2 Entrées ........................................................................................ 10

4.1.1.3 Sorties ......................................................................................... 12

4.1.1.4 Règles de gestion ......................................................................... 13

4.1.1.5 Codes erreurs ............................................................................... 14

4.2 Ressource /balancing_per_entity .......................................................... 14 4.2.1 GET /balancing_per_entity ..................................................................... 14

4.2.1.1 Modalités d’appel .......................................................................... 14

4.2.1.2 Entrées ........................................................................................ 16

4.2.1.3 Sorties ......................................................................................... 17


4.2.1.5 Codes erreurs ............................................................................... 19

4.3 Ressource /reserves_per_brp ............................................................... 19 4.3.1 GET /reserves_per_brp........................................................................... 19


4.3.1.2 Entrées ........................................................................................ 21

4.3.1.3 Sorties ......................................................................................... 23


4.3.1.5 Codes erreurs ............................................................................... 25

4.4 Ressource /reserves_per_entity ............................................................ 25 4.4.1 GET /reserves_per_entity ....................................................................... 25


4.4.1.2 Entrées ........................................................................................ 27


3

4.4.1.3 Sorties ......................................................................................... 29


4.4.1.5 Codes erreurs ............................................................................... 31

5 DETAILS DES ERREURS __________________________________ 32

5.1 Erreurs fonctionnelles .......................................................................... 34

5.2 Erreurs techniques ............................................................................... 35

6 ANNEXES ___________________________________________ 37

6.1 Fichiers Exemples ................................................................................ 37

FIN DU DOCUMENT _____________________________________ 37


4

1 Introduction

Ce document décrit l’API Speed Balancing en version 1.0 mise à disposition par RTE aux Clients Responsables d’Equilibre dans le but d’exposer les Volumes d’Energie d’Equilibrage (Services

Systèmes et Mécanisme d’Ajustement) activés sur leurs périmètres. Ces données sont disponibles

en temps réel, c’est-à-dire 15 min après le pas de règlement des écarts.

Documents de référence

Référence courte

Titre du document Référence complète

[R1] CGU des API RTE Lien d’accès

1.1 Définitions

Les termes utilisés dans le Guide d’Utilisation et dont la première lettre est une majuscule sont définis

ci-dessous ou, à défaut, dans les Conditions Générales d’Utilisation [R1] :

API Application Programming Interface (Interface de programmation

applicative)

Authentification Mode de Protection permettant de s’assurer que l’identité de l’Émetteur ou du Récepteur a été vérifiée par RTE et qu’il est donc autorisé à accéder au

SI et à utiliser les Applications.

EIC « Energy Identification Code », système d’identification unique des acteurs et des objets du marché de l’énergie (ex : entités, zones, points de mesures,

liaisons électriques d’interconnexion), défini par l’ENTSO-E.

Émetteur Partie qui émet un Message.

ENTSO-E Association « European Network of Transmission System Operators for

Electricity » (www.entsoe.eu), association qui rassemble des GRT

Européens

Message Ensemble de données informatiques destiné à véhiculer des informations

et structuré selon un ordre spécifié dans le Guide d’Utilisation. Un Message peut être émis par l’Utilisateur ou RTE.

Méthode Une méthode est la manière dont le client interagit avec la ressource de

l’API. Il s’agit d’un verbe http (par exemple : GET pour lecture)

Partie ou Parties Dans le cadre du Guide d’Utilisation, il s’agit, individuellement, soit de RTE soit de l’Utilisateur et, conjointement, de RTE et de l’Utilisateur.

Récepteur Partie qui reçoit le Message de l’Émetteur.

Ressource Une ressource représente la donnée sur laquelle l’application cliente interagit.

URL Uniform Resource Locator : chaîne de caractères suivant un format

spécifique permettant de localiser une ressource sur un réseau et d’identifier un moyen d’agir (protocole) sur cette ressource.

Utilisateur(s) Personne morale ayant validé les Conditions Générales d’Utilisation des API de RTE et accédant au SI de RTE afin d’utiliser les API mises à dispositions

par RTE.

https://data.rte-france.com/fr/cgu


5

Mécanisme

d’Ajustement

Mécanisme mis en place par RTE, en application de ses missions légales

(notamment l’article L.321-10 du Code de l’énergie) et statutaires en vue d’assurer les quatre fonctions suivantes :

- assurer en temps réel l’Equilibre P=C ;

- reconstituer les minima requis en Réserves Primaire et Secondaire ;

- reconstituer les minima requis en Marge à Echéance et Réserve

Rapide ;

- résoudre les Congestions du RPT.

Services Système Services comprenant le Réglage Primaire et Secondaire de la fréquence

1.2 Assistance technique

En cas de difficulté pour l’accès ou l’utilisation d’une API, l’Utilisateur peut faire appel aux services

d’assistance téléphonique mis en place par RTE dans les conditions techniques prévues dans les Conditions Générales d’Utilisation.


6

2 Description fonctionnelle de l’API Speed Balancing

2.1 Description générale

Le modèle d’équilibrage français repose aujourd’hui en grande partie sur les Responsables d’Equilibre

en complément de RTE qui est en charge d’assurer l’équilibre physique.

Cette API a pour but de mettre à disposition des Responsables d’Equilibre les volumes d’énergies

d’équilibrage (Mécanisme d’Ajustement - MA et Services Systèmes - SSY) activés sur leurs périmètres.

Ces données sont disponibles en temps réel, c’est-à-dire 15 min après le pas de règlement des écarts.

Les données peuvent être mises à jour après le contrôle du réalisé.

Le service mettra à disposition des clients les données à partir de Septembre 2017 pour le MA et les

SSY.

2.2 Pré-requis à l’utilisation des API

L’API Speed Balancing est destinée aux Clients titulaires d’un Accord de participation en tant que Responsable d’équilibre et à tous tiers mandatés.

2.2.1 Confidentialité des données

Les informations contenues dans les Messages ne pourront être utilisées à d’autres fins que celles

prévues dans les Conditions Générales d’Utilisation [R1].

2.2.2 Résiliation

L’abonnement à une API est automatiquement résilié lorsque l’utilisateur supprime son compte sur le

portail Digital RTE.

Si l’Utilisateur souhaite ne plus utiliser une API sans résilier l’abonnement, il suffit de cesser l’émission

des appels à l’API.

2.3 Ressource « balancing_per_brp »

Cette ressource permet de récupérer pour le même Responsable d’Equilibre, les données « Ajustements

» avec différentes agrégations en fonction du type de sites constitutifs des supports d’offre.

Cette ressource est uniquement accessible en lecture, via une méthode de type GET.

2.4 Ressource « balancing_per_entity »

Cette ressource permet de récupérer pour le même Responsable d’Equilibre, les données « Ajustements » par EDA Injection appartenant au périmètre de ce même RE.


2.5 Ressource « reserves_per_brp »

Cette ressource permet de récupérer pour le même Responsable d’Equilibre, les données « Services

Système » avec différentes agrégations, en fonction du type de sites constitutifs des supports d’offre.


2.6 Ressource « reserves_per_entity »

Cette ressource permet de récupérer pour le même Responsable d’Equilibre, les données « Services

Système » par EDR Injection appartenant au périmètre de ce même RE.


7


2.7 Agrégation des données

2.7.1 Mécanisme d’ajustement

2.7.2 Réserves

Regroupement des données par type de sites constitutifs des supports d’offre

Soutirage Hors modèle corrigé

(maille RE)

Injection RPT et RPD (maille EDA)

Soutirage Modèle Corrigé RPT et RPD (maille RE)

Point d’échange

(maille EDA)

Regroupement des données par type de sites constitutifs des supports d’offre

Soutirage Hors modèle corrigé

(maille RE)

Injection RPT et RPD (maille EDA)

Soutirage Modèle Corrigé RPT et RPD (maille RE)

Point d’échange

(maille EDA)


8

3 Accès à l’API

L’accès à l’API décrite dans ce document se fait via le protocole REST / JSON.

Comme pour toutes les API mises à disposition par RTE, l’accès et l’utilisation de ces API sont soumis aux termes des Conditions Générales d’Utilisation [R1].

La méthode d’autorisation d’accès aux API est OAuth, dont les usages sont décrits dans la FAQ sujet - Fiche pratique OAuth2.

A noter que le code EIC de la société est requis pour l’utilisation de ces API. Pour obtenir un code EIC, il est nécessaire de renseigner le formulaire disponible à l’adresse suivante :

https://www.services-rte.com/fr/formulaire-code-eic.html

Par ailleurs, l’API ID Referential disponible sur le Portail Data permet de récupérer les identifiants

des PPE du périmètre de l’Utilisateur.

https://data.rte-france.com/fr/faq/

https://data.rte-france.com/fr/faq/

https://www.services-rte.com/fr/formulaire-code-eic.html

https://data.rte-france.com/catalog/-/api/partners/ID-Referential/v1.0


9

4 Ressources exposées par l’API « Speed Balancing »

4.1 Ressource /balancing_per_brp

4.1.1 GET /balancing_per_brp

4.1.1.1 Modalités d’appel

La ressource est exposée de la manière suivante :

Exposition REST / JSON

Méthode GET

URL ressource

https://digital.iservices.rte-france.com/private_api/speed_balancing/v1/balancing_per_brp?company_id=123

456&brp_perimeter_eic_code=78910

ou https://digital.iservices.rte-

france.com/private_api/speed_balancing/v1/balancing_per_brp?company_id=123456&brp_perimeter_eic_code=78910&start_date=2015-06-

08T00:00:00Z&end_date=2016-06-

08T00:00:00Z&direction=ABCDE&site_type=FGHIJ

URL sandbox (1) https://digital.iservices.rte-

france.com/private_api/speed_balancing/v1/sandbox/balancing_per_brp

(1) La sandbox vous permet de tester l’accessibilité de l’API ainsi que de visualiser le format de données retourné depuis le portail DATA. L’appel à la ressource n’est pas paramétrable et retourne toujours la

même donnée.

Préconisations d’appels2

Les données sont calculées au plus près du temps réel, 15 minutes après le pas de règlement des écarts.

Elles peuvent être mises à jour après le contrôle du réalisé, ou en cas de contestation.

Pour chaque donnée mise à disposition, une date de mise à jour permet d’identifier les rejeux.

Seules les valeurs non nulles sont renvoyées par la ressource.

Il est conseillé de faire les appels à partir de 15 minutes après le pas de règlement des écarts pour obtenir les données temps réel.

Pour une date D, il est conseillé de faire un appel en M+1 pour obtenir les données après contrôle du Réalisé.

Les données sont disponibles à partir de la date d'activation du service par la société.


10

4.1.1.2 Entrées

NOM CARD. DESCRIPTION TYPE VALEURS / FORMAT REGLES

company_id 1 Le code EIC de la société

qui appelle le service string Alpha Numérique (30)

SPEEDBAL-RG09

SPEEDBAL-RG10

brp_perimeter

_eic_code 1

Le code EIC du RE pour lequel les données sont

récupérées

string Alpha Numérique (30) SPEEDBAL-RG04

SPEEDBAL-RG05

start_date 0..1 La date de début

(incluse) Date

YYYY-MM-

DDTHH:mm:ssZ3

SPEEDBAL-RG01 SPEEDBAL-RG02

SPEEDBAL-RG03

end_date 0..1 La date de fin (exclue) date YYYY-MM-

DDTHH:mm:ssZ3


SPEEDBAL-RG03

direction 0..1 Le sens (à la hausse ou à la baisse)

string UPWARD ou DOWNWARD

SPEEDBAL-RG06

site_type 0..1 Le type du site string

Z71 (Soutirage Télérelevé Modèle

Corrigé)

Z70 (Soutirage Télérelevé Hors Modèle

Corrigé) Z72 (Soutirage Profilé)

A23 (Point d’échange)

Z85 (Injection)

SPEEDBAL-RG07

3 Les dates en entrée sont exprimées en heure UTC.

Remarques La même donnée peut être envoyée plusieurs fois par l’Utilisateur si les périodes précisées dans des

requêtes successives se chevauchent. La gestion de ces doublons est alors à la main de l’Utilisateur.

Pour obtenir les données sur une journée, il est conseillé de renseigner en paramètre le code EIC de la société, le code EIC du RE, la date de début et la date de fin.

Si la date de début et la date de fin ne sont pas renseignées, la ressource renverra les données de la journée en cours.

Exemples d’appel :

Avec les paramètres obligatoires :

URL:

GET

/private_api/speed_balancing/v1/balancing_per_brp?company_id=123456&brp_perimeter_eic_code=78910

HTTP/1.1

Headers:

Host: digital.iservices.rte-france.com

Authorization: Bearer < Bearer >

Body:

Avec tous les paramètres :


11

URL:

GET

/private_api/speed_balancing/v1/balancing_per_brp?company_id=123456&brp_perimeter_eic_code=78910

&start_date=2015-06-08T00:00:00Z&end_date=2016-06-08T00:00:00Z&direction=ABCDE&site_type=FGHIJ

HTTP/1.1

Headers:



Body:


12

4.1.1.3 Sorties

NOM CARD. DESCRIPTION

balancing_per_brp 1 Objet {JSON} structuré comme suit :

1

NOM CARD. DESCRIPTION TYPE VALEURS / FORMAT

start_date 1 La date de début est comprise dans

l'intervalle date YYYY-MM-DDTHH:mm:ssZ4

end_date 1 La date de fin n'est pas comprise dans


resolution 1 Granularité string "PT30M" (peut évoluer à terme)

brp_perimet

er_eic_code 1 Code EIC du périmètre RE string

mesure 0..n Tableau de valeurs {JSON} structuré comme suit :

0..

n


direction 1 Hausse ou baisse string UPWARD ou DOWNWARD

site_type 1 Type de sites constitutifs des entités d’ajustement

string

Z71 (Soutirage Télérelevé

Modèle Corrigé)

Z70 (Soutirage Télérelevé Hors

Modèle Corrigé)

Z72 (Soutirage Profilé)


Z85 (Injection)

values 0..n Tableau de valeurs {JSON} structuré comme suit :

0..

n

NOM CARD DESCRIPTION TYPE VALEURS / FORMAT

start_date 1 Date de début du pas de

temps date

YYYY-MM-

DDTHH:mm:ssZ4

end_date 1 Date de fin du pas de temps date YYYY-MM-

DDTHH:mm:ssZ4

value 1 Valeur du point de la série temporelle, exprimé en MWh

numérique Le séparateur décimal

est le point (.)

updated_date 1

Date de modification/création

du point dans l'application source

date YYYY-MM-

DDTHH:mm:ssZ4

4Les dates en retour sont exprimées en heure UTC.


13

4.1.1.4 Règles de gestion

Règle de gestion en fonction des paramètres d’entrée :

Paramètres en entrées

Description Numéro company_id (Obligatoire)

brp_perimeter_eic_code (Obligatoire)

start_date (Facultatif)

end_date (Facultatif)

direction (Facultatif)

site_type (Facultatif)

Renseigné Renseigné Renseigné Renseigné Renseigné Renseigné Si la période entre les paramètres start_date et end_date est supérieure à 1 mois, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-

RG01

Renseigné Renseigné Incorrect Incorrect Renseigné Renseigné Si les paramètres start_date et end_date ne sont pas au format « YYYY-MM-DDTHH:mm:ssZ », un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG02

Renseigné Renseigné Renseigné Renseigné Renseigné Renseigné Si le paramètre start_date est supérieur à end_date, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG03

Renseigné Vide Renseigné Renseigné Renseigné Renseigné Si le paramètre brp_perimeter_eic_code est absent, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG04

Renseigné Incorrect Renseigné Renseigné Renseigné Renseigné Si le paramètre brp_perimeter_eic_code est inconnu, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG05

Renseigné Renseigné Renseigné Renseigné Incorrect Renseigné Si le paramètre direction est inconnu, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG06

Renseigné Renseigné Renseigné Renseigné Renseigné Incorrect Si le paramètre site_type est inconnu, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG07

Vide Renseigné Renseigné Renseigné Renseigné Renseigné Si le paramètre company_id est absent, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG09

Incorrect Renseigné Renseigné Renseigné Renseigné Renseigné Si le paramètre company_id est inconnu, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG10


14

4.1.1.5 Codes erreurs

Le tableau suivant liste les codes erreurs pouvant être retournés lors de l'appel à la ressource.

Le détail de ces erreurs est décrit au chapitre 5 ci-dessous.

Type d’erreur Code erreur Détails

Fonctionnelle SPEEDBAL_COMMON_F01 §5.1










Technique 401 §5.2

Technique 403 §5.2

Technique 404 §5.2

Technique 408 §5.2

Technique 413 §5.2

Technique 414 §5.2

Technique 429 §5.2

Technique 500 §5.2

Technique 503 §5.2

Technique 509 §5.2

4.2 Ressource /balancing_per_entity

4.2.1 GET /balancing_per_entity




Méthode GET

URL ressource

https://digital.iservices.rte-

france.com/private_api/speed_balancing/v1/balancing_per_entity?company_id=123456&brp_perimeter_eic_code=78910

ou


15


france.com/private_api/speed_balancing/v1/balancing_per_entity?company_id=123456&brp_perimeter_eic_code=78910&start_date=2015-06-

08T00:00:00Z&end_date=2016-06-08T00:00:00Z&direction=ABCDE

URL sandbox (1) https://digital.iservices.rte-france.com/private_api/speed_balancing/v1/sandbox/balancing_per_entity


même donnée.



Elles peuvent être mises à jour après le contrôle du réalisé, ou en cas de contestation.




Pour une date D, il est conseillé de faire un appel en M+1 pour obtenir les données après contrôle du

Réalisé.



16

4.2.1.2 Entrées




SPEEDBAL-RG09

SPEEDBAL-RG10

brp_perimeter

_eic_code 1


récupérées


SPEEDBAL-RG05


(incluse) Date

YYYY-MM-

DDTHH:mm:ssZ3


SPEEDBAL-RG03


DDTHH:mm:ssZ3


SPEEDBAL-RG03



SPEEDBAL-RG06


Remarques

La même donnée peut être envoyée plusieurs fois par l’Utilisateur si les périodes précisées dans des requêtes successives se chevauchent. La gestion de ces doublons est alors à la main de l’Utilisateur.

Pour obtenir les données sur une journée, il est conseillé de renseigner en paramètre le code EIC de la

société, le code EIC du RE, la date de début et la date de fin.

Si la date de début et la date de fin ne sont pas renseignées, la ressource renverra les données de la

journée en cours.



URL:

GET

/private_api/speed_balancing/v1/balancing_per_entity?company_id=123456&brp_perimeter_eic_code=78910

HTTP/1.1

Headers:



Body:


URL:

GET

/private_api/speed_balancing/v1/balancing_per_entity?company_id=123456&brp_perimeter_eic_code=78

910&start_date=2015-06-08T00:00:00Z&end_date=2016-06-08T00:00:00Z&direction=ABCDE

HTTP/1.1

Headers:



Body:


17

4.2.1.3 Sorties


balancing_per_entity 1 Objet {JSON} structuré comme suit :

1


start_date 1 La date de début est comprise dans l'intervalle

date YYYY-MM-DDTHH:mm:ssZ4

end_date 1 La date de fin n'est pas comprise dans l'intervalle


resolution 1 Granularité string "PT30M" (peut évoluer à

terme)

brp_perimeter_eic_code

1 Code EIC du périmètre RE string


0..

n



entity_code

1 Code de l’entité d’ajustement appartenant au périmètre du RE en

question

string


0..

n



temps date

YYYY-MM-

DDTHH:mm:ssZ4


DDTHH:mm:ssZ4

value 1 Valeur du point de la série temporelle, exprimé en MWh

numérique Le séparateur décimal

est le point (.)

updated_date 1


du point dans l'application source

date YYYY-MM-

DDTHH:mm:ssZ4



18




Description

Numéro company_id (Obligatoire)





Renseigné Renseigné Renseigné Renseigné Renseigné Si la période entre les paramètres start_date et end_date est supérieure à 1 mois, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG01

Renseigné Renseigné Incorrect Incorrect Renseigné Si les paramètres start_date et end_date ne sont pas au format « YYYY-MM-DDTHH:mm:ssZ », un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG02

Renseigné Renseigné Renseigné Renseigné Renseigné Si le paramètre start_date est supérieur à end_date, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG03

Renseigné Vide Renseigné Renseigné Renseigné Si le paramètre brp_perimeter_eic_code est absent, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG04

Renseigné Incorrect Renseigné Renseigné Renseigné Si le paramètre brp_perimeter_eic_code est inconnu, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG05

Renseigné Renseigné Renseigné Renseigné Incorrect Si le paramètre direction est inconnu, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG06

Vide Renseigné Renseigné Renseigné Renseigné Si le paramètre company_id est absent, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG09

Incorrect Renseigné Renseigné Renseigné Renseigné Si le paramètre company_id est inconnu, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG10


19














Technique 401 §5.2

Technique 403 §5.2

Technique 404 §5.2

Technique 408 §5.2

Technique 413 §5.2

Technique 414 §5.2

Technique 429 §5.2

Technique 500 §5.2

Technique 503 §5.2

Technique 509 §5.2

4.3 Ressource /reserves_per_brp

4.3.1 GET /reserves_per_brp




Méthode GET

URL ressource


france.com/private_api/speed_balancing/v1/reserves_per_brp?company_id=1234

56&brp_perimeter_eic_code=78910 ou

https://digital.iservices.rte-france.com/private_api/speed_balancing/v1/reserves_per_brp?company_id=1234

56&brp_perimeter_eic_code=78910&energy_type=A95&start_date=2015-06-


20

08T00:00:00Z&end_date=2016-06-



france.com/private_api/speed_balancing/v1/sandbox/reserves_per_brp


même donnée.



Elles peuvent être mises à jour à posteriori en cas de contestation.






21

4.3.1.2 Entrées




SPEEDBAL-RG09

SPEEDBAL-RG10

brp_perimeter

_eic_code 1


récupérées


SPEEDBAL-RG05

energy_type 0..1 Type d’énergie – réglage primaire ou secondaire

string A95 (FCR), A96 (aFRR) SPEEDBAL-RG08


(incluse) Date

YYYY-MM-

DDTHH:mm:ssZ3

SPEEDBAL-RG01



DDTHH:mm:ssZ3

SPEEDBAL-RG01




SPEEDBAL-RG06

site_type 0..1 Le type du site string

Z71 (Soutirage

Télérelevé Modèle Corrigé)

Z70 (Soutirage

Télérelevé Hors Modèle Corrigé)

Z72 (Soutirage Profilé) A23 (Point d’échange)

Z85 (Injection)

SPEEDBAL-RG07


Remarques La même donnée peut être envoyée plusieurs fois par l’Utilisateur si les périodes précisées dans des


Pour obtenir les données sur une journée, il est conseillé de renseigner en paramètre le code EIC de la

société, le code EIC du RE, la date de début et la date de fin.

Si la date de début et la date de fin ne sont pas renseignées, la ressource renverra les données de la

journée en cours.



URL:

GET

/private_api/speed_balancing/v1/reserves_per_brp?company_id=123456&brp_perimeter_eic_code=78910

HTTP/1.1

Headers:



Body:



22

URL:

GET

/private_api/speed_balancing/v1/reserves_per_brp?company_id=123456&brp_perimeter_eic_code=78910&

energy_type=A95&start_date=2015-06-08T00:00:00Z&end_date=2016-06-


HTTP/1.1

Headers:



Body:


23

4.3.1.3 Sorties


reserves_per_brp 1 Objet {JSON} structuré comme suit :

1


start_date 1 La date de début est comprise dans


end_date 1 La date de fin n'est pas comprise dans


resolution 1 Granularité string "PT30M" (peut évoluer à terme)

brp_perimeter

_eic_code 1 Code EIC du périmètre RE string


0..

n



site_type 1 Type de sites constitutifs des entités d’ajustement

string

Z71 (Soutirage Télérelevé

Modèle Corrigé)

Z70 (Soutirage Télérelevé Hors

Modèle Corrigé)

Z72 (Soutirage Profilé)


Z85 (Injection)

energy_ty

pe 1

Type d’énergie – réglage primaire ou

secondaire string

A95 (FCR)

A96 (aFRR)


0..

n



temps date

YYYY-MM-

DDTHH:mm:ssZ4


DDTHH:mm:ssZ4

value 1 Valeur du point de la série

temporelle, exprimé en MWh numérique

Le séparateur décimal

est le point (.)

updated_date 1


du point dans l'application

source

date YYYY-MM-

DDTHH:mm:ssZ4



24






energy_type

(Facultatif)




site_type (Facultatif)

Renseigné Renseigné Renseigné Renseigné Renseigné Renseigné Renseigné Si la période entre les paramètres start_date et end_date est supérieure à 1 mois, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG01

Renseigné Renseigné Renseigné Incorrect Incorrect Renseigné Renseigné Si les paramètres start_date et end_date ne sont pas au format « YYYY-MM-DDTHH:mm:ssZ », un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG02

Renseigné Renseigné Renseigné Renseigné Renseigné Renseigné Renseigné Si le paramètre start_date est supérieur à end_date, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG03

Renseigné Vide Renseigné Renseigné Renseigné Renseigné Renseigné Si le paramètre brp_perimeter_eic_code est absent, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG04

Renseigné Incorrect Renseigné Renseigné Renseigné Renseigné Renseigné Si le paramètre brp_perimeter_eic_code est inconnu, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG05

Renseigné Renseigné Renseigné Renseigné Renseigné Incorrect Renseigné Si le paramètre direction est inconnu, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG06

Renseigné Renseigné Renseigné Renseigné Renseigné Renseigné Incorrect Si le paramètre site_type est inconnu, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG07

Renseigné Renseigné Incorrect Renseigné Renseigné Renseigné Renseigné Si le paramètre energy_type est inconnu, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG08

Vide Renseigné Renseigné Renseigné Renseigné Renseigné Renseigné Si le paramètre company_id est absent, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG09

Incorrect Renseigné Renseigné Renseigné Renseigné Renseigné Renseigné Si le paramètre company_id est inconnu, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG10


25
















Technique 401 §5.2

Technique 403 §5.2

Technique 404 §5.2

Technique 408 §5.2

Technique 413 §5.2

Technique 414 §5.2

Technique 429 §5.2

Technique 500 §5.2

Technique 503 §5.2

Technique 509 §5.2

4.4 Ressource /reserves_per_entity

4.4.1 GET /reserves_per_entity




Méthode GET

URL ressource


france.com/private_api/speed_balancing/v1/reserves_per_entity?company_id=123456&brp_perimeter_eic_code=78910

ou


26


france.com/private_api/speed_balancing/v1/reserves_per_entity?company_id=123456&brp_perimeter_eic_code=78910&energy_type=A95&start_date=2015-06-

08T00:00:00%2B02:00&end_date=2016-06-08T00:00:00%2B02:00&direction=ABCDE


france.com/private_api/speed_balancing/v1/sandbox/reserves_per_entity

(1) La sandbox vous permet de tester l’accessibilité de l’API ainsi que de visualiser le format de données

retourné depuis le portail DATA. L’appel à la ressource n’est pas paramétrable et retourne toujours la

même donnée.



Elles peuvent être mises à jour à posteriori en cas de contestation.



Il est conseillé de faire les appels à partir de 15 minutes après le pas de règlement des écarts pour

obtenir les données temps réel.



27

4.4.1.2 Entrées




SPEEDBAL-RG09

SPEEDBAL-RG10

brp_perimeter

_eic_code 1


récupérées


SPEEDBAL-RG05

energy_type 0..1 Type d’énergie – réglage primaire ou secondaire

string A95 (FCR), A96 (aFRR) SPEEDBAL-RG08


(incluse) date

YYYY-MM-

DDTHH:mm:ssZ3

SPEEDBAL-RG01



DDTHH:mm:ssZ3

SPEEDBAL-RG01




SPEEDBAL-RG06


Remarques

La même donnée peut être envoyée plusieurs fois par l’Utilisateur si les périodes précisées dans des


Pour obtenir les données sur une journée, il est conseillé de renseigner en paramètre le code EIC de la société, le code EIC du RE, la date de début et la date de fin.

Si la date de début et la date de fin ne sont pas renseignées, la ressource renverra les données de la journée en cours.



URL:

GET

/private_api/speed_balancing/v1/reserves_per_entity?company_id=123456&brp_perimeter_eic_code=78910

HTTP/1.1

Headers:



Body:


URL:

GET

/private_api/speed_balancing/v1/reserves_per_entity?company_id=123456&brp_perimeter_eic_code=789

10&energy_type=A95&start_date=2015-06-08T00:00:00%2B02:00&end_date=2016-06-

08T00:00:00%2B02:00&direction=ABCDE

HTTP/1.1

Headers:



28


Body:


29

4.4.1.3 Sorties


reserves_per_entity 1 Objet {JSON} structuré comme suit :

1


start_date 1 La date de début est comprise dans l'intervalle


end_date 1 La date de fin n'est pas comprise dans l'intervalle


resolution 1 Granularité string "PT30M" (peut évoluer à

terme)

brp_perimeter_eic_code

1 Code EIC du périmètre RE string


0..

n



entity_code

1 Code de l’entité de réserve appartenant au périmètre du RE en

question

string

energy_ty

pe 1

Type d’énergie – réglage primaire ou

secondaire string

A95 (FCR)

A96 (aFRR)


0..

n



temps date

YYYY-MM-

DDTHH:mm:ssZ4


DDTHH:mm:ssZ4

value 1 Valeur du point de la série

temporelle, exprimé en MWh numérique

Le séparateur décimal

est le point (.)

updated_date 1


du point dans l'application

source

date YYYY-MM-

DDTHH:mm:ssZ4



30






energy_type (Facultatif)




Renseigné Renseigné Renseigné Renseigné Renseigné Renseigné Si la période entre les paramètres start_date et end_date est supérieure à 1 mois, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-

RG01

Renseigné Renseigné Renseigné Incorrect Incorrect Renseigné Si les paramètres start_date et end_date ne sont pas au format « YYYY-MM-DDTHH:mm:ssZ », un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG02

Renseigné Renseigné Renseigné Renseigné Renseigné Renseigné Si le paramètre start_date est supérieur à end_date, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG03

Renseigné Vide Renseigné Renseigné Renseigné Renseigné Si le paramètre brp_perimeter_eic_code est absent, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG04

Renseigné Incorrect Renseigné Renseigné Renseigné Renseigné Si le paramètre brp_perimeter_eic_code est inconnu, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG05

Renseigné Renseigné Renseigné Renseigné Renseigné Incorrect Si le paramètre direction est inconnu, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG06

Renseigné Renseigné Incorrect Renseigné Renseigné Renseigné Si le paramètre energy_type est inconnu, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG08

Vide Renseigné Renseigné Renseigné Renseigné Renseigné Si le paramètre company_id est absent, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG09

Incorrect Renseigné Renseigné Renseigné Renseigné Renseigné Si le paramètre company_id est inconnu, un code erreur fonctionnel 400 est renvoyé.

SPEEDBAL-RG10


31















Technique 401 §5.2

Technique 403 §5.2

Technique 404 §5.2

Technique 408 §5.2

Technique 413 §5.2

Technique 414 §5.2

Technique 429 §5.2

Technique 500 §5.2

Technique 503 §5.2

Technique 509 §5.2


32

5 Détails des erreurs

Le schéma ci-dessous présente les codes retournés à l’Utilisateur de l’API en fonction du séquencement

des appels.

Ce paragraphe concerne les erreurs génériques à toutes les ressources de l’API et à ce titre il ne décrit pas les erreurs de requêtes (code http 400). Ces erreurs sont décrites ressource par ressource dans le

paragraphe correspondant.

En cas d’erreur lors de la phase d’authentification (validation du login et du mot de passe) un code HTTP 401 « unauthorized » est retourné à l’appelant.

La seconde étape est de vérifier que l’Utilisateur ne dépasse pas le nombre maximal d’appels autorisé pour l’organisation. En cas de dépassement, l’appelant en est informé par un code HTTP 429. La réponse

du serveur contient dans ce cas un entête "Retry-After:" indiquant le temps d'attente (en secondes) que le client doit attendre avant de renvoyer sa demande.

La troisième étape est de vérifier si l’appelant (identifié par le jeton OAuth2 ou le certificat PKI) a bien

créé une application sur le Portail Data. Si ce n’est pas le cas l’appelant en est informé par un code HTTP 403 « forbidden ».

La quatrième étape consiste à vérifier si l'API est bien associée à l’application (notion d'abonnement). Si ce n’est pas le cas, l’appelant en est informé par un code HTTP 403 « forbidden ».

La cinquième étape consiste à accéder aux ressources de RTE. Diverses erreurs fonctionnelles peuvent

se produire. Celles-ci sont communiquées à l’Utilisateur en tant qu’erreur JSON avec un code http 400.


33

En cas d’incident technique lors du traitement de la requête quelle que soit l’étape, l’appelant en sera informé par un code HTTP 500.

Structure JSON :

{

"error": "libelle_court, codification explicite de l’erreur",

"error_description": "libellé long, lisible par un utilisateur",

"error_uri": " URI vers le guide d’utilisation de l'API ou la FAQ/documentation sur le Portail Data "

"error_details" : {

"transaction_id" : "identifiant unique d’appel, utile en cas d’incident"

}

}

Le libellé court (« error ») est un code permettant à l’application appelante de traiter

automatiquement les messages des erreurs. Il est représenté par une suite de mots séparés

par des « _ ».

Le libellé long (« error_description ») est une description permettant aux utilisateurs de

comprendre de façon plus précise l’origine de l’erreur. Ce libellé doit être validé par le métier

afin de s’assurer qu’il est suffisamment explicite.

L’URI vers le guide d’utilisation est présent pour donner plus d’explications en fonction de l’Api

appelée.

Le champ transaction_id : fournit un identifiant unique d’appel. Cet identifiant peut être

communiqué aux services d’assistance RTE en cas d’incident.


34

5.1 Erreurs fonctionnelles

Ce tableau récapitule les erreurs fonctionnelles retournées par la ressource correspondant à une erreur

dans la requête (code http 400) :

SPEEDBAL_COMMON_F01

RG Si la période entre les paramètres start_date et end_date est supérieure à 1 mois, le Service

génère cette erreur.

Message The API does not provide feedback on a period greater than 1 month, in one call. To retrieve

all the data please make it with several calls to the API.

Exemple

d'appel

GET /speed_balancing/v1/balancing_per_brp?company_id=CodeValide& brp_perimeter_eic_code=CodeValide&start_date=2018-06-08T00:00:00Z&end_date=2018-

08-08T00:00:00Z

SPEEDBAL_COMMON_F02

RG Si les paramètres start_date et end_date ne sont pas au format « YYYY-MM-DDTHH:mm:ssZ », le Service génère cette erreur.

Message One of the dates in the API input does not follow the format described in the user guide.

Please check compliance with the format for each field.

Exemple

d'appel

GET /speed_balancing/v1/balancing_per_brp?company_id=CodeValide&

brp_perimeter_eic_code=CodeValide&start_date=2018-06-08&end_date=2018-08-08

SPEEDBAL_COMMON_F03

RG Si le paramètre start_date est supérieur à end_date le Service génère cette erreur.

Message The field 'start_date' in the API input is more recent than the field 'end_date'. Please correct the values of these fields.

Exemple

d'appel

GET /speed_balancing/v1/balancing_per_brp?company_id=CodeValide&

brp_perimeter_eic_code=CodeValide&start_date=2018-06-08T00:00:00Z&end_date=2018-05-08T00:00:00Z

SPEEDBAL_COMMON_F04

RG Si le paramètre brp_perimeter_eic_code est absent, le Service génère cette erreur.

Message Missing parameter : brp_perimeter_eic_code.

Exemple

d'appel GET /speed_balancing/v1/balancing_per_entity?company_id=CodeValide

SPEEDBAL_COMMON_F05

RG Si le paramètre brp_perimeter_eic_code est inconnu, le Service génère cette erreur.

Message Unknown value of the parameter : brp_perimeter_eic_code.

Exemple

d'appel

GET /speed_balancing/v1/balancing_per_entity?company_id=CodeValide&

brp_perimeter_eic_code=CodeNONValide

SPEEDBAL_COMMON_F06

RG Si le paramètre direction est inconnu, le Service génère cette erreur.

Message Unknown value of the parameter : direction.

Exemple

d'appel


brp_perimeter_eic_code=CodeValide&start_date=2015-06-

08T00:00:00%2B02:00&end_date=2016-06-08T00:00:00%2B02:00&direction=CodeNONValide&site_type=CodeValide

SPEEDBAL_COMMON_F07

RG Si le paramètre site_type est inconnu, le Service génère cette erreur.

Message Unknown value of the parameter : site_type.

Exemple

d'appel


brp_perimeter_eic_code=CodeValide&start_date=2015-06-

08T00:00:00%2B02:00&end_date=2016-06-08T00:00:00%2B02:00&direction=CodeValide&site_type=CodeNONValide

SPEEDBAL_COMMON_F08

RG Si le paramètre energy_type est inconnu, le Service génère cette erreur.

Message Unknown value of the parameter : energy_type

Exemple

d'appel

GET

/speed_balancing/v1/reserves_per_brp?company_id=CodeValide&brp_perimeter_eic_code=


35

CodeValide&energy_type=CodeNONValide&start_date=2015-06-

08T00:00:00%2B02:00&end_date=2016-06-08T00:00:00%2B02:00&direction=CodeValide&site_type=CodeValide

SPEEDBAL_COMMON_F09

RG Si le paramètre company_id (code EIC) est absent, le Service génère cette erreur.

Message Missing parameter : company_id.

Exemple

d'appel GET /speed_balancing/v1/balancing_per_brp? brp_perimeter_eic_code=CodeValide

SPEEDBAL_COMMON_F10

RG Si le paramètre company_id (code EIC) est invalide ou inconnu, le Service génère cette erreur.

Message Unknown value of the parameter : company_id

Exemple

d'appel

GET /speed_balancing/v1/balancing_per_brp?company_id=CodeNONValide&

brp_perimeter_eic_code=CodeValide

SPEEDBAL_COMMON_F11

RG Si la société n’a pas les autorisations pour accéder au service, le Service génère cette erreur.

Message The company does not have sufficient authorization to access this service. Please contact RTE Market services

Exemple d'appel

GET /speed_balancing/v1/balancing_per_brp?company_id=CodeNONValide& brp_perimeter_eic_code=CodeValide

5.2 Erreurs techniques

401

Code http 401

Message Unauthorized

Description Erreur générée lorsque l’authentification a échouée

403

Code http 403

Message Forbidden

Description Erreur générée si l’appelant n’est pas habilité à appeler la ressource

404

Code http 404

Message Not Found

Description La ressource appelée n’existe pas ou aucune page n’a été trouvée

408

Code http 408

Message Request Time-out

Description Erreur générée sur non réponse du service appelé ou retour en timeout (http 408) du

service appelé.

413

Code http 413

Message Request Entity Too Large


36

Description La taille de la réponse à la requête dépasse 7Mo (maximum atteint pour des appels sur 3

PDC et sur un mois max)

414

Code http 414

Message Request-URI Too Long

Description L’URI transmise par l’appelant dépasse 2048 caractères.

429

Code http 429

Message Too Many Requests

Description Le nombre d’appel maximum dans un certain laps de temps est dépassé.

500

Code http 500

Message Internal Server Error

Description

Toute autre erreur technique.

(Cette erreur est accompagnée d’un message JSON avec un champ error_code et

error_description)

503

Code http 503

Message Service Unavailable

Description Erreur générée sur maintenance (http 503).

509

Code http 509

Message Bandwidth Limit Exceeded.

Description L‘ensemble des requêtes des clients atteint la limite maximale.


37

6 Annexes

6.1 Fichiers Exemples

Une fois l’Utilisateur connecté sur le Portail Data, des exemples de fichiers (notamment les réponses de

l’API) sont disponibles en ligne avec le descriptif de l'API.

FIN DU DOCUMENT