API et webhook expliqués : ce que c’est et quoi demander avant de connecter un logiciel

API et webhook : de quoi parle-t-on ?

Une API et un webhook permettent à deux logiciels d’échanger des données directement, sans que personne ne recopie quoi que ce soit ni n’envoie de fichier. API signifie application programming interface : une porte d’entrée convenue, par laquelle un autre logiciel lit ou modifie des données, selon des règles fixes et le plus souvent avec une clé. Un webhook est un message qu’un logiciel envoie de lui-même à un autre quand quelque chose se passe.

Dans une société de service, il s’agit en général de quelques flux précis : le logiciel comptable récupère les factures comptabilisées, un outil d’automatisation crée une tâche dès qu’une intervention est terminée.

Quelle différence entre une API et un webhook ?

Tout tient à qui prend l’initiative.

• Avec une API, l’autre logiciel demande. « Y a-t-il de nouvelles factures depuis hier ? » Il pose la question à son propre rythme, par exemple toutes les heures ou la nuit, et peut aussi modifier des données s’il en a le droit.
• Avec un webhook, votre logiciel prévient. Dès qu’un événement se produit, par exemple une facture comptabilisée, un court message part vers une adresse internet de l’autre logiciel. Celui-ci doit donc être joignable en permanence.

Les deux se combinent souvent. Le webhook annonce « facture comptabilisée », puis l’autre logiciel demande le détail de cette facture par l’API.

Une clé API est un accès, avec des droits

Une clé API fonctionne comme un mot de passe pour un logiciel. Celui qui la détient obtient l’accès qui y est attaché, sans qu’on lui demande qui il est. D’où trois règles :

1. Ne donnez que le nécessaire. Si la comptabilité ne fait que lire les factures, la clé reçoit seulement le droit de lire les factures. Une clé qui fuit ou une erreur dans la connexion ne peut alors pas faire plus que ce que cette clé permet.
2. Faites tourner la connexion sous un utilisateur à part. Vous voyez ce que fait la connexion, et vous pouvez l’arrêter sans bloquer un collègue.
3. Conservez la clé comme un mot de passe, et donnez-lui une fin. Ne l’envoyez jamais dans un e-mail ordinaire. Une date d’expiration oblige à la renouveler sciemment. Si la collaboration s’arrête, révoquez la clé.

Pourquoi un webhook est-il signé ?

Un webhook arrive sur une adresse accessible depuis internet. Quiconque connaît cette adresse pourrait en principe y envoyer un faux message, par exemple « facture payée ». La signature règle ce problème. L’expéditeur calcule un code sur le message avec un secret que seuls les deux logiciels connaissent, et l’envoie avec le message. Le destinataire refait le calcul. Si le code correspond, le message vient du bon expéditeur et n’a pas été modifié en route. Une méthode courante s’appelle HMAC-SHA256.

La signature ne sert que si le destinataire la vérifie. Posez donc la question à celui qui construit la connexion.

Dix questions à poser avant de connecter deux logiciels par API

Une connexion est un petit projet. Faites mettre par écrit les réponses à ces questions avant que quoi que ce soit ne soit construit :

1. Quelles données passent ? Seulement les factures et notes de crédit comptabilisées, ou aussi les clients et les paiements ?
2. Dans quel sens ? De votre logiciel de service vers la comptabilité, l’inverse, ou les deux ? Et quel logiciel a le dernier mot si une adresse diffère entre les deux ?
3. À quelle fréquence, ou à quel moment ? Tout de suite par un webhook, ou une fois par nuit par l’API ?
4. Qui construit la connexion ? Votre éditeur, celui de l’autre logiciel, ou un tiers ? Avec quelle documentation ?
5. Qui l’entretient ? Les logiciels évoluent. Qui adapte la connexion, et qui paie ce travail ?
6. Que se passe-t-il en cas d’erreur ? Qui est prévenu, où voit-on ce qui n’est pas passé, et y a-t-il un nouvel essai ?
7. À qui appartient la clé ? Sous quel utilisateur la connexion fonctionne-t-elle, et qui garde la clé ?
8. Quels droits reçoit la clé ? Lecture seule, ou aussi modification ? Et dans quelles parties du logiciel ?
9. Comment retirer l’accès ? À la fin de la collaboration, ou si vous soupçonnez une fuite.
10. Comment tester ? D’abord avec quelques enregistrements, et qui contrôle le résultat avant la mise en service ?

Si des données personnelles de vos clients partent chez un autre fournisseur, voyez avec votre conseiller juridique ce que vous devez convenir avec ce fournisseur. Les questions à poser sur l’hébergement de vos données se trouvent dans neuf questions RGPD sur vos données dans un logiciel SaaS.

Parfois, un fichier suffit

Tout échange ne demande pas une connexion. Un export et un import font le même travail, à la main :

Pour un flux mensuel de quelques lignes, ou si l’autre logiciel ne sait pas utiliser d’API, un fichier est souvent le chemin le plus simple. Quand la tâche devient quotidienne et que quelqu’un doit y penser chaque fois, une connexion se justifie plus vite.

Un exemple : les factures vers la comptabilité

Une société de traitement de l’eau comptabilise ses factures dans son logiciel de service. Son comptable travaille dans son propre logiciel et reçoit chaque mois un export par e-mail. Il propose de passer par une API.

La responsable administrative pose les dix questions. Réponse : seulement les factures et notes de crédit comptabilisées, dans un seul sens, une fois par nuit. L’éditeur du logiciel comptable construit la connexion. La clé fonctionne sous un utilisateur à part qui peut seulement lire les factures, et elle expire après un an, pour que quelqu’un la renouvelle sciemment. En cas d’erreur, le logiciel comptable prévient la responsable administrative. Le premier mois, l’export continue en parallèle et le comptable compare les deux. Ensuite, l’export disparaît.

Comment cela fonctionne dans Digitalnatie Service Suite

Dans Digitalnatie Service Suite, la connexion avec d’autres logiciels se règle dans la configuration, écran des intégrations, onglet de l’API et des webhooks. En haut de l’onglet figurent l’adresse de l’API et un lien vers sa documentation, pour celui qui construit la connexion.

• Un droit sur demande : les clés API et les webhooks demandent un droit technique qu’aucun modèle de rôle ne donne, pas même celui de l’administrateur. Vous le demandez à Digitalnatie.
• Un utilisateur à part : en créant une clé API, vous lui donnez un nom et vous choisissez l’utilisateur dont elle reprend exactement les droits. Choisissez de préférence un utilisateur séparé, aux droits limités. L’administrateur invite cet utilisateur et lui attribue ses rôles dans la gestion des rôles.
• Seulement l’accès nécessaire : vous cochez ce que le logiciel peut lire (clients, sites, installations, interventions, contrats, stock, factures, rapports) et ce qu’il peut modifier. Si vous le souhaitez, vous fixez une date d’expiration et limitez la clé à certaines adresses IP.
• Affichée une seule fois : Service Suite ne garde qu’une empreinte de la clé. Copiez-la tout de suite et conservez-la comme un mot de passe. Vous pouvez la remplacer par une nouvelle clé, ou la révoquer définitivement.
• Les webhooks : vous indiquez un nom et une adresse de réception, en https sur internet. Les adresses internes sont refusées. Vous choisissez les événements à envoyer, par exemple une intervention créée, une intervention terminée, ou une facture ou note de crédit comptabilisée.
• Signés et renvoyés : chaque notification est signée en HMAC-SHA256, pour que le destinataire puisse vérifier qu’elle vient de Service Suite. Si un envoi échoue, il est retenté plus tard, à intervalles croissants. Après 20 échecs de suite, le webhook est désactivé, et vous le réactivez une fois le problème résolu.
• Sans connexion : l’administrateur importe des données depuis un modèle Excel ou CSV, contrôlé avant toute écriture. La liste des interventions et les rapports s’exportent en CSV ; la vue financière propose un export Excel du compte de résultats, à ceux qui y ont accès.

Bon à savoir : qu’un logiciel comptable ou un autre programme puisse se connecter ainsi dépend de ce que ce logiciel prend en charge. Posez la question à son éditeur. Supprimer un webhook efface aussi l’historique de ses envois. Dans l’onglet des services, WhatsApp Business et les serveurs MCP peuvent être connectés et testés, mais rien ne part encore par ces connexions.

Qui peut faire quoi dans le logiciel lui-même est expliqué dans droits d’accès : qui voit quoi, et le chargement d’un fichier clients dans importer ses données clients. Voyez aussi le module facturation et achats.

Questions fréquentes

Quelle est la différence entre une API et un webhook ?

Avec une API, un autre logiciel demande lui-même des données, à son propre rythme, et peut aussi en modifier s’il en a le droit. Avec un webhook, votre logiciel prévient de lui-même qu’un événement s’est produit, par exemple une facture comptabilisée, en envoyant un message vers une adresse internet de l’autre logiciel. Les deux se combinent souvent.

Qu’est-ce qu’une clé API ?

Une clé API est un accès pour un logiciel, comme un mot de passe pour une personne. Celui qui la détient obtient les droits qui y sont attachés. Ne donnez donc à une clé que les droits dont la connexion a besoin, et conservez-la comme un mot de passe.

Pourquoi un webhook est-il signé ?

Un webhook arrive sur une adresse accessible depuis internet. Grâce à la signature, le destinataire peut vérifier que le message vient du bon expéditeur et n’a pas été modifié en route. Cela ne sert que si le logiciel destinataire vérifie bien la signature.

Peut-on connecter Service Suite à un logiciel comptable ?

Si votre logiciel comptable sait travailler avec une API ou des webhooks, il peut lire des données par une clé API, par exemple les factures, et recevoir des notifications, par exemple une facture ou une note de crédit comptabilisée. Qui construit la connexion se convient avec l’éditeur du logiciel comptable, et le droit de créer clés et webhooks se demande à Digitalnatie. Sinon, l’export et l’import de fichiers restent la solution.

Tout le monde peut-il créer une clé API dans Service Suite ?

Non. Les clés API et les webhooks demandent un droit technique qu’aucun modèle de rôle ne donne, pas même celui de l’administrateur. Vous le demandez à Digitalnatie.