Obtention via HTTP des fichiers PDF générés par le service de SMS/MMS certifiés

Transcription

1 Obtention via HTTP des fichiers PDF générés par le service de SMS/MMS certifiés PDF XML API Lleidaetworks Serveis Telemàtics, S.A. Version 2.0

2 Copyright (c) Lleidaetworks Serveis Telemátics, S.A. Tous droits réservés Ce document contient des informations privées et confidentielles. Il est strictement interdit de distribuer ses contenus totale ou partiellement par tout moyen, physique ou numérique, sans l'autorisation explicite du titulaire. 2

3 Table des matières.. 1 Introduction Aspects généraux Types de fichier et nomenclature employée Documents de SMS Terminés (MT) Documents de MMS Terminés (MMST) Documents de SMS Générés (MO) Documents de MMS Générés (MMSO) Fichier DTD Liste d'opérations de l'api Éléments utilisés lors des opérations XML Élément user Élément password Élément dst Éléments mt_id Élément mmst_id Élément srs Élément mo Élément mmso Format XML de la réponse Codes d'état de la réponse SMS Certifié et Contrat SMS. État État du processus de signature Format de la requête signature_status Subéléments de l'élément result Exemples SMS Certifié et Contrat SMS. Mode Base Récupération du document (mode base64) Format de la requête get_pdf_content Subéléments de l'élément result Exemples

4 SMS Certifié et Contrat SMS. Mode Binaire Récupération du document (mode binaire) Format de la requête download_pdf Subéléments de l'élément result Exemples MO Certifié. État État du processus de signature Format de la requête mo_signature_status Subéléments de l'élément result Exemples MO Certifié. Mode Base Récupération du document (mode base64) Format de la requête mo_get_pdf_content Subéléments de l'élément result Exemples MO Certifié. Mode Binaire Récupération du document (mode binaire) Format de la requête mo_download_pdf Subéléments de l'élément result Exemples MMS Certifié et Contrat MMS. État État du processus de signature Format de la requête mmst_signature_status Subéléments de l'élément result Exemples MMS Certifié et Contrat MMS. Mode Base Récupération du document (mode base64) Format de la requête mmst_get_pdf_content Subéléments de l'élément result Exemples MMS Certifié et Contrat MMS. Mode Binaire Récupération du document (mode binaire) Format de la requête mmst_download_pdf Subéléments de l'élément result Exemples

5 . 17 MMSO Certifié. État État du processus de signature Format de la requête mmso_signature_status Subéléments de l'élément result Exemples MMSO Certifié. Mode Base Récupération du document (mode base64) Format de la requête mmso_get_pdf_content Subéléments de l'élément result Exemples MMSO Certifié. Mode Binaire Récupération du document (mode binaire) Format de la requête mmso_download_pdf Subéléments de l'élément result Exemples Site html de test Certification de messages reçus (MO o MMSO) otes additionnelles et restrictions d'utilisation Disponibilité des données Ratios de requête autorisés

6 1 Introduction L'api PDFXMLAPI permet d'obtenir, à travers des requêtes HTTP, les fichiers générés par le service de SMS certifié ou MMS certifié de Lleida etworks depuis des réseaux sécurisés par des pare-feu ne permettant que le trafic sortant de navigation web standard. En outre, l'utilisation du protocole HTTP et le format XML pour la représentation des données assure une intégration rapide avec l'application du client, car la majorité des langages de programmation disposent d'un excellent support pour tous les deux. Actuellement, l'api permet de télécharger ou récupérer une copie de plusieurs types de documents, en fonction de l'événement qui donne lieu à leur génération, qu'ils soient liés à l'envoi d'un SMS (MT), à l'envoi d'un MMS(MMST), à la réception certifiée au courrier d'un SMS (MO) ou à la réception certifiée au courrier d'un MMS (MMSO) 6

7 2 Aspects généraux L'appel des opérations disponibles pour la requête de l'état de signature et l'obtention des documents certifiés est fait à travers l'exécution du CGI placé sur L'appel CGI doit être fait avec la méthode POST du protocole HTTP. L'appel au CGI doit inclure la variable xmloù l'on trouve les données de l'opération codifiés suivant le format XML, décrit dans les sections suivantes. La réponse du CGI sera normalement en format XML, à l'exception d'un pas particulier dans les opérations du type download (mode binaire) disponibles pour chaque type de fichier (opérations donwload_pdf, mo_download_pdf, mmst_download_pdf y mmso_download_pdf). Pour ce type d'opérations, lorsqu'il est possible de renvoyer le document demandé, le résultat obtenu ne sera pas du type xml, mais il sera renvoyé le contenu binaire du pdf directement. Pour cela, ces opérations sont idéales pour être utilisées comme lien ou url directe de téléchargement du fichier (avec un traitement minimale de la réponse obtenue). Si vous choisissez l'utilisation des opérations de récupération de fichiers en mode base64 (comme get_pdf_content), le contenu des fichiers pdf sera envoyé au client dans la même réponse XML, avec les données binaires codées au format base64. Ensuite, le client pourra choisir entre sauvegarder lesdites données au ce format directement et les décoder adéquatement pour obtenir le fichier pdf d'origine (les données binaires). La disponibilité des fichiers dans le référentiel du système une fois terminé le processus de signature et génération du fichier pdf correspondant est limitée à plusieurs mois. Toute combinaison incorrecte des éléments exigés ou la requête des données d'un SMS (MT) ou d'un MMS (MMST) qui n'a pas été envoyé avec demande d'accusé de réception certifié, renverra un résultat erroné (status -3 Requête Invalide). Voir la section 7.1 pour essayer d'éviter toute possible casuistique d'erreur. 7

8 3 Types de fichier et nomenclature employée Il existe plusieurs types de document certifié: les générés par l'action initiale d'envoyer un message certifié ou contrat (principalement un SMS ou MMS terminé) ou les générés inconditionnellement par le fait d'avoir activé la certification des messages reçus à un numéro attribué (uniquement pour SMS ou MMS à l'origine). Cette documentation fera référence aux SMS envoyés (Terminated) ou reçus (Originated) avec la notation MT ou MO respectivement. Pour les MMS envoyés ou les MMS reçus, l'on utilisera de manière similaire la notation MMST ou MMSO respectivement. Tenant compte de ce fait, chaque type de document pourra être lié à son message principal ou de référence de la façon suivante: SMS certifié: lié uniquement à l'envoi d'un MT. Contrat SMS: lié à l'envoi d'un MT, mais conditionné à la réception ultérieure d'un MO de réponse. MO certifié: lié uniquement à la réception d'un MO reçu (si la certification sms reçus a été préalablement activée). MMS certifié: lié uniquement à l'envoi d'un MMST. Contrat MMS: lié à l'envoi d'un MMST, mais conditionné à la réception ultérieure d'un MMSO de réponse. MMSO certifié: lié uniquement à la réception d'un MMSO reçu (si la certification mms reçus a été préalablement activée). 3.1 Documents de SMS Terminés (MT) Il s'agit des SMS Certifiés et des Contrats SMS. Le SMS Certifié inclut dans son document le texte du sms envoyé, donc l'on obtient toujours un document de l'opération. Le Contrat SMS inclut dans son document le texte du SMS envoyé à la destination choisie, ainsi que le texte du premier sms reçu comme possible réponse depuis la destination choisie. Cette modalité ne générera un document que sous certaines conditions. Si la remise échoue, la modalité de Contrat SMS ne générera aucun document. Pour pouvoir obtenir correctement le document résultant lié à l'envoi d'un SMS Certifié ou un Contrat SMS (pdf signé numériquement et avec horodatage d'un tiers), il faut procéder avec le correct envoi du message MT avec accusé certifié (type de certificat D ou T) et, facultativement, indiquer un identifiant d'utilisateur unique pour le SMS ou mt_id. 8

9 La spécification du mt_id de l'utilisateur lors de l'envoi d'un SMS est une opération optionnelle dans les APIs qui ne doit pas être confondue avec l'utilisation d'autres id transactionnelles exigées pour l'utilisation des APIs. Il est possible que l'une de nos APIs ne supporte pas encore la spécification de cette valeur optionnelle, ou que celles-ci soient sous un autre nom ou tag. Pour une information plus complète sur la réalisation de l'envoi de messages avec accusé certifié et spécifiant un mt_id d'utilisateur, vous pouvez consulter la documentation correspondante au protocole ou l'api utilisés pour la réalisation de l'envoi des messages. La génération de documents du type Contrat SMS exige obligatoirement que l'utilisateur de la plateforme de messagerie de Lleida.net ait un numéro de retour long attribué statiquement. Si le récepteur d'un contrat SMS réponds à ce numéro avec un SMS dans le délai convenu pour ce MT, le document sera généré. Si le délai expire ou est remplacé préalablement par un nouveau contrat, le MT ne générera aucun document. 3.2 Documents de MMS Terminés (MMST) Il s'agit des MMS Certifiés et des Contrats MMS. Le MMS Certifié inclut dans son document le contenu du MMS envoyé, donc l'on obtient toujours un document de l'opération. Le Contrat MMS inclut dans son document le texte du MMS envoyé à la destination choisie, ainsi que le contenu du premier MMS reçu comme possible réponse depuis la destination choisie. Cette modalité ne générera un document que sous certaines conditions. Si la remise échoue, la modalité de Contrat MMS ne générera aucun document. Pour pouvoir obtenir correctement le document résultant lié à l'envoi d'un MMS Certifié ou un Contrat MMS (pdf signé numériquement et avec horodatage d'un tiers), il faut procéder avec le correct envoi du message MMST avec accusé certifié (type de certificat D ou T) et, facultativement, indiquer un identifiant d'utilisateur unique pour le MMS ou mmst_id. La spécification du mmst_id de l'utilisateur lors de l'envoi d'un MMS est une opération optionnelle dans les APIs qui ne doit pas être confondue avec l'utilisation d'autres id transactionnelles exigées pour l'utilisation des APIs. Il est possible que l'une de nos APIs ne supporte pas encore la spécification de cette valeur optionnelle, ou que celles-ci soient sous un autre nom ou tag. Pour une information plus complète sur la réalisation de l'envoi de messages avec accusé certifié et spécifiant un mmst_id d'utilisateur, vous pouvez consulter la documentation correspondante au protocole ou l'api utilisés pour la réalisation de l'envoi des messages. La génération de documents du type Contrat MMS exige obligatoirement que l'utilisateur de la plateforme de messagerie de Lleida.net ait un numéro de retour long attribué statiquement. Si le récepteur d'un contrat MMS réponds à ce numéro avec un MMS dans le délai convenu pour ce MMST, le document sera généré. Si le délai expire ou est remplacé préalablement par un nouveau contrat, le MMST ne générera aucun document. 9

10 3.3 Documents de SMS Générés (MO) Il 'agit des MO Certifiés. Un document du type MO Certifié inclut uniquement le texte d'un SMS reçu. Pour cela, la génération d'un MO Certifié est conditionnée à l'activation préalable de la certification entrante des messages SMS reçus, et elle est compatible simultanément avec la génération d'autres documents de SMS, comme les SMS Certifiés ou les Contrats SMS. Pour configurer ce type de certification, reportez-vous à la section 21. Les méthodes facilitées dans cette api pour les MO permettent d'obtenir une deuxième copie ou sauvegarde des pdf envoyés à l'adresse de courrier configurée. Pour effectuer la récupération de cette copie, il est indispensable, entre autres, de connaître l'id des MO, qu'il soit à travers l'information notifiée dans les protocoles TPC (voir commande ICOMIGMO du protocole de Lleidanet ou la commande DELIVER_SM dans le cas de SMPP) ou à travers une requête à l'api d'administration des messages reçus. 3.4 Documents de MMS Générés (MMSO) Il 'agit des MO Certifiés. Un document du type MMSO Certifié inclut uniquement le texte d'un MMS reçu. Pour cela, la génération d'un MMSO Certifié est conditionnée à l'activation préalable de la certification entrante des messages MMS reçus, et elle est compatible simultanément avec la génération d'autres documents de MMS, comme les MMS Certifiés ou les Contrats MMS. Pour configurer ce type de certification, reportez-vous à la section 21. Les méthodes facilitées dans cette api pour les MMSO permettent d'obtenir une deuxième copie ou sauvegarde des pdf envoyés à l'adresse de courrier configurée. Pour effectuer la récupération de cette copie, il est indispensable, entre autres, de connaître l'id des MMSO, qu'il soit à travers l'information notifiée dans les protocoles TPC (voir commande ICOMIGMMS du protocole de Lleidanet ) ou à travers une requête à l'api d'administration des messages reçus. 10

11 4 Fichier DTD Le fichier DTD qui décrit le format XML à utiliser pour exécuter la requête de cette API est le suivant: <!ELEMET signature_status (user,password,dst,(mt_id mt))> <!ELEMET get_pdf_content (user,password,dst,(mt_id mt))> <!ELEMET download_pdf ((user,password,dst,(mt_id mt))> <!ELEMET mo_signature_status (user,password,src,dst,mo)> <!ELEMET mo_get_pdf_content (user,password,src,dst,mo)> <!ELEMET mo_download_pdf (user,password,src,dst,mo)> <!ELEMET mmst_signature_status (user,password,dst,(mmst_id mmst))> <!ELEMET mmst_get_pdf_content (user,password,dst,(mmst_id mmst))> <!ELEMET mmst_download_pdf ((user,password,dst,(mmst_id mmst))> <!ELEMET mmso_signature_status (user,password,src,dst,mmso)> <!ELEMET mmso_get_pdf_content (user,password,src,dst,mmso)> <!ELEMET mmso_download_pdf (user,password,src,dst,mmso)> <!ELEMET user (#PCDATA)> <!ELEMET password (#PCDATA)> <!ELEMET dst (#PCDATA)> <!ELEMET src (#PCDATA)> <!ELEMET mt_id (#PCDATA)> <!ELEMET mt (#PCDATA)> <!ELEMET mo (#PCDATA)> <!ELEMET mmst_id (#PCDATA)> <!ELEMET mmst (#PCDATA)> <!ELEMET mmso (#PCDATA)> 11

12 5 Liste d'opérations de l'api La liste d'opérations d'appel pour cette API en fonction du type de document que vous souhaitez récupérer est la suivante: Opérations pour MT (SMS Certifié ou Contrat SMS): signature_status get_pdf_content download_pdf Opérations pour MMST (MMS Certifié o Contrat MMS): mmst_signature_status mmst_get_pdf_content mmst_download_pdf Opérations pour MO (MO Certifié): mo_signature_status mo_get_pdf_content mo_download_pdf Opérations pour MMSO (MMSO Certifié): mmso_signature_status mmso_get_pdf_content: mmso_download_pdf 12

13 La grille suivante décrit brièvement les opérations: Opération signature_status get_pdf_content download_pdf mmst_signature_status mmst_get_pdf_content mmst_download_pdf mo_signature_status mo_get_pdf_content mo_download_pdf mmso_signature_status mmso_get_pdf_content mmso_download_pdf Description COSULTER l'état du processus de signature d'un document de MT (SMS Certifié ou Contrat SMS) COSULTER l'état du processus de signature d'un document de MT (SMS Certifié ou Contrat SMS) et OBTEIR le contenu du fichier généré en BASE64(*). Variante de l'opération get_pdf_content avec résultat BIAIRE COSULTER l'état du processus de signature d'un document de MMST (MMS Certifié ou Contrat MMS) COSULTER l'état du processus de signature d'un document de MMST (MMS Certifié ou Contrat MMS) et OBTEIR le contenu du fichier généré en BASE64(*). Variante de l'opération mmst_get_pdf_content avec résultat BIAIRE COSULTER l'état du processus de signature d'un MO Certifié (**). COSULTER l'état du processus de signature d'un document de MO Certifié et OBTEIR le contenu du fichier généré en BASE64(*). Variante de l'opération mo_get_pdf_content avec résultat BIAIRE COSULTER l'état du processus de signature d'un MMSO Certifié (**). COSULTER l'état du processus de signature d'un document de MMSO Certifié et OBTEIR le contenu du fichier généré en BASE64(*). Variante de l'opération mmso_get_pdf_content avec résultat BIAIRE (*)Pour obtenir les données binaires d'origine il faut décoder la chaîne en BASE64. (**)Pour activer la certification des messages reçus reportez-vous à la section

14 6 Éléments utilisés lors des opérations XML Ci-dessous sont décris les possibles éléments qui peuvent être inclus dans l'appel des diverses opérations disponibles dans l'api: 6.1 Élément user Cet élément est commun à toutes les opérations et doit contenir le login de l'utilisateur dans la plateforme de messagerie de Lleida.net. 6.2 Élément password Cet élément est commun à toutes les opérations et doit contenir le mot de passe de l'utilisateur dans la plateforme de messagerie de Lleida.net. 6.3 Éléments dst Pour les opérations qui exigent cette valeur, l'élément doit contenir le numéro de téléphone du destinataire du message en format international, avec le signe + au début suivi du code du pays, de la façon suivante: <dst> </dst> 6.4 Éléments mt_id Pour les opérations qui exigent cette valeur, l'élément doit contenir l'identifiant alphanumérique unique (normalement optionnel pour les apis d'envoi) que l'utilisateur attribue au correspondant SMS terminé (MT), lors de l'envoi d'un SMS Certifié ou d'un Contrat SMS. Pour plus de détails sur l'attribution d'un identifiant mt_id à l'envoi d'un SMS (MT), veuillez consulter la documentation spécifique de l'api ou du protocole d'envoi (protocole propriétaire TCP ou protocole SMPP) utilisé. Même si cet identifiant n'est pas actuellement case sensitive, nous vous conseillons de les générer et les utiliser pour toutes les APIs de manière cohérente, en générant ou en utilisant ces identifiants soit en majuscules soit en minuscules. La spécification de cet ID optionnel peut ne pas être disponible en tous les APIs d'envoi de SMS. 14

15 6.5 Élément mmst_id Pour les opérations qui exigent cette valeur, l'élément doit contenir l'identifiant alphanumérique unique (d'habitude à utilisation optionnelle dans les apis d'envoi) que l'utilisateur attribue au correspondant MMS terminé (MMST) au moment d'envoyer un MMS Certifié ou un Contrat MMS. Pour plus de détails sur l'attribution d'un identifiant mmst_id à l'envoi d'un MMS (MMST), veuillez consulter la documentation spécifique de l'api ou du protocole d'envoi (protocole propriétaire TCP) utilisé. Même si cet identifiant n'est pas actuellement case sensitive, nous vous conseillons de les générer et les utiliser pour tous les APIs de manière cohérente, en générant ou en utilisant ces identifiants soit en majuscules soit en minuscules. La spécification de cet ID optionnel peut ne pas être disponible en tous les APIs d'envoi de MMS. 6.6 Élément src Cette valeur est utilisée uniquement dans les opérations qui ont un rapport avec les messages générés (opérations pour MO Certifié ou MMSO Certifié). Pour les opérations qui exigent cette valeur, l'élément doit contenir le numéro du téléphone d'origine du message reçu dans la plateforme de messagerie de LLeidanet, en format international, avec le signe + au début suivi du code du pays, de la façon suivante: <src> </src> 6.7 Élément mo Cette valeur est exclusivement utilisée dans les opérations de MO Certifié et doit contenir l'identifiant numérique que la plateforme de messagerie de Lleidanet attribue au SMS reçu. 6.8 Élément mmso Cette valeur est exclusivement utilisée dans les opérations de MMSO Certifié et doit contenir l'identifiant numérique que la plateforme de messagerie de Lleidanet attribue au MMS reçu. 15

16 7 Format XML de la réponse Pour toutes les opérations qui reçoivent comme réponse un autre document XML, son nœud sera toujours l'élément <result>. Cet élément se compose de plusieurs éléments (toujours présents) communs à toutes les opérations, suivis d'autres éléments spécifiques pour l'opération spécifique d'appel. Les subéléments communs à toutes les opérations présentes dans cet élément <result> seront les suivants: action: Contient le nom identificateur de l'opération appelée status: Contient un code d'état informatif du succès ou de l'échec de l'opération. msg: Contient un texte informatif du succès ou de l'échec de l'opération. Outre que ces champs communs, l'élément <result> se compose d'autres éléments spécifiques, qui sont détaillés dans la section correspondante à chacune des opérations d'appel possibles. ormalement, ces éléments additionnels apparaîtront dans le résultat lorsque l'opération appelée sera renvoyée avec status Codes d'état de la réponse Les codes d'état admis par le paramètre status sont les suivants: Code Signification 100 Correct 0 Erreur inconnue -1 XML invalide -2 utilisateur invalide -3 Requête invalide 16

17 L'erreur -3 Requête Invalide peut apparaître dans plusieurs situations: Pour éviter toutes ces possibles casuistiques, veuillez tenir compte des conseils suivants: Attribuez des identifiants uniques de message (mt_id o mmst_id) aux SMS ou MMS envoyés. Dans le cas contraire, il pourrait être impossible de récupérer l'un de vos documents à travers cette API. Utilisez cette API uniquement pour les MT et MMST envoyés avec accusé de réception certifié (Contrat SMS/MMS Certifié). Cette api ne fournit aucun service aux SMS ou MMS envoyés avec accusé conventionnel. Utilisez cette API uniquement pour les MO ou MMSO reçus qui ont été redirigés vers le courrier en tant que certifiés. Pour activer la génération de documents MO ou MMSO certifié lisez la section 21. Respectez les périodes de requête et les limites pour chaque type de document. Les requêtes anticipées au début du processus de signature obtiendront un statut de requête invalide. Le délai de requête valide pour un SMS/MMS certifié commence après la réception d'un accusé de réception correspondant avec un statut final (Delivered, Failed, etc) et termine 48 heures après au maximum. Le délai de requête valide pour un SMS/MMS certifié commence après l'envoi du MT/MMST et termine soit quand il expire, quand il est remplacé par un autre, quand il est lié à une réponse MO/MMSO, soit après 31 jours calendaires (la première des options à y parvenir). Le délai de requête valide pour un MO/MMSO certifié commence immédiatement après la réception du message entrant dans la plateforme, soumis à des conditions (lire la section 21). Les documents générés sont disponibles dans le référentiel pendant un minimum de 6 mois. 17

18 8 SMS Certifié et Contrat SMS. État 8.1 État du processus de signature L'opération signature_status permet de consulter uniquement l'état du processus de signature d'un SMS Certifié ou d'un Contrat SMS. 8.2 Format de la requête signature_status Le root element du document XML pour l'appel de cette opération doit être obligatoirement le tag signature_status. Dans ce élément doivent apparaître les éléments suivants: Élément Optionnel Description user Login de l'utilisateur dans la plateforme de messagerie de Lleidaet password Mot de passe de l'utilisateur dans la plateforme de messagerie de Lleidaet dst uméro de destination du SMS envoyé, en format international mt_id Identifiant unique du SMS envoyé, généré par l'utilisateur 8.3 Subéléments de l'élément result Le root element du résultat de cette requête est l'élément <result> (voir section 7). Dans le cas où la requête ne finisse pas avec succès, l'élément <result> ne contient que les subéléments communs. Si l'opération de requête termine avec succès (status=100), l'élément <result> contient, en plus, les subéléments suivants: mt_id: L'identifiant du message demandé lors de la requête dst: Le numéro de destination demandé lors de la requête mt: Identifiant de MT attribué dans la plateforme de messagerie de Lleidanet mo: Identifiant de MO attribué dans la plateforme de messagerie de Lleidanet du correspondant sms de réponse d'un Contrat SMS terminé ou 0 dans les autres cas. status_code: Codes d'état de la signature. Voir grille. status_desc: Message descriptif de l'état de la signature. Voir grille. 18

19 tm_last_update: Date de la dernière modification de l'état de la signature en format unix timestamp. Les subéléments <status_code> et <status_desc>, peuvent être respectivement les suivants codes et descriptions: Code Description Signification 1 Waiting for service Le serveur de signature numérique est en train d'initialiser, ou un service de tiers n'est pas disponible temporairement. Fichier en attente de génération. Génération du contenu et traitement de la demande de signature numérique du 2 Query done contenu. Fichier en attente de génération. Introduction de la signature dans le 3 Generating the content fichier PDF. Fichier en attente de génération. 4 Sending mail notification Envoi de notification par courrier à l'utilisateur Fichier ne pas encore disponible. COTRAT SMS (*) en attente SMS Transaction Pending d'attribution à une réponse MO. Attente 60 to link with a MO de l'arrivée du MO de réponse pour ce contrat. 61 SMS Transaction Linked with a MO 62 SMS Transaction Expired 5 Finished pdf COTRAT SMS (*) correctement lié à une réponse MO. Le fichier PDF sera généré dans quelques instants COTRAT SMS (*) expiré, aucun MO de réponse n'a été reçu pendant les 31 jours après l'envoi du MT. Le fichier PDF ne sera pas généré Processus de signature terminé. Fichier temporairement disponible dans le référentiel. OTE: Les états 5 et 62 sont des états finaux pour cette requête (*) signifie un état ne pas applicable qu'au cas du Contrat SMS 19

20 8.4 Exemples 1) Exemple de requête xml pour obtenir l'état de la signature d'un SMS Certifié ou d'un Contrat SMS: <signature_status> <user>miusuario</user> <password>micontraseña</password> <dst> </dst> <mt_id> </mt_id> </signature_status> 2) Exemple de réponse avec statut correct: <result> <action>signature_status</action> <status>100</status> <msg>success</msg> <mt>111111</mt> <mo>0</mo> <mt_id> </mt_id> <dst> </dst> <status_code>5</status_code> <status_desc>finished pdf</status_desc> <tm_last_update> </tm_last_update> </result> 3) Exemple de réponse avec statut correct: <result> <action>signature_status</action> <status>100</status> <msg>success</msg> <mt>111111</mt> <mo>0</mo> <mt_id> </mt_id> <dst> </dst> <status_code>62</status_code> <status_desc>sms Transaction Expired</status_desc> <tm_last_update> </tm_last_update> </result> 4) Exemple de réponse avec statut incorrect: <result> <action>signature_status</action> <status>-3</status> <msg>invalid query</msg> </result> 20

21 9 SMS Certifié et Contrat SMS. Mode Base Récupération du document (mode base64) L'opération get_pdf_content permet d'obtenir le contenu d'un fichier PDF (codé en BASE64) déjà généré, correspondant à l'envoi d'un SMS Certifié ou d'un Contrat SMS. Si le fichier n'est pas encore terminé, l'on renverra l'état du processus de signature actuel. 9.2 Format de la requête get_pdf_content Le root element du document XML pour l'appel de cette opération doit être obligatoirement le tag get_pdf_content. Dans ce élément doivent apparaître les éléments suivants: Élément Optionnel Description user Login de l'utilisateur dans la plateforme de messagerie de Lleidaet password Mot de passe de l'utilisateur dans la plateforme de messagerie de Lleidaet dst uméro de destination du SMS envoyé, en format international mt_id Identifiant unique du SMS envoyé, généré par l'utilisateur 9.3 Subéléments de l'élément result Le root element du résultat de l'opération get_pdf_content est l'élément <result> (voir section 7). Dans le cas où la requête ne finisse pas avec succès, l'élément <result> ne contient que les subéléments communs. Si l'opération de requête termine avec succès (status=100), l'élément <result> contient, en plus, les subéléments <dst>, <mt_id>, <tm_last_update>,<file_name>, <file_status>, <file_desc> et <file_content> (ce dernier est ajouté en fonction de la valeur de file_status). 21

22 mt_id: L'identifiant du message demandé lors de la requête dst: Le numéro de destination demandé lors de la requête mt: EW. Identifiant du MT dans la plateforme de messagerie de Lleidanet mo: EW. Identifiant de MO dans la plateforme de messagerie de Lleidanet du correspondant sms de réponse d'un Contrat SMS terminé ou 0 dans les autres cas. file_status: Code d'état de la signature. Voir grille. file_desc: Message descriptif de l'état de la signature. Voir grille. file_name: om interne du fichier dans le système. tm_last_update: Date de la dernière modification de l'état de la signature en format unix timestamp. file_content: Le contenu en base64 du fichiers PDF, si file_status=50. Les subéléments <file_status> et <file_desc>, peuvent être respectivement les suivants codes et descriptions: Code Description Signification Le serveur de signature numérique est en train d'initialiser, ou un service de tiers n'est pas 1 Waiting for service disponible temporairement. Fichier en attente de génération. Génération du contenu et traitement de la demande 2 Query done de signature numérique du contenu. Fichier en attente de génération. Introduction de la signature dans le fichier PDF. 3 Generating the content Fichier en attente de génération. Envoi de notification par courrier à l'utilisateur Fichier 4 Sending mail notification ne pas encore disponible. 60 COTRAT SMS (*) en attente d'attribution à une SMS Transaction Pending réponse MO. Attente de l'arrivée du MO de réponse to link with a MO pour ce contrat. 61 SMS Transaction Linked with a MO 62 SMS Transaction Expired 5 Finished pdf 50 Finished pdf and file exists 51 Finished pdf but nonexistent file OTE: Les états 62, 50 et 51 sont des états finaux pour cette requête (*) signifie un état ne pas applicable qu'au cas du Contrat SMS COTRAT SMS (*) correctement lié à une réponse MO. Le fichier PDF sera généré dans quelques instants COTRAT SMS (*) expiré, aucun MO de réponse n'a été reçu pendant les 31 jours après l'envoi du MT. Le fichier PDF ne sera pas généré Le processus de signature a terminé mais il n'a pas été possible de connecter temporairement avec le référentiel. Veuillez réessayer à nouveau la requête pour résoudre la disponibilité finale du fichier. Processus de signature terminé. Fichier disponible dans le référentiel. Processus de signature terminé. Fichier non disponible dans le référentiel (supprimé) 22

23 Le subélément <file_content>, en plus de contenir le fichier en base64, est qualifié avec les suivants attributs MIME: Content-Type= application/pdf Content-Transfer-Encoding= base64 Content-Disposition= inline 9.4 Exemples Le root element du résultat de l'opération get_pdf_content est l'élément <result> (voir section 7). 1) Exemple de requête xml pour obtenir le contenu BASE64 d'un SMS Certifié ou d'un Contrat SMS: <get_pdf_content> <user>miusuario</user> <password>micontraseña</password> <dst> </dst> <mt_id>123123a</mt_id> </get_pdf_content> 2) Exemple de réponse avec statut correct: <result> <action>get_pdf_content</action> <status>100</status> <msg>success</msg> <mt>111111</mt> <mo>0</mo> <mt_id>123123a</mt_id> <dst> </dst> <tm_last_update> </tm_last_update> <file_status>50</file_status> <file_desc>finished and file exists</file_desc> <file_name>lnst_file_format_signat.pdf</file_name> <file_content Content-Type='application/pdf' Content-Transfer-Encoding='base64' Content-Disposition='inline'> JVBERi0xLjQKJeLjz9MKMiAwIG9iaiA8PC9UeX... trrl3f+jpcxm28o8txucdqfz= </file_content> </result> 23

24 3) Exemple de réponse avec statut correct: <result> <action>get_pdf_content</action> <status>100</status> <msg>success</msg> <mt>111111</mt> <mo>0</mo> <mt_id>123123a</mt_id> <dst> </dst> <tm_last_update> </tm_last_update> <file_status>51</file_status> <file_desc>finished pdf but non-existent file</file_desc> <file_name>lnst_file_format_signat.pdf</file_name> </result> 4) Exemple de réponse avec statut correct: <result> <action>get_pdf_content</action> <status>100</status> <msg>success</msg> <mt>111111</mt> <mo>0</mo> <mt_id>123123a9</mt_id> <dst> </dst> <tm_last_update> </tm_last_update> <file_status>62</file_status> <file_desc>sms Transaction Expired</file_desc> <file_name></file_name> </result> 24

25 10 SMS Certifié et Contrat SMS. Mode Binaire 10.1 Récupération du document (mode binaire) L'opération download_pdf permet d'obtenir le contenu du fichier PDF (données BIAIRES) déjà généré, correspondant à l'envoi d'un SMS Certifié ou d'un Contrat SMS. Si le fichier n'est pas encore terminé, l'on renverra l'état du processus de signature actuel. Si la réponse de l'opération download_pdf renvoie le contenu binaire du fichier PDF, le résultat de l'opération ne sera pas xml, mais du type applicationpdf. Si la réponse de l'opération download_pdf ne renvoie pas un fichier mais un état d'opération, le format xml de réponse de celle-ci sera identique au spécifié dans la section précédente pour l'opération get_pdf_content, mais avec la valeur correspondante download_pdf spécifié dans le champ action. De cette manière, si le fichier PDF existe dans le référentiel (état 50 de la méthode get_pdf_content) et celui-ci peut être renvoyé, la réponse HTTP sera du type suivant: Content-type: application/x-unknown Content-type: application/pdf Content-Disposition: attachment; filename=nombre.pdf; BIARI-RESULT Le fait d'inclure un header additionnel du type applicationx-unknown fait possible qu'un navigateur puisse appeler au cgi et, en cas d'obtenir le fichier, la boîte de dialogue "Enregistrer sous..." sera affichée automatiquement. De cette manière, l'utilisateur peut choisir le dossier local de disque où il souhaite d'enregistrer le PDF obtenu. Pour le reste des cas possibles, la réponse HTTP continuera en mode XML normal: Content-type: text/xml XML-RESULT 25

26 10.2 Format de la requête download_pdf Le root element du document XML pour l'appel de cette opération doit être obligatoirement le tag download_pdf. Dans ce élément doivent apparaître les éléments suivants: Élément Optionnel Description user Login de l'utilisateur dans la plateforme de messagerie de Lleidaet password Mot de passe de l'utilisateur dans la plateforme de messagerie de Lleidaet dst uméro de destination du SMS envoyé, en format international mt_id Identifiant unique du SMS envoyé, généré par l'utilisateur Toute combinaison incorrecte des éléments exigés ou la requête d'état d'un MT qui n'a pas été envoyé avec demande d'accusé de réception certifié, renverra un résultat erroné (status -3 Requête Invalide). Voir la section 7.1 pour essayer d'éviter toute possible casuistique d'erreur Subéléments de l'élément result Si l'on envoie un XML comme résultat de l'opération, le format de réponse de celle-ci sera identique à celui de l'opération get_pdf_content, sauf dans le cas particulier où l'on renvoie un résultat binaire (pour le cas où file_status = 50). Si l'on renvoie un résultat BIAIRE comme résultat de l'opération au lieu d'un XML, l'on doit comprendre que l'état de l'opération est de succès (status 100), que l'état du processus de la signature a terminé et que le fichier pdf existe dans le référentiel (file_status 50). Pour le reste des cas, le root element du résultat de cette requête est l'élément <result> (voir section 7). Dans le cas où la requête ne finisse pas avec succès, l'élément <result> ne contient que les subéléments communs. Si l'opération de requête termine avec succès (status=100) et que l'on renvoie un XML, l'élément <result> contient, en plus, les subéléments <dst>, <mt_id>, <tm_last_update>,<file_name>, <file_status> et <file_desc> 26

27 10.4 Exemples 1) Exemple de requête xml effectuée pour obtenir le contenu BIAIRE d'un SMS Certifié ou d'un Contrat SMS: <download_pdf> <user>miusuario</user> <password>micontraseña</password> <dst> </dst> <mt_id>123123a</mt_id> </download_pdf> 2) Exemple de réponse avec statut correct pour le cas particulier file_status=50 (les signes??? dénotent des données binaires): Content-type: application/x-unknown Content-type: application/pdf Content-Disposition: attachment; filename=nombre.pdf;????????????????????????????????? 3) Exemple de réponse avec statut correct et file_status!=50: <result> <action>download_pdf</action> <status>100</status> <msg>success</msg> <mt>111111</mt> <mo>0</mo> <mt_id>123123a</mt_id> <dst> </dst> <tm_last_update> </tm_last_update> <file_status>51</file_status> <file_desc>finished pdf but non-existent file</file_desc> <file_name>lnst_file_format_signat.pdf</file_name> </result> 27

28 11 MO Certifié. État 11.1 État du processus de signature L'opération mo_signature_status permet de consulter uniquement l'état du processus de signature de MO Certifié Format de la requête mo_signature_status Le root element du document XML pour l'appel de cette opération doit être obligatoirement le tag mo_signature_status. Dans ce élément doivent apparaître les éléments suivants: Élément Optionnel Description user Login de l'utilisateur dans la plateforme de messagerie de Lleidaet password Mot de passe de l'utilisateur dans la plateforme de messagerie de Lleidaet src uméro d'origine du MO ou SMS envoyé, en format international dst uméro de destination du MO ou SMS reçu, en format international uméro de Lleidanet attribué mo Identifiant unique du MO reçu dans la plateforme de messagerie de Lleidanet 28

29 11.3 Subéléments de l'élément result Le root element du résultat de cette requête est l'élément <result> (voir section 7). Dans le cas où la requête ne finisse pas avec succès, l'élément <result> ne contient que les subéléments communs. Si l'opération de requête termine avec succès (status=100) et que l'élément <result> contient, en plus, les subéléments <src>, <dst>, <mo>, <tm_last_update>, <status_code> et <status_desc>. mo: L'identifiant du message demandé lors de la requête src: Le numéro d'origine demandé lors de la requête dst: Le numéro de destination demandé lors de la requête (numéro de retour de l'utilisateur) status_code: Code d l'état du processus de signature Voir grille. status_desc: Message descriptif de l'état du processus de signature. Voir grille. tm_last_update: Date de la dernière modification de l'état de la signature en format unix timestamp. Les subéléments <status_code> et <status_desc>, peuvent être respectivement les suivants codes et descriptions: Code Description Signification 1 Waiting for service Le serveur de signature numérique est en train d'initialiser, ou un service de tiers n'est pas disponible temporairement. Fichier en attente de génération. 2 Query done Génération du contenu et traitement de la demande de signature numérique du contenu. Fichier en attente de génération. 3 Generating the content Introduction de la signature dans le fichier PDF. Fichier en attente de génération. 4 Sending mail notification Envoi de notification par courrier à l'utilisateur Fichier ne pas encore disponible. 5 Finished pdf Processus de signature terminé. Fichier temporairement disponible dans le référentiel. OTE: L'état 5 est un état final pour cette requête 29

30 11.4 Exemples 1) Exemple de requête xml pour obtenir l'état de la signature d'un MO Certifié: <mo_signature_status> <user>miusuario</user> <password>micontraseña</password> <src> </src> <dst> </dst> <mo> </mo> </mo_signature_status> 2) Exemple de réponse avec status correct: <result> <action>mo_signature_status</action> <status>100</status> <msg>success</msg> <src> </src> <dst> </dst> <mo> </mo> <status_code>5</status_code> <status_desc>finished pdf</status_desc> <tm_last_update> </tm_last_update> </result> 30

31 12 MO Certifié. Mode Base Récupération du document (mode base64) L'opération mo_get_pdf_content permet d'obtenir l'état du processus de signature et le contenu du fihcier PDF (codé en BASE64), généré correspondant à la réception d'un MO Certifié. Si le fichier n'est pas disponible, l'on renverra l'information concernant l'état du processus de signature Format de la requête mo_get_pdf_content Le root element du document XML pour l'appel de cette opération doit être obligatoirement le tag mo_get_pdf_content. Dans ce élément doivent apparaître les éléments suivants: Élément Optionnel Description user Login de l'utilisateur dans la plateforme de messagerie de Lleidaet password Mot de passe de l'utilisateur dans la plateforme de messagerie de Lleidaet src uméro d'origine du MO ou SMS envoyé, en format international dst uméro de destination du MO ou SMS reçu, en format international uméro de Lleidanet attribué mo Identifiant unique du MO reçu dans la plateforme de messagerie de Lleidanet 12.3 Subéléments de l'élément result Le root element du résultat de cette requête est l'élément <result> (voir section 7). Dans le cas où la requête ne finisse pas avec succès, l'élément <result> ne contient que les subéléments communs. Si l'opération de requête termine avec succès (status=100), l'élément <result> contient, en plus, les subéléments <src>, <dst>, <mo>, <tm_last_update>,<file_name>, <file_status>, <file_desc> et <file_content> (ce dernier est ajouté en fonction de la valeur de file_status). 31

32 mo: L'identifiant du message demandé lors de la requête src: Le numéro d'origine demandé lors de la requête dst: Le numéro de destination demandé lors de la requête (numéro de retour de l'utilisateur) file_status: Code d'état de la signature. Voir grille. file_desc: Message descriptif de l'état de la signature. Voir grille. file_name: om interne du fichier dans le système. tm_last_update: Date de la dernière modification de l'état de la signature en format unix timestamp. file_content: Le contenu en base64 du fichiers PDF, si file_status=50. Les subéléments <file_status> et <file_desc>, peuvent être respectivement les suivants codes et descriptions: Code Description Signification 1 Waiting for service Le serveur de signature numérique est en train d'initialiser, ou un service de tiers n'est pas disponible temporairement. Fichier en attente de génération. 2 Query done Génération du contenu et traitement de la demande de signature numérique du contenu. Fichier en attente de génération. 3 Generating the content Introduction de la signature dans le fichier PDF. Fichier en attente de génération. 4 Sending mail notification Envoi de notification par courrier à l'utilisateur Fichier ne pas encore disponible. 5 Finished pdf Le processus de signature a terminé mais il n'a pas été possible de connecter temporairement avec le référentiel. Veuillez réessayer à nouveau la requête pour résoudre la disponibilité finale du fichier. 50 Finished pdf and file exists Processus de signature terminé. Fichier disponible dans le référentiel. 51 Finished pdf but non-existent Processus de signature terminé. Fichier non file disponible dans le référentiel (supprimé) OTE: Les états 5, 50 et 51 sont des états finaux pour cette requête Le subélément <file_content>, en plus de contenir le fichier en base64, est qualifié avec les suivants attributs MIME: Content-Type= application/pdf Content-Transfer-Encoding= base64 Content-Disposition= inline 32

33 12.4 Exemples 1) Exemple de requête xml pour obtenir le contenu en BASE64 d'un MO Certifié: <mo_get_pdf_content> <user>miusuario</user> <password>micontraseña</password> <src> </src> <dst> </dst> <mo> </mo> </mo_get_pdf_content> 2) Exemple de réponse avec status correct: <result> <action>mo_get_pdf_content</action> <status>100</status> <msg>success</msg> <src> </src> <dst> </dst> <mo>999999</mo> <tm_last_update> </tm_last_update> <file_status>50</file_status> <file_desc>finished and file exists</file_desc> <file_name>tsa_id.pdf</file_name> <file_content Content-Type='application/pdf' Content-Transfer-Encoding='base64' Content-Disposition='inline'> JVBERi0xLjQKJeLjz9MKMiAwIG9iaiA8PC9UeX BlL1hPYmplY3QvQ29sb3JTcGFjZVsvSW5kZXhl fl/9wl/8ehhpx1mjiywfhyaeeereravwpmu2l trrl3f+jpcxm28o8txucdqfz= </file_content> </result> 3) Exemple de réponse avec status correct: <result> <action>mo_get_pdf_content</action> <status>100</status> <msg>success</msg> <src> </src> <dst> </dst> <mo>999999</mo> <mo> </mo> <tm_last_update> </tm_last_update> <file_status>51</file_status> <file_desc>finished pdf but non-existent file</file_desc> <file_name>tsa_id.pdf</file_name> </result> 33

34 13 MO Certifié. Mode Binaire 13.1 Récupération du document (mode binaire) L'opération mo_download_pdf permet d'obtenir l'état du processus de signature et le contenu du fichier PDF (données BIAIRES directement), généré correspondant à la réception d'un MO Certifié. Si le fichier n'est pas disponible, l'on renverra l'information concernant l'état du processus de signature. Si la réponse de l'opération mo_download_pdf renvoie le contenu binaire du fichier PDF généré, celle-ci sera du type applicationpdf. Si la réponse de l'opération mo_download_pdf ne renvoie pas un fichier mais un état d'opération, le format xml de réponse de celle-ci sera identique au spécifié dans la section précédente pour l'opération mo_get_pdf_content, mais avec la valeur correspondante mo_download_pdf spécifié dans le champ action. De cette manière, si le fichier PDF existe dans le référentiel (état 50 de la méthode mo_get_pdf_content) et celui-ci peut être renvoyé, la réponse HTTP sera du type suivant: Content-type: application/x-unknown Content-type: application/pdf Content-Disposition: attachment; filename=nombre.pdf; BIARI-RESULT Le fait d'inclure un header additionnel du type applicationx-unknown fait possible qu'un navigateur puisse appeler au cgi et, en cas d'obtenir le fichier, la boîte de dialogue "Enregistrer sous..." sera affichée automatiquement. De cette manière, l'utilisateur peut choisir le dossier local de disque où il souhaite d'enregistrer le PDF obtenu. Pour le reste des cas possibles, la réponse HTTP continuera en mode XML normal: Content-type: text/xml XML-RESULT 34

35 13.2 Format de la requête mo_download_pdf Le root element du document XML pour l'appel de cette opération doit être obligatoirement le tag mo_download_pdf. Dans ce élément doivent apparaître les éléments suivants: Élément Optionnel Description user Login de l'utilisateur dans la plateforme de messagerie de Lleidaet Mot de passe de l'utilisateur dans la plateforme de messagerie de passwor Lleidaet d src uméro d'origine du MO ou SMS envoyé, en format international dst uméro de destination du MO ou SMS reçu, en format international uméro de Lleidanet attribué mo Identifiant unique du MO reçu dans la plateforme de messagerie de Lleidanet 13.3 Subéléments de l'élément result Si l'on envoie un XML comme résultat de l'opération, le format de réponse de celle-ci sera identique à celui de l'opération mo_get_pdf_content, sauf dans le cas particulier où l'on renvoie un résultat binaire (pour le cas où file_status = 50). Si l'on renvoie un résultat BIAIRE comme résultat de l'opération au lieu d'un XML, l'on doit comprendre que l'état de l'opération est de succès (status 100), que l'état du processus de la signature a terminé et que le fichier pdf existe dans le référentiel (file_status 50). Pour le reste des cas, le root element du résultat de cette requête est l'élément <result> (voir section 7). Dans le cas où la requête ne finisse pas avec succès, l'élément <result> ne contient que les subéléments communs. Si l'opération de requête termine avec succès (status=100) et l'on renvoie un XML, l'élément <result> contient, en plus, les subéléments <src>, <dst>, <mo>, <tm_last_update>,<file_name>, <file_status> et <file_desc> 35

36 13.4 Exemples 1) Exemple de requête xml effectuée pour obtenir le contenu BIAIRE d'un MO Certifié: <mo_download_pdf> <user>miusuario</user> <password>micontraseña</password> <src> </src> <dst> </dst> <mo> </mo> </mo_download_pdf> 2) Exemple de réponse avec status correct pour le cas particulier file_status=50 (les signes??? dénotent des données binaires): Content-type: application/x-unknown Content-type: application/pdf Content-Disposition: attachment; filename=nombre.pdf;????????????????????????????????? 3) Exemple de réponse avec status correct et file_status!=50: <result> <action>mo_download_pdf</action> <status>100</status> <msg>success</msg> <src> </src> <dst> </dst> <mo> </mo> <tm_last_update> </tm_last_update> <file_status>51</file_status> <file_desc>finished pdf but non-existent file</file_desc> <file_name>lnst_file_format_signat.pdf</file_name> </result> 36

37 14 MMS Certifié et Contrat MMS. État 14.1 État du processus de signature L'opération mmst_signature_status permet de consulter uniquement l'état du processus de signature d'un MMS Certifié ou d'un Contrat MMS Format de la requête mmst_signature_status Le root element du document XML pour l'appel de cette opération doit être obligatoirement le tag mmst_signature_status. Dans ce élément doivent apparaître les éléments suivants: Élément Optionnel Description user Login de l'utilisateur dans la plateforme de messagerie de Lleidaet password Mot de passe de l'utilisateur dans la plateforme de messagerie de Lleidaet dst uméro de destination du MMS envoyé, en format international mmst_id Identifiant unique du MMS envoyé, généré par l'utilisateur 14.3 Subéléments de l'élément result Le root element du résultat de cette requête est l'élément <result> (voir section 7). Dans le cas où la requête ne finisse pas avec succès, l'élément <result> ne contient que les subéléments communs. Si l'opération de requête termine avec succès (status=100), l'élément <result> contient, en plus, les subéléments suivants: mmst_id: L'identifiant du message demandé lors de la requête dst: Le numéro de destination demandé lors de la requête mmst: Identifiant de MMST attribué dans la plateforme de messagerie de Lleidanet mmso: Identifiant de MMSO attribué dans la plateforme de messagerie de Lleidanet du correspondant mms de réponse d'un Contrat MMS terminé ou 0 dans les autres cas. status_code: Code d'état de la signature. Voir grille. status_desc: Message descriptif de l'état de la signature. Voir grille. 37