Version 1.
Guide d’Utilisation API Téléchargement
GUIDE D’UTILISATION
API
TELECHARGEMENT
Version 1.0
Date d’entrée en vigueur : 18 Décembre 2017
1
Guide d’Utilisation API Téléchargement Version 1.0
SOMMAIRE
1 Introduction ....................................................................................................................................3
1.1 Définitions .....................................................................................................................................3
1.2 Assistance technique......................................................................................................................3
2.1 Description générale ......................................................................................................................4
2.2 Pré-requis à l’utilisation des API ......................................................................................................4
2.2.1 Confidentialité des données .....................................................................................................4
2.2.2 Résiliation ...............................................................................................................................4
3 Accès à l’API....................................................................................................................................5
4.1 Ressource /flow/{flow_code}/files ..................................................................................................6
4.1.1 GET flow/<flow_code>/files .....................................................................................................6
[Link] Modalités d’appel ..............................................................................................................6
[Link] Entrées .............................................................................................................................6
[Link] Sorties ..............................................................................................................................7
4.2 Ressource /flow/{flow_code}/files/last ............................................................................................9
4.2.1 GET /flow/{flow_code}/files/last ...............................................................................................9
[Link] Modalités d’appel ..............................................................................................................9
[Link] Entrées .............................................................................................................................9
[Link] Sorties ..............................................................................................................................9
4.3 Ressource /flow/{flow_code}/files/{file_id} ................................................................................... 10
4.3.1 GET /flow/{flow_code}/files/{file_id} ...................................................................................... 10
[Link] Modalités d’appel ............................................................................................................ 10
[Link] Entrées ........................................................................................................................... 10
[Link] Sorties ............................................................................................................................ 11
5 Détails des erreurs ......................................................................................................................... 12
6 Annexes ............................................................................................................................................ 13
FIN DU DOCUMENT ............................................................................................................................ 14
2
Guide d’Utilisation API Téléchargement Version 1.0
1 Introduction
Ce document décrit l’API de téléchargement en version 1 mise à disposition par RTE à ses Clients
dans le but d’exposer les données de l’application RMC :
La liste des fichiers disponibles au téléchargement,
Le téléchargement d’un fichier via son identifiant,
Le téléchargement du dernier fichier disponible
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.
Émetteur Partie qui émet un Message.
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.
Opération Une opération 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.
Traduction des valeurs anglaises retournées par l’API :
Valeur en Anglais en sortie de l’API Traduction en Français
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.
3
Guide d’Utilisation API Téléchargement Version 1.0
2 Description fonctionnelle de l’API Téléchargement
2.1 Description générale
Le Service de cette API permet d’obtenir les données :
La liste des fichiers disponibles au téléchargement,
Le téléchargement d’un fichier via son identifiant,
Le téléchargement du dernier fichier disponible
2.2 Pré-requis à l’utilisation des API
Les API RMC sont destinées aux acteurs du marché de l’électricité et au grand public. Néanmoins les
utilisateurs de l’API doivent posséder un certificat de sécurité.
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
Si l’Utilisateur souhaite ne plus utiliser une API, il suffit de cesser l’émission des appels à l’API.
4
Guide d’Utilisation API Téléchargement Version 1.0
3 Accès à l’API
L’accès à l’API décrite dans ce document se fait via le protocole REST.
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 se fait par certificat.
5
Guide d’Utilisation API Téléchargement Version 1.0
4 Ressources exposées par l’API « RmcTelechargement »
4.1 Ressource /flow/{flow_code}/files
4.1.1 GET flow/<flow_code>/files
[Link] Modalités d’appel
La ressource est exposée de la manière suivante :
Exposition REST / JSON
Méthode GET
[Link]
URL [Link]/RmcTelechargement/api/flow/<flow_code>/files?status=ALL&start_date=<DD-
ressource MM-YYYY>&end_date=<DD-MM-YYYY>
[Link] Entrées
NOM CARD. DESCRIPTION TYPE VALEURS / FORMAT
Code du canal du flux RMC des fichiers
String Exemple : R1-F-MAIL
recherchés
flow_code 1..1
ALL : tous les statuts
0 : nouveaux fichiers (non
Statut des fichiers recherchés Enum téléchargés)
1 : fichiers archivés (déjà
status 1..1 téléchargé)
Date de début de recherche des fichiers String DD-MM-YYYYY
start_date 1..1
Date de fin de recherche des fichiers String DD-MM-YYYYY
End_date 1..1
Exemples d’appel * :
URL:
[Link]
MAIL/files?status=ALL&start_date=01-09-2017&end_date=15-09-2017
* Tous les paramètres sont obligatoires
6
Guide d’Utilisation API Téléchargement Version 1.0
[Link] Sorties
CARD
NOM DESCRIPTION
.
Aucun
Tableau de fileDTO {JSON} contenant n occurrences. Sa
1..1
structure est la suivante :
CARD TYPE
NOM DESCRIPTION VALEURS / FORMAT
.
String
id 1..1 Identifiant du fichier
_
String
name 1..1 Nom du fichier _
availabilityDate Date de mise à disposition du fichier YYYY-MM-
1..1 Date DDThh:mm:ss:SSS
Format JSON du retour :
GET /flow/R1-F-MAIL/files?status=ALL&start_date=01-01-2001&end_date=31-12-2017
HTTP/1.1 200 OK
[
{
"id": "254159",
"name": "FTP vers [Link]",
"availabilityDate": "2017-08-29 11:12:00.043"
},
{
"id": "254158",
"name": "FTP vers [Link]",
"availabilityDate": "2017-08-29 11:03:30.039"
},
{
"id": "254154",
"name": "FTP vers [Link]",
"availabilityDate": "2017-08-29 10:07:00.045"
},
{
"id": "254153",
"name": "FTP vers mail_zip.zip",
"availabilityDate": "2017-08-29 09:58:30.04"
},
{
"id": "254152",
"name": "FTP vers mail_zip.zip",
"availabilityDate": "2017-08-29 09:58:00.039"
}
]
7
Guide d’Utilisation API Téléchargement Version 1.0
[Link] Règles de gestion
Règles de gestion en fonction des paramètres d’entrée :
Numéro Description
FILES_RG01 L’ensemble des paramètres sont obligatoires
Le champ status doit prendre une des valeurs suivantes :
ALL : tous les fichiers
FILES_RG02
0 : nouveaux fichiers (non encore téléchargés)
1 : fichiers archivés (déjà téléchargé au moins une fois)
FILES_RG03 Le champ start_date doit être inférieur ou égal à end_date
Règles de gestion appliquées en sortie :
Numéro Description
FILES_RG04 Les données de sortie sont triées en fonction du champ availability_date
[Link] Codes erreurs
Le tableau suivant liste les codes erreurs pouvant être retournés lors de l'appel à la ressource.
Type Code erreur Détails
d’erreur
Technique 204 No File retrieved for current parameters.
400 The correct syntax to use for this API is:
/api/flow/flow_code/files?status=X&start_date=DD-MM-
Technique YYYY&end_date=DD-MM-YYYY.
400 Status parameter has to be 0 (for new files) or 1 (for
Technique archived files) or ALL.
400 Date format is DD-MM-YYYY and end_date parameter must
Technique be greater than start_date parameter.
403 You don’t have the necessary rights for accessing to this
Technique API Service or this flow.
500 Internal server Error.
Technique
Technique 500 Technical Error during the retrieving of files.
Technique 500 Technical error during the authentication process.
Technique 500 Technical error during the retrieving of user’s applications.
8
Guide d’Utilisation API Téléchargement Version 1.0
4.2 Ressource /flow/{flow_code}/files/last
4.2.1 GET /flow/{flow_code}/files/last
[Link] Modalités d’appel
La ressource est exposée de la manière suivante :
Exposition REST / JSON
Méthode GET
[Link]
URL
ressource
Préconisations d’appels
La durée de rétention des fichiers est de 3 mois. Passé ce délai, les fichiers ne sont plus disponibles.
[Link] Entrées
VALEURS / FORMAT
NOM CARD. DESCRIPTION TYPE
Code du canal du flux RMC des
flow_code 1..1 Texte Exemple : R1-F-MAIL
fichiers recherchés
Exemple :
URL:
GET /flow/{flow_code}/files/last
[Link] Sorties
L’api renvoie le fichier demandé sous la forme d’un flux binaire
[Link] Règles de gestion
Règle de gestion en fonction des paramètres d’entrée :
N/A
Règles de gestion appliquées en sortie :
N/A
9
Guide d’Utilisation API Téléchargement Version 1.0
[Link] Codes erreurs
Le tableau suivant liste les codes erreurs pouvant être retournés lors de l'appel à la ressource.
Type d’erreur Code erreur Détails
Technique 204 There is no last file for this flow code on the server.
403
You don’t have the necessary rights for accessing to this API
Technique Service or this flow.
500 Internal server Error.
Technique
500 Technical Error during the retrieving of files.
Technique
500 Technical error during the authentication process.
Technique
500 Technical error during the retrieving of user’s applications.
Technique
4.3 Ressource /flow/{flow_code}/files/{file_id}
4.3.1 GET /flow/{flow_code}/files/{file_id}
[Link] Modalités d’appel
La ressource est exposée de la manière suivante :
Exposition REST / JSON
Méthode GET
[Link]
URL
[Link]/RmcTelechargement/api/flow/<flow_code>/files/<file_id>
ressource
Préconisations d’appels
La durée de rétention des fichiers est de 3 mois. Passé ce délai, les fichiers ne sont plus disponibles.
[Link] Entrées
VALEURS / FORMAT
NOM CARD. DESCRIPTION TYPE
Code du canal du flux RMC des
flow_code 1..1 Texte Exemple : R1-F-MAIL
fichiers recherchés
Exemple :
URL:
GET /flow/{flow_code}/files/last
10
Guide d’Utilisation API Téléchargement Version 1.0
[Link] Sorties
L’api renvoie le fichier demandé sous la forme d’un flux binaire
[Link] Règles de gestion
Règle de gestion en fonction des paramètres d’entrée :
N/A
Règles de gestion appliquées en sortie :
N/A
[Link] Codes erreurs
Le tableau suivant liste les codes erreurs pouvant être retournés lors de l'appel à la ressource.
Type d’erreur Code erreur Détails
Technique 204 There is no file on the server for the given id.
400 The correct syntax to use for this API is:
Technique /api/flow/flow_code/files/file_id.
400 File Id must be a positive number.
Technique
403 You don’t have the necessary rights for accessing to this API
Technique Service or this flow.
500 Internal server Error.
Technique
500 Technical Error during the retrieving of files.
Technique
500 Technical error during the authentication process.
Technique
500 Technical error during the retrieving of user’s applications.
Technique
11
Guide d’Utilisation API Téléchargement Version 1.0
5 Détails des erreurs
En cas d’erreur, le message se trouve dans l’attribut « x-rmc-message » de l’entête de la réponse.
Exemple :
12
Guide d’Utilisation API Téléchargement Version 1.0
6 Annexes
204
Code http 204
Message No content
Exemple
d'appel Aucun résultat avec les paramètres d’entrée renseignés
400
Code http 400
Message Bad request
Exemple
d'appel La syntaxe de la requête n’est pas correcte
403
Code http 403
Message Forbidden
Exemple
d'appel Tentative d’accès à une ressource interdite
404
Code http 404
Message Not Found
Exemple
d'appel La ressource appelée n’existe pas ou aucune donnée n’a été trouvée
408
Code http 408
Message Request Time-out
Exemple Erreur générée sur non réponse du service appelé ou retour en timeout (http 408) du
d'appel service appelé.
413
Code http 413
Message Request Entity Too Large
Exemple
d'appel La taille de la requête dépasse 5Mo
414
Code http 414
Message Request-URI Too Long
Exemple
d'appel L’URI transmise par l’appelant dépasse 512 caractères.
13
Guide d’Utilisation API Téléchargement Version 1.0
429
Code http 429
Message Too Many Requests
Exemple
d'appel Le nombre d’appel maximum dans un certain laps de temps est dépassé.
500
Code http 500
Message Internal Server Error
Toute autre erreur technique.
Exemple (Cette erreur est accompagnée d’un message JSON avec un champ error_code et
d'appel error_description)
503
Code http 503
Message Service Unavailable
Exemple
d'appel Erreur générée sur maintenance (http 503).
509
Code http 509
Message Bandwidth Limit Exceeded.
Exemple
d'appel L’ensemble des requêtes des clients atteint la limite maximale.
FIN DU DOCUMENT
14