Intégration API

Pipedrive : utiliser les objets, champs et webhooks v2

Jérémy Chomel Dawap
  • Publié le : 7 septembre 2024
  • Mis à jour le : 11 novembre 2026
  • Temps de lecture : 16 minutes
  1. Accéder à l’API et réussir une première lecture
  2. Choisir entre token personnel et OAuth
  3. Comprendre contacts, organisations, deals et activités
  4. Créer une affaire et conserver son identifiant
  5. Lire les champs personnalisés sans perdre leur sens
  6. Paginer et reprendre une collecte incrémentale
  7. Calculer le budget et traiter les erreurs 429
  8. Recevoir un webhook v2 et traiter les doublons
  9. Passer du deal à une commande ERP contrôlée
  10. Diagnostiquer les incidents et choisir le bon connecteur
  11. Poursuivre avec les exemples et les cas métier
  12. Conclusion : réussir le premier échange, puis sa reprise
Portrait de Jérémy Chomel

Le premier appel réussi à Pipedrive ne suffit pas à fiabiliser un échange CRM : c’est sa reprise qui révèle les erreurs d’identité et les créations en double. Commencez par une connexion autorisée et une lecture limitée, puis vérifiez ce qui se passe quand un import reprend, qu’un contact change d’email ou qu’un événement arrive après une correction manuelle.

Ce guide présente les premiers appels REST, les relations entre objets, les champs personnalisés, la pagination, les quotas et les webhooks v2. Il s’adresse aux développeurs et aux équipes CRM qui doivent vérifier un échange avant de le relier à un ERP, un portail B2B ou un autre logiciel. Une simple configuration d’application existante peut suffire si elle couvre déjà vos règles.

Les requêtes et les données ci-dessous sont des exemples à adapter dans une sandbox. Aucun résultat client ni connexion à votre compte n’est présumé. Les contrats cités ont été vérifiés dans la documentation officielle le 11 novembre 2026 ; le laboratoire PHP associé utilise des réponses simulées et précise ce qu’il contrôle réellement.

Dawap conçoit des échanges API entre logiciels métier. Si vous devez préciser les données maîtres, la reprise et les responsabilités, notre offre d’intégration Pipedrive avec votre SI permet de cadrer le premier flux avec vos équipes.

Accéder à l’API et réussir une première lecture

Préparer le compte et le domaine

La procédure officielle pour retrouver le token indique le parcours dans les préférences personnelles. Si l’accès API n’est pas disponible, vérifiez son activation et vos permissions avec l’administrateur. N’utilisez pas un token trouvé dans un export ou un ancien journal.

Remplacez companydomain par le domaine du compte à tester et fournissez le token par votre gestionnaire de secrets. Le premier appel ci-dessous lit une seule affaire. Il ne crée ni ne modifie de fiche. Les variables shell sont des paramètres à préparer localement ; le token ne doit pas être enregistré dans Git, une capture ou un ticket.

curl --fail-with-body --silent --show-error \
  --url "https://${PIPEDRIVE_COMPANY_DOMAIN}.pipedrive.com/api/v2/deals?limit=1" \
  --header "x-api-token: ${PIPEDRIVE_API_TOKEN}"

Lire le succès et l’identifiant utile

Une réponse JSON doit être interprétée selon le schéma de l’opération. Vérifiez le statut HTTP, success, les données retournées et les informations de pagination. La réponse fictive suivante illustre une affaire déjà existante ; les propriétés non nécessaires à cette lecture sont omises.

{
  "success": true,
  "data": [{"id": 5071, "title": "Renouvellement — fictif"}],
  "additional_data": {"next_cursor": null}
}

Une liste vide ne prouve pas une absence globale de données : elle peut dépendre du filtre et de la visibilité de l’utilisateur. Avant d’élargir le périmètre, confirmez avec l’administrateur quelle affaire témoin doit être accessible. Le statut 200 ne prouve pas non plus que votre application a traité toutes les pages.

Choisir entre token personnel et OAuth

Un token personnel peut servir à une intégration interne bornée. Il est lié à un utilisateur et à une entreprise ; sa rotation affecte les connexions qui l’emploient. L’authentification officielle documente son passage dans l’en-tête x-api-token. Un token personnel et un access token OAuth ne sont pas interchangeables.

Pour une application distribuée à plusieurs clients, préparez le flux OAuth et les scopes adaptés. Conservez le contexte d’entreprise, la destination API retournée par l’autorisation et les jetons renouvelés dans un stockage protégé. Validez le paramètre state du parcours et coordonnez les renouvellements si plusieurs workers partagent une connexion.

Le choix doit aussi couvrir l’exploitation : que se passe-t-il quand l’utilisateur quitte l’entreprise, quand un scope manque ou quand une autorisation est retirée ? Ne journalisez jamais les secrets pour faciliter le diagnostic. Des logs utiles indiquent l’identité de la connexion et la cause de l’échec, sans copier son en-tête d’authentification.

Comprendre contacts, organisations, deals et activités

Les objets à distinguer dans votre contrat d’échange
ObjetCe qu’il représenteContrôle avant écriture
PersonUn contact, éventuellement lié à une organisationIdentité source et correspondance avec son ID
OrganizationUne société ou une organisation commercialeRattachement métier et compte ERP qualifié
DealUne affaire avec montant, statut et étapeContact, organisation, pipeline et étape accessibles
ActivityUne action commerciale ou un rendez-vousResponsable, date et origine de l’action
ProductUn produit du catalogue CRMCorrespondance avec la référence produit utilisée en gestion

Un lead et un deal ne sont pas synonymes. Le premier peut rester dans une phase de qualification, tandis que le second suit une affaire. Décidez du signal qui autorise leur conversion ; créer une affaire pour chaque visite ou panier transforme vite le pipeline en liste de bruit commercial.

L’ordre de vos écritures dépend des liens nécessaires : retrouver l’organisation, retrouver le contact, puis rattacher l’affaire est une séquence fréquente. Ce n’est pas une obligation native universelle. Une fiche sans organisation peut être légitime ; un connecteur ne doit pas en inventer une pour respecter un schéma arbitraire.

Avant de choisir les endpoints, définissez quel système peut modifier l’identité du client, son propriétaire commercial ou son compte de facturation. Le guide sur les responsabilités d’écriture entre CRM et ERP aide à arbitrer ces conflits. Si plusieurs CRM ou applications partagent ces données, notre accompagnement en intégration API CRM permet de cadrer leurs responsabilités communes.

Créer une affaire et conserver son identifiant

L’endpoint POST /api/v2/deals reçoit un titre et les propriétés documentées pour l’affaire. Le contact 42 de cet exemple est fictif : remplacez-le par l’ID d’une fiche existante et autorisée dans votre sandbox. Cette requête crée une affaire si elle est exécutée sur un vrai compte.

curl --fail-with-body --silent --show-error \
  --request POST \
  --url "https://${PIPEDRIVE_COMPANY_DOMAIN}.pipedrive.com/api/v2/deals" \
  --header "x-api-token: ${PIPEDRIVE_API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"title":"Renouvellement — fictif","person_id":42,"value":12500,"currency":"EUR"}' 

Conservez l’ID retourné avec la clé de l’opportunité source et le compte connecté. Pour une mise à jour, utilisez le chemin et la méthode de l’opération v2, par exemple PATCH /api/v2/deals/{id}. Vérifiez les relations entre pipeline et étape avant de changer stage_id. La référence Deals regroupe plusieurs générations : la mention v1 dans l’URL de documentation n’impose pas la version de chaque endpoint.

Si le POST expire sans réponse exploitable, son effet peut être inconnu. Une deuxième création n’est pas un simple retry sans conséquence. Mettez le dossier en attente, recherchez les preuves de l’écriture initiale puis confirmez la correspondance. Un nom identique ne constitue pas une preuve suffisante pour rapprocher automatiquement deux affaires.

Lire les champs personnalisés sans perdre leur sens

Distinguer la définition du champ et la valeur d’une affaire

Le nom visible d’un champ, sa clé technique et les ID de ses options ont des rôles différents. La documentation des champs personnalisés précise que les clés sont propres au compte. Deux champs appelés « Référence ERP » dans deux entreprises ne partagent donc pas nécessairement leur clé API.

Pour les opérations v2 concernées, custom_fields porte un objet indexé par la clé du champ. La chaîne ci-dessous est une clé fictive de quarante caractères ; elle doit être remplacée par la clé réellement créée et vérifiée dans votre environnement.

{
  "custom_fields": {
    "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa": "OPP-2048"
  }
}

Ne pas traduire une option depuis son seul libellé

Une option peut être renommée sans que le connecteur reçoive une nouvelle décision sur son code ERP. Préservez la distinction entre sélection, définition reçue et mapping approuvé. Le guide sur une option Pipedrive renommée et sa correspondance ERP fournit un exercice pour tester cette situation.

Pour une collecte, demandez seulement les champs nécessaires et vérifiez leur représentation selon l’endpoint. L’absence d’une propriété dans une réponse ne signifie pas toujours qu’il faut vider sa valeur en cible. Distinguez champ non demandé, valeur absente et suppression explicitement autorisée.

Paginer et reprendre une collecte incrémentale

Les listes v2 concernées retournent un curseur dans additional_data.next_cursor. Transmettez ce curseur sur l’appel suivant avec les mêmes filtres. Il ne faut ni l’incrémenter ni considérer une première page complète comme la fin de la collecte. La limite maximale est propre à l’endpoint ; relisez son contrat avant de fixer votre taille de page.

Pour les contacts, updated_since et updated_until permettent de définir une fenêtre de modification. La référence Persons v2 précise que la borne basse est inclusive et la borne haute exclusive. Une stratégie possible fixe une borne haute au début du lot, traite toutes les pages puis confirme cette borne comme point de reprise. Une fenêtre de recouvrement et une déduplication peuvent absorber certaines répétitions ; elles ne remplacent pas la qualification des suppressions, des droits et des mises à jour concurrentes.

Ne confirmez pas le checkpoint avant l’écriture locale durable. Après un crash au milieu d’une page, le même lot doit pouvoir être relu sans dupliquer les effets. Le tutoriel du client PHP sous Symfony exécute deux pages fictives avec le curseur réellement transmis par le SDK.

Calculer le budget et traiter les erreurs 429

Pipedrive distingue un budget journalier en tokens, partagé au niveau de l’entreprise, et des limites de pic d’appels. Le coût varie selon l’opération et sa version. Plusieurs connecteurs peuvent donc consommer le même budget même si chacun semble raisonnable isolément. Les règles et les coûts actuels sont publiés dans la documentation du rate limiting et dans chaque endpoint.

Pour dimensionner une collecte, comptez les pages, les recherches complémentaires et les écritures. Exemple purement arithmétique : 10 000 fiches à 100 par page demandent au moins 100 lectures. Si l’opération choisie coûte 10 tokens, ces lectures représentent 1 000 tokens, hors erreurs et reprises. Faire une recherche distincte pour chaque fiche peut coûter bien davantage que conserver des correspondances fiables.

  • Pic temporaire : réduire la concurrence et reporter le travail selon les indications retournées.
  • Budget journalier épuisé : suspendre les appels concernés et planifier la reprise après le renouvellement du budget ; un backoff court n’y suffit pas.
  • Enrichissement secondaire : le différer avant d’interrompre le flux métier prioritaire.

Le budget ne se renouvelle pas nécessairement à minuit dans votre fuseau. Le code doit éviter les réveils simultanés de tous les workers. Une hausse des 429 après l’ajout d’un autre outil, ou une explosion des recherches unitaires, sont deux signaux à examiner avant de demander davantage de capacité.

Recevoir un webhook v2 et traiter les doublons

Un webhook notifie votre application d’un changement. Il ne remplace pas toujours les lectures nécessaires pour décider de l’effet métier. La version de la notification est distincte de celle de l’endpoint qui crée sa souscription : les webhooks généraux v2 sont notamment configurés via POST /api/v1/webhooks. Vérifiez les objets couverts dans le guide officiel v2.

L’extrait fictif suivant illustre les identités à conserver. Le contenu complet de data et de previous dépend de l’objet et de l’événement ; ces deux blocs ne sont pas des états universels interchangeables.

{
  "meta": {
    "id": "evenement-fictif-001",
    "entity": "deal",
    "entity_id": "5071",
    "company_id": "compte-fictif",
    "action": "change",
    "attempt": 1,
    "version": "2.0"
  },
  "data": {"id": 5071},
  "previous": {}
}

Authentifiez la réception selon la configuration retenue ; les webhooks généraux documentent notamment HTTP Basic. Ne supposez pas l’existence d’une signature HMAC si votre contrat n’en prévoit pas. Vérifiez le schéma et stockez l’événement durablement avant d’envoyer un 2XX. Un traitement asynchrone peut ensuite appliquer les règles métier sans bloquer la réception.

Dédupliquez par compte et ID d’événement, puis protégez séparément l’effet métier, par exemple la relation entre un deal et une commande. Un événement rejoué ne doit pas recréer le document. Un événement retardé ne doit pas restaurer aveuglément une ancienne valeur ; relisez l’état utile et les priorités d’écriture. Vérifiez aussi les permissions du propriétaire de la souscription quand une notification attendue manque.

Passer du deal à une commande ERP contrôlée

Un deal gagné exprime une décision commerciale. Pour créer une commande, l’ERP peut encore demander un compte facturable, des références produits, une version de devis acceptée et des conditions valides. Le middleware transporte ces informations et leurs contrôles ; il ne remplace pas les règles de gestion de l’ERP.

La correspondance doit conserver le deal, le document obtenu, le compte et la version de décision. Après timeout, elle permet de rechercher l’effet initial avant de créer un autre document. Une fusion d’organisations CRM ne doit pas réaffecter silencieusement une facture existante ou choisir entre deux comptes ERP.

Le guide du deal Pipedrive à la facture ERP précise cette acceptation opérationnelle. Le cas fusion d’organisations et compte ERP conservé traite les anciennes références et les conflits. La qualification des interfaces de gestion se fait avec l’installateur ERP lorsque son intervention est nécessaire.

Après une interruption, le rattrapage des ventes Pipedrive non transmises montre une collecte paginée et un checkpoint atomique. Pour les écritures, le formulaire B2B avec journal durable protège les étapes de création ; le contrôle des produits du devis ERP porte le sens des lignes et des montants.

Diagnostiquer les incidents et choisir le bon connecteur

Relier une erreur à l’action suivante

  • 401 : vérifier le secret ou le renouvellement OAuth avant de relancer les lots.
  • 403 ou fiche non visible : vérifier les permissions et le contexte de connexion.
  • Validation refusée : contrôler types, champs et identifiants liés dans le compte.
  • Deux créations après reprise : examiner la persistance et l’unicité de la correspondance.
  • Notifications manquantes : examiner souscription, droits, réponse du récepteur et suivi des livraisons.

Conservez le statut, l’opération, l’identité technique de l’objet et la corrélation utile. Le support doit pouvoir distinguer une entrée à corriger d’une écriture à rapprocher. Un dump complet de contact ou un token dans les logs ajoute une exposition sans fournir la décision de reprise.

Un 403 n’indique pas toujours un manque de permission sur une fiche. Si sa réponse est une page HTML Cloudflare après une série de 429, les appels par token peuvent avoir déclenché la protection contre le trafic excessif décrite dans la documentation des quotas. Arrêtez la boucle et corrigez sa cadence avant une reprise ; changer le responsable CRM ne résoudrait pas ce blocage.

Proportionner l’outil aux règles

Un connecteur natif convient si les objets, déclencheurs et transformations nécessaires sont couverts. Une plateforme d’automatisation peut accélérer un flux limité si ses coûts, ses reprises et sa supervision conviennent au volume. Un middleware sur mesure devient pertinent quand plusieurs systèmes se partagent les écritures, que les identités doivent être conservées durablement ou que les exceptions métier demandent un traitement explicite.

Comparez le coût complet : abonnement, exécutions, quota API, corrections et maintenance. Le premier choix à faire est celui du flux à fiabiliser. Commencez par des données et des scénarios de recette bornés, différez les enrichissements et refusez une ouverture générale tant que les cas de réponse perdue restent sans procédure.

Décider de la reprise avant d’ouvrir le flux
Situation observéeDécisionPreuve attendue
Un webhook arrive deux foisRéutiliser l’événement reçu sans recommencer son effet métierUne seule affaire ou commande liée à la même décision
Le POST de création expireSuspendre cette création et rechercher son résultatID retrouvé avec une correspondance certaine, ou absence d’effet établie avant nouvelle tentative
Le budget journalier est épuiséConserver la file et attendre le renouvellementAucun appel en boucle ; reprise depuis le dernier checkpoint confirmé
Deux comptes ERP correspondent au même client CRMFaire arbitrer le rattachement avant la commandeCompte facturable choisi et décision enregistrée par le responsable métier

Poursuivre avec les exemples et les cas métier

Reproduire le transport avec le client PHP

Le laboratoire SDK Pipedrive pour PHP et Symfony vérifie les chemins, les modèles et la pagination avec des réponses simulées. Il permet de commencer les tests sans disposer d’un secret de production.

Qualifier les opportunités issues du B2B

Le parcours Pipedrive et e-commerce B2B distingue les signaux d’achat utiles, le compte de commande et les conditions commerciales. Il aide à éviter une affaire créée pour chaque activité du portail.

Conclusion : réussir le premier échange, puis sa reprise

Une première lecture valide un accès et un objet témoin. Une intégration fiable doit ensuite conserver les identités, parcourir toutes les données nécessaires et contrôler les effets des écritures. Les champs personnalisés et les statuts doivent garder un sens explicable entre les logiciels.

La pagination, les quotas et les webhooks rendent les échanges plus efficaces lorsqu’ils s’appuient sur des décisions de reprise. Le timeout d’une création et le budget épuisé demandent des actions différentes. Les traiter comme un même retry déplace le problème vers les équipes.

Avant d’ouvrir le flux, choisissez une affaire témoin, les identifiants à conserver et le responsable des exceptions. Testez une livraison répétée, une réponse perdue et un conflit de compte. Le résultat attendu doit pouvoir être vérifié dans Pipedrive et dans le logiciel destinataire, sans déduire la réussite du seul statut HTTP.

Dawap vous accompagne pour intégrer Pipedrive à votre système d’information : cadrage des objets et des données maîtres, réalisation du flux, recette des incidents et procédure de reprise avec vos équipes. Le premier lot porte sur un échange borné dont vous pouvez contrôler le résultat et l’exploitation.

Portrait de Jérémy Chomel

Relier Pipedrive aux opérations métier

Nous cadrons le premier échange, les responsabilités de données et les critères de reprise avec vos équipes.

Articles recommandés

SDK Pipedrive dans Symfony : client officiel, pagination et reprise Intégration API SDK Pipedrive en PHP et Symfony : appels v2 et reprise Lire l'article
  • 28 janvier 2025
  • Lecture ~18 min

Le client PHP officiel prépare les appels v2, mais la reprise appartient à votre application. Ce tutoriel configure le SDK dans Symfony, distingue clé source et ID distant, puis fournit un programme reproductible. Vingt contrôles locaux vérifient pagination, création de contact, deal et blocage après timeout, sans appel externe.

Du deal à la facture : fiabiliser le passage de Pipedrive vers l’ERP Intégration API Du deal Pipedrive à la facture ERP Lire l'article
  • 3 mars 2024
  • Lecture ~22 min

Un deal gagné attend parfois un compte facturable ou la bonne version du devis. Ce guide explique les contrôles ADV, le retour des statuts ERP et la reprise après une réponse perdue. Un exercice local montre comment retrouver la commande avant de renvoyer sa référence dans Pipedrive. Le parcours couvre aussi les relances de facture.

Organisation Pipedrive conservée et comptes ERP examinés après une fusion Intégration API Fusion Pipedrive : quel compte ERP conserver ? Lire l'article
  • 3 octobre 2026
  • Lecture ~9 min

Après une fusion Pipedrive, deux comptes ERP restent possibles. Le cas montre comment retrouver les deux depuis la fiche conservée et préserver les documents déjà créés.

Illustration du contrôle d’une option Pipedrive renommée avant préparation de son code ERP Intégration API Pipedrive : une option renommée Lire l'article
  • 24 août 2025
  • Lecture ~17 minutes

Une option Pipedrive passe de Revendeur à Partenaire. Quel code envoyer à l’ERP ? Retrouvez la définition du champ avec l’API v2, puis exécutez les 43 contrôles Python sur des données fictives. Comparez les résultats quand l’équipe confirme le code existant, approuve un autre code ou doit encore trancher la correspondance.

Passer du guide à un échange Pipedrive exploitable

Partons du deal, du document ERP attendu et des incidents à couvrir pour définir un premier flux vérifiable.