Integration REST externe (cle API)
L'integration REST externe est une « porte » controlee par laquelle un autre systeme (ERP, backend de site, 1C ou couche d'integration, application maison) peut creer et mettre a jour des taches et des affaires dans LadVen OS via une API standard avec une cle d'acces. Et personne ne transmet d'identifiant ni de mot de passe et ne travaille sous le compte administrateur.
Chaque appel est execute par un compte de service dedie (un bot) avec le minimum de droits necessaires : uniquement les actions que vous avez autorisees, et uniquement dans les directions, projets, pipelines et etapes que vous avez definis. Toutes les requetes passent par les regles habituelles du portail — acces, controles, automatisation, notifications — et sont consignees dans un journal consultable pour chaque integration.
La connexion s'ajoute une seule fois dans le hub d'integrations (section CRM → Integrations, route /crm/integrations).
Quand l'utiliser
L'integration REST est necessaire lorsque « quelque chose se produit dans un autre systeme — et qu'une tache ou une affaire doit apparaitre automatiquement dans LadVen OS ». Scenarios typiques :
- l'ERP ou le site cree une tache ou une sollicitation lorsqu'une commande, une demande ou un ticket arrive ;
- une application maison maintient les taches et les affaires en synchronisation avec une base externe ;
- un systeme externe joint des fichiers, laisse des commentaires, enregistre du temps ou fait avancer une affaire dans les etapes au fur et a mesure du travail de l'autre cote.
En quoi cela differe des formulaires et des webhooks : le formulaire de site et le webhook sont une reception a sens unique de demandes dans le CRM. L'integration REST est une liaison programmatique bidirectionnelle : le systeme externe lit (recupere des taches, des affaires, l'historique) et ecrit (cree et met a jour). Le portail lui-meme n'envoie pas de webhooks sortants via cette connexion — c'est la partie externe qui s'adresse au portail.
Comment configurer
La connexion se cree via un assistant pas a pas (CRM → Integrations → ajouter « Integration REST externe »). Etape par etape, en termes operationnels :
- Nom et activite. Donnez un nom clair a l'integration et decidez de l'activer immediatement ou non. Vous pouvez lancer tout de suite une verification de la connexion.
- Compte de service. Choisissez un bot existant ou creez-en un nouveau directement dans l'assistant (nom et identifiant). Ce n'est ni un collaborateur ni un administrateur : l'integration travaille en son nom. Si vous choisissez un compte disposant de droits administrateur, l'assistant vous avertit — c'est voulu, les integrations recoivent le minimum de droits.
- Scenario et niveau de droits. Choisissez l'ensemble d'operations adapte a votre besoin : « Taches et CRM », « Taches uniquement » ou « CRM uniquement ». Puis le niveau de droits : lecture seule, creation et modification, ou gestion. Les droits s'appliquent au compte de service avant la delivrance de la cle.
- Actions autorisees. Cochez les operations precises que l'integration peut effectuer. Le principe est le strict necessaire : n'activez que ce qui est reellement utile. Tout ce qui n'est pas coche sera refuse avant execution.
- Perimetre. Limitez l'integration aux directions, projets, pipelines et etapes voulus. C'est un cadre par-dessus les droits du compte : meme une action autorisee ne s'execute qu'a l'interieur du perimetre defini.
- Champs et limites. Definissez quels champs des taches et des affaires l'integration peut modifier, la limite de requetes par minute et le pic admissible, ainsi que la liste blanche d'adresses IP depuis lesquelles les appels sont autorises.
- Creation de la cle et verification. Enregistrez — le portail affiche une seule fois la cle d'acces sur l'ecran de resultat, avec un bouton de copie. C'est aussi a cet endroit que vous pouvez lancer une verification de la connexion.
Apres sa creation, la connexion dispose d'un journal des requetes : quelles operations ont ete appelees, avec quel resultat et avec les details de chaque appel (les donnees sensibles sont masquees dans les enregistrements).
Securite et cle d'acces
L'integration REST repose sur le principe du moindre privilege — c'est important pour le proprietaire de l'entreprise :
- La cle s'affiche une seule fois. Copiez-la et enregistrez-la aussitot dans un gestionnaire de secrets. Le portail ne montrera plus cette cle et ne la conserve pas en clair. Si la cle doit etre changee, regenerez-la en repassant l'assistant pour cette connexion.
- Compte de service dedie. L'integration ne travaille pas sous une personne ni sous un administrateur ; elle a sa propre zone de responsabilite et ses propres droits.
- Cadres d'acces. Les actions autorisees, le perimetre (directions, projets, pipelines, etapes), la liste blanche de champs, la limite de requetes et la liste blanche d'IP limitent ce que l'integration peut faire et d'ou.
- Journal. Chaque appel est enregistre — on peut analyser qui a modifie quoi via l'integration.
Ne montrez jamais sur des captures d'ecran et ne publiez jamais la cle reelle, l'en-tete d'autorisation, les adresses IP de la liste blanche ou l'identifiant du compte de service. Pour les illustrations, utilisez des valeurs manifestement fictives.
Erreurs frequentes
- Donner a l'integration un compte administrateur au lieu d'un bot de service.
- Activer plus d'actions que necessaire au lieu de l'ensemble minimal requis.
- Ne pas copier la cle a usage unique au moment de la creation.
- Ne pas definir de liste blanche d'IP ni de limite de requetes.
- Definir un perimetre trop large — tout le portail au lieu du seul pipeline voulu.
- S'attendre a ce que le portail se mette a envoyer des webhooks sortants : l'integration fonctionne par appels entrants, c'est le systeme externe qui s'adresse au portail.
Comment verifier que cela fonctionne
- Lancez la verification de la connexion a la fin de l'assistant (ou activez son execution immediate).
- Assurez-vous que la fiche de la connexion affiche un etat actif et sain.
- Consultez le journal des requetes — il doit y figurer des appels reussis.
- Verifiez qu'une tache ou une affaire de test est bien apparue avec le bon responsable, le bon pipeline et la bonne etape, et que l'automatisation et les notifications ont fonctionne comme d'habitude.