Introduction

Vous êtes présentement dans la documentation de l'API eZmax et eZsign. Cette documentation est disponible en français et en anglais.

Dans notre portail, vous pourrez accéder à la documentation de l'API, à la référence de l'API, aux SDK et à d'autres outils pour vous aider à intégrer nos solutions.

Si vous constatez une erreur ou une omission dans la documentation, veuillez nous en informer. Nous corrigerons le problème rapidement.

Intégration

Nous vous recommandons de consulter d'abord la documentation de l'API afin de vous familiariser avec les possibilités d'intégration et les ressources disponibles.

Si vous détenez un forfait eZsign Entreprise, êtes un partenaire ou êtes un développeur autorisé dans le cadre de notre programme de développeurs, vous pouvez communiquer avec notre équipe pour obtenir de l'assistance relativement à votre intégration à l'adresse support-api@ezmax.ca.

Le soutien technique peut notamment porter sur les exigences de votre projet, la logique d'affaires, la configuration requise, la génération des clés API ainsi que les différentes fonctions susceptibles d'être implémentées afin d'atteindre vos objectifs.

Pour les autres utilisateurs, aucun service de soutien technique n'est offert relativement à l'API. Nous vous recommandons de faire appel à un développeur ou à un intégrateur autorisé pour vous accompagner dans votre projet d'intégration.

S'abonner aux releases du dépôt GitHub eZmax API

Pour être informé chaque fois qu'une nouvelle version de nos SDK ou de notre documentation est publiée, vous pouvez vous abonner aux releases de notre dépôt GitHub.

Si vous n'avez pas encore de compte GitHub, créez-en un gratuitement. Une fois connecté, accédez au dépôt eZmax API sur GitHub. Dans le menu Watch, sélectionnez Custom.

Cochez ensuite Releases, puis cliquez sur Apply.

Vous recevrez ainsi automatiquement une notification par courriel chaque fois qu'une nouvelle release est publiée.

Philosophie

Nous utilisons nos propres API pour construire nos interfaces. Autrement dit, il n'existe pas d'API distincte pour un usage interne : nos équipes et nos clients utilisent la même API. Cela signifie que tout ce qui peut être réalisé dans notre application peut également être automatisé à l'aide de cette API.

Nous croyons fermement aux standards ouverts et à l'open source. C'est pourquoi nous avons adopté la philosophie OpenAPI, afin de rendre l'ensemble des fonctionnalités de notre plateforme accessible au moyen de fichiers de référence publics.

OpenAPI

OpenAPI est une spécification permettant de décrire des API de manière standardisée, principalement dans des architectures REST.

L'un des principaux avantages du standard OpenAPI réside dans la richesse de son écosystème. Il existe un grand nombre d'outils, commerciaux et open source, permettant notamment la génération de code, la conversion, la validation et la génération de documentation. OpenAPI était auparavant connu sous le nom de Swagger. Par exemple, le site OpenAPI Tools regroupe de nombreux outils basés sur le standard OpenAPI. Pour en savoir plus sur le standard OpenAPI, consultez le site officiel : OpenAPI Initiative.

Si vous avez besoin de notre fichiers de spécifications JSON pour travailler avec ces outils, il est disponible ici : ezmax.v1.3.json.

Dans les sections suivantes, nous explorerons les différentes façons d'interagir avec notre API.

Options d'intégration de l'API

SDK

Nous fournissons des SDK préconstruits afin de faciliter l'intégration de notre API par nos clients. Il s'agit de la façon la plus simple d'accéder à ses fonctionnalités.

Ces SDK sont générés à l'aide d'OpenAPI Generator, et nous recommandons fortement leur utilisation. Des exemples d'implémentation sont également fournis pour faciliter la prise en main.

La plupart de nos SDK incluent une documentation propre au langage utilisé. Cette documentation complète la présente documentation et la référence de l'API, qui décrit le fonctionnement général de l'API.

L'ensemble des SDK disponibles est accessible dans la section SDK officiels (voir ci-dessous).

SDK officiels

Les SDK officiels eZmax facilitent l'intégration de l'API dans votre environnement de développement. Ils sont générés à partir de notre spécification OpenAPI et sont disponibles pour plusieurs langages de programmation.

INFO

Les SDK sont fournis en anglais uniquement afin de faciliter leur maintenance. Des intégrateurs francophones peuvent également vous assister.

Langage	SDK	Gestionnaire de paquets
C	eZmax-SDK-c
C#	eZmax-SDK-csharp	NuGet
Dart	eZmax-SDK-dart
Go	eZmax-SDK-go
Java	eZmax-SDK-java
Kotlin	eZmax-SDK-kotlin
PHP	eZmax-SDK-php	Composer
Python	eZmax-SDK-python
Qt5 C++	eZmax-SDK-cpp-qt-client
Ruby	eZmax-SDK-ruby
Swift 6	eZmax-SDK-swift6
TypeScript	eZmax-SDK-typescript-axios	npm

Si le langage de programmation que vous utilisez ne figure pas dans la liste proposée, ou si vos besoins nécessitent une approche particulière, vous pouvez communiquer avec notre équipe technique afin d'évaluer la possibilité de créer ou de publier un SDK adapté à votre environnement. Il est également possible de générer votre propre SDK selon des standards différents grâce à l'approche présentée dans la section consacrée aux SDK personnalisés.

SDK personnalisés

Vous pouvez générer et personnaliser votre propre SDK à l'aide de tout générateur compatible avec OpenAPI 3.0, tel que OpenAPI Generator, Swagger Codegen ou toute autre solution open source ou commerciale. Pour ce faire, il vous suffit de fournir le fichier de spécification OpenAPI à votre générateur. La version la plus récente des spécifications est disponible ici.

Cette approche s'adresse généralement à des cas d'utilisation avancés nécessitant un contrôle plus fin sur la génération du SDK, notamment au niveau de la nomenclature des variables, du nommage des fonctions, de la structure du code et des espaces de noms.

Nous utilisons nous-mêmes OpenAPI Generator en interne, puisqu'il s'agit du générateur officiel et recommandé. Il prend en charge un grand nombre de langages et propose également des options avancées de personnalisation. D'autres solutions existent, notamment des générateurs intégrés à certains environnements de développement (IDE).

OpenAPI Generator propose également une section dédiée à la personnalisation avancée des modèles, et Swagger Codegen offre également des options de configuration et de génération plus poussées. Ces fonctionnalités ne sont pas couvertes dans la présente documentation et s'adressent principalement à des développeurs expérimentés ayant des besoins spécifiques.

Effectuer des appels REST

Dans certains cas, les clients peuvent utiliser un langage de programmation non pris en charge par les générateurs de SDK, ou préférer ne pas utiliser de SDK (officiel ou personnalisé). Cette approche est également courante dans certains environnements legacy ou dans des langages moins répandus.

Il est alors possible d'interagir directement avec notre API via des requêtes HTTP REST.

Notre API est entièrement basée sur les principes REST et prend en charge les méthodes standard GET, POST, PUT, PATCH et DELETE. Elle peut donc être utilisée directement par tout langage de programmation capable d'effectuer des appels HTTP, ce qui permet d'envoyer des requêtes directement à nos points de terminaison.

Cette approche offre une grande flexibilité, puisqu'il suffit de se référer à la référence de l'API pour construire les requêtes appropriées et traiter les réponses manuellement. Chaque point de terminaison est documenté avec les paramètres requis, le format de la requête et la structure de la réponse.

Plateformes d'automatisation

Nous sommes intégrés à des plateformes d'automatisation commerciales qui permettent aux utilisateurs de créer des flux de travail et d'automatiser des tâches et des processus sans nécessiter de développement avancé.

Ces plateformes reposent sur une approche low-code, avec des composants visuels et des blocs fonctionnels prédéfinis.

Nous prenons actuellement en charge les plateformes suivantes :

• Microsoft Power Automate, qui fait partie de la suite Microsoft 365. Veuillez vous référer à la documentation technique de Power Automate pour les détails d'installation, de configuration et de mise en place.
• Salesforce Flow, pour lequel nous vous invitons à consulter la documentation officielle afin d'obtenir les informations relatives à la configuration et à l'utilisation de la plateforme.

Ces outils permettent notamment de créer des flux déclenchés par des événements, comme la création d'un document, la complétion d'une signature ou l'ajout d'un utilisateur, puis d'enchaîner des actions telles que la récupération de données via notre API, le traitement de documents ou l'envoi de notifications vers d'autres systèmes comme SharePoint ou des services de messagerie.

Grâce à ces intégrations, les power users peuvent automatiser des processus complets sans avoir à effectuer directement des appels REST ni à utiliser un SDK.

Intégrations partenaires

Plusieurs développeurs de logiciels ont déjà intégré notre API directement dans leurs solutions, ce qui permet à leurs clients d'activer la fonctionnalité sans intégration manuelle.

Dans le cadre de ces intégrations partenaires, la configuration est généralement préétablie et l'activation peut souvent être effectuée directement dans le logiciel utilisé. Une section dédiée dans eZmax permet également d'installer automatiquement certaines intégrations compatibles. Nous vous invitons à consulter la section Intégrations afin de vérifier si la solution peut être installée directement ou si une configuration auprès du fournisseur est requise.

Voici une liste non exhaustive des intégrations actuellement disponibles :

• Hopem
• PG Solutions
• Centiva

Cette liste d'intégrations partenaires peut être mise à jour régulièrement. Pour consulter les intégrations les plus récentes, veuillez vous référer à la section dédiée dans le produit.

Si vous êtes un développeur de logiciels et souhaitez être ajouté à cette liste d'intégrations partenaires, veuillez contacter notre équipe afin d'évaluer la possibilité d'être ajouté à la liste.

Débogage

Postman

Postman est un outil qui permet de concevoir, tester et déboguer des API. Il peut être utilisé pour envoyer des requêtes REST, consulter les réponses du serveur et valider le comportement des différents points de terminaison.

Afin de faciliter l'utilisation de notre API, eZmax fournit une référence Postman prête à importer. Cette référence contient la structure des requêtes disponibles dans l'API et permet de retrouver une organisation similaire à celle présentée dans la documentation en ligne.

Pour commencer, téléchargez la dernière version de la référence Postman disponible ezmax.v1.3 [Postman].json.

Sélectionnez le fichier de référence Postman correspondant à la version souhaitée, puis cliquez sur Download raw file afin de télécharger le fichier.

Dans Postman, cliquez sur le menu à trois points verticaux, puis sélectionnez Import. Choisissez ensuite le fichier de référence téléchargé précédemment.

Une fois l'importation terminée, la collection API eZmax apparaît dans Postman. Sa structure correspond à l'organisation des objets et des points de terminaison présentés dans la documentation de l'API.

En ouvrant la section Variables, vous pouvez configurer les valeurs utilisées par les requêtes, notamment l'environnement, la région ainsi que la clé d'autorisation.

Remplacez la valeur par défaut (CHANGEME) par votre propre clé d'autorisation afin de permettre l'authentification des requêtes.

Par exemple, pour récupérer un dossier eZsign existant, accédez à la section Object_Ezsignfolder, puis sélectionnez l'opération Retrieve an existing Ezsignfolder. Entrez l'identifiant du dossier à récupérer et cliquez sur Send afin d'envoyer la requête au serveur.

La réponse retournée par le serveur s'affiche directement dans Postman, ce qui permet de vérifier les données reçues et de comprendre le fonctionnement de l'appel effectué.

Postman est donc un outil complémentaire utile pour reproduire des appels API, valider des paramètres et faciliter le dépannage lors du développement d'une intégration.

Cette section présente uniquement une introduction aux fonctionnalités principales de Postman. Pour des besoins plus avancés, consultez la documentation officielle de Postman afin d'explorer l'ensemble des possibilités offertes par l'outil.

Outils de développement du navigateur

Comprendre comment notre logiciel interagit avec l'API peut grandement vous aider à exploiter pleinement ses fonctionnalités. Si vous ne savez pas exactement comment fonctionne l'API ou quels paramètres envoyer, les outils de développement de votre navigateur peuvent vous aider à y voir plus clair. Ils permettent d'inspecter le trafic réseau et d'analyser les requêtes API effectuées par le logiciel.

Cette approche est particulièrement utile, puisque notre logiciel utilise lui-même nos API. Vous pouvez ainsi observer directement les requêtes qu'il envoie et comprendre comment les différentes fonctionnalités sont mises en œuvre, ainsi que la façon dont les données circulent entre le logiciel et l'API.

Cette compréhension vous permettra de reproduire certaines fonctionnalités, de résoudre plus facilement des problèmes et de prendre des décisions éclairées lors de l'intégration avec notre API.

Analyser les requêtes API à l'aide des outils de développement du navigateur

Les outils de développement du navigateur sont disponibles dans la plupart des navigateurs modernes (Google Chrome, Microsoft Edge, Mozilla Firefox, Safari, etc.). Bien que leur apparence et certaines fonctionnalités puissent varier selon le navigateur, le système d'exploitation ou la version utilisée, le principe demeure le même.

Dans la documentation, les exemples sont présentés avec Google Chrome, mais les mêmes étapes peuvent être reproduites avec les outils équivalents des autres navigateurs.

Si vous souhaitez comprendre comment une fonctionnalité du logiciel interagit avec l'API, par exemple la création d'un dossier eZsign, ouvrez l'onglet Network, puis sélectionnez le filtre Fetch/XHR. Vous pourrez ainsi visualiser toutes les requêtes REST échangées entre l'application et le serveur pendant votre utilisation du logiciel.

Après avoir effectué une action, comme la création d'un dossier et le passage à l'étape suivante, une nouvelle requête apparaît dans la liste. Dans cet exemple, une requête POST est envoyée vers la route /3/object/ezsignfolder afin de créer un dossier. Le code de réponse 201 Created confirme que la ressource a été créée avec succès.

En sélectionnant cette requête, plusieurs onglets permettent d'examiner les informations échangées avec l'API :

• Headers : permet notamment de consulter les en-têtes HTTP, l'URL appelée et la méthode utilisée.
• Payload : affiche les paramètres envoyés au serveur dans la requête.

• Response : affiche les données retournées par le serveur.

Le contenu de l'onglet Payload correspond directement à la structure de la requête décrite dans la référence de l'API. De la même façon, l'onglet Response contient la réponse retournée par le serveur, qui correspond à la structure de réponse documentée.

Si vous avez des questions sur les paramètres à envoyer ou sur le fonctionnement d'un point de terminaison, la comparaison de ces informations avec la documentation constitue une excellente façon de comprendre le comportement de l'API. Vous pouvez ainsi reproduire les mêmes appels dans votre propre intégration en utilisant les mêmes structures de requête et de réponse que celles employées par le logiciel.