Accès HTTP/HTTPS Description Nom du fichier DS-Description-Accès HTTP-HTTPS Version 1.1 Date de modification 30.08.2017 L'auteur du document info@dolphin.ch Classification public DOLPHIN Systems AG Samstagernstrasse 45 8832 Wollerau Suisse www.dolphin.ch www.ecall.ch
Contenu 1. INTRODUCTION... 1 2. EXIGENCES... 2 3. PROTOCOLE... 2 4. FORMATS DES MESSAGES... 2 4.1 ORDRE DE TRANSMISSION DES MESSAGES TEXTE... 3 4.2 ORDRE DE TRANSMISSION POUR LES MESSAGES FAX... 6 4.3 DEMANDE DE TRANSMISSION DE MESSAGES VOCAUX... 8 4.4 MESSAGE DE RESULTAT... 9 4.5 MEMOIRE TAMPON... 10 4.5.1 RECHERCHE DE NOUVEAUX MESSAGES.... 10 4.5.2 SUPPRIMER DES MESSAGES DE LA MEMOIRE TAMPON... 12 4.6 REPONSE SMS... 13 4.7 MESSAGE DE NOTIFICATION... 14 5. CODES D ERREUR... 16 6. CONNEXIONS... 17 6.1 ADRESSES D ACCES POUR LES ORDRES DE TRANSMISSION... 17 6.2 ADRESSE IP DES REPONSES OU ENTREES (ECALL -> CLIENT)... 17 7. IDENTIFICATION... 18 8. TEST DE L ACCES... 18 ANNEXE JEU DE CARACTERES POUR LES SMS... 19 DS-Description-Accès HTTP-HTTPS I
1. Introduction Ce document décrit l accès HTTP/HTTPS d ecall. L accès HTTP d ecall vous permet d appeler une URL directement pour envoyer des messages à différents systèmes d appel. Il y a aussi l option d accès HTTPS. L avantage est que les données peuvent être transférées sous forme cryptée. Dans ce qui suit, nous ne parlerons que de l accès HTTP. Sauf indication expresse, les mêmes instructions s appliquent à l accès HTTPS. Structure du document : Exigences Protocole Formats des messages Codes d erreur Connexion Identification Test de l accès DS-Description-Accès HTTP-HTTPS 1
2. Exigences Les conditions préalables suivantes doivent être remplies avant que vous puissiez envoyer des messages via l interface HTTP : Vous devez avoir un compte Business avec ecall. L accès par URL doit être configuré sur votre compte Business. Votre logiciel doit pouvoir appeler une URL pour envoyer des messages. 3. Protocole La transmission d un ordre de transmission à ecall est traitée en quatre étapes au maximum : 1. Le client envoie l ordre de transmission à ecall. 2. ecall envoie un message de résultat au client. 3. ecall enverra une notification au donneur d ordre si cela est souhaité (par ex. Actuellement pas possible via un appel URL ; voir une autre interface). 4. ecall renvoie une réponse d un récepteur de téléphone portable si cela est souhaité (par ex. (Actuellement impossible via un appel URL ; voir autre interface). 4. Formats des messages Tous les messages se composent d un mot d ordre et d une liste de paramètres. Les éléments individuels du message sont séparés par le signe «&». L identifiant du paramètre et la valeur sont séparés par un signe égal. L ordre est complété par CR LF. Les Identifiants des paramètres sont insensibles à la casse, c.-à-d. Ils ne sont pas sensibles à la casse. Les caractères spéciaux dans les chaînes de caractères doivent être spécifiés par la notification hexadécimale habituelle (par exemple %20 est espace, etc.). Format général ECALLURL.ASP?WCI=Interface&[Function]=[Kommando]&[Parameter 1]=[Parameter 1 Value]&[Parameter 2]=[Parameter 2 Value] DS-Description-Accès HTTP-HTTPS 2
4.1 Ordre de transmission des messages texte Ordre SendPage Ordre pour un message texte. Paramètre obligatoire Address Numéro de pager ou numéro de téléphone mobile complet (format international), ou plusieurs numéros séparés par un point-virgule, ou le nom d une personne ou d un groupe défini dans le carnet d adresses du compte ecall. Message Le texte qui doit apparaître sur le pager/téléphone mobile ne doit pas contenir «&» ou «=». CrLfs doivent être remplacés par les caractères <CR> et <LF>. AccountName Nom du compte Business ecall. AccountPassword Mot de passe du compte Business ecall. Paramètres optionnels JobID Identification univoque du message. Fonctions avancées CallBack Numéro de rappel valable uniquement pour les téléphones portables, jusqu à 16 chiffres ou jusqu à 11 caractères alphanumériques possibles. Vous ne pouvez pas utiliser un numéro SMS ecall comme numéro de rappel! Answer Les adresses de réception peuvent être définies ici pour le transfert d une réponse SMS. Les valeurs possibles sont : (voir paramètre Notification) Un exemple de message est décrit au point 4.6. Remarque : Si le paramètre «Answer» est envoyé, la valeur «CallBack» est ignorée. DS-Description-Accès HTTP-HTTPS 3
Notification Les adresses de réception peuvent être définies ici pour le transfert d un statut d envoi. Les valeurs possibles sont : - Par SMS vers un numéro de téléphone portable (par ex.. : «0041791234567») - Par e-mail à l adresse e-mail (ex. : «hans.muster@mycompany.ch») - Via socket vers IP/port (par ex. : «193.93.208.151/12345») - Via appel HTTP(S) (par ex. : http:/www.mycompany.ch/notifcations.asp») - Inscrire uniquement dans le journal de bord (par ex. «...») entrée vide. Les valeurs peuvent également être combinées en séparant les valeurs individuelles par un point-virgule «;» par ex. «0041791234567;0041781234567;hans.muster@mycompany.ch» Un exemple de message est décrit au point 4.7. Attention : Plage de validité des ports pour la notification (ou AlwaysNotification) jusqu à 32767. AlwaysNotification Adresse de réception pour la notification dès que le statut du message (pager ou téléphone portable) a changé. Remarque : Si le paramètre «AlwaysNotification» est transmis, le paramètre «Notification» est superflu. SendDate Détermine l heure de transmission de la tâche si elle doit être envoyée avec un délai (aaaaa-mm-jjj hh:mm:ss). MsgType Possibilité de soumettre un type de message spécifique. Les types définis sont : Flash -> Flash SMS Flash PrioSMS+ -> PrioSMS+ NoLog Lorsque ce paramètre est passé, ce message n est pas écrit dans le journal de bord. DS-Description-Accès HTTP-HTTPS 4
Exemples ECALLURL.ASP?WCI=Interface&Function=SendPage&Address=+41791112233&Message=Hello World&AccountName=xxx&AccountPassword=yyy ECALLURL.ASP?WCI=Interface&Function=SendPage&Address=+41791112233&Message=Hello World&AccountName=xxx&AccountPassword=yyy&AllwaysNotification=name@domain.ch&Answer=na me@domain.ch ECALLURL.ASP?WCI=Interface&Function=SendPage&Address=+41791112233&Message=Hello World&AccountName=xxx&AccountPassword=yyy&CallBack=+41791234567&Notification=192.168.0.5 6/15300&SendDate=2004-12-20%2020:31:50&JobID=123AB ECALLURL.ASP?WCI=Interface&Function=SendPage&Address=+41791112233&Message=Hello World&AccountName=xxx&AccountPassword=yyy&MsgType=Flash&NoLog=1 Remarque : Le contenu d une notification ou d une réponse à un téléphone portable, un pager ou une adresse e-mail est limité au statut de la notification ou de la réponse du destinataire. Le JobID est une exception, si ce paramètre a été utilisé, car il est inséré à la fin du texte de l e-mail. DS-Description-Accès HTTP-HTTPS 5
4.2 Ordre de transmission pour les messages fax Ordre SendFax Ordre pour un message fax. Paramètre obligatoire Address Numéro de fax complet (format ), ou plusieurs numéros, séparés par un pointvirgule, ou le nom d une personne ou d un groupe défini dans le carnet d adresses du compte ecall. Message être remplacés par les Texte du message fax, ne doit pas contenir «&» ou «=». Les CrLfs doivent caractères <CR> et <LF>. AccountName Nom du compte Business ecall. AccountPassword Mot de passe du compte Business ecall. Paramètres optionnels Job ID E Identification univoque du message. Fonctions avancées CallingNumber Numéro de l expéditeur. Subject Titre du message. FaxHeaderID En-tête de télécopieur Expéditeur. FaxHeaderID Info d en-tête de fax. SendDate Détermine le temps de transmission de l ordre s il doit être envoyé en différé (yyyy-mm-dd hh:mm:ss). MaxRetries Nombre de tentatives de rappel. RetestsTimeIntervalInMinMin. Temps entre les tentatives de rappel. NoCoversheet Pas utiliser de page de garde DS-Description-Accès HTTP-HTTPS 6
Exemples ECALLURL.ASP?WCI=Interface&Function=SendFax&Address=+41447873071&Message=Testmitteilu ng&accountname=xxx&accountpassword=yyy ECALLURL.ASP?WCI=Interface&Function=SendFax&Address=+41447873071&Subject=Test&Messag e=testmitteilung&accountname=xxx&accountpassword=yyy&fromtext=+41431234576&senddate=2 009-12-20%2020:50&JobID=123AB DS-Description-Accès HTTP-HTTPS 7
4.3 Demande de transmission de messages vocaux Ordre SendVoice Ordre pour un message vocal. Paramètre obligatoire Address Numéro complet (format international). Message Texte du message vocal, ne doit pas contenir d onglets. CrLfs doivent être remplacés par les caractères <CR> et <LF>. AccountName Nom du compte Business ecall. AccountPassword Mot de passe du compte Business ecall. Paramètres optionnels JobID Identification univoque du message. Fonctions avancées Langue des messages Détermine la langue dans laquelle le texte est lu. Les paramètres des langues sont les suivants : Allemand=DE, Français=FR, Italien=IT, Anglais=FR, Anglais=EN Par défaut : La langue est reconnue automatiquement. FromText SendDate Contient le nom du donneur d ordre qui est lu avant le message. Détermine le temps de transmission de l ordre s il doit être envoyé en différé (yyyy-mm-dd hh:mm:ss). Exemple ECALLURL.ASP?WCI=Interface&Function=SendVoice&Address=+41447873070&Message=Testmitteil ung&accountname=xxx&accountpassword=yyy ECALLURL.ASP?WCI=Interface&Function=SendVoice&Address=+41447873070&FromText=Hans%20 Muster&Message=Testmitteilung&AccountName=xxx&AccountPassword=yyy&MessageLanguage=FR &SendDate=2009-12-20%2020:50&JobID=123AB DS-Description-Accès HTTP-HTTPS 8
4.4 Message de résultat Ordre ResultPage Ordre pour un message de résultat. Paramètre obligatoire ResultCode Code du résultat (selon le paragraphe Codes d erreur). ResultText Résultat en texte clair (selon le paragraphe «Codes d erreur»). Exemple ResultPage ResultCode:0 ResultText: Veuillez noter que le message de résultat indique uniquement si l ordre de transmission a été accepté par ecall. Il n indique pas si l ordre a été transmis avec succès au centre d appels approprié ou même au destinataire. Pour ce faire, ecall fournit d autres mécanismes via d autres interfaces. DS-Description-Accès HTTP-HTTPS 9
4.5 Mémoire tampon Pour les ordres GetNextMessage et DeleteMessage, le cache du site web doit être activé. Dans le cas contraire, les messages reçus ne sont pas enregistrés dans la mémoire et ne peuvent pas y être inclus par la suite. La mémoire peut être réglée sous «Réception SMS» «3. Transférer les SMS reçus (facultatif)» comme transfert. 4.5.1 Recherche de nouveaux messages. Cet ordre lit le message le plus ancien reçu dans le numéro SMS privé. En outre, un numéro d identification unique est fourni, qui est à nouveau utilisé pour la suppression de la mémoire tampon. En option, le numéro de téléphone mobile loué peut être spécifié. Si tel est le cas, le message le plus ancien qui est arrivé à ce numéro est renvoyé. Si l option «MobileNumber» est manquante, le message le plus ancien de tous les numéros loués de ce compte est renvoyé. Ordre GetNextMessage Ordre pour le message suivant en mémoire. Paramètre obligatoire AccountName Nom du compte Business ecall. AccountPassword Mot de passe du compte Business ecall. Paramètres optionnels MobileNumber Numéro de portable loué au format international Exemple ECALLURL.ASP?WCI=Interface&Function=GetNextMessage&AccountName=xxx&AccountPassword=y yy ECALLURL.ASP?WCI=Interface&Function=GetNextMessage&AccountName=xxx&AccountPassword=y yy&mobilenumber=+41763331111 DS-Description-Accès HTTP-HTTPS 10
Réponse pour GetNextMessage Les structures de réponse ne sont plus basées sur leur propre protocole ecall, mais sur une structure XML. Par exemple, s il n y a pas de message dans la mémoire, le statut 11204 est renvoyé comme résultat («aucun nouveau message reçu») et le nœud SMS n est PAS affiché. Structure (sans contenu). <IncomingSMS> <Result> <ResultCode></ResultCode> <ResultText></ResultText> </Result> <MessageID></MessageID> <SMS> <Message></Message> <AddressTo></AddressTo> <AddressFrom></AddressFrom> <TimeStamp></TimeStamp> </SMS> </IncomingSMS> (selon le paragraphe Codes d erreur) (selon le paragraphe Codes d erreur) (-> Supprimer le message) (Format internat.) (Format internat.) (Format: dd.mm.yyyy hh:mm:ss) DS-Description-Accès HTTP-HTTPS 11
4.5.2 Supprimer des messages de la mémoire tampon Cet ordre supprime le message du cache, mais pas du compte. Le message est toujours visible sur le site web sous «Messages reçus». Ordre DeleteMessage Ordre pour un message texte. Paramètre obligatoire AccountName Nom du compte Business ecall. AccountPassword MessageID Mot de passe du compte Business ecall. ID de message défini par ecall (inclus dans la réponse à l appel GetNextMessage) Exemple ECALLURL.ASP?WCI=Interface&Function=DeleteMessage&AccountName=xxx&AccountPassword=yy y&messageid=zzz Réponse pour DeleteMessage Cette structure de réponse décrit si un message a pu être supprimé avec succès de la mémoire temporaire. Voilà à quoi ça ressemble : Structure (sans contenu). ddeletemsg>ddeletemsg <Result> <ResultCode></ResultCode>ResultCode>. <ResultText></ResultText> </Result> </DeleteMsg> DS-Description-Accès HTTP-HTTPS 12
4.6 Réponse SMS Ordre Réponse Ordre pour un message de réponse. Paramètre obligatoire AdressTo Numéro du destinataire AdressFrom Numéro de l expéditeur Message Contenu de la réponse TimeStamp Temps de la réception (dd.mm.yyyy hh:mm:ss). Paramètres optionnels JobID Contient l identification unique du message s il a été inclus dans la demande d envoi. Confirmation de lecture OK<ETX> Pour que nous puissions marquer l accusé de réception comme «transmis», vous devez répondre à la réception du message avec OK<ETX>. Après cela, la connexion sera coupée. Exemple http:/www.mycompany.ch/answers.asp?function=answer&addressto=0041766012999&addressfrom =0041791234567&Message=Meine+Anwort&TimeStamp=11%2E12%2E2015+10%3A37%3A00 DS-Description-Accès HTTP-HTTPS 13
4.7 Message de notification Ordre Notification Ordre d un message de notification. Paramètre obligatoire ResultCode Code d état du message (selon le tableau de notification). ResultText Number TimeStamp Statut en texte clair (selon le tableau de notification). Contient le numéro de destinataire de cet avis. Contient l heure de réception du message envoyé (dd.mm.yyyyyyyy hh:mm:ss). Paramètres optionnels JobID Contient l identification unique du message s il a été inclus dans la demande d envoi. Confirmation de lecture OK<ETX> Pour que nous puissions marquer l accusé de réception comme «transmis», vous devez répondre à la réception du message avec OK<ETX>. Après cela, la connexion sera coupée. Exemple http:/www.mycompany.ch/notifcations.asp?function=notification&resultcode=0&resulttext=message +has+been+delivered×tamp=1z%2e07%2e2014+12%3a55%3a15&number=0041787557539& JobID:FB551638-A320-476F-A47D-F2EE68 DS-Description-Accès HTTP-HTTPS 14
Tableau de notification ResultCode ResultText Description 0 Message has been delivered La réception du message transmis a été confirmée par le destinataire. 1 Message has been buffered La réception du message transmis n a pas encore pu être confirmée. 2 Message has not been delivered La réception du message transmis n a pas pu être confirmée. 3 Error Code / Error Message Détermine l erreur pendant le transfert vers le centre de contrôle correspondant. 4 Transmission OK L ordre de transmission pourrait être transmis à la centrale correspondante. DS-Description-Accès HTTP-HTTPS 15
5. Codes d erreur ErrorCode ErrorText Description 11000 SyntaxError SyntaxError 11001 PermissionDenied Accès refusé 11100 AdrAdCInvalid Adresse du destinataire invalide ou incorrecte 11101 AdrNAdInvalid Adresse de confirmation invalide ou incorrecte 11102 AdrAdCMissing Pas d adresse de destinataire disponible 11103 AdrAdCMissing Pas d adresse de notification disponible 11104 AdrAdCTooMany Envoyé à trop d adresses de destinataires 11105 AdrAdCNotAllowed L adresse du destinataire se situe en dehors de la plage définie. 11200 MsgNoCharacters Aucun message disponible 11201 MsgInvalidCharacters Caractères invalides dans le message 11202 MsgSendTimeInvalid Temps de transmission invalide spécifié 11203 MsgSendTimeNotAllowed Le temps de transmission se situe en dehors de la fenêtre de temps. 11204 MsgNoNewMsg Aucun message reçu n existe 11300 AccNoUser Utilisateur inconnu 11301 AccNoUnits Trop peu de points disponibles 11303 AccNoFreeUnits Pas assez de points gratuits disponibles 11400 CallSystemInvalid Système d appel invalide 11401 CallSystemInvalidForUser Système d appel invalide pour cet utilisateur (système d appel invalide pour l utilisateur) 11402 CallSystemNotSupported Le système d appel n est pas pris en charge 11403 CallSystemConfused Le système d appel est temporairement perturbé. 11500 DMissing Aucun identifiant n existe 11501 IDInvalid L identification n a pas pu être trouvée 11502 IDDoesNotExist L ID n existe pas dans le système. 11600 StateAlreadyTransmitted Le message a déjà été envoyé 11700 DataReadError Le contenu des données n a pas pu être lu 11800 CBMsgError Callback contient un numéro ou un texte interdit. 11911 JobIDRequired Aucun identifiant du job n existe dans la demande du statut 11912 JobIDNotFound Aucun job avec cet identifiant n a été trouvé DS-Description-Accès HTTP-HTTPS 16
6. Connexions 6.1 Adresses d accès pour les ordres de transmission L accès URL de ecall est actuellement configuré comme suit. Accès non cryptés Général : Serveur 1 direct : Serveur 2 direct : Accès crypté Général : Serveur 1 direct : Serveur 2 direct : http://www.ecall.ch/ecallurl/ecallurl.asp?wci=interface... http://www1.ecall.ch/ecallurl/ecallurl.asp?wci=interface... http://www2.ecall.ch/ecallurl/ecallurl.asp?wci=interface... https://www.ecall.ch/ecallurl/ecallurl.asp?wci=interface... https://www1.ecall.ch/ecallurl/ecallurl.asp?wci=interface... https://www2.ecall.ch/ecallurl/ecallurl.asp?wci=interface... 6.2 Adresse IP des réponses ou entrées (ecall -> Client) Source adresse IP : 193.93.208.200 193.93.208.149 193.93.208.153 Port source : indéfini (ouvert ; 0 à 65535) DS-Description-Accès HTTP-HTTPS 17
7. Identification ecall n accepte les ordres que si l expéditeur peut être identifié. Les caractéristiques suivantes peuvent être utilisées pour identifier le client : Champ de différence dans l en-tête HTTP Nom de compte et mot de passe Les caractéristiques peuvent bien sûr aussi être combinées. Veuillez nous contacter pour d autres options d identification. 8. Test de l accès Pour un simple test de l accès, vous pouvez utiliser votre navigateur web. Veuillez respecter les conditions d utilisation de l accès. Vous devez également savoir si le nom du compte et le mot de passe du compte sont requis pour l identification (peut également être désactivé). 1. Démarrez votre navigateur. 2. Copiez l URL ci-dessous dans la barre d adresse de votre navigateur. http://www1.ecall.ch/ecallurl/ecallurl.asp?wci=interface&function=sendpage&address=074034 2686&Message=Test&AccountName=foo&AccountPassword=bar Veuillez définir les valeurs pour AccountName et AccountPassword en fonction de vos valeurs. 3. Vous recevrez une réponse comme décrit au point 4.5. DS-Description-Accès HTTP-HTTPS 18
Annexe Jeu de caractères pour les SMS Pour envoyer des caractères spéciaux, on peut utiliser le codage par défaut (% plus le jeu de caractères ANSI dans le code HEX) tel qu il est utilisé pour une URL. Exemple d une distance : «Hans Muster» -> «Hans%20Patterns». HEX Zeichen HEX Zeichen HEX Zeichen HEX Zeichen HEX Zeichen HEX Zeichen HEX Zeichen HEX Zeichen 0? 20 SP 40 @ 60 ` 80 A0? C0 A E0 à 1? 21! 41 A 61 a 81? A1 C1 A E1 a 2? 22 " 42 B 62 b 82? A2? C2 A E2 a 3? 23 # 43 C 63 c 83? A3 C3 A E3 a 4? 24 $ 44 D 64 d 84? A4 C4 Ä E4 ä 5? 25 % 45 E 65 e 85? A5 C5 Å E5 å 6? 26 & 46 F 66 f 86? A6? C6 Æ E6 æ 7? 27 ' 47 G 67 g 87? A7 C7 ç E7 c 8? 28 ( 48 H 68 h 88? A8? C8 E E8 è 9? 29 ) 49 I 69 i 89? A9? C9 É E9 é 0A LF 2A * 4A J 6A j 8A S AA? CA E EA e 0B? 2B + 4B K 6B k 8B? AB? CB E EB e 0C? 2C, 4C L 6C l 8C? AC? CC I EC ì 0D CR 2D - 4D M 6D m 8D? AD? CD I ED i 0E? 2E. 4E N 6E n 8E Z AE? CE I EE i 0F? 2F / 4F O 6F o 8F? AF? CF I EF i 10? 30 0 50 P 70 p 90? B0? D0? F0? 11 DC1 31 1 51 Q 71 q 91? B1? D1 Ñ F1 ñ 12? 32 2 52 R 72 r 92? B2? D2 O F2 ò 13? 33 3 53 S 73 s 93? B3? D3 O F3 o 14? 34 4 54 T 74 t 94? B4? D4 O F4 o 15? 35 5 55 U 75 u 95? B5? D5 O F5 o 16? 36 6 56 V 76 v 96? B6? D6 Ö F6 ö 17? 37 7 57 W 77 w 97? B7? D7? F7? 18? 38 8 58 X 78 x 98? B8? D8 Ø F8 ø 19? 39 9 59 Y 79 y 99? B9? D9 U F9 ù 1A? 3A : 5A Z 7A z 9A s BA? DA U FA u 1B? 3B ; 5B [ 7B { 9B? BB? DB U FB u 1C? 3C < 5C \ 7C 9C? BC? DC Ü FC ü 1D? 3D = 5D ] 7D } 9D? BD? DD Y FD y 1E? 3E > 5E ^ 7E ~ 9E z BE? DE? FE? 1F? 3F? 5F _ 7F? 9F Y BF DF ß FF y DS-Description-Accès HTTP-HTTPS 19