API Web Service TéléAlerte

Transcription

API Web Service TéléAlerte
Version 1.4 (janvier 2016)
Auteurs : Hennie Reyneke, Etienne Bauchet, Stéphane Gibouin.
Table des matières
Table des matières ................................................................................................................................... 2
Introduction, démarche technique ........................................................................................................... 4
Prérequis : notion de scénario .................................................................................................................. 4
Définition des architectures et protocoles............................................................................................... 5
Moyen de sécurisation ............................................................................................................................. 5
Intégration fournisseur extérieur ............................................................................................................. 5
Présentation : fonctionnalités du Web Service ........................................................................................ 6
Services ou classes de base : ................................................................................................................ 6
Types de données : ............................................................................................................................... 7
Types de données spécifiques.............................................................................................................. 7
Implémentation SOAP : ............................................................................................................................ 8
Authentification :.................................................................................................................................. 8
1.
Récupération de la liste des sites auxquels l’identifiant API est associé. .............................. 8
2.
Récupération de l’objet de session ...................................................................................... 10
Méthodes : ............................................................................................................................................. 12
Gestion des scénarios ............................................................................................................................. 15
GetScriptList ....................................................................................................................................... 15
Script ............................................................................................................................................... 15
Structure de la réponse : ........................................................................................................................ 16
GetScriptDetails .................................................................................................................................. 17
ScriptParameters ............................................................................................................................ 17
GetSubscribersDetails ........................................................................................................................ 19
Subscriber ....................................................................................................................................... 19
evaluateScript ..................................................................................................................................... 21
LoadIntroMsg ..................................................................................................................................... 22
LoadMainMsg ..................................................................................................................................... 22
LoadEndMsg ....................................................................................................................................... 22
LaunchScript ....................................................................................................................................... 23
LaunchScriptParameters .................................................................................................................... 24
2
launchParams ................................................................................................................................. 24
fileUpload ........................................................................................................................................... 25
aSyncImportCSV ................................................................................................................................. 26
MapWrapper .................................................................................................................................. 26
syncImportCSV ................................................................................................................................... 27
ImportResults ................................................................................................................................. 28
getImportCSVStatus ........................................................................................................................... 30
getImportResults ................................................................................................................................ 31
getStats ............................................................................................................................................... 32
Media – Possible String values ....................................................................................................... 32
StatisticalResult .............................................................................................................................. 33
Script ............................................................................................................................................... 35
Gestion des envois directs...................................................................................................................... 36
SendSMS ............................................................................................................................................. 36
GetSMSStatus (*)............................................................................................................................... 38
GetUStatus (v1.5+) ............................................................................................................................. 39
StatusDetails ................................................................................................................................... 39
sendFastMailCampaign ...................................................................................................................... 40
Kit de développement JAVA : ................................................................................................................. 41
Kit de développement PHP : .................................................................................................................. 41
Kit de développement C# : ..................................................................................................................... 41
Conclusion............................................................................................................................................... 41
Annexe 1 : Statuts d’envoi ...................................................................................................................... 42
Annexe 2 : Scénario d’envoi d’un SMS Vocal (avec authentification) .................................................... 43
3
Introduction, démarche technique
La TéléAlerte de GEDICOM est un système de gestion complet et performant qui permet de gérer des
campagnes téléphoniques, sms, fax, mail et pager. Gedicom a mis en place un Web Service
permettant d’intégrer les fonctionnalités du système TéléAlerte à d’autres logiciels. Cette intégration
est indépendante des langages de programmation utilisés côté client et serveur.
Un ensemble de fonctionnalités de base sont présentes par défaut sur le système. L’équipe de
développeur de Gedicom peut rapidement intégrer de nouvelles méthodes à la demande.
Gedicom met à disposition un « package SDK PHP côté client» illustrant les intégrations décrites dans
le présent document.
Prérequis : notion de scénario
Le scénario permet de prédéfinir un ensemble de comportements lors de l’envoi d’une campagne
média.
La campagne média regroupe un nombre défini de destinataires sur un ou plusieurs médias (Tél, Sms,
Fax, etc…).
Le scénario permet donc de s’abstraire d’un ensemble de comportements plus ou moins complexes
(exemple : appel de tel groupe en priorité sur les portables et si absence envoi sur SMS etc…). Le
principe étant de définir par avance (préprogrammer) les campagnes et ainsi de ne fournir que les
informations nécessaires lors de l’envoi ; cela consolide le processus et permet de rapidement
intégrer par API des situations qui peuvent être multiples et complexes.
4
Définition des architectures et protocoles
Le protocole utilisé est SOAP.
SOAP est un protocole bâti sur XML et qui permet la transmission de messages. Il définit les règles
permettant de structurer les messages qui peuvent transiter par http entre le client et le serveur. Ces
derniers ont pour contrainte d’être écrits dans des langages permettant de formuler et de
comprendre les messages SOAP. Un fichier WSDL, disponible sur internet offre la description du Web
Service.
Afin de lancer les développements, effectuer rapidement des tests et pour simplifier il est possible
aussi d’utiliser des méthodes http/https directes (service en dehors de la production).
Moyen de sécurisation
Le service API SOAP TéléAlerte de Gedicom est protégé et seuls les utilisateurs autorisés peuvent
l’utiliser. La sécurité est assurée par :
-
Un identifiant et un mot de passe API obligatoires
-
Transmission des données SSL
Un échec de l’authentification interdit l’accès à l’API SOAP TéléAlerte. Le processus s’appuie sur une
notion de « session » ; un jeton ou identifiant unique de session une fois l’authentification doit être
conservé du côté client, cela assure un niveau de sécurité accru et un allégement des volumes
d’échanges (augmentation substantielle des performances sur de gros volumes d’envoi).
Intégration fournisseur extérieur
Gedicom délivre cette API aux intégrateurs divers du marché afin d’étendre la capacité du service
fournisseur (SMS, Fax, etc…). Vous pouvez demander à votre intégrateur de rajouter les
fonctionnalités Gedicom afin de n’avoir qu’un seul point API d’échange.
5
Présentation : fonctionnalités du Web Service
Fonctionnalités de base via le Web Service. Ces méthodes s’appuient sur une notion de scénario :
-
Session cryptée entre client et serveur
-
Récupération de la liste des scénarios définis au préalable sur le site classique de
TéléAlerte
-
Récupération des informations générales et détaillées liés aux scénarios (id, description,
messages textes et vocaux, groupes concernés, nombre de destinataires etc.)
-
Définition de l’ordre d’affichage des scénarios
-
Définition d’un code couleur pour chaque scénario
-
Téléchargement des messages vocaux liés aux scénarios
-
Evaluation du nombre de destinataires d’un scénario
-
Déclenchement d’un scénario
Certaines fonctionnalités ont été intégrées afin de faciliter l’émission de SMS ou SMS Vocal sans
notion de scénario :
-
Envoi direct de SMS avec les options de bases.
-
Récupération de l’état d’envoi d’un SMS.
Services ou classes de base :
Les fonctionnalités de l’API SOAP de TéléAlerte sont mises en œuvre par deux services :
Service
Description
SOAPSessionFactoryService
Gère l’authentification.
WSDL
GedServerService
Méthodes de récupération d’informations
liées aux scénarios. Méthode de
déclenchement des scénarios.
WSDL
6
Types de données :
L’API utilise les types de données primitives suivants :
Valeur
Détails
Base64Binary
Donnée binaire encodée en Base64 : format utilisé pour l’envoi des messages
vocaux.
String
Chaîne de caractère.
int
Entier. Exemple : La méthode evaluateScript retourne le nombre de numéros
de téléphones concernés par le scénario.
boolean
Valeurs possibles : true / false
Types de données spécifiques
En plus des données primitives, l’API définie ses propres types de données complexes :
Valeur
Détails
script
Type d’objet retourné par la méthode GetScriptList. Ce type d’objet contient
les informations suivantes : Id, label, position du scénario, couleur du scénario.
GetScriptList renvoie autant d’objets script qu’il y a de scénarios enregistrés.
scriptParameters
Type d’objet retourné par la méthode GetScriptDetails
GetScriptDetails. Il contient des
informations détaillées concernant un scénario : Id, catégorie, label, position,
couleur, description, titre des messages vocaux, liste des groupes, texte des
mails, des sms et des pagers.
7
Implémentation SOAP :
Authentification :
L’authentification est gérée par le service suivant : SOAPSessionFactoryService. Elle peut se faire en 2
étapes.
1. Récupération de la liste des sites auxquels l’identifiant API est associé.
Cette étape est facultative pour la majorité de nos clients. Il faut en effet que le client dispose de
plusieurs sites séparés (plusieurs contrats) et souhaitant gérer sur un même identifiant plusieurs
sites. Vous pouvez directement aller à l’étape 2.
Structure de la requête :
<soapenv:Envelope xmlns:soap="http://soap.gedicom.com/"
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Header>
<wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsu:Timestamp wsu:Id="Timestamp-9" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis200401-wss-wssecurity-utility-1.0.xsd">
<wsu:Created>2013-11-15T16:07:18.576Z</wsu:Created>
<wsu:Expires>2013-11-15T16:08:18.576Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</soapenv:Header>
<soapenv:Body>
<soap:PreLogin>
<UserLog>api_username</UserLog>
<Passwd>api_password</Passwd>
</soap:PreLogin>
</soapenv:Body>
</soapenv:Envelope>
Annotations de la requête :
Ligne
Commentaire
3 à 12
Le header doit obligatoirement contenir un Timestamp (Ligne 5 à 9).
13 à 18
Le body doit contenir les identifiants du WebService.
Dans le corps de la requête, le client doit définir les éléments suivants :
Elément
Valeur
Description
<UserLog>
api_username
Votre identifiant API fournit par Gedicom sur
demande.
<Passwd>
api_password
Votre mot de passe API généré par Gedicom.
8
Structure de la réponse :
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsse="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<S:Header>
<wsse:Security S:mustUnderstand="1">
<wsu:Timestamp wsu:Id="_1"
xmlns:ns15="http://schemas.xmlsoap.org/ws/2006/02/addressingidentity" xmlns:ns14="http://docs.oasisopen.org/ws-sx/ws-secureconversation/200512" xmlns:ns13="http://www.w3.org/2003/05/soap-envelope">
<wsu:Created>2013-11-16T09:58:19Z</wsu:Created>
<wsu:Expires>2013-11-16T10:03:19Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</S:Header>
<S:Body>
<ns2:PreLoginResponse xmlns:ns2="http://soap.gedicom.com/"
xmlns:ns3="http://www.w3.org/2005/08/addressing">
<return>[{"SiteLongName":"_Site de démonstration de Gedicom","SiteName":"GedDemo"}]</return>
</ns2:PreLoginResponse>
</S:Body>
</S:Envelope>
Annotations de la réponse :
Ligne
Commentaire
6 à 16
Le header contient toujours un élément <Timestamp>…</Timestamp>
17
Début du corps de la réponse
20
La balise <return> contient un tableau JSON ayant une entrée par site dont l’accès
est autorisé pour ces identifiants (en général un seul site).
22
Fin du corps de la réponse
9
2. Récupération de l’objet de session
Cette requête permet d’initier un partage de session entre les parties et ainsi il suffit de réinjecter
l’identifiant unique à chaque requête afin d’éviter à redéposer systématiquement les identifiants et
mots de passe. Le partage est d’autant plus sécurisé. L’objet renvoie aussi la classe permettant de
déclencher les méthodes fournies par Gedicom (GedServer).
Structure de la requête :
<soapenv:Header>
</wsu:Timestamp>
</wsse:Security>
</soapenv:Header>
<soapenv:Body>
<soap:Login>
<WebSite>APIDemo</WebSite>
</soap:Login>
</soapenv:Body>
</soapenv:Envelope>
La structure de la requête SOAP est la même que pour la requête de récupération des sites. Il faut
ajouter le paramètre <WebSite>.
Elément
Valeur
Description
<WebSite>
APIDemo
Site choisi par l’utilisateur. Les noms des sites sont
fournis par Gedicom, lors de la souscription à l’option
API TéléAlerte.
10
<S:Header>
</wsu:Timestamp>
</wsse:Security>
</S:Header>
<S:Body>
<ns2:LoginResponse xmlns:ns2="http://soap.gedicom.com/"
<return>
<ns3:Address>https://www.acces-gedicom.com:443/GedWSServer/GedServer</ns3:Address>
<ns3:ReferenceParameters>
<jaxws:objectId xmlns:jaxws="http://jax-ws.dev.java.net/xml/ns/"
xmlns:wsa="http://www.w3.org/2005/08/addressing">object_id_value</jaxws:objectId>
</ns3:ReferenceParameters>
<ns3:Metadata wsdli:wsdlLocation="http://soap.gedicom.com/ https://www.accesgedicom.com:443/GedWSServer/GedServer?wsdl" xmlns:wsdli="http://www.w3.org/ns/wsdl-instance">
<wsam:InterfaceName xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata"
xmlns:jaxws="http://jax-ws.dev.java.net/xml/ns/" xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"
xmlns:wsns="http://soap.gedicom.com/">wsns:GedServer</wsam:InterfaceName>
<wsam:ServiceName EndpointName="GedServerPort"
xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" xmlns:jaxws="http://jaxws.dev.java.net/xml/ns/" xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:wsns="http://soap.gedicom.com/">wsns:GedServerService</wsam:ServiceName>
</ns3:Metadata>
</return>
</ns2:LoginResponse>
</S:Body>
</S:Envelope>
Annotations de la réponse SOAP :
Ligne
Description
6 à 16
Header. Chaque réponse SOAP contient un timestamp dans son header.
21
L’élément <Address> contient l’adresse du WebService permettant d’utiliser les
fonctionnalités du système de TéléAlerte (GedServer).
24
L’élément <jaxws:objectId> contient un identifiant unique qui sera utilisé pour
effectuer les requêtes pendant toute la session. Cet identifiant ne sera plus valide
après déconnexion.
29 à 45
L’élément <ns3:metadata> contient des informations additionnelles notamment
le nom de l’interface (GedServer) et le nom du service correspondant
(GedServerService).
11
Méthodes :
Voici la liste des méthodes pour le service GedServerService.
Méthodes de gestion des scénarios :
Méthode
Description
GetScriptList
Renvoie la liste des scénarios enregistrés sur le site de TéléAlerte.
GetScriptDetails
Renvoie les informations détaillées d’un scénario à partir de son
identifiant.
GetSubscribersDetails
Renvoie les informations détaillées d’un abonné à partir de son
identifiant.
evaluateScript
Nombre de destinataires d’un scénario.
LoadIntroMsg
Télécharger le message d’introduction d’un scénario.
LoadMainMsg
Télécharger le message principal d’un scénario.
LoadEndMsg
Télécharger le message de fin d’un scénario.
LaunchScript
Déclencher un scénario.
LaunchScriptParameters Déclencher un scénario avec possibilité de spécifier certains paramètres
et/ou de fournir des valeurs aux groupes utilisés
fileUpload
Télécharger un fichier sur le serveur. Ce fichier pourra ensuite être
utilisé pour importer son contenu dans le système.
aSyncImportCSV
Importation d’un fichier CSV de façon asynchrone
syncImportCSV
Importation d’un fichier CSV de façon synchrone
getImportCSVStatus
Obtenir le statut d'une importation CSV.
getImportResults
Obtenir les résultats d'une importation CSV.
getStats
Obtenir les statistiques d'une campagne
Logout
Déconnecter la session.
SensSMS
Envoi d’un SMS simple
GetSMSStatus
GetSMSStatus
Récupération de l’état d’un envoi de SMS simple
GetUStatus
Retourne les statuts d’un envoi unique
sendFastMailCampaign
Envoi d’une campagne rapide mail en précisant le sujet, le texte, le
format (text/html, charset=UTF-8 par défaut), une liste d'options (cf.
détail fonction) et la liste des adresses des destinataires.
12
13
Corps
En-tête
Schéma de l’enveloppe d’une requête :
Timestamp: <wsu:Timestamp>
objectId : <jaxws:objectId>
Eléments propres
à chaque opération
TéléAlerte
En-tête générale d’une requête :
<soapenv:Header>
<wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401wss-wssecurity-utility-1.0.xsd">
<wsu:Timestamp wsu:Id="TS-1">
</wsu:Timestamp>
</wsse:Security>
xmlns:wsa="http://www.w3.org/2005/08/addressing">fe3cea34-d2fb-4802-8fcb-3c041029bc20</jaxws:objectId>
</soapenv:Header>
Annotations de la réponse SOAP :
Ligne
Description
6à9
Chaque en-tête de requête doit comporter un Timestamp.
11
Chaque en-tête doit également comporter un objectId. Il faut réutiliser l’objectId
renvoyé à l’étape 2 de l’authentification.
14
Gestion des scénarios
GetScriptList
Retourne la liste des scenarios disponibles
Parameters
Type
Description
Aucun paramètre
Return Type
Description
ArrayList<Script>
ArrayList des différents scenarios (type Script)
Methods
Attributes
Script
int id;
String label;
int WSOrder;
String WSColor;
Getter- and setter methods for
each attribute.
Corps de la requête :
<soapenv:Body>
<soap:GetScriptList/>
</soapenv:Body>
15
<S:Header>
</wsu:Timestamp>
</wsse:Security>
</S:Header>
<S:Body>
<ns2:GetScriptListResponse xmlns:ns2="http://soap.gedicom.com/">
<return>
<id>168</id>
<label>Test_1 API TeleAlerte</label>
<WSColor>b</WSColor>
<WSOrder>0</WSOrder>
</return>
</ns2:GetScriptListResponse>
</S:Body>
</S:Envelope>
Annotations de la réponse :
Ligne
Description
8 à 14
Chaque réponse contient un Timestamp
20
L’élément <id> contient l’id du scénario en question
21
L’élément <label> contient le nom donné au scénario
22
L’élément <WSColor> contient un code couleur affecté au scénario. Cet élément
peut également être défini afin d’être adapté aux besoins du client.
23
L’élément <WSOrder> contient la position du scénario. Cette position peut
également être définie.
16
GetScriptDetails
Retourne les paramètres d’un scenario.
Parameters
Type
Description
ScriptId
String
Numéro (id) du scénario
Return Type
Description
ScriptParameters
Objet de type ScriptParameters retourné (voir description ci-dessous)
Methods
Attributes
ScriptParameters
int id;
String label;
String desc;
String GrpList;
String IntoMsgLabel;
String MainMsgLabel;
String EndMsgLabel;
int type;
int cat;
int WSOrder;
String WSColor;
String SMSTxt;
String MailSub;
String MailTxt;
String PagerTxt;
each attribute.
<soapenv:Body>
<soap:GetScriptDetails>
<ScriptId>168</ScriptId>
</soap:GetScriptDetails>
</soapenv:Body>
17
Corps de la réponse :
<S:Body>
<ns2:GetScriptDetailsResponse xmlns:ns2="http://soap.gedicom.com/">
<return>
<cat>0</cat>
<desc>Test démo</desc>
<endMsgLabel>null</endMsgLabel>
<grpList><![CDATA[<div><input type="hidden" name="OpChk" value="90"><input type="hidden"
name="Op90" value="0"><b>90</b> - Test CCH /Gedicom</div>]]></grpList>
<id>168</id>
<introMsgLabel>null</introMsgLabel>
<mailSub/>
<mailTxt/>
<mainMsgLabel>Test CCH2</mainMsgLabel>
<pagerTxt/>
<smsTxt>Campagne de test de CCH pour démo Gedicom</smsTxt>
<type>0</type>
<WSColor>b</WSColor>
<WSOrder>0</WSOrder>
<label>Test CCH Démo Gedicom</label>
</return>
</ns2:GetScriptDetailsResponse>
</S:Body>
Eléments de la réponse :
Elément
Description
<cat>
Catégorie du message.
<desc>
Description du message.
<endMsgLabel>
Libellé du message de fin. ‘null’ si aucun message de fin n’est enregistré.
<grpList>
Liste des groupes associés au scénario
<introMsgLabel> Libellé du message d’introduction. ‘null’ si aucun message d’introduction n’est
enregistré.
<mailSub>
Sujet du mail associé au scénario.
<mailTxt>
Texte du mail.
<mainMsgLabel> Libellé du message de fin. ‘null’ si aucun message principal n’est enregistré.
<pagerTxt>
Texte du message pager.
<smsTxt>
Texte du sms.
<type>
Type du scénario.
18
Retourne les informations de la fiche d’un abonné (sans les données étendues).
Parameters
Type
Description
PhoneId
String
Référence de l’abonné.
Return Type
Description
Subscriber
Retourne les informations de la fiche d’un abonné (voir ci-dessous)
Methodes
Attributes
Subscriber
String PhoneId;
String TypeAbo;
String Civility;
String Name;
String FullAddress;
String PostalCode;
String City;
String EmailAddress;
String PhoneId2;
String PhoneId3;
String PhoneId4;
String PhoneId5;
String PhoneId6;
String PhoneId7;
String SMS;
String Fax;
String BirthDate;
String Floor;
String NbOfPeople;
String Launguage;
String FreeZone1;
String FreeZone2;
String FreeZone3;
String GPSCoords;
String CountryCode;
each attribute.
19
<soapenv:Body>
<soap:getSubscribersDetails>
<PhoneId>0123456789</PhoneId>
</soap:getSubscribersDetails>
</soapenv:Body>
<S:Body>
<ns2:getSubscribersDetailsResponse xmlns:ns2="http://soap.gedicom.com/">
<return>
<birthDate/>
<city/>
<civility/>
<countryCode/>
<emailAddress/>
<fax/>
<floor>0</floor>
<freeZone1/>
<freeZone2/>
<freeZone3/>
<fullAddress>31 Rue de la Paix</fullAddress>
<GPSCoordinates/>
<language/>
<name>Toto</name>
<nbOfPeople>1</nbOfPeople>
<phoneId>0123456789</phoneId>
<phoneId2/>
<phoneId3/>
<phoneId4/>
<phoneId5/>
<phoneId6/>
<phoneId7/>
<postalCode/>
<SMS/>
<typeAbo/>
</return>
</ns2:getSubscribersDetailsResponse>
</S:Body>
20
evaluateScript
Evalue le nombre de destinataires du scenario.
Parameters
Type
Description
ScriptId
String
Identifiant (numéro) du scenario.
Return Type
Description
int
Nombre de destinataires.
<soapenv:Body>
<soap:evaluateScript>
</soap:evaluateScript>
</soapenv:Body>
<S:Body>
<ns2:evaluateScriptResponse xmlns:ns2="http://soap.gedicom.com/">
<return>1</return>
</ns2:evaluateScriptResponse>
</S:Body>
21
LoadIntroMsg
Permet de télécharger le message d’introduction du dernier script chargé (GetScriptDetails).
Parameters
Type
Description
No parameters.
Return Type
Description
DataHandler
Returns a DataHandler object.
LoadMainMsg
Permet de télécharger le message principal du dernier script chargé (GetScriptDetails).
Parameters
Type
Description
No parameters.
Return Type
Description
DataHandler
LoadEndMsg
Permet de télécharger le message de fin du dernier script chargé (GetScriptDetails).
Parameters
Type
Description
No parameters.
Return Type
Description
DataHandler
<soapenv:Body>
<soap:Load...Msg/>
</soapenv:Body>
22
<S:Body>
<ns2:Load...MsgResponse xmlns:ns2="http://soap.gedicom.com/">
<return>base64binary</return>
</ns2:Load...MsgResponse>
</S:Body>
La réponse comporte des données binaires encodées au format base64 correspondant au message
vocal demandé.
LaunchScript
Lance une campagne à partir d’un scénario.
Parameters
Type
Description
ScriptId
String
Identifiant du scenario.
Return Type
Description
int
Numéro de la campagne créée (-1 si erreur)
<soapenv:Body>
<soap:LaunchScript>
</soap:LaunchScript>
</soapenv:Body>
<S:Body>
<ns2:LaunchScriptResponse xmlns:ns2="http://soap.gedicom.com/">
<return>18000</return>
</ns2:LaunchScriptResponse>
</S:Body>
23
LaunchScriptParameters
Lance une campagne à partir d’un scénario. Cette méthode permet de définir les valeurs de certains
paramètres du scénario et de fournir (le cas échéant) des valeurs aux groupes dynamiques variables
ciblés par ce scénario.
Parameters
Type
Description
ScriptId
String
Identifiant du scenario (numéro de scenario)
launchParams[] launchParam Table d’objets launchParams contenant les paramètres que le
scénario devra prendre en compte pour lancer la campagne.
String
values[]
Table des valeurs attendues par le(s) groupe(s) dynamique(s)
variable(s) du scénario
Return Type
Description
int
Identifiant de la campagne créée (-1 si erreur)
Methodes
Attributes
launchParams
String FieldName;
String Value;
String ExtField;
String ExtValue;
each attribute.
<soapenv:Body>
<soap:LaunchScriptParameters>
<values>17001</values>
</soap:LaunchScriptParameters>
</soapenv:Body>
24
<S:Body>
<ns2:LaunchScriptParametersResponse xmlns:ns2="http://soap.gedicom.com/">
</ns2:LaunchScriptParametersResponse>
</S:Body>
Le serveur retourne la valeur de la campagne créée (ici 38451). Cet identifiant pourra ensuite, par
exemple, être utilisé pour obtenir des statistiques sur cette campagne.
fileUpload
Méthode permettant de charger un fichier sur le serveur. Le fichier chargé pourra ensuite être utilisé
par le système, par exemple pour importer son contenu.
Parameters
Type
Description
fileName
String
Nom complet (absolu) du fichier à charger (sur votre système)
fileData
DataHandler Contenu du fichier
Return Type
Description
String
Nom du fichier chargé sur le serveur
<soapenv:Body>
<soap:fileUpload>
<fileName>C:\Test\test.csv</fileName>
<fileData>cid:652891985198</fileData>
</soap:fileUpload>
</soapenv:Body>
<S:Body>
<ns2:fileUploadResponse xmlns:ns2="http://soap.gedicom.com/">
<return>test_c100f9ece9.csv</return>
</ns2:fileUploadResponse>
</S:Body>
Le nom du fichier serveur (ici test_c100f9ece9.csv) servira de référence pour importer son
contenu (voir méthodes aSyncImportCSV et syncImportCSV).
25
aSyncImportCSV
Importer un fichier CSV dans le système de façon asynchrone.
Parameters
Type
Description
fileReference
String
Référence du fichier sur le serveur
associations
MapWrapper MapWrapper contenant les associations entre noms de colonnes du
fichier et nom de champs (voir Annexe 1). Key=nom de colonne,
Value=nom de champs.
options
MapWrapper MapWrapper contenant les options d’importation (voir Annexe 1).
Return Type
Description
int
Référence (numéro) de l’opération d’importation.
Methodes
Members
MapWrapper
Map<String, String> map;
Map getMap()
setMap(Map map)
MapWrapper getWrapperFromMap(Map<String, String> map)
<soapenv:Body>
<soap:asyncImportCSV>
<fileReference>test.csv</fileReference>
<associations>
<map>
<entry key="col1">PHONE1</entry>
<entry key="col2">FIRSTNAME</entry>
<entry key="col3">ADDRESS</entry>
</map>
</associations>
<options>
</options>
</soap:asyncImportCSV>
</soapenv:Body>
26
<S:Body>
<ns2:asyncImportCSVResponse xmlns:ns2="http://soap.gedicom.com/">
</ns2:asyncImportCSVResponse>
</S:Body>
syncImportCSV
Importer un fichier CSV dans le système de façon synchrone.
Parameters
Type
Description
fileReference
String
Référence du fichier sur le serveur
associations
MapWrapper MapWrapper contenant les associations entre noms de colonnes du
fichier et nom de champs (voir Annexe 1). Key=nom de colonne,
Value=nom de champs.
options
MapWrapper MapWrapper contenant les options d’importation (voir Annexe 1).
Return Type
Description
ImportResults
Retourne un objet de type ImportResults (voir ci-dessous) contenant
les résultats de l’importation.
27
Methodes
Attributes
ImportResults
int total;
int updated;
int notUpdated;
int added;
int deletedFromSys;
int newUsers;
int deleted;
int doubled;
int grpId;
int emptyLines;
int ignored;
boolean importTxt;
String selectedFields;
int grpOpion;
String SQLError;
each attribute.
<soapenv:Body>
<soap:syncImportCSV>
<fileReference>test.csv</fileReference>
<associations>
<map>
<entry key="col1">PHONE1</entry>
<entry key="col2">FIRSTNAME</entry>
<entry key="col3">ADDRESS</entry>
</map>
</associations>
<options>
</options>
</soap:syncImportCSV>
</soapenv:Body>
28
<S:Body>
<ns2:syncImportCSVResponse xmlns:ns2="http://soap.gedicom.com/">
<return>
<added>0</added>
<deleted>0</deleted>
<deletedFromSys>0</deletedFromSys>
<doubled>0</doubled>
<emptyLines>0</emptyLines>
<grpId>0</grpId>
<grpOption>0</grpOption>
<ignored>0</ignored>
<importTxt>false</importTxt>
<newUsers>0</newUsers>
<notUpdated>0</notUpdated>
<total>1</total>
<updated>1</updated>
</return>
</ns2:syncImportCSVResponse>
</S:Body>
29
getImportCSVStatus
Retourne le statut de l’opération d’importation importationId.
Parameters
Type
Description
importationId
int
Return Type
Description
String
Retourne le statut de l’opération d’importation.
"Process launched but not started" = pas encore démarée
"Processing" = en cours
"Done" = terminée avec succès
"Error" = en erreur
"Operation does not exist" = opération inexistante
<soapenv:Body>
<soap:getImportCSVStatus>
<importationId>413</importationId>
</soap:getImportCSVStatus>
</soapenv:Body>
<S:Body>
<ns2:getImportCSVStatusResponse xmlns:ns2="http://soap.gedicom.com/">
<return>Done</return>
</ns2:getImportCSVStatusResponse>
</S:Body>
30
getImportResults
Retourne le résultat d’une operation d’importation.
Parameters
Type
Description
importationId
int
Return Type
Description
ImportResults
Retourne un objet de type ImportResults (voir ci-dessous) contenant
les résultats de l’importation.
<soapenv:Body>
<soap:getImportResults>
<importationId>413</importationId>
</soap:getImportResults>
</soapenv:Body>
<S:Body>
<ns2:getImportResultsResponse xmlns:ns2="http://soap.gedicom.com/">
<return>
<added>0</added>
<deleted>0</deleted>
<deletedFromSys>0</deletedFromSys>
<doubled>0</doubled>
<emptyLines>0</emptyLines>
<grpId>0</grpId>
<grpOption>0</grpOption>
<ignored>0</ignored>
<importTxt>false</importTxt>
<newUsers>0</newUsers>
<notUpdated>0</notUpdated>
<total>1</total>
<updated>1</updated>
</return>
</ns2:getImportResultsResponse>
</S:Body>
31
getStats
Retourne la liste des statistiques générales pour la campagne nID et le media media.
Parameters
Type
Description
nID
int
Identifiant de la campagne (par défaut si aucune référence la dernière
campagne est choisie, si 0 alors référence des envois unitaires ex.
SendSMS –ceux sans notion de campagne-).
media
String
Identifiant du media (voir liste ci-dessous).
DateStart
String
Option : date de début de l’analyse statistique (notion importante
pour l’option 0 en nID). Format JJ/MM/AAAA HH:mm:ss.
DateStop
String
Option : date de fin de l’analyse statistique. Si aucune information ou
paramètre absent, la date courante est prise en compte.
Return Type
Description
List<StatisticalResult>
Retourne une liste des statistiques (objet StatisticalResult, voir
description ci-dessous).
Possible Values
Media – Possible String values
String SUBSCRIBERS;
String CALL; (VOICE AND VOCAL SMS)
String GSM;
String SMS;
String FAX;
String MAIL;
String PAGER;
String ANSWERS;
32
Attributes
int rowNum;
int stat;
Methodes
StatisticalResult
each attribute.
<soapenv:Body>
<soap:getStats>
<nID>413</nID>
<media>MAIL</media>
</soap:getStats>
</soapenv:Body>
<S:Body>
<ns2:getStatsResponse xmlns:ns2="http://soap.gedicom.com/">
<return>
<rowNum>50</rowNum>
<stat>1</stat>
</return>
<return>
<rowNum>51</rowNum>
<stat>1</stat>
</return>
<return>
<rowNum>53</rowNum>
<stat>0</stat>
</return>
<return>
<rowNum>52</rowNum>
<stat>0</stat>
</return>
</ns2:getStatsResponse>
</S:Body>
33
Logout
Ferme la connexion (session) au web-service.
Parameters
Type
Description
Aucun paramètre.
Return Type
Description
Pas de retour.
<soapenv:Body>
<soap:Logout/>
</soapenv:Body>
<S:Body>
<ns2:LogoutResponse xmlns:ns2="http://soap.gedicom.com/"/>
</S:Body>
Après cette opération, l’objectid utilisé dans toutes les requêtes expire. Il faut renouveler le
processus d’authentification.
GetScriptList
Retourne tous les scenarios disponibles
Parameters
Type
Description
Aucun paramètre.
Return Type
Description
ArrayList<Script>
Liste des scenarios disponibles. Voir description de l’objet Script cidessous.
34
Methods
Attributes
Script
int id;
String label;
int WSOrder;
String WSColor;
each attribute.
35
Gestion des envois directs
SendSMS
Envoi unitaire de SMS, une notion de « workflow » permet d’attribuer une logique de cascade en
fonction des résultats du SMS.
Parameters
Type
Description
Phone
String
Numéro de mobile de destination (si 0 alors simulation, le SMS ou le
SMS Vocal génère un état aléatoire)
SmsTxt
String
Texte SMS (limité à 160 caractères, sauf si envoi vocal)
Options
MapWrapper
MapWrapper contenant les options d’importation.
Options actuellement implémentées :
• Workflow : Choix de l’acheminement des envois. Valeurs :
- 0 (défaut) : le SMS est envoyé en direct avec les options de
base (GSM7, 48 heures attente réponses… les paramètres
peuvent être écrasés grâce au paramètre « options »)
- 1 : forçage SMS vocal, passage direct du SMS en vocal sans
envoi de SMS.
- […] : d’autres workflows peuvent être ajoutés en fonction
des besoins clients (par exemple envoi SMS, si échec envoi
sur SMS Vocal, si appel occupé, envoi sur télécopie etc…)
• […] : Options disponibles suivant cahier des charges client.
Non implémentées encore.
Return Type
Description
int
Référence de l’envoi
<soapenv:Body>
<soap:sendSMS>
<Phone>0601020304</Phone>
<SmsTxt>Bonjour, information par SMS.</SmsTxt>
<Options>
<Workflow>0</Workflow>
</Options>
</soap: sendSMS >
</soapenv:Body>
36
<S:Body>
<ns2:SendSMSResponse xmlns:ns2="http://soap.gedicom.com/">
</ns2: SendSMSResponse >
</S:Body>
Elément
Description
<return>
Identifiant unique pour cet envoi. Référence à rappeler lors de la scrutation des
statistiques (=> StatRef de la méthode suivante).
37
GetSMSStatus (*)
Obsolète. Remplacé dans la prochaine version par la méthode GetUStatus, plus générique et
complète.
Retourne le statut d’un SMS.
Parameters
Type
Description
StatRef
String
Référence de l’envoi.
Return Type
Description
int
Statut de l’envoi du SMS (voir annexe 1 pour plus de détails).
<soapenv:Body>
<soap:GetSMSStatus>
<StatRef>123456</StatRef>
</soap: GetSMSStatus >
</soapenv:Body>
<S:Body>
<ns2:GetSMSStatusResponse xmlns:ns2="http://soap.gedicom.com/">
<return>0</return>
</ns2:GetSMSStatusResponse>
</S:Body>
Elément
Description
<return>
Etat (statut) des SMS : cf. Annexe 1
38
GetUStatus (v1.5+)
Retourne les statuts d’un envoi unique. Attention, dû à la gestion des workflows plusieurs domaines
de statistiques peuvent être retournés.
Parameters
Type
Description
StatRef
String
Référence de l’envoi.
Return Type
Description
List<StatusDetails>
Liste sur chaque média utilisé énumérant le dernier état enregistré
sur le média concerné.
Attributes
String media;
String target;
int status;
String statusDate;
Methods
StatusDetails
each attribute.
Voir l’annexe 1 pour la signification des statuts
<soapenv:Body>
<soap:GetUStatus>
</soap: GetUStatus >
</soapenv:Body>
<S:Body>
<return>
<media>CALL</media>
<target>0123456789</target>
<status>51</status>
<statusDate>01/01/2014 12:35</statusDate>
</return>
</S:Body>
39
sendFastMailCampaign
Lance une campagne à partir d’un scénario.
Parameters
Type
Description
subject
String
Identifiant du scenario.
body
String
Corps du mail
options
MapWrapper MapWrapper contenant les options de campagne
Aucune option définie dans cette version.
addresses
String[]
Table des adresses mail des destinataires
Return Type
Description
int
Numéro de la campagne créée (-1 si erreur)
<soapenv:Body>
<ns2:sendFastMailCampaign xmlns:ns2="http://soap.gedicom.com/"
<subject>test d'envoi en webservice</subject>
<body><b>OK !</b> ça marche !</body>
<addresses>[email protected]</addresses>
<addresses>[email protected]</addresses>
</ns2:sendFastMailCampaign>
</soapenv:Body>
<S:Body>
<ns2:sendFastMailCampaignResponse xmlns:ns2="http://soap.gedicom.com/">
</ns2:sendFastMailCampaignResponse>
</S:Body>
40
Kit de développement JAVA :
Un kit de développement de l’API TéléAlerte est fourni à la demande. Il comporte les sources
nécessaires à la création d’un client java ainsi qu’un exemple d’utilisation.
Kit de développement PHP :
Un kit de développement PHP est fourni à la demande. L’outil utilisé pour la création du client
WebService est nusoap. Un exemple d’utilisation est également fourni dans un fichier sample.php.
Kit de développement C# :
Un document explicatif, guidant la génération d’une application cliente est téléchargeable sur notre
site.
Conclusion
Le web service de Gedicom est une solution simple, sécurisée et fonctionnelle qui facilite le
déclenchement des scénarios définis au préalable sur le site de TéléAlerte sur différents canaux
(téléphone, sms, email, fax, pager,…). Il permet aussi l’envoi « à la volée » d’un certain nombre de
média, notamment le SMS et le SMS Vocal. L’évolutivité de cet outil permet à Gedicom de fournir un
service qui correspond aux contraintes de l’ensemble des cahiers des charges pour les web services.
41
Annexe 1 : Statuts d’envoi
TOUS LES MEDIAS :
-1 : En attente forcée par le système Gedicom
0 : pris en compte
7 : Injoignable (mauvais numéro?)
TELEPHONE :
1 : Le numéro a décroché
2 : Le numéro est occupé
3 : Personne ne décroche
4 : Un répondeur détecté vraisemblablement
5 : Une nouvelle tentative d’appel est demandée
6 : Injoignable (6)
9 : L'abonné ne souhaite pas être rappelé
10 : Tentative d'appel échouée (10)
11 : Injoignable (11)
12 : Injoignable (12)
13 : Ecoute du message
20 : Le message est validé
50 : Validation, l'utilisateur tape '0'
…
60 : Validation, l'utilisateur tape '*'
61 : Validation, l'utilisateur tape '#'
FAX :
14 : Le fax n'est pas reçu
17 : Fax pris en compte par l'opérateur
21 : Le fax a été transmis
SMS :
15 : L'envoi SMS a échoué
18 : Sms pris en compte par l'opérateur
22 : SMS pris en compte par l'opérateur téléphonique
EMAIL :
16 : Erreur lors de l’envoi de l’email
23 : Email envoyé correctement
PAGER :
19 : L'envoi pager a échoué
24 : Message pager envoyé à l'opérateur
42
Annexe 2 : Scénario d’envoi d’un SMS Vocal (avec authentification)
LOGIN (SOAPSESSIONFACTORYSERVICE) :
Requête :
<soapenv:Header>
</wsu:Timestamp>
</wsse:Security>
</soapenv:Header>
<soapenv:Body>
<soap:Login>
<WebSite>APIDemo</WebSite>
</soap:Login>
</soapenv:Body>
</soapenv:Envelope>
Réponse :
<S:Header>
</wsu:Timestamp>
</wsse:Security>
</S:Header>
<S:Body>
<ns2:LoginResponse xmlns:ns2="http://soap.gedicom.com/"
<return>
<ns3:Address>https://www.acces-gedicom.com:443/GedWSServer/GedServer</ns3:Address>
<ns3:ReferenceParameters>
</ns3:ReferenceParameters>
<ns3:Metadata wsdli:wsdlLocation="http://soap.gedicom.com/ https://www.accesgedicom.com:443/GedWSServer/GedServer?wsdl" xmlns:wsdli="http://www.w3.org/ns/wsdl-instance">
<wsam:InterfaceName xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata"
xmlns:jaxws="http://jax-ws.dev.java.net/xml/ns/" xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:wsns="http://soap.gedicom.com/">wsns:GedServer</wsam:InterfaceName>
<wsam:ServiceName EndpointName="GedServerPort"
xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" xmlns:jaxws="http://jaxws.dev.java.net/xml/ns/" xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:wsns="http://soap.gedicom.com/">wsns:GedServerService</wsam:ServiceName>
</ns3:Metadata>
</return>
</ns2:LoginResponse>
</S:Body>
</S:Envelope>
A l’issu de la phase d’authentification on récupère l’identifiant de session : fe3cea34-d2fb-4802-8fcb3c041029bc20
43
ENVOI SMS VOCAL (GEDSERVERSERVICE) :
Requête :
<soapenv:Header>
<wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsu:Timestamp wsu:Id="TS-1">
</wsu:Timestamp>
</wsse:Security>
</soapenv:Header>
<soapenv:Body>
<soap:sendSMS>
<Phone>0601020304</Phone>
<SmsTxt>Bonjour, ceci est une information par SMS Vocal</SmsTxt>
<Options>
<Workflow>1</Workflow>
</Options>
</soap:sendSMS>
</soapenv:Body>
</soapenv:Envelope>
Réponse :
<S:Header>
…
</S:Header>
<S:Body>
<ns2:SendSMSResponse xmlns:ns2="http://soap.gedicom.com/">
</ns2: SendSMSResponse >
</S:Body>
</S:Envelope>
Le SMS Vocal a bien été envoyé. Pour suivre le status d’envoi, il suffit maintenant d’interroger la
méthode GetUStat en fournissant la référence d’envoi : 123456
INTERROGATION STATUT DE L’ENVOI (GEDSERVERSERVICE) :
Requête :
<soapenv:Header>
…
</soapenv:Header>
<soapenv:Body>
<soap:GetUStatus>
</soap:GetUStatus>
</soapenv:Body>
</soapenv:Envelope>
44
Réponse :
…
<S:Body>
<return>
<media>CALL</media>
<target>0601020304</target>
<status>51</status>
<statusDate>18/11/2013 07:58</statusDate>
</return>
</S:Body>
…
L’appel vocal a été reçu, écouté et validé (statut 51 = touche tappée « 1 »).
45

API Web Service TéléAlerte

Transcription

Documents pareils

offre d`emploi planet form

Ralisation d`un Extranet de l`Enseignement Suprieur et de la

Soapbox 2014

Déploiement d`un web service SOAP sur Tomcat

API Web Service TéléAlerte

rester moi-même - World Cancer Day

ANNEXE 6 Technique de rédaction : SOAP

body de maintien intégral

body attack