Français
Introduction
Nous publions tout ce qui concerne notre API sur GitHub à cette adresse : https://github.com/eZmaxinc. Vous y trouverez les dépôts Git contenant la spécification, la documentation et les SDK.
La référence de l'API et les SDK sont fournis en anglais uniquement afin d'en faciliter la maintenance, mais nous avons également des intégrateurs francophones qui peuvent vous assister.
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 fortement de planifier une rencontre en ligne réunissant votre équipe technique et un intégrateur eZmax. Cette rencontre permettra de revoir 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. Il s'agit d'un excellent moyen d'accélérer et de sécuriser votre projet d'intégration.
Si vous détenez un forfait eZsign Entreprise, le soutien technique relatif à l'API est inclus. Les intégrateurs agréés et les utilisateurs autorisés dans le cadre de notre programme de développeurs peuvent également obtenir de l'assistance en communiquant avec notre équipe à l'adresse mailto:support-api@ezmax.ca.
Pour tous les autres utilisateurs, aucun service de soutien technique n'est offert relativement à l'API. Nous vous recommandons de faire appel à un intégrateur agréé figurant dans notre liste d'intégrations ou de communiquer avec nous afin d'obtenir davantage d'information sur notre programme de développeurs autorisés.
Si vous êtes admissible au soutien technique et que la documentation ne répond pas à vos besoins, n'hésitez pas à communiquer avec nous. Nous pourrons vous accompagner dans vos démarches et, lorsque pertinent, apporter les améliorations nécessaires à la documentation afin de faciliter vos travaux d'intégration.
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 nos fichiers de référence JSON pour travailler avec ces outils, ils sont disponibles dans le dépôt eZmax API, dans la section Specs. Vous y trouverez nos spécifications d'API (fichiers .json), compatibles avec de nombreux outils tels que les générateurs de code, les convertisseurs, les générateurs de documentation, les IDE et les générateurs de SDK.
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 via nos dépôts GitHub. Les SDK officiels pour les principaux langages, notamment PHP et C#, sont épinglés en haut de notre page GitHub pour un accès rapide.
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.
Afin d'assurer une distribution efficace et des mises à jour simplifiées, certains de nos SDK sont distribués via les principaux gestionnaires de paquets, notamment :
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 dans le dossier specs de notre dépôt GitHub.
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 :
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 dans le dossier specs du dépôt GitHub de l'API eZmax.
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 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 documentation 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.