qu'est-ce que c'est et quelles sont ses fonctionnalités ?
La Personal Calendar API fournit à votre application un accès en temps réel aux calendriers des clients d'Orange France, leur permettant ainsi de visualiser leurs événements et d'y ajouter de nouvelles entrées avec leur permission.
L'API offre un accès sécurisé et contrôlé au calendrier de l'utilisateur.
Le diagramme ci-dessous illustre comment cette API peut être intégrée dans un site Web :
En un mot, la Personal Calendar API vous permet :
d'ajouter un événement au calendrier de l'utilisateur.
prochainement, de récupérer la liste des événements que l'utilisateur a rajouté à son calendrier.
prochainement, de consulter la disponibilité de l'utilisateur pour une période donnée.
(haut de page)
avant de démarrer
Pour commencer à tester cette API, assurez-vous d'avoir bien lu et compris la section sur les Personal APIs (alpha)
vous remarquerez qu'il est nécessaire de suivre les étapes suivantes :
étape 1 - devenir membre d'Orange Partner
étape 2 - accéder à l'administrator web interface
Ensuite, une fois dans l'administrator web interface, vous pourrez vous inscrire à la Personal Calendar API.
Une fois votre inscription validée, nous vous enverrons un e-mail et un fichier ZIP contenant :
Votre clé d'accès (SERVICE_ID et SERVICE_PWD).
Le URL de l'API (PersonalCalendarV1URL).
Les exemples de codes.
Les instructions d'utilisation relatives à tous ces éléments.
en savoir plus sur l'administrator web interface
(haut de page)
comment authentifier l'utilisateur
Premièrement, les utilisateurs doivent être authentifiés avant que l'accès à leur calendrier soit accordé.
L'authentification est effectuée via l'Authentication API qui renverra un jeton d'utilisateur.
Vous inclurez ensuite le jeton dans tous les appels de la Personal Calendar API.
Ci-dessous, un exemple sur la manière dont l'appel est effectué :
|
Format:
[PersonalCalendarV1URL]?action=[action name]&token=[user token]¶m=[value]...
Example:
[PersonalCalendarV1URL]?action=addevent&token=Hjlkzjlfkzef23423kjlkjr¶m=value...
|
Si vous souhaitez savoir si votre code a fonctionné, nous pouvons vous fournir un compte de test pour que vous puissiez consulter les résultats comme si vous étiez un client Orange. Une fois votre inscription validée, nous vous montrerons comment en obtenir un.
(haut de page)
ajouter un événement « Hello World »
Ajouter un événement « Hello World » au calendrier d'un client Orange est facile.
Premièrement, récupérez un jeton d'utilisateur en utilisant l'Authentication API. Ce jeton d'utilisateur sera utilisé comme paramètre « jeton » lors de l'appel de la Calendar API.
Pour plus d'informations, consultez la section comment authentifier l'utilisateur.
Vous pourrez ensuite appeler la requête suivante (en ajoutant un événement « Hello World ») :
|
[PersonalCalendarV1EndPoint]?action=addevent&title=Hello%20World&location=&description=&
startdate=21/06/2008&starttime=20:00&enddate=21/06/2008&endtime=21:00&datepattern=dd/MM/yyyy&
timepattern=HH:mm&token=Hjlkzjlfkzef23423kjlkjr |
Le code ci-dessus ajoutera l'événement au calendrier de l'utilisateur Orange. Facile.
(haut de page)
les méthodes de la Personal Calendar API en détail
La Personal Calendar API offre trois méthodes :
addevent geteventlist (bientôt disponible)
checkavailability (bientôt disponible)
addevent
Ajouter un événement au calendrier d'un client Orange France.
Pour appeler l'API, créez l’URL selon le format suivant dans votre application Web et invoquez-le via HTTP GET :
|
Format:
[PersonalCalendarV1EndPoint]?action=addevent&title=[title]&location=[location]&
description=[description]&startdate=[start date]&starttime=[start time]&enddate=[end date]&
endtime=[end time]&datepattern=dd/MM/yyyy&timepattern=HH:mm&token=[user token]
Example:
[PersonalCalendarV1EndPoint]?action=addevent&title=test&location=some%20location&
description=some%20description&startdate=10/01/2000&starttime=10:00&enddate=10/01/2000&
endtime=11:00&datepattern=dd/MM/yyyy&timepattern=HH:mm&token=Hjlkzjlfkzef23423kjlkjr |
paramètres d'entrée
| Nom |
Description |
Obligatoire |
Type |
| title |
the title of the event |
Oui |
String |
| startdate |
start date of event |
Oui |
Date |
| enddate |
end date of event |
Oui |
Date |
| starttime |
start time of event |
Oui |
Time |
| endtime |
end time of event |
Oui |
Time |
| datepattern |
date format, value = dd/MM/yyyy |
Oui |
String |
| timepattern |
time format, value = HH:mm |
Oui |
String |
| description |
description of the event |
Oui |
String |
| location |
location of the event |
Oui |
String |
| token |
user token that is retrieved using the Authentication API |
Oui |
String |
exemple de réponse
Si l'événement est correctement ajouté, la réponse contiendra l'ID de l'événement ainsi qu'un résultat = 0 et se présentera comme suit :
|
<?xml version="1.0" encoding="UTF-8" ?>
<xpage version="1.0">
<command-list>
<command action="cauupdate" request="s01">
<event-data>
<eventid>4790</eventid>
<id>10012000</id>
</event-data>
<result>0</result>
</command>
</command-list>
<parameter-list />
</xpage> |
(haut de page)
les codes d'erreur de la Personal Calendar API
Lorsqu'une erreur se produit, la réponse contient un code d'erreur (paramètre de « type »), un sous-type interne et le message :
|
<command request="" action="action">
<result>-yyy</result>
<error subtype="xxx" type="yyy">message</error>
</command> |
Ci-dessous, un tableau décrivant les erreurs les plus significatives :
| Code d'erreur |
Message |
| 1 |
'mandatory parameter' is missing. |
| 2 |
'parameter' is invalid. |
| 4 |
The command 'action' is unknown. |
| 5 |
'end-userid' is incorrect (database is corrupted). |
| 100 |
Service Calendar non disponible pour cet utilisateur final. |
(haut de page)
