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
| Objet | Ce qu’il représente | Contrôle avant écriture |
|---|---|---|
| Person | Un contact, éventuellement lié à une organisation | Identité source et correspondance avec son ID |
| Organization | Une société ou une organisation commerciale | Rattachement métier et compte ERP qualifié |
| Deal | Une affaire avec montant, statut et étape | Contact, organisation, pipeline et étape accessibles |
| Activity | Une action commerciale ou un rendez-vous | Responsable, date et origine de l’action |
| Product | Un produit du catalogue CRM | Correspondance 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.
| Situation observée | Décision | Preuve attendue |
|---|---|---|
| Un webhook arrive deux fois | Réutiliser l’événement reçu sans recommencer son effet métier | Une seule affaire ou commande liée à la même décision |
| Le POST de création expire | Suspendre cette création et rechercher son résultat | ID retrouvé avec une correspondance certaine, ou absence d’effet établie avant nouvelle tentative |
| Le budget journalier est épuisé | Conserver la file et attendre le renouvellement | Aucun appel en boucle ; reprise depuis le dernier checkpoint confirmé |
| Deux comptes ERP correspondent au même client CRM | Faire arbitrer le rattachement avant la commande | Compte 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.