api http - SMS mode

fic he pro du it
Marketing et communication mobile
Développez une
api http
smsmode vous fournit des ApI pour l’envoi de sms
à intégrer dans vos applications. nos requêtes sms
http vous permettent d’automatiser l’envoi de vos
informations. Outre l’envoi diﬀéré, l’interface API pour les
sms oﬀre de nombreuses possibilités : personnalisation
de l’expéditeur, gestion des accusés de réception,
gestions des contacts...
Version 1.2 - Mise à jour : 3 juillet 2014
FONCTIONNEMENT
Quel est le principe de l’api http ?
Coûts
Frais de mise en place : aucun.
sms
Frais d’utilisation : le prix des sms
sms
sms
envoyés.
sms
Pré-Requis
Requêtes disponibles :
plateforme
sMsmode
• Envoi immédiat ou programmé
de sms (éco, pro, pro+, réponse)
• Récupération des compte-
application externe (cf documentation
• Solde du compte
• Transfert de crédits de
ci-après)
www
compte à compte
Applications
• Ajout de contact
• Suppression de sms
Intégration d’un module sms dans
• Historique des sms
• Notification automatique de
la modification des comptesrendus de réception
Acheter des crédits sms
Intégrer la requête http à votre
rendus de réception
• Création de sous-comptes
Ouvrir un compte sur sMsmode
votre
application
un progiciel de caisse
sms d’alerte automatique de serveur
“down” ou “up” ...
Développez une
api http
TABLE DES MATIÈRES
1. envoi de sms ............................................................................................................................................................................................ 1
URL de base .................................................................................................................................................................................... 1
Paramètres obligatoires........................................................................................................................................................... 1
Paramètres optionnels ............................................................................................................................................................. 2
Réponses ........................................................................................................................................................................................... 2
Caractères et encodage .......................................................................................................................................................... 2
2. Compte-rendu de réception ....................................................................................................................................................... 4
URL de base .................................................................................................................................................................................... 4
Paramètres obligatoires........................................................................................................................................................... 4
Réponses ........................................................................................................................................................................................... 4
3. Solde du compte ................................................................................................................................................................................... 5
URL de base .................................................................................................................................................................................... 5
Paramètres obligatoires........................................................................................................................................................... 5
Réponses ........................................................................................................................................................................................... 5
4. Création de sous-compte ............................................................................................................................................................. 6
URL de base .................................................................................................................................................................................... 6
Paramètres obligatoires........................................................................................................................................................... 6
Réponses ........................................................................................................................................................................................... 6
5. transfert de crédit de compte à compte......................................................................................................................... 7
URL de base .................................................................................................................................................................................... 7
Paramètres obligatoires........................................................................................................................................................... 7
Paramètres optionnels ............................................................................................................................................................. 7
Réponses ........................................................................................................................................................................................... 7
6. Ajout de contact .................................................................................................................................................................................... 8
URL de base .................................................................................................................................................................................... 8
Paramètres obligatoires........................................................................................................................................................... 8
Paramètres optionnels ............................................................................................................................................................. 8
Réponses ........................................................................................................................................................................................... 8
7. Suppression de sms .......................................................................................................................................................................... 9
URL de base .................................................................................................................................................................................... 9
Paramètres obligatoires........................................................................................................................................................... 9
Réponses ........................................................................................................................................................................................... 9
8. liste des sms envoyés .................................................................................................................................................................... 10
URL de base .................................................................................................................................................................................... 10
Paramètres obligatoires........................................................................................................................................................... 10
Paramètres optionnels ............................................................................................................................................................. 10
Réponses ........................................................................................................................................................................................... 10
9. récupération du statut du sms ............................................................................................................................................... 11
URL de base .................................................................................................................................................................................... 11
Paramètres obligatoires........................................................................................................................................................... 11
Réponses ........................................................................................................................................................................................... 11
10. Envoi de sms avec réponse autorisée et notification....................................................................................... 12
11. Notification de compte-rendu automatique .............................................................................................................. 13
Paramètres retournés par sMsmode ............................................................................................................................. 13
12. envoi de sms voix (ou sms vocal) ....................................................................................................................................... 14
URL de base .................................................................................................................................................................................... 14
Paramètres obligatoires........................................................................................................................................................... 14
Paramètres optionnels ............................................................................................................................................................. 14
Réponses ........................................................................................................................................................................................... 14
DOCUMENTATION
1. enVOI de SmS
L’interface HTTP permet d’automatiser l’envoi de sms vers un ou plusieurs destinataires.
Ces messages peuvent être envoyés immédiatement ou en programmé.
Bien que le mode HTTP soit supporté, il est fortement conseillé pour des raisons de sécurité
d’utiliser le mode HttpS.
Les méthodes HTTP GET et POST sont supportées, mais seule la méthode pOSt permet
l’envoi de sms à plus de 300 destinataires (en une seule requête).
ExEmplES
https://api.smsmode.com/http/1.6/sendSMS.do?pseudo=jean&pass=abcd1234&
message=Bonjour+Maman&numero=3363123456,0623123457
https://api.smsmode.com/http/1.6/sendSMS.do?pseudo=jean&pass=abcd1234&
message=Bon+anniversaire&numero=3363123456&date_envoi=21122005-14:35
URL de base
L’URL de base pour la requête http est la suivante : https://api.smsmode.com/http/1.6/sendSMS.do
L’URL de base a changé, mais l’ancienne URL https://www.sms.smsmode.com/fr/1.5/sendSMS.do reste
toujours valable.
Paramètres obligatoires
paramètre
description
pseudo
Identifiant de l’utilisateur.
pass
Mot de passe.
message
Message du sms à envoyer. Nombre maximal de caractères pour 1 sms =160. Pour un texte
avec plus de 160 caractères, se reporter aux paramètres optionnels ci-dessous.
numero (ou groupe)
Liste de numéros séparés par une virgule. Ces numéros peuvent être sous le format national
(0600000000) ou international (33600000000).
L’envoi par méthode HTTP GET limite le nombre de destinataires à 300, la méthode POST n’a
pas cette limitation.
groupe (ou numero)
Nom du groupe contenant les numéros destinataires, préalablement créé sur le compte sMsmode.
1
Développez une
api http
Paramètres optionnels
paramètre
classe_msg
description
• 2 : sms pro, par défaut 2
• 4 : sms avec réponse autorisée (+0,2 crédit)
• 5 : sms éco (0,54 crédit/sms, seulement en France Métropolitaine)
date_envoi
Date d’envoi du message - format : ddmmyyyy-hh:mm.
compteRendu
La valeur “true” permet d’obtenir le(s) compte(s)-rendu(s) de réception du sms par destinataire.
Le sms éco ne peut avoir de compte-rendu de réception.
refClient
Donnée client optionnelle renvoyée lors de la notification automatique de compte-rendu. Cette
donnée peut être utilisée pour “taguer” la requête avec votre propre identifiant.
emetteur
Emetteur du sms envoyé si le compte contient plusieurs émetteurs. Maximum 11 caractères,
pas d’accent ni d’espace. Fonctionnalité uniquement disponible pour le sms pro (le sms éco ne
peut avoir d’émetteur personnalisé).
nbr_msg
Nombre maximum de message (valeur par défaut 5). Le message sera coupé s’il dépasse cette
limite. Selon le nombre de caractères souhaités, indiquez le nombre de messages à envoyer
comme suit :
• de 0 à 160 caractères => nbr_msg=1
• de 161 à 306 caractères => nbr_msg=2
• de 307 à 459 caractères => nbr_msg=3
notification_url
URL sur laquelle vous souhaitez recevoir la notification de compte-rendu du sms (se référer au
paragraphe 12).
Réponses
La réponse à une requête d’envoi http est de la forme : code_retour | description | smsID (présent si code retour 0).
Code retour
description
0
Accepté - le message a été accepté par le système et est en cours de traitement.
31
Erreur interne.
32
Erreur d’authentification.
33
Crédits insuffisants.
35
Un paramètre obligatoire est manquant.
50
Temporairement inaccessible.
Caractères et encodage
Seul un certain nombre de caractères sont gérés pour l’envoi de sms (spécifications GSM 03.38), si vous spécifiez un
caractère qui n’est pas présent dans la liste, celui ci sera remplacé par “?”. L’encodage utilisé est celui de la norme
ISO-8859-15. Voici la liste des caractères acceptés et leur correspondance :
2
Caractère
Code
ISO-8859-15
Code
ASCII
Nouvelle
ligne
%0A
10
Retour
chariot
%0D
13
Espace
+
32
!
%21
33
“
%22
34
#
%23
35
$
%24
36
%
%25
37
&
%26
38
‘
%27
39
(
%28
40
)
%29
41
*
*
42
+
%2B
43
,
%2C
44
-
-
45
.
.
46
/
%2F
47
0
0
48
1
1
49
2
2
50
3
3
51
4
4
52
5
5
53
6
6
54
7
7
55
8
8
56
9
9
57
:
%3A
59
<
%3C
60
=
%3D
61
>
%3E
62
?
%3F
63
@
%40
64
A
A
65
B
B
66
C
C
67
D
D
68
E
E
69
Caractère
Code
ISO-8859-15
Code
ASCII
Caractère
Code
ISO-8859-15
Code
ASCII
F
F
70
s
s
115
G
G
71
t
t
116
H
H
72
u
u
117
I
I
73
v
v
118
J
J
74
w
w
119
K
K
75
x
x
120
L
L
76
y
y
121
M
M
77
z
z
122
N
N
78
¡
%A1
161
O
O
79
£
%A3
163
P
P
80
€
%A4
164
Q
Q
81
¥
%A5
165
R
R
82
§
%A7
167
S
S
83
¿
%BF
191
T
T
84
Ä
%C4
196
U
U
85
Å
%C5
197
V
V
86
Æ
%C6
198
W
W
87
Ç
%C7
199
X
X
88
È
%C8
200
Y
Y
89
É
%C9
201
Z
Z
90
Ñ
%D1
209
_
_
95
Ö
%D6
214
a
a
97
Ø
%D8
216
b
b
98
Ü
%DC
220
c
c
99
ß
%DF
223
d
d
100
à
%E0
224
e
e
101
ä
%E4
228
f
f
102
å
%E5
229
g
g
103
æ
%E6
230
h
h
104
è
%E8
232
i
i
105
é
%E9
233
j
j
106
ì
%EC
236
k
k
107
ñ
%F1
241
l
l
108
ò
%F2
242
m
m
109
ö
%F6
246
n
n
110
ø
%F8
248
o
o
111
ù
%F9
249
p
p
112
Ü
%FC
252
q
q
113
r
r
114
3
Développez une
api http
2. COmpte-rendu de réCeptIOn
L’interface HTTP permet de récupérer l’état des comptes-rendus de réception d’un sms
(pas pour le sms éco). Pour cela il faut que le compte-rendu ait été demandé lors de l’envoi
du sms (paramètre compteRendu=true).
Limite de la recherche : les sms doivent avoir été envoyés dans les 30 derniers jours par
rapport à la date du jour.
ExEmplE
https://api.smsmode.com/http/1.6/compteRendu.do?pseudo=jean&pass=abcd1234&
smsID=12345678
URL de base
L’URL de base pour la requête http est la suivante : https://api.smsmode.com/http/1.6/compteRendu.do
Paramètres obligatoires
paramètre
description
pseudo
Identifiant de l’utilisateur.
pass
Mot de passe.
smsID
Numéro identifiant le sms dont on souhaite connaître le ou les comptes-rendus de réception.
Ce numéro est contenu dans la réponse du serveur lors d’un envoi de sms par l’interface HTTP.
Réponses
La réponse à une requête d’envoi http est de la forme : numéro_destinataire statut | numéro_destinataire statut | ...
ExEmplE
33600000000 11 | 33611111111 13 : dans cet exemple le sms a été reçu par le numéro 0600000000 et a été
délivré à l’opérateur pour le numéro 0611111111 (cas d’un téléphone éteint ou hors réseau).
Code retour
4
description
0
SMS envoyé.
2
Erreur interne lors de l’envoi du SMS.
11
Reçu : le sms a été reçu par le téléphone portable.
13
Délivré opérateur : le sms a été délivré à l’opérateur dont dépend votre destinataire.
31
Erreur interne lors de la requête.
34
Erreur routage : le réseau destinataire n’a pas été reconnu.
35
Erreur réception : l’opérateur n’a pas réussi à délivrer le sms sur le téléphone destinataire.
61
Le SMS n’existe pas ou plus.
3. Solde du compte
L’interface http permet d’obtenir le solde de votre compte sms, c’est-à-dire le nombre de
crédits sms restants. Pour cela, il faut envoyer la requête http GET suivante : https://api.
smsmode.com/http/1.6/credit.do?pseudo=jean&pass=abcd1234
URL de base
L’URL de base pour la requête http est la suivante : https://api.smsmode.com/http/1.6/credit.do
Paramètres obligatoires
Paramètre
Description
pseudo
Identifiant de l’utilisateur.
pass
Mot de passe.
Réponses
La réponse à une requête d’envoi http est un simple chiffre correspondant au solde du compte :
Exemple
212.5
5
Développez une
api http
4. CréAtIOn de SOuS-COmpte
L’interface http permet de créer des sous-comptes à partir d’un compte existant, il suffit de
spécifier les nouveaux identifiants et mot de passe.
ExEmplE
https://api.smsmode.com/http/1.6/createSubAccountdo?pseudo=aaaaaa&pass=
xxxxxxx&newPseudo=bbbbbb&newPass=yyyyyy
URL de base
L’URL de base pour la requête http est la suivante : https://api.smsmode.com/http/1.6/createSubAccount.do
Paramètres obligatoires
paramètre
description
pseudo
Identifiant de l’utilisateur.
pass
Mot de passe.
newPseudo
Identifiant du sous-compte à créer.
newPass
Mot de passe du sous-compte à créer.
Réponses
Statut
6
description
0
Création effectuée
31
Erreur interne.
32
Erreur d’authentification.
35
Paramètres incorrects.
41
Identifiant déjà existant.
5. Transfert de crédit de compte à compte
L’interface http permet de transférer une somme de crédits sms d’un compte vers un autre.
Exemple
https://api.smsmode.com/http/1.6/creditTransfert.do?pseudo=aaaaaa&pass=xxxxxx&
targetPseudo=bbbbb&creditAmount=12&reference=blablabla
URL de base
L’URL de base pour la requête http est la suivante : https://api.smsmode.com/http/1.6/creditTransfert.do
Paramètres obligatoires
Paramètre
Description
pseudo
Identifiant de l’utilisateur.
pass
Mot de passe.
targetPseudo
Identifiant du compte vers lequel on veut transférer les crédits sms.
creditAmount
Nombre de crédits sms à transférer.
Paramètres optionnels
Paramètre
reference
Description
Référence de la transaction.
Réponses
Statut
Description
0
Transfert effectué.
31
Erreur interne.
32
Erreur d’authentification.
33
Crédits insuffisants.
35
Paramètres incorrects.
40
Identifiant inexistant.
7
Développez une
api http
6. AJOut de COntACt
L’interface HTTP permet d’automatiser l’ajout d’un contact au carnet d’adresse. Elle permet
aussi de créer un groupe de contacts si celui spécifié n’existe pas.
ExEmplE
https://api.smsmode.com/http/1.6/addContact.do?pseudo=pseudo&pass=pass
&nom=Dupond&prenom=jacques&mobile=06xxxxxxxxxx&groupes=Groupe1,Groupe2
URL de base
L’URL de base pour la requête http est la suivante : https://api.smsmode.com/http/1.6/addContact.do
Paramètres obligatoires
paramètre
description
pseudo
Identifiant de l’utilisateur.
pass
Mot de passe.
nom
Nom du contact à ajouter.
mobile
Numéro de téléphone du contact.
Paramètres optionnels
paramètre
description
prenom
Prénom du contact.
groupes
Liste du ou des groupes auxquels le contact appartient. Si un groupe n’existe pas, il est créé automatiquement.
Réponses
La réponse à une requête d’envoi http est de la forme : code_retour | description
Code retour
8
description
0
Contact ajouté
31
Erreur interne.
7. Suppression de SMS
L’interface HTTP permet de supprimer un sms enregistré (programmé ou non).
Exemple
https://api.smsmode.com/http/1.6/deleteSMS.do?pseudo=aaaaaa&pass=xxxxxx&
smsID=06000000
URL de base
L’URL de base pour la requête HTTP est la suivante : https://api.smsmode.com/http/1.6/deleteSMS.do
Paramètres obligatoires
Paramètre
Description
pseudo
Identifiant de l’utilisateur.
pass
Mot de passe.
smsID (ou numero)
Identifiant du sms à supprimer, cet identifiant est retourné par le système lors de l’utilisation de
la requête d’envoi de sms.
numero (ou smsID)
Un des numéros de portable présent dans les destinataires du sms à supprimer. Seul le sms le
plus récent correspondant à ce critère sera supprimé.
Réponses
Statut
Description
0
Sms supprimé.
31
Erreur interne.
32
Erreur d’authentification.
35
Paramètre(s) incorrect(s) : “pseudo”, “pass”, “numero” ou “smsID” sont obligatoires.
61
Sms non trouvé.
9
Développez une
api http
8. lISte deS SmS enVOYéS
L’interface HTTP permet de visualiser la liste des sms envoyés.
ExEmplE
https://api.smsmode.com/http/1.6/smsList.do?pseudo=aaaaaa&pass=xxxxxx&oﬀset=20
URL de base
L’URL de base pour la requête http est la suivante : https://api.smsmode.com/http/1.6/smsList.do
Paramètres obligatoires
paramètre
description
pseudo
Identifiant de l’utilisateur.
pass
Mot de passe.
Paramètres optionnels
paramètre
offset
description
Nombre de sms à visualiser, 50 derniers par défaut.
Réponses
La réponse à la requête http est de la forme : ssmsId | date_envoi | texte_sms | téléphone_destinataire | coût_en_
crédit | nbre_de_destinataires |
paramètre
10
description
31
Erreur interne.
32
Erreur d’authentification.
35
Paramètre(s) incorrect(s) : “pseudo” et “pass” sont obligatoires.
9. Récupération du statut du SMS
L’interface http permet de récupérer le statut d’un sms (envoyé, programmé, en erreur, etc.).
Limite de la recherche : les sms doivent avoir été enregistrés dans les 30 derniers jours par
rapport à la date du jour.
Exemple
https://api.smsmode.com/http/1.6/smsStatus do?pseudo=jean&pass=abcd1234&smsID=12345678
URL de base
L’URL de base pour la requête http est la suivante : https://api.smsmode.com/http/1.6/smsStatus.do
Paramètres obligatoires
Paramètre
Description
pseudo
Identifiant de l’utilisateur.
pass
Mot de passe.
smsID
Numéro identifiant le sms dont on souhaite connaître le ou les comptes-rendus de réception.
Ce numéro est contenu dans la réponse du serveur lors d’un envoi de sms par l’interface HTTP.
Réponses
La réponse à une requête d’envoi Http est de la forme : statut | description
Exemple
0 | Envoyé
Statut
Description
0
Envoyé.
2
Non envoyé – erreur interne.
10
Envoi programmé.
11
Reçu (seulement si compte-rendu a été sélectionné, sinon “Envoyé”).
14
Délivré (seulement si compte-rendu a été sélectionné, sinon “Envoyé”).
32
Votre authentification a échoué (“pseudo” et/ou “mot de passe” inexistants).
35
Paramètre(s) incorrect(s) : “pseudo”, “pass”, “smsID” sont obligatoires.
39
Erreur réception (seulement si compte-rendu a été sélectionné, sinon” Envoyé”).
11
Développez une
api http
10. enVOI de SmS AVeC répOnSe
AutOrISée et nOtIfICAtIOn
L’interface http permet d’envoyer un sms auquel le destinataire peut répondre. Il faut
rajouter un paramètre dans la requête d’envoi (cf paragraphe 1). L’entête du sms est
un numéro auquel le destinataire peut répondre. Les réponses sont enregistrées sur
le compte sMsmode depuis lequel est envoyé le sms réponse. Elles sont visualisables
dans le menu “mes sms” sur l’interface graphique smsMode.com, soit en cliquant sur
“réponses reçues”, soit en cliquant sur le détail du sms origine. Si vous souhaitez recevoir
une requête http GET vous notifiant de la réponse, il vous faut entrer le paramètre “url
notification réception SMS” dans le menu “mes données personnelles >> développeurs”.
Dans ce cas dès qu’une réponse est reçue par la plateforme, une notification vous est
envoyée avec les paramètres suivants :
paramètre
12
description
numero
Numéro smsMode ayant traité la réponse, à ne pas confondre avec “emetteur”.
message
Texte du SMS encodé en UTF-8.
Emetteur
Numéro de la personne ayant répondu.
date_reception
Date de réception du compte-rendu au format ddmmyyyy-hhmmss.
smsID
Référence du sms initial.
refClient
Ce paramètre est envoyé s’il est présent dans la requête initiale d’envoi de sms.
11. Notification de compte-rendu
automatique
L’interface http permet de recevoir une notification lorsque le statut du compte-rendu de
réception change (par exemple de “délivré opérateur” à “reçu”). Vous devez ajouter les
paramètres “notification_url” et “compteRendu” à “true”, lors de la requête d’envoi de sms.
Exemple
https://api.smsmode.com/http/1.6/sendSMS.do?pseudo=xxxx&pass=xxxxx&message=
Bonjour+test&numero=336xxyyzzaa&compteRendu=true&notification_url=http://www.
votreURLdeNotificationdeCR.com/compteRenduNotification.php&refClient=12azer34
Paramètres retournés par sMsmode
Paramètre
Description
numero
Numéro destinataire du SMS sous la forme internationale : ex. 336xxyyzzaa.
date_reception
Date de réception du compte-rendu au format yyyy-mm-dd hh:mm:ss
statut
• 11 Reçu
• 13 Délivré opérateur
• 33 Non envoyé - crédit insuffisant
• 34 Erreur routage
• 35 Erreur réception
smsID
SMS ID initialement retourné par le serveur.
refClient
Ce paramètre est envoyé s’il est présent dans la requête initiale d’envoi de sms.
Exemple
http://www.votreURLdeNotificationdeCR.com/compteRenduNotification.php?numero=336xxyyzzaa
&date_reception=2010-03-25+09%3A52%3A17&statut=11&smsID=S7EpYZ5kmS87&refClient=12azer34
13
Développez une
api http
12. enVOI de SmS VOIX (Ou SmS VOCAl)
L’interface http permet d’automatiser l’envoi de sms “voix”. Un sms voix est un sms transformé en
appel, c’est-à-dire que le destinataire écoute le sms au lieu de le lire. Il peut être envoyé immédiatement
ou programmé. Le texte doit être rédigé phonétiquement pour une meilleure traduction du message
(il est préférable d’effectuer un test unitaire au préalable pour s’assurer de la compréhension du texte).
ExEmplE
https://api.smsmode.com/http/1.6/sendVoiceMessage.do?pseudo=jean&pass=abcd1234
&message=Bonjour+Maman&numero=3363123456&title=ceci+est+le+titre
URL de base
L’URL de base pour la requête http est la suivante : https://api.smsmode.com/http/1.6/sendVoiceMessage.do
Paramètres obligatoires
paramètre
description
pseudo
Identifiant de l’utilisateur.
pass
Mot de passe.
message
Message du sms à envoyer. Nombre maximal de caractères pour 1 sms =160.
numero
Liste de numéros séparés par une virgule. Ces numéros peuvent être sous le format national
(0600000000) ou international (33600000000). L’envoi par méthode HTTP GET limite le nombre
de destinataires à 300, la méthode POST n’a pas cette limitation.
Paramètres optionnels
paramètre
description
title
Titre lu au début du sms vocal, par exemple : ‘Message de la société xx’ (par défaut ‘Ceci est un message de sMsmode’).
date_envoi
Date d’envoi du message - format : ddmmyyyy-hh:mm.
Réponses
La réponse à une requête d’envoi http est de la forme : code_retour | description | smsID (présent si code retour 0)
Code retour
description
0
Accepté - le message a été accepté par le système et est en cours de traitement.
31
Erreur interne.
32
Erreur d’authentification.
33
Crédits insuffisants.
35
Un paramètre obligatoire est manquant.
50
Temporairement inaccessible.
Pour l’encodage du texte se reporter à la grille d’encodage du chapitre 1.
14
Marketing et communication mobile
une marque Calade Technologies
Technopôle de Château Gombert - BP100 13382 Marseille Cedex 13
Tél. : 04 91 05 64 61 - Fax : 04 91 05 50 51
Mèl : [email protected]
www.smsmode.com

Download Report