|
Qu'est-ce que c'est et quelles sont ses fonctionnalités?
La Personal Contacts API fournit à votre application un accès temps réel aux listes de contacts des clients d'Orange France,
vous permettant ainsi de visualiser leurs carnets d'adresses et d'y ajouter de nouvelles entrées, avec leur permission.
L'API offre un accès sécurisé et contrôlé à liste de contacts de l'utilisateur.
Le diagramme ci-dessous illustre comment l'API peut être intégrée dans un site Web (cas de l'ajout d'un contact au carnet d'adresses):
En un mot, la Personal Contacts API vous permet:
 de récupérer une liste de contacts correspondant aux critères de recherche.
de sélectionner un contact pour en récupérer les données.
d'ajouter un contact au carnet d'adresses de l'utilisateur.
(haut de page)
avant de démarrer
Pour commencer à tester cette API, assurez-vous d'avoir lu et compris la section 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 Contacts 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 and SERVICE_PWD).
Le URL de l'API (PersonalContactsV1URL).
Les exemple 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 ne 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 Contacts API.
Ci-dessous, un exemple sur la manière dont l'appel est effectué:
|
Format:
[My ContactsV1URL]?action=[action name]&token=[user token]¶m=[value]...
Example:
[My ContactsV1URL]?action=getcontact&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 contact « Hello World »
Ajouter un contact « Hello World » au carnet d'adresse 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 du « jeton » dans l'appel de la Personal Contacts API.
Pour plus d'informations, consultez la section comment authentifier l'utilisateur.
Vous pourrez ensuite appeler la requête suivante (en ajoutant un contact « Hello World ») :
|
[My ContactsV1URL]?action=addcontact&token=[user token]&lastname=World&firstname=World&
nickname=HelloWorld&company=Orange&function=JobTitle&department=World&
emailperso=hello.world@helloworld.com |
Le code ci-desssus ajoutera le contact à la liste des contacts de l'utilisateur. Facile.
(haut de page)
les méthodes de la Personal Contacts API en détail
La Personal Contacts API offre quatre méthodes:
findcontactlist getcontact addcontact adddevice
findcontactlist
Trouver des contacts correspondant aux critères de recherche.
Pour appeler l'API, créez l'URL selon le format suivant dans votre application Web et invoquez-le via HTTP GET:
|
Format:
[PersonalContactsV1URL]?action=findcontactlist&search=[search string]&token=[user token]
Example:
[PersonalContactsV1URL]?action=findcontactlist&search=Orange&token=Hjlkzjlfkzef23423kjlkjr |
paramètres d'entrée
| Nom |
Description |
Obligatoire |
Type |
| search |
Les premiers caractères du prénom ou du nom du contact à trouver.
Les caractères de remplacement (*) sont interdits et les chaînes complexes doivent être
mises entre « » et encodées en URL, par exemple: %22complexe+chaîne%22, Orange.
|
Oui |
String |
| token |
Jeton d'utilisateur récupéré grâce à l'Authentication API. |
Oui |
String |
exemple de réponse
|
<?xml version="1.0" encoding="UTF-8" ?>
<xpage version="1.0">
<command-list>
<command request="g10" action="ctcfindcontactlist">
<data-list total-data="2" nbpage="1" page="1" nbentries="2">
<data view="shallow" id="1" type="contact">
<firstname>Orange</firstname>
<lastname>World</lastname>
</data>
<data view="shallow" id="2" type="contact">
<firstname>Orange</firstname>
<lastname>Partner</lastname>
</data>
</data-list>
<result>0</result>
</command>
</xpage> |
description des codes de réponses
| Nom |
Description |
| data-list |
Liste des contacts correspondant à la requête. |
| data |
Entrée du contact, contenant son prénom et son nom. |
| result |
Code de résultat de la réponse. 0 signifie que l'opération a réussi. |
(back to API methods in detail)
getcontact
Obtenir les coordonnées d'un contact.
Pour appeler l'API, créez le format d'URL suivant dans votre application Web et invoquez-le via HTTP GET:
|
Format:
[PersonalContactsV1URL]?action=getcontact&cid=[contact id]&token=[user token]
Example:
[PersonalContactsV1URL]?action=getcontact&cid=C1&token=Hjlkzjlfkzef23423kjlkjr |
paramètres d'entrée
| Nom |
Description |
Obligatoire |
Type |
| cid |
L'identifiant unique des coordonnées du contact à récupérer.
La valeur est la valeur de l' « id » dans le paramètre <data view>
dans la réponse findcontactlist.
|
Oui |
String |
| token |
jeton récupéré grâce à l'Authentication API |
Oui |
String |
exemple de réponse
|
<?xml version="1.0" encoding="UTF-8" ?>
<xpage version="1.0">
<command-list>
<command request="g10" action="ctcgetcontact">
<data-list>
<data view="deep" id="1" type="contact">
<firstname>Robert</firstname>
<lastname>Smith</lastname>
<gender>0</gender>
<company>Custland Ltd</company>
<device-list>
<device order="0" info-type="pro" subtype="isdn" type="phone" display="true"
id="dv2">0147905466 </device>
</device-list>
<address-list>
<address info-type="home">
<streetline1>24, Fascination Street</streetline1>
<streetline2>Appt 34</streetline2>
<zip-code>766546</zip-code>
<city>London</city>
<state>England</state>
</address>
</address-list>
</data>
</data-list>
</command>
</command-list>
</xpage> |
description des codes de réponses
| Nom |
Description |
| data |
Entrée du contact, contenant ses informations personnelles. |
| gender |
0=inconnu, 1=masculin, 2=féminin. |
| device-list |
Liste des terminaux associés au contact. |
| device |
Terminal de communication, défini par son type et son sous-type:
type - sous-types associés.
email - internet
téléphone - voix, mobile, fax, rnis, vidéo, pager, voiture
chat - Web irc
url - web, wap
messagerie instantanée - msn, simple, icg, aim, jabber, wv, yahoo |
| address-list |
Liste des adresses associées au contact. |
(back to API methods in detail)
addcontact
Ajouter un contact à liste des contacts de l'utilisateur.
Pour appeler l'API, créez le format d'URL suivant dans votre application Web et invoquez-le via HTTP GET:
|
Format:
[PersonalContactsV1URL]?action=addcontact&lastname=[last name]&firstname=[first name]&
nickname=[nickname]&company=[company]&function=[function]&
department=[department]&emailperso=[emailperso]&token=[user token]
Example:
[PersonalContactsV1URL]?action=addcontact&lastname=World&firstname=Hello&
nickname=HelloWorld&company=Orange&function=function&department=department&
emailperso=hello.world@helloworld.com&token=[Hjlkzjlfkzef23423kjlkjr |
paramètres d'entrée
| Nom |
Description |
Obligatoire |
Type |
| lastname |
Le nom du contact. |
Il est obligatoire d'indiquer au
moins l'une de ces informations |
String |
| firstname |
Le prénom du contact. |
String |
| nickname |
Le surnom du contact. |
String |
| company |
L'entreprise du contact. |
String |
| function |
La fonction du contact. |
Oui |
String |
| department |
Le service du contact. |
Oui |
String |
| emailperso |
L'adresse e-mail du contact. |
Oui |
String |
| token |
jeton récupéré grâce à l'Authentication API |
Oui |
String |
exemple de réponse
|
<?xml version="1.0" encoding="UTF-8" ?>
<xpage version="1.0">
<command-list>
<command request="g10" action="ctcupdatecontact">
<result>0</result>
<id>c6</id>
</command>
</command-list>
</xpage> |
Dans lequel le <result> (résultat) contient le code de retour de l'opération. 0 signifie que l'opération a réussi.
(back to API methods in detail)
adddevice
Associer un terminal défini par son type et son sous-type à un contact existant.
Les types de terminaux disponibles avec leurs sous-types associés:
type - sous-types associés.
email - internet
phone - voix, mobile, fax, rnis, vidéo, pager, voiture
chat - web irc
url - web, wap
messagerie instantanée - msn, simple, icg, aim, jabber, wv, yahoo
Pour appeler l'API, créez le format d'URL suivant dans votre application Web et invoquez-le via HTTP GET:
|
Format:
[PersonalContactsV1URL]?action=adddevice&cid=[contact id]&type=[device type]&
subtype=[device subtype]&order=[order]&value=[value]&token=[user token]
Example:
[PersonalContactsV1URL]?action=adddevice&cid=c6&type=phone&
subtype=voice&order=5&value=0123456789&token=Hjlkzjlfkzef23423kjlkjr |
paramètres d'entrée
| Nom |
Description |
Obligatoire |
Type |
| cid |
L'identifiant unique des coordonnées du contact à récupérer.
La valeur est la valeur de l' « id » dans le paramètre <data view> dans la réponse findcontactlist
|
Oui |
String |
| type |
Type de terminal (e-mail, téléphone, chat, url, messagerie instantanée). |
Oui |
String |
| subtype |
Sous-type de terminal (Internet, voix, mobile, fax, rnis, vidéo, pager, voiture, irc, Web, WAP, msn, simple, icq, aim, jabber, wv, yahoo). |
Oui |
String |
| order |
Ordre d'affichage |
Oui |
String |
| value |
Identifiant du terminal (numéro, adresse …) |
Oui |
String |
| token |
jeton récupéré grâce à l'Authentication API |
Oui |
String |
exemple de réponses
|
<?xml version="1.0" encoding="UTF-8" ?>
<xpage version="1.0">
<command-list>
<command action="cdvupdatedevice" request="g10">
<result>0</result>
</command>
</command-list>
</xpage> |
Dans lequel le <result> (résultat) contient le code retour de l'opération. 0 signifie que l'opération a réussi.
(back to API methods in detail)
(haut de page)
codes d'erreurs de la Personal Contacts API
Lorsqu'une erreur se produit, la réponse contient les paramètres suivants, le résultat et le sous-type du code erreur dans le format suivant:
|
<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 |
Statut |
Message |
| 1 |
Action inconnue |
« paramètre obligatoire manquant. » |
| 2 |
Paramètre manquant |
« paramètre » non valide. |
| 4 |
Paramètre non valide |
La commande « action » est inconnue. |
| 5 |
ID d'utilisateur non valide |
« id-utilisateurfinal » incorrecte (base de données corrompue). |
| 100 |
Données non trouvées |
Service AddressBook non disponible pour cet utilisateur. |
(haut de page)
|
