Guide
Intégration API Pipedrive : brancher un assistant IA
Jetons, OAuth, scopes, budget d'appels quotidien, webhooks v2 : ce qu'il faut savoir pour brancher un assistant IA sur Pipedrive. Lu le 15/11/2026.
Mis à jour le
Brancher un assistant IA sur Pipedrive passe par son API (interface de programmation). Trois points décident de la solidité du projet : le budget d'appels, que Pipedrive compte en jetons par jour et par rafales de 2 secondes ; l'autorisation, par OAuth avec des périmètres (scopes) à choisir au plus juste ; et les webhooks v2, qui préviennent l'assistant d'un changement mais se désactivent si votre serveur ne répond pas. Voici ce que dit la documentation développeur de Pipedrive, lue le 15/11/2026.
Le budget d'appels : des jetons, pas des requêtes
Pipedrive ne compte pas le nombre de requêtes, mais leur coût. La page sur les limites (mise à jour le 17/09/2026) décrit un budget quotidien partagé par l'entreprise : 30 000 jetons de base × un multiplicateur selon l'offre × le nombre de sièges. Il se remet à zéro à minuit, heure du serveur.
| Offre | Multiplicateur | Rafale par 2 s (jeton d'API) | Rafale par 2 s (application OAuth) |
|---|---|---|---|
| Lite | 1 | 20 | 80 |
| Growth | 2 | 40 | 160 |
| Premium | 5 | 100 | 400 |
| Ultimate | 7 | 120 | 480 |
Quelques coûts donnés en exemple : lire une fiche 2 jetons, lire une liste 20, mettre à jour une fiche 10, rechercher 40. Les points d'accès de la version 2 de l'API coûtent moins cher que ceux de la v1. L'API de recherche a sa propre limite : 10 requêtes par 2 secondes, quelle que soit l'offre. Une fois le budget épuisé, les requêtes reçoivent une erreur 429 jusqu'au lendemain ; un client qui insiste peut recevoir une erreur 403.
Exemple de calcul, en hypothèse. Prenons un client en offre Growth avec 5 sièges : 30 000 × 2 × 5 = 300 000 jetons par jour. Un assistant qui, pour chaque question, fait une recherche (40) et lit deux fiches (2 × 2) consomme 44 jetons. Mille questions par jour font 44 000 jetons, environ 15 % du budget. Mais ce budget est partagé avec les autres intégrations du client : relevez-les avant de conclure. Et la recherche, plafonnée à 10 requêtes par 2 secondes, sera le premier goulet en pointe.
L'autorisation : OAuth et scopes
Pour une application, Pipedrive utilise OAuth (protocole d'autorisation). Le déroulé documenté : redirection vers oauth.pipedrive.com, accord de l'utilisateur, retour avec un code valable 5 minutes, échange du code contre un jeton d'accès valable 60 minutes et un jeton de rafraîchissement. Ce dernier expire après 60 jours sans usage ; s'il expire, il faut refaire l'installation complète. Le pas à pas général est sur Connexion OAuth à un CRM.
Les scopes vont par paires lecture / écriture complète : deals:read ou deals:full, contacts:read ou contacts:full, activities:read ou activities:full, leads:read ou leads:full, et d'autres (produits, projets, webhooks, champs personnalisés, search:read, admin…). L'utilisateur accepte ou refuse tous les scopes demandés : la documentation recommande de ne demander que ceux qui sont « absolutely necessary ».
| Ce que fait l'assistant | Scopes suffisants |
|---|---|
| Répondre sur les affaires et les contacts | deals:read, contacts:read, search:read |
| Créer une activité de rappel | activities:full en plus |
| Créer un prospect | leads:full en plus |
| Recevoir les changements | webhooks:full en plus |
Le scope admin n'a rien à faire dans un projet d'assistant.
Les webhooks v2 : utiles, mais exigeants
Les webhooks v2 envoient une requête à votre serveur quand une donnée change. On les règle par action (create, change, delete, ou toutes) et par objet (deal, lead, person, organization, activity…). Règles documentées :
- 40 webhooks au plus par utilisateur ;
- réponse attendue en moins de 10 secondes ;
- en cas d'échec, trois nouvelles tentatives, après 3, 30 et 150 secondes ;
- après 10 échecs de première tentative, le webhook est suspendu 30 minutes, et « the webhook's event message is lost » ;
- sans aucune livraison réussie pendant 3 jours consécutifs, le webhook est supprimé.
Conséquence : un serveur d'intégration en panne un week-end peut faire disparaître les webhooks. La surveillance fait partie de la maintenance, et le rattrapage des événements perdus de la gestion des erreurs.
Natif ou externe ?
Pipedrive a ses propres fonctions d'IA, dont un générateur de rapports, décrit sur la fiche Pipedrive de crm.nl-q.com. Un assistant externe se justifie quand il doit répondre à partir d'autres sources que Pipedrive, sur un autre canal, ou sous la marque du client.
Points à vérifier avant de chiffrer
- L'offre et le nombre de sièges du client, pour calculer le budget de jetons.
- Les autres intégrations qui consomment déjà ce budget.
- La liste des scopes, réduite au strict nécessaire.
- Le renouvellement du jeton de rafraîchissement, surveillé.
- La disponibilité du serveur qui reçoit les webhooks.
Questions fréquentes
Combien d'appels API un assistant peut-il faire sur Pipedrive ?
Pipedrive compte en jetons : un budget quotidien de 30 000 jetons de base, multiplié par un coefficient selon l'offre (1 à 7) et par le nombre de sièges. Chaque opération coûte un nombre de jetons, de 2 pour lire une fiche à 40 pour une recherche.
Combien de temps dure un jeton OAuth Pipedrive ?
Le jeton d'accès expire au bout de 60 minutes. Le jeton de rafraîchissement expire s'il n'est pas utilisé pendant 60 jours ; chaque usage remet ce délai à 60 jours.
Que se passe-t-il si mon serveur ne répond pas à un webhook Pipedrive ?
Pipedrive réessaie trois fois (après 3, 30 et 150 secondes), puis supprime le webhook s'il n'a eu aucune livraison réussie pendant 3 jours consécutifs. Après 10 échecs de première tentative, il est suspendu 30 minutes et l'événement est perdu.
Sources
Pages consultées pour écrire cet article :