Upload
others
View
4
Download
0
Embed Size (px)
Citation preview
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.4 Règles de gestion ......................................................................... 18
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.1 Modalités d’appel .......................................................................... 19
4.3.1.2 Entrées ........................................................................................ 21
4.3.1.3 Sorties ......................................................................................... 23
4.3.1.4 Règles de gestion ......................................................................... 24
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.1 Modalités d’appel .......................................................................... 25
4.4.1.2 Entrées ........................................................................................ 27
Guide d’Utilisation API Speed Balancing Version 1.0
3
4.4.1.3 Sorties ......................................................................................... 29
4.4.1.4 Règles de gestion ......................................................................... 30
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
Guide d’Utilisation API Speed Balancing Version 1.0
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.
Guide d’Utilisation API Speed Balancing Version 1.0
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.
Guide d’Utilisation API Speed Balancing Version 1.0
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.
Cette ressource est uniquement accessible en lecture, via une méthode de type GET.
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.
Cette ressource est uniquement accessible en lecture, via une méthode de type GET.
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.
Guide d’Utilisation API Speed Balancing Version 1.0
7
Cette ressource est uniquement accessible en lecture, via une méthode de type GET.
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)
Guide d’Utilisation API Speed Balancing Version 1.0
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.
Guide d’Utilisation API Speed Balancing Version 1.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é.
Guide d’Utilisation API Speed Balancing Version 1.0
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-RG01 SPEEDBAL-RG02
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 :
Guide d’Utilisation API Speed Balancing Version 1.0
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:
Host: digital.iservices.rte-france.com
Authorization: Bearer < Bearer >
Body:
Guide d’Utilisation API Speed Balancing Version 1.0
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
l'intervalle date YYYY-MM-DDTHH:mm:ssZ4
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
NOM CARD. DESCRIPTION TYPE VALEURS / FORMAT
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é)
A23 (Point d’échange)
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.
Guide d’Utilisation API Speed Balancing View Version 1.0
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
Guide d’Utilisation API Speed Balancing View Version 1.0
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
Fonctionnelle SPEEDBAL_COMMON_F02 §5.1
Fonctionnelle SPEEDBAL_COMMON_F03 §5.1
Fonctionnelle SPEEDBAL_COMMON_F04 §5.1
Fonctionnelle SPEEDBAL_COMMON_F05 §5.1
Fonctionnelle SPEEDBAL_COMMON_F06 §5.1
Fonctionnelle SPEEDBAL_COMMON_F07 §5.1
Fonctionnelle SPEEDBAL_COMMON_F09 §5.1
Fonctionnelle SPEEDBAL_COMMON_F10 §5.1
Fonctionnelle SPEEDBAL_COMMON_F11 §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
4.2.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_entity?company_id=123456&brp_perimeter_eic_code=78910
ou
Guide d’Utilisation API Speed Balancing Version 1.0
15
https://digital.iservices.rte-
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
(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é.
Guide d’Utilisation API Speed Balancing Version 1.0
16
4.2.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-RG01 SPEEDBAL-RG02
SPEEDBAL-RG03
direction 0..1 Le sens (à la hausse ou à la baisse)
string UPWARD ou DOWNWARD
SPEEDBAL-RG06
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_entity?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 :
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:
Host: digital.iservices.rte-france.com
Authorization: Bearer < Bearer >
Body:
Guide d’Utilisation API Speed Balancing Version 1.0
17
4.2.1.3 Sorties
NOM CARD. DESCRIPTION
balancing_per_entity 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 l'intervalle
date YYYY-MM-DDTHH:mm:ssZ4
resolution 1 Granularité string "PT30M" (peut évoluer à
terme)
brp_perimeter_eic_code
1 Code EIC du périmètre RE string
mesure 0..n Tableau de valeurs {JSON} structuré comme suit :
0..
n
NOM CARD. DESCRIPTION TYPE VALEURS / FORMAT
direction 1 Hausse ou baisse string UPWARD ou DOWNWARD
entity_code
1 Code de l’entité d’ajustement appartenant au périmètre du RE en
question
string
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.
Guide d’Utilisation API Speed Balancing View Version 1.0
18
4.2.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)
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
Guide d’Utilisation API Speed Balancing View Version 1.0
19
4.2.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
Fonctionnelle SPEEDBAL_COMMON_F02 §5.1
Fonctionnelle SPEEDBAL_COMMON_F03 §5.1
Fonctionnelle SPEEDBAL_COMMON_F04 §5.1
Fonctionnelle SPEEDBAL_COMMON_F05 §5.1
Fonctionnelle SPEEDBAL_COMMON_F06 §5.1
Fonctionnelle SPEEDBAL_COMMON_F09 §5.1
Fonctionnelle SPEEDBAL_COMMON_F10 §5.1
Fonctionnelle SPEEDBAL_COMMON_F11 §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.3 Ressource /reserves_per_brp
4.3.1 GET /reserves_per_brp
4.3.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/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-
Guide d’Utilisation API Speed Balancing Version 1.0
20
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/reserves_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 à posteriori 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.
Les données sont disponibles à partir de la date d'activation du service par la société.
Guide d’Utilisation API Speed Balancing Version 1.0
21
4.3.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
energy_type 0..1 Type d’énergie – réglage primaire ou secondaire
string A95 (FCR), A96 (aFRR) SPEEDBAL-RG08
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-RG01
SPEEDBAL-RG02 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/reserves_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 :
Guide d’Utilisation API Speed Balancing Version 1.0
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-
08T00:00:00Z&direction=ABCDE&site_type=FGHIJ
HTTP/1.1
Headers:
Host: digital.iservices.rte-france.com
Authorization: Bearer < Bearer >
Body:
Guide d’Utilisation API Speed Balancing Version 1.0
23
4.3.1.3 Sorties
NOM CARD. DESCRIPTION
reserves_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
l'intervalle date YYYY-MM-DDTHH:mm:ssZ4
resolution 1 Granularité string "PT30M" (peut évoluer à terme)
brp_perimeter
_eic_code 1 Code EIC du périmètre RE string
mesure 0..n Tableau de valeurs {JSON} structuré comme suit :
0..
n
NOM CARD. DESCRIPTION TYPE VALEURS / FORMAT
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é)
A23 (Point d’échange)
Z85 (Injection)
energy_ty
pe 1
Type d’énergie – réglage primaire ou
secondaire string
A95 (FCR)
A96 (aFRR)
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.
Guide d’Utilisation API Speed Balancing View Version 1.0
24
4.3.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)
energy_type
(Facultatif)
start_date (Facultatif)
end_date (Facultatif)
direction (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
Guide d’Utilisation API Speed Balancing View Version 1.0
25
4.3.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
Fonctionnelle SPEEDBAL_COMMON_F02 §5.1
Fonctionnelle SPEEDBAL_COMMON_F03 §5.1
Fonctionnelle SPEEDBAL_COMMON_F04 §5.1
Fonctionnelle SPEEDBAL_COMMON_F05 §5.1
Fonctionnelle SPEEDBAL_COMMON_F06 §5.1
Fonctionnelle SPEEDBAL_COMMON_F07 §5.1
Fonctionnelle SPEEDBAL_COMMON_F08 §5.1
Fonctionnelle SPEEDBAL_COMMON_F09 §5.1
Fonctionnelle SPEEDBAL_COMMON_F10 §5.1
Fonctionnelle SPEEDBAL_COMMON_F11 §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.4 Ressource /reserves_per_entity
4.4.1 GET /reserves_per_entity
4.4.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/reserves_per_entity?company_id=123456&brp_perimeter_eic_code=78910
ou
Guide d’Utilisation API Speed Balancing Version 1.0
26
https://digital.iservices.rte-
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
URL sandbox (1) https://digital.iservices.rte-
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.
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 à posteriori 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.
Les données sont disponibles à partir de la date d'activation du service par la société.
Guide d’Utilisation API Speed Balancing Version 1.0
27
4.4.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
energy_type 0..1 Type d’énergie – réglage primaire ou secondaire
string A95 (FCR), A96 (aFRR) SPEEDBAL-RG08
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-RG01
SPEEDBAL-RG02 SPEEDBAL-RG03
direction 0..1 Le sens (à la hausse ou à la baisse)
string UPWARD ou DOWNWARD
SPEEDBAL-RG06
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/reserves_per_entity?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 :
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:
Host: digital.iservices.rte-france.com
Guide d’Utilisation API Speed Balancing Version 1.0
28
Authorization: Bearer < Bearer >
Body:
Guide d’Utilisation API Speed Balancing Version 1.0
29
4.4.1.3 Sorties
NOM CARD. DESCRIPTION
reserves_per_entity 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 l'intervalle
date YYYY-MM-DDTHH:mm:ssZ4
resolution 1 Granularité string "PT30M" (peut évoluer à
terme)
brp_perimeter_eic_code
1 Code EIC du périmètre RE string
mesure 0..n Tableau de valeurs {JSON} structuré comme suit :
0..
n
NOM CARD. DESCRIPTION TYPE VALEURS / FORMAT
direction 1 Hausse ou baisse string UPWARD ou DOWNWARD
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)
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.
Guide d’Utilisation API Speed Balancing View Version 1.0
30
4.4.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)
energy_type (Facultatif)
start_date (Facultatif)
end_date (Facultatif)
direction (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
Guide d’Utilisation API Speed Balancing View Version 1.0
31
4.4.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
Fonctionnelle SPEEDBAL_COMMON_F02 §5.1
Fonctionnelle SPEEDBAL_COMMON_F03 §5.1
Fonctionnelle SPEEDBAL_COMMON_F04 §5.1
Fonctionnelle SPEEDBAL_COMMON_F05 §5.1
Fonctionnelle SPEEDBAL_COMMON_F06 §5.1
Fonctionnelle SPEEDBAL_COMMON_F08 §5.1
Fonctionnelle SPEEDBAL_COMMON_F09 §5.1
Fonctionnelle SPEEDBAL_COMMON_F10 §5.1
Fonctionnelle SPEEDBAL_COMMON_F11 §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
Guide d’Utilisation API Speed Balancing Version 1.0
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.
Guide d’Utilisation API Speed Balancing Version 1.0
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.
Guide d’Utilisation API Speed Balancing Version 1.0
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
GET /speed_balancing/v1/balancing_per_entity?company_id=CodeValide&
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
GET /speed_balancing/v1/balancing_per_entity?company_id=CodeValide&
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=
Guide d’Utilisation API Speed Balancing Version 1.0
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
Guide d’Utilisation API Speed Balancing Version 1.0
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.
Guide d’Utilisation API Speed Balancing Version 1.0
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