Depuis la version 1.11.2 des web services, sous la forme d'API REST, sont disponibles. Esup-Signature propose une documentation automatique disponible sur votre instance à l'adresse "https://<votre adresse>/swagger-ui.html"
La documentation est aussi consultable (mais non testable...) sur le site de démonstration à cette adresse : https://esup-signature-demo.univ-rouen.fr/swagger-ui.html
Utilisation des web services
Les web services d'esup-signature étant au format REST, il est possible de les tester à l'aide de commandes curl. Des exemples sont proposés dans cette documentation ainsi de dans la documentation swagger. De plus, il est possible de tester les web services directement depuis l'interface swagger. (Dans esup-signature Admin → APIs Doc)
Dans tous les cas la/les machine(s) qui exécutent les web service (directement, via commandes curl ou qui utilise swagger) doivent être déclarées dans la configuration d'esup-signature. L'accès aux web services permet d'effectuer beaucoup d'actions il est donc sécurisé par adresse IP, à configurer dans src/main/resources/application.yml au niveau du paramètres : ws-access-authorize-ips
Tester les web services directement via swagger
Il est possible de tester les web services depuis l'interface swagger. Pour cela il faut modifier la valeur supported-submit-methods dans application.yml
supported-submit-methods: ["get", "put", "post"]
Ne pas oublié d'ajouter l'IP de la machine sur laquelle on teste dans ws-access-authorize-ips
Les circuits nécessitant l'envoi d'un fichier (multipart files) ne peuvent pas être testés directement via l'interface swagger
Démarrer un formulaire
Accès : https://<votre adresse>/ws/forms/{id}/new
Description : Ce web service va créer une nouvelle instance du formulaire désigné pas le paramètre "id" de l'url d'accès.
Attributs :
Attribut | Description |
---|---|
createByEppn | eppn du propriétaire du futur document |
recipientEmails | Si les participants de certaines étapes sont configurables, il faut saisir un tableau de String[]. Ex : ["2*toto@univ-ville.fr","2*tata@univ-rouen.fr"] , ici les deux participants seront affectés à l'étape 2 (suivant le pattern étape*email) |
allSignToCompletes | Pour chaque étape, il est possible de forcer le fait que tous les participants de l'étapes doivent signer. Il faut transmettre un tableau de String comportant les numéros des étapes pour lesquelles tous les participants doivent signer. |
targetEmails | Pour que la demande soit transmise par à la fin du circuit, il est possible, d'envoyer un tableau de String contenant la liste des destinataires finaux |
targetUrl | url pour la destination finale des formulaire terminés. Ex : smb://stockage.univ-ville.fr/form |
Exemple de commande curl :
curl -X 'POST' \ 'https://esup-signature.univ-ville.fr/ws/forms/99999/new?eppn=esupd@univ-ville.fr&recipientEmails=2*toto@univ-ville.fr&recipientEmails=2*tata@univ-ville.fr&targetEmails=1*titi@univ-rouen.fr' \ -H 'accept: */*' \ -d ''
Envoyer un document dans un circuit existant
Accès : https://<votre adresse>/ws/workwlos/{id}/new
Description : Ce web service va déposer d'un document dans une nouvelle instance d'un circuit
Attributs :
Attribut | Description |
---|---|
multipartFile (obligatoire) | Multipart stream du fichier à signer |
createByEppn (obligatoire) | eppn du propriétaire du futur document |
recipientEmails | Si les participants de certaines étapes sont configurables, il faut saisir un tableau de String[]. Ex : ["2*toto@univ-ville.fr","2*tata@univ-rouen.fr"] , ici les deux participants seront affectés à l'étape 2 (suivant le pattern étape*email) |
allSignToCompletes | Pour chaque étape, il est possible de forcer le fait que tous les participants de l'étapes doivent signer. Il faut transmettre un tableau de String comportant les numéros des étapes pour lesquelles tous les participants doivent signer. |
targetEmails | Pour que la demande soit transmise par à la fin du circuit, il est possible, d'envoyer un tableau de String contenant la liste des destinataires finaux |
targetUrl | url pour la destination finale des formulaire terminés. Ex : smb://stockage.univ-ville.fr/form |
Exemple de commande curl :
curl -v -i -X POST \ -H 'content-type: multipart/form-data;' \ -F 'multipartFiles=@Document.pdf' \ 'https://esup-signature.univ-ville.fr/ws/workflows/99999/new?createByEppn=esup@univ-ville.fr&title=test'