avant de commencer
Avant de commencer, merci de lire les informations ci-dessous et de suivre toutes les instructions.
Vous pourrez ensuite passer à la section « pour commencer ».
deux choses à faire avant de commencer
sur l'API Manager
deux choses à faire avant de commencer
Pour commencer à tester cette API, assurez-vous d'avoir bien lu et compris la section sur les
Personal APIs (alpha) section
Ensuite, une fois dans l'API Manager, vous pourrez vous inscrire à la Personal Contacts API.
Les étapes ci-dessous décrivent des aspects importants de l'interface
La première fois que vous vous connecterez à l'API Manager, nous vous demanderons de remplir un formulaire pour nous fournir des informations incluant :
l'URL de votre site Web
le nom de votre site Web
le logo de votre site Web
Ces informations nous aideront à valider votre inscription.
Les informations que vous nous fournirez sur le site Web seront communiquées aux utilisateurs pour leur permettre de définir leurs paramètres en matière de respect de la vie privée et de déterminer s'ils vous autoriseront, vous, le développeur, à accéder à leurs informations personnelles via les Personal APIs.
Vous aurez ensuite accès à un écran vous permettant de solliciter une inscription à n'importe laquelle des API.
Souvenez-vous que vous DEVEZ d'abord vous inscrire à la Personal Contacts API.
Une fois votre inscription validée, vous recevrez un e-mail et un fichier ZIP contenant les éléments suivants :
Votre clé d'accès (SERVICE_ID et SERVICE_PWD).
L'URL de l'API
Les exemples de codes.
Les instructions d'utilisation relatives à tous ces éléments.
accédez à l'API Manager
pour commencer
Maintenant que vous avez lu la section « avant de commencer » et que l'API Manager vous est plus familière, vous êtes prêt à en savoir plus sur…
comment authentifier l'utilisateur?
ajouter un contact "Hello World"
les méthodes de la Personal Contacts API en détail
les codes d'erreur de la Personal Contacts API
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.
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.
les méthodes de la Personal Contacts API en détail
La Personal Contacts API offre quatre méthodes:
findcontactlist
getcontact
addcontact
adddevice
getpicture
addpicture
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 |
The first characters of the first name or last name of contacts to find.
Wild cards (*) are forbidden and complex strings must be put between " " and URLEncoded,
for example: %22complex+string%22, Orange.
|
Oui |
String |
| token |
user token that is retrieved using the 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. |
(retour aux méthodes de l'API en détail)
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>
<civility>0</civility>
<maritalstatus>0</maritalstatus>
<birthday>1951-01-01</birthday>
<company>Custland Ltd</company>
<device-list>
<device display="true" id="1400761728" info-type="pro" order="1" subtype="internet" type="email">rob516.smith@custlandcy.com</device>
<device display="true" id="1295666158" info-type="perso" order="1" subtype="voice" type="phone">0123456789</device>
<device display="false" id="1400732085" info-type="perso" order="1" subtype="web" type="url">www.robsmith516.com</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><?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>
<civility>0</civility>
<maritalstatus>0</maritalstatus>
<birthday>1951-01-01</birthday>
<company>Custland Ltd</company>
<device-list>
<device display="true" id="1400761728" info-type="pro" order="1" subtype="internet" type="email">rob516.smith@custlandcy.com</device>
<device display="true" id="1295666158" info-type="perso" order="1" subtype="voice" type="phone">0123456789</device>
<device display="false" id="1400732085" info-type="perso" order="1" subtype="web" type="url">www.robsmith516.com</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. |
| civility |
0=inconnu, 1=Monsieur, 2=Madame, 3=Mademoiselle. |
| device-list |
Liste des terminaux associés au contact. |
| device |
Terminal de communication, défini par son type et son sous-type:
type - associate subtypes.
email - internet
phone - voice, mobile, fax, video
url - web |
| address-list |
Liste des adresses associées au contact. |
(retour aux méthodes de l'API en détail)
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
| Name |
Description |
Obligatoire |
Type |
| lastname |
nom. |
Au moins un champs parmi les quatre doit être présent dans la requête |
String |
| firstname |
prénom |
String |
| nickname |
surnom |
String |
| company |
employeur |
String |
| function |
fonction |
Non |
String |
| department |
département |
Non |
String |
| emailperso |
adresse éléctronique |
Non |
String |
| emailperso |
date de naissance |
Non |
ISO8601 |
| emailperso |
Civilité:
- 0 : inconnu
- 1 : Monsieur
- 2 : Madame
- 3 : Mademoiselle |
Non |
Integer |
| token |
token d'usage renvoyé par Authentication |
Yes |
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.
(retour aux méthodes de l'API en détail)
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 - associate subtypes.
email - internet
phone - voice, mobile, fax, video
url - web
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, url). |
Oui |
String |
| subtype |
Sous-type de terminal :
- internet (email)
- voice, mobile, fax, video (phone)
- web (url) |
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.
(retour aux méthodes de l'API en détail)
getpicture
Obtenir la photo 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=getpicture&
cid=[contact id]&token=[user token]
Example:
[PersonalContactsV1URL]?action=getpicture&
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éponses
<?xml version="1.0" encoding="UTF-8"?> <xpage version="1.0">
<command-list> <command action="ctcgetmedialist" request="aaa">
<data-list> <filename content="/9j/4AAQSkZJRgABAQAAAQABAA
D/2wBDAAkGBwgHBgkIBwgKCgkLDRYPDQwMDRsUFRAWIB0iIiAd
Hx8kKDQsJCYxJx8fLT0tMTU3Ojo6Iys/RD84QzQ5Ojf/2wBDAQoKCg
0MDRoPDxo3JR8lNzc3Nzc3 Nzc3Nzc3Nzc3Nzc3Nzc3Nzc3Nzc3Nz
c3Nzc3Nzc3Nzc3Nzc3Nzc3Nzc3Nzf/wAARCACCAIIDASIAAhEBAx
EB/8QAGwABAAIDAQEAAAAAAAAAAAAAAAEFAwQGAgf/xAB
AEAABAwMBBQQHAwkJAAAAAAAB AAIDBAURIRITMUFRBmFxg
RQVIiMyUpFiocEWM0JDcoKSscIHJDREc4Oi8PH/xAAUAQEAAAAA
AAAA AAAAAAAAAAAA/8QAFBEBAAAAAAAAAAAAAAAAAA
AAAP/aAAwDAQACEQMRAD8A+4IiICIiAtavuFHb YN/X1UNPFnG1K
8NBPQZ4nuWhdLtM2sFstMTZq8t2pHvBMVMw8HSY1JOuGjU4OoG
SvFs7PwU1T6fV yy1lxcMOqqjBc0fKwDRje5vnk6kPDe0TqpwFptVb
VtP66Rm4jHm/Dj5NKh1d2jeMNtttpvtTVr3/ AHNjA+9XmwM5I1681Ib4
DwQURqu0TD+ZtEo6iaRn9JXl11v0Q2n2eilA4iC4na8g6MD7wugx3l
MfaKChHahkf+PtF2pAP0jTb5v1iL1aW65UNzh31vqoaiMHDjG7Oyeh
HEHuOqzmJh1LGE9cYKqrl2fo ax/pGw6Cra3DamFxZI399uHY7jkdy
C5Rc9brrU2+sjtd9ftOkdsUtcQAJzyY8DRsnho7lg+yOhQE REBERA
REQFo3qv8AVlsmqmx72VoDYYh+skcdljfNxA81vKhuDjX9qKGiAz
DQxmsl/bdlkQ+m9Pk1 Bu2S3erqMMkk3tTI4y1ExGDLKfid+AHIADkrF
QFKAiIgKFKICIiCuvVuiuVvmppcgSNxtN0c08QQ eRBAI7wFh7N3G
Wuonw1pb6wpH7mqDdAXAZDwOjgQ4dM45FWzuHhquZnPq3tvR
SjSG5076V+OBkjz JH/xMoQdOiIgIiICIiAuc7Iv9PNxu/FtbVuMLscYme
7YR3ENLv3ludr5pafsxdJYHmN7aZ+JBxYM YLvIZPksdJV0dniorfN
u6aMtEUBcQG5A0Znk7A0B48uaC7RQDnClAREQEWrc7hBbaR1RU
FxGQ1jG DL5Hk4a1o5knQBVdRdLhHsvqfVtsjdnYbW1G1I/ybho8nO
QXyLnIu0E0GZqs0dVQhzWyVVDJn0ck ge8YTkN1ztAnA1IAGV0aC
MLme3TA22Q1gJbJR1UFQx3Qtfr5EZB7iunXNf2gg/krcS0ElkBdp3An
8EHSooGoyFKAilEEIiIMNZ6P6JN6Zu/Rt27e7zGzsY1znljOVxd2pJJux
lFC1lQblLsi3ZeWysf7Tow5+QWkRghxJ+biTg9DdsXKvhs7dYQBPW
/6YPsRn9twOerWOHML1d9iW5WylkaHNfK6QZ5OYA5p+qCOy1Bc
qC2bq8VjKmoMjnAsboxp4NzgbRHzYBP3q4ChnwhSgIiIKO/09bLcLZ
JRRNeWOkAe8ZbA 9zQBIRzw3eDHMkDTOVu2630tEC6FhfO/G8qJ
PallPHLnc/DgOQA0WW4tc6jlbFMYZdkmN7eLXcjj nry5rVsFQ6otsM8
md/I0GVpBG7f+kzB1GDka9EGr2mZSxsFRPC1/93nZNkfFBu3FzT1G
Q1Wdpjli tdHHUvc+ZkDGyOcclzg0ZJ81Q3Zwut4FtjO212IpMcBC0h8
xPc73cfiXdDjqUEFc524zNZ30reNT LFT/AMb2s/rK6MkAEnkuduoNxv
8AbLewZbA/02od8rWHDB4ueQfBh6IOjCIEQEUoghERByNuvNJZQ6i
uMNRHXyTPdNI6I+/eXEBzSfjy0NwG5wMNwMYFjXSslqrTW07y+MS
Euy0ghr24zrqNcceq373P BTWmqlqYBURiMgwFodvSdAzB0OSQPN
eKChMFppKSVwfJFAyN72n4i0AE/Uc0G/Hw8F6XlowfFekB ERBoSy
vivMEeSY54H6dHMII+oc76BYb7NHS02+nnqfacI46emcGvnefhY08cn
xAAyTgAkbNwoRWC FzZpIJ4X7cUsWMtOCCMEEEEHUH+YBWKktEU
NWKypmmrKsAtZNUEe7B4hjQA1ueZAyeZKDF2etAtl M50oYayfDpnM
yWjjhjc67LcnHUkuOrirbKLy8kDIQalzrYaGkkqahxEUQycDJJ5ADmScA
DmSFrWC hmgZPW1zQ2urHB8rAciJoGGRg/ZGc9XOcRoQsMUXrW9O
fIM0dteGxsP6yoIBLj3NDgB9ouPFoKvE BERAREQEREGKpp4aqnkgqYm
SwyN2XseMhw6ELlLdNVOuVMLHR3NtuMhEktVOx1O6MEglrXPMjeHs
4AB0yMajsFR22AUN9rqWlc4Uhijn3JOWxyPdJtbPQHZzs8M6jGSgu1K
hSgIoQ4AJIQCRkaoOCxvP BgGpWQDCCV4k4L11XmTgf+8kFd2eINFO
4cTW1OfKZ4/BWipezx3VVd6Jx9qOsMrR1ZIA7P8AFvB+ 6VdICIiAiIgIiI
Co66WS1Xl9fLDJJQ1MLI5ZImF5gewuIc5oydkh+MgaFuuhyLxEFQe01l
DQRcqZ +RkBjw4/QZKxflXaTwmnI6tpJj/QrzzRBz7e11rlqhSUzp56ojIp
2wPa8jr7YGnet+lnrKlofPSu pejXSAkDv049w+qx3yKMzW2d4G1FVta
HdA9rmkeeR546KyIzH4jigxxghzy47TjgAnp0WdYYyXOJ PM6Dw/8AV
l8UBQdAfHKlOeCOIQUddm33ujrhpFMRRz920fduPg/2f91Xq0LnRMuND
PSyuLWysLC9 vFp+Yd4OCO9oSx1kldbIpahoZUtzFUNHBsrCWvx3bQO
O7CDfREQEREBERAREQEREFff4XT2arbF+ dZHvYj0kZ7TD/E0LZilbPTx
Ss+GRoc3wOv8AJZnAOaWngRgrn6a4SWW300F5pnQRwRNiNW14fC
SG 4GTo5ue9uM4GckZC9A2dSeC94zhVUNXc6tu9gt0cUDj7HpczmSEd
SwMOznoTnqAdFlLrweEdAzv3 j3Y8tkILHooPEFVxhvDv87Qs8KR5x57
z8FBttVKMT3esIPFsTY4x5HZ2h9UGW419PbojLVPwHECN jRtPkd8rGjV
zjjgFFkgnhodqrYGVE8j5pGB2dgucSG5HHAwM88KaO00NHMZ4YAagg
tM8rjJIR023 Eux3ZW8gIiICIiAiIgIiIClEQQodwREEhERAREQEREBERBKIiD//
2Q==" display="false" id="1429530340" info-type="perso" order="1"
subtype="picture" type="media"/> <typeImage>gif</typeImage>
</data-list><result>0</result> </command> </command-list>
<parameter-list/> </xpage> |
description des codes de réponses
| Nom |
Description |
| data-list |
Liste des images du contact. |
| filename |
Fichier image du contact, le fichier est encodé en base 64 dans l'attribut content. |
| typeImage |
Format de l'image associée au contact : gif, jpeg ou bmp. |
(retour aux méthodes de l'API en détail)
addpicture
Ajouter une photo à un contact, cette requête contient le fichier image à transférer.
Les formats d'images suivants sont acceptés : JPEG, GIF, BMP
Pour appeler l'API, créez un message multi-part dans votre application Web et postez-le à l'url [PersonalContactsV1URL] :
Exemple :
POST [PersonalContactsV1URL] HTTP/1.1
Content-Type: multipart/form-data;boundary=---------------------------41184676334
Content-Length: 29277
-----------------------------41184676334
Content-Disposition: form-data; name="action"
add picture
-----------------------------41184676334
Content-Disposition: form-data; name="cid"
C1
-----------------------------41184676334
Content-Disposition: form-data; name="token"
Hjlkzjlfkzef23423kjlkjr
-----------------------------41184676334
Content-Disposition: form-data; name="file"; filename="picture.jpg"
Content-Type: image/jpeg
[binary content] |
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 |
| file |
Fichier à transférer. |
Oui |
String |
exemple de réponses
<?xml version="1.0" encoding="UTF-8" ?>
<xpage version="1.0">
<command-list>
<command action="ctcaddmedia" 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.
(retour aux méthodes de l'API en détail)
les 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 |
unkown action |
« paramètre obligatoire manquant. » |
| 2 |
missing parameter |
« paramètre » non valide. |
| 4 |
invalid parameter |
La commande « action » est inconnue. |
| 5 |
invalid user ID |
« id-utilisateurfinal » incorrecte (base de données corrompue). |
| 100 |
data not found |
Service AddressBook non disponible pour cet utilisateur. |
(back to top)
