L'application mobile SELL&SIGN est conçue pour être utilisée de manière autonome, mais aussi pour être interfacée à d'autres applications qui pourront l'utiliser pour faire signer des contrats à valeur probante sur mobile.
L'intégration de SELL&SIGN avec une autre application sur un appareil mobile Android se fait par communication entre votre application "hôte" et l'application SELL&SIGN. Celle-ci doit donc être installée préalablement sur le mobile depuis le Google Play Store.
Ces échanges entre les deux applications se feront via deux modes selon les besoins :
- url scheme et
- android.content.Intent avec un EXTRA_STREAM
Appairage de votre application
L'application SELL&SIGN requiert une authentification de l'utilisateur pour accéder à son environnement dédié sur notre cloud. Pour éviter que l'utilisateur doive saisir son mot de passe lorsqu'il ouvre SELL&SIGN depuis votre application, vous pouvez créer un token d'authentification via un dialogue sécurisé entre vos serveurs et le cloud SELL&SIGN.
Comme pour Affichage de la page de signature, vous allez ainsi pouvoir créer un token temporaire que vous fournirez à votre application.
La méthode à utiliser est :
https://[host]/calinda/hub/createTemporaryToken.actionElle ne peut être appelée qu’en HTTP POST. Cet appel requiert l'usage de votre token d'API tel que cela est décrit sur cette page Authentification.
Le contenu des données POST doit être en JSON :
{ "email" : [email],
"time" : [time]
}- email : adresse email de l'utilisateur qui correspondra à son identifiant
- time : date en millisecondes UTC d’expiration du token
Le service retourne alors un token de ce type :
1P4o!Z|dkKdGePcpSMhJtDKfRofYKH+Ez2Jr8pCUmVFZVYGW/skM0b+gglYMsjhcmAP7DRFYVpmQegWd2Ugs5PoiWQoESrxBECk7Hvs+Q2jK0IgndaAEkmhyC99z5QUVLqiU+5MvfE9QuTD8Ex2H38qFfmmyPgtU4wTpMaK57CNye49ISc= URL d'appel App-to-App
L'application SELL&SIGN déclare, lorsqu'elle est installée, l'usage du schéma url suivant : sellsign://
Pour effectuer l'appairage basé sur le token que vous avez généré depuis votre serveur, votre application peut donc appeler l'url suivante :
sellsign://auth?token=[votre token]&success_callback_url=[votre url de retour]&error_callback_url=[votre url de retour en cas d'erreur]- votre token : le token url encodé que vous a reçu lors du chapitre précédent.
- votre url de retour (facultatif): cette url doit être basée sur un schéma url propre à votre application. Exemple : myapp://sellsign/auth/ok
- votre url de retour pour erreur (facultatif) : cette url doit être basée sur un schéma url propre à votre application. Exemple : myapp://sellsign/auth/error . SELL&SIGN ajoutera un paramètre message contenant le message url encodé de l'erreur.
Tous les paramètres utilisés pour cette url doivent être "url encodés".
Demander une synchronisation
L'application SELL&SIGN ayant des capacités 'offline', il peut être intéressant si votre application dispose des mêmes capacités de demander une synchronisation montante/descendante des données.
Pour cela, il suffit d'appeler l'url suivante :
sellsign://sync/incremental?success_callback_url=[votre url de retour]&error_callback_url=[votre url de retour en cas d'erreur]- votre url de retour (facultatif): cette url doit être basée sur un schéma url propre à votre application. Exemple : myapp://sellsign/auth/ok
- votre url de retour pour erreur (facultatif) : cette url doit être basée sur un schéma url propre à votre application. Exemple : myapp://sellsign/auth/error . SELL&SIGN ajoutera un paramètre message contenant le message url encodé de l'erreur.
Tous les paramètres utilisés pour cette url doivent être "url encodés".
Cette action permet de réaliser une synchronisation incrémentale, mais il peut parfois être nécessaire de faire une synchronisation complète en appelant l'url suivante :
sellsign://sync/full?success_callback_url=[votre url de retour]&error_callback_url=[votre url de retour en cas d'erreur]Envoyer un contrat pour signature
L'envoi d'un contrat entre nos deux applications requiert le passage d'un fichier PDF (binaire). Le schéma url ne sera pas suffisant et complexe, il est nécessaire d'utiliser l'objet android.content.Intent et la méthode startActivity .
Intent shareIntent = new Intent();
shareIntent.setAction( Intent.ACTION_SEND );
shareIntent.putExtra( Intent.EXTRA_STREAM, Uri.fromFile( my_sellsign_file ) );
shareIntent.setType( "application/sellsign" );
startActivity( shareIntent );
L'application SELL&SIGN se déclare comme le réceptacle des fichiers de type .sellsign ou application/sellsign. Vous allez donc générer un fichier de type .sellsign qui va contenir les informations à propos du contrat, du client, des signataires mais aussi le fichier pdf.
Ce fichier est structuré selon le format json.
Exemple :
{"customer":{"number":"my_customer_number","mode":2,"contractor_id":-1,"fields":[{"key":"firstname","value":"Jean"},{"key":"lastname","value":"Dupont"},{"key":"civility","value":"MONSIEUR"},{"key":"companyName","value":"cal"}]},"contractors":[],"contract":{"contract_definition_id":1,"pdf_file_name":"my_contract.pdf","pdf_file_path":"data:application\/pdf;base64,JVBERi.....UlRU9GCg==","contract_id":-1},"contract_properties":[{"key":"my_internal_contract_id","value":"AF72379987","to_fill_by_user":0}],"files":[],"options":[],"error_callback_url":"myapp:\/\/error?id=AF72379987","success_callback_url":"myapp:\/\/success?id=AF72379987"}Le bloc "customer" définit le client destinataire du contrat. Il est défini par un numéro de client unique "number". On peut définir le "mode" de signature (voir encadré).
La sous-partie "fields" du bloc "customer" permet de définir tous les champs à remplir pour le client. La liste des champs supportés est disponible ici.
Le bloc "contract" définit le contenu du contrat et la référence à un contrat-type par son identifiant via le paramètre "contract_definition_id". La valeur de ce paramètre vous est fournie lors de votre inscription à nos services. Le paramètre "pdf_file_name" permet de nommer le fichier contrat. Ensuite le paramètre "pdf_file_path" doit contenir un data uri de votre fichier pdf. La partie binaire y est donc encodé en base64.
Le bloc "contract_properties" vous permet de définir un ou plusieurs éléments de clé-valeur qui seront associés au contrat.
Il est possible comme dans le cas des schéma d'url d'obtenir des callbacks avec "success_callback_url" et "error_callback_url".
Quand un contrat est soumis à SELL&SIGN de cette façon, si les données sont complètes l'utilisateur est directement placé sur la page de signature. En fin de signature, il lui sera proposé, selon les capacités de connexion disponible, de synchroniser immédiatement ou de le faire plus tard. Une fois cette réponse donnée, les callbacks sont appelés.
Les modes de signature
Pour gérer les différents modes de signature lors de la création d'un contrat, de l'envoi d'un contrat en un seul appel, vous devez renseigner des paramètres obligatoires de type :
- signature_mode
- mode
Ces paramètres correspondent donc aux modes de signature que vous choisissez en fonction du paramétrage de votre environnement. Ceux-ci peuvent prendre les valeurs de 1 à 12, comme présentées dans le tableaux ci-après.
| Contralia par DOCAPOSTE (avec Certinomis) |
La Signature par SELL&SIGN (avec Certinomis) |
|
| Face-à-face SMS : Signature par code à usage unique envoyé immédiatement par SMS (INSTANT_OTP) | 1 | 9 |
| Face-à-face PAD : Signature tactile immédiate (INSTANT_PAD) | 2 | 10 |
| Mail + SMS : Envoi d’un mail pour une signature différée par code SMS (MAIL_OTP) | 3 | 11 |
| Mail + Collecte + SMS : Envoi d'un email avec collecte d'informations ou de documents pour une signature différée par code SMS (MAIL_OTP), dans le cas d’un contrat avec collecte. Ce signataire sera sollicité avant les autres signataires à distance. | 6 | 12 |
| Destinataire en copie : Envoi d'un mail à une personne en copie | 7 | 7 |
| Prévalidation : Envoi du contrat à un prévalidateur qui va déterminer si le contrat est valide, il sera par la suite envoyé aux signataires | 8 | 8 |
Ajouter des pièces jointes
Pour joindre des pièces jointes à un contrat, il faut ajouter des éléments 'file' à la liste 'files' de la façon suivante :
"files":
[
{
"path": "data:image/png;base64,JVBERi0x........",
"name": "cal.png",
"type": "image/png"
},
{
"path": "data:application/pdf;base64,JVBERi0x..",
"name": "notice.pdf",
"type": "application/pdf"
}
]L'attribut 'path' doit donc contenir le fichier dans un format data uri comme pour le contrat vu plus haut.
Que faire si mon application ne sait pas générer de PDF ?
Pas facile de générer un PDF sur un terminal mobile Android. Il est donc possible que votre application ne sache pas le faire. Pas de problème, elle peut demander à SELL&SIGN de le générer pour elle !
Faites générer votre PDF par SELL&SIGN !
En utilisant un modèle de contrat associé à modèle-type de PDF, et en passant en paramètre les options à remplir dedans, vous pouvez obtenir de SELL&SIGN la génération du PDF avant la signature !
Nous vous accompagnons