Intégration API

SDK Pipedrive en PHP et Symfony : appels v2 et reprise

Jérémy Chomel Dawap
  • Publié le : 28 janvier 2025
  • Mis à jour le : 11 novembre 2026
  • Temps de lecture : 18 minutes
  1. Choisir le SDK et le périmètre de la première intégration
  2. Installer une version précise du client PHP
  3. Configurer le client dans Symfony sans exposer les secrets
  4. Conserver la correspondance entre vos clés et les ID Pipedrive
  5. Créer un contact et relier un deal avec les modèles v2
  6. Parcourir les contacts avec le curseur retourné
  7. Bloquer une seconde création après une réponse perdue
  8. Distinguer authentification, validation et quotas
  9. Recevoir les événements sans confondre livraison et traitement
  10. Exécuter le laboratoire et comprendre ses limites
  11. Préparer la recette de votre connecteur
  12. Approfondir les règles CRM et ERP
  13. Conclusion : un SDK vérifié, une reprise décidée
Portrait de Jérémy Chomel

Une personne peut être créée dans Pipedrive alors que votre application reçoit un timeout. Rejouer le même POST risque alors de produire un doublon. Le SDK officiel simplifie les appels et les modèles ; votre application doit conserver la correspondance avec l’identifiant distant et traiter séparément les écritures dont le résultat est inconnu.

Ce tutoriel utilise PHP 8.1 ou supérieur et le paquet pipedrive/pipedrive:19.2.1, avec son namespace API v2. Il montre la configuration utilisable dans Symfony, les modèles de contact et de deal, la pagination et une politique de reprise. Les noms, emails, identifiants et réponses des exemples sont fictifs.

Vous pouvez exécuter les appels avec le SDK officiel et des réponses simulées. Le programme vérifie vingt conditions, dont la transmission du curseur et le blocage d’une seconde création après timeout. Il fonctionne sans token et sans appel HTTP externe.

Pour relier ce code aux règles de vos équipes, Dawap peut cadrer votre connecteur Pipedrive avec vos logiciels métier. Décidez notamment qui valide le rattachement à un compte ERP et qui reprend une création dont le résultat reste inconnu. Si le flux traverse plusieurs outils, ces responsabilités se définissent dans le cadre de votre intégration API CRM.

Choisir le SDK et le périmètre de la première intégration

Le client PHP officiel est généré à partir du contrat OpenAPI. Il fournit les classes d’API, les modèles et la désérialisation. Les namespaces v1 et v2 sont distincts : importer un modèle de la mauvaise version peut changer le chemin, les propriétés ou le type de réponse attendu.

Commencez par une seule relation utile : un contact source, sa fiche Pipedrive et le deal qu’il faut rattacher. Un SDK n’est pas une architecture de synchronisation : il ne choisit ni la source de vérité d’un champ, ni le bon compte ERP, ni la décision à prendre après une réponse perdue. Ne développez pas un nouveau client HTTP si le SDK couvre le contrat ; gardez plutôt les règles métier dans un service séparé.

Installer une version précise du client PHP

La version utilisée ici exige PHP ^8.1, cURL, JSON et mbstring, ainsi que Guzzle. Vérifiez le composer.json du tag choisi plutôt que de déduire les prérequis d’un ancien exemple. Dans un projet Symfony existant, examinez les contraintes de dépendances avant la mise à jour et conservez le fichier de verrouillage.

composer require pipedrive/pipedrive:19.2.1
composer show pipedrive/pipedrive

Le numéro est figé pour rendre ce tutoriel reproductible ; ce n’est pas une recommandation de rester indéfiniment sur cette version. Lors d’une évolution, relancez vos tests de sérialisation et de reprise. La version du paquet et la version de l’API sont deux informations différentes à consigner dans votre procédure de déploiement.

Configurer le client dans Symfony sans exposer les secrets

Pour une intégration par token personnel, le SDK v2 utilise l’en-tête x-api-token. Le token est lié à un utilisateur et à une entreprise. Stockez-le dans le gestionnaire de secrets ou dans une variable d’environnement hors Git. L’exemple de configuration ci-dessous peut vivre dans config/services.yaml ; adaptez les noms de services à votre application.

services:
    app.pipedrive.configuration:
        class: Pipedrive\versions\v2\Configuration
        calls:
            - setApiKey: ['x-api-token', '%env(PIPEDRIVE_API_TOKEN)%']

    app.pipedrive.http:
        class: GuzzleHttp\Client
        arguments:
            - {timeout: 10, connect_timeout: 3}

    Pipedrive\versions\v2\Api\PersonsApi:
        arguments:
            $client: '@app.pipedrive.http'
            $config: '@app.pipedrive.configuration'

    Pipedrive\versions\v2\Api\DealsApi:
        arguments:
            $client: '@app.pipedrive.http'
            $config: '@app.pipedrive.configuration' 

Les délais de dix et trois secondes sont des paramètres d’exemple, à choisir selon vos objectifs de service. Ils bornent l’attente ; ils ne prouvent pas qu’une écriture interrompue a échoué. Un token manquant doit empêcher le démarrage du connecteur, plutôt que produire une rafale de requêtes non autorisées.

Pour une application OAuth, utilisez un flux d’autorisation complet : vérification de state, scopes nécessaires, stockage protégé des jetons et coordination de leur renouvellement. Le SDK expose une configuration OAuth et une notification de mise à jour des tokens. Un worker ne doit pas écraser les jetons renouvelés par un autre. La documentation d’authentification distingue les deux modes ; un access token OAuth ne se copie pas dans le champ réservé au token personnel.

Conserver la correspondance entre vos clés et les ID Pipedrive

EXT-2048 peut être l’identifiant d’un contact dans votre logiciel. L’API Pipedrive attend l’ID numérique de sa fiche pour une mise à jour, par exemple 42. Une correspondance doit donc relier le compte connecté, le type d’objet, la clé source et l’ID distant. Dans une base partagée, la clé source seule ne suffit pas à distinguer deux entreprises clientes.

Il n’existe pas de propriété native universelle external_id à ajouter librement aux requêtes illustrées ici. Une table locale peut porter la correspondance. Si vous utilisez aussi un champ personnalisé Pipedrive, retrouvez sa clé réelle dans le compte cible et placez-la sous custom_fields dans le contrat v2. La clé de quarante caractères du laboratoire est fictive.

Ajoutez une contrainte d’unicité sur la clé de correspondance et sérialisez les créations concurrentes d’un même contact. Une recherche par email aide au rapprochement, mais deux fiches peuvent partager une adresse ; une recherche vide suivie d’un POST n’est pas, à elle seule, un upsert atomique. Un changement d’email ne doit pas faire perdre la relation déjà validée.

Créer un contact et relier un deal avec les modèles v2

Après injection de PersonsApi et DealsApi, les appels suivants utilisent les modèles du paquet fixé plus haut. Sur une vraie connexion, ils créent des données : utilisez une sandbox et des valeurs choisies pour votre recette. Le programme téléchargeable les exécute uniquement avec des réponses simulées.

use Pipedrive\versions\v2\Model\PostPersonRequestBody;
use Pipedrive\versions\v2\Model\UpdatePersonRequestBody;
use Pipedrive\versions\v2\Model\DealPostRequestBody;

$created = $persons->addPerson(new PostPersonRequestBody([
    'name' => 'Alex Martin — fictif',
    'emails' => [['value' => 'alex@example.com', 'primary' => true]],
]));
$personId = $created->getData()?->getId();
if (!$created->getSuccess() || !is_int($personId) || $personId < 1) {
    throw new RuntimeException('Création à rapprocher avant de poursuivre.');
}
// Enregistrer la correspondance avec $personId avant la prochaine étape.
$persons->updatePerson($personId, new UpdatePersonRequestBody([
    'name' => 'Alex Martin — nom corrigé',
]));
$deal = $deals->addDeal(new DealPostRequestBody([
    'title' => 'Renouvellement — fictif',
    'person_id' => $personId,
    'value' => 12500,
    'currency' => 'EUR',
]));

Dans le scénario simulé, les requêtes sont POST /api/v2/persons, PATCH /api/v2/persons/42 et POST /api/v2/deals. Envoyez les adresses sous forme de tableau dans emails. Pour modifier le contact, placez son ID Pipedrive dans l’URL. Pour lui rattacher le deal, transmettez ce même ID dans person_id.

Le montant fictif de 12 500 EUR n’est pas un résultat client. Avant de fixer stage_id, pipeline_id ou org_id, vérifiez leur existence et leurs relations dans le compte autorisé. Un statut commercial gagné ne vaut pas acceptation d’une commande par votre ERP. La correspondance deal–commande demande son propre état confirmé.

Parcourir les contacts avec le curseur retourné

Une première page réussie ne prouve pas que tous les contacts ont été lus. Avec cette version du SDK, la réponse fournit les données et un curseur dans additional_data.next_cursor. Ce curseur est opaque : transmettez-le tel quel, sans calculer la page suivante à partir du nombre de contacts reçus.

$cursor = null;
do {
    $page = $persons->getPersons(limit: 100, cursor: $cursor);
    foreach ($page->getData() as $person) {
        // Écrire ou contrôler cette fiche de façon rejouable.
        $personId = $person->getId();
    }
    $cursor = $page->getAdditionalData()?->getNextCursor();
} while ($cursor !== null && $cursor !== '');

Pour tester le curseur sur deux réponses fictives, le laboratoire limite chaque page à une fiche. En production, adaptez la taille à la limite documentée et à votre budget d’appels. Enregistrez le point de reprise après le traitement de la page pour éviter de sauter des fiches si le processus s’arrête. Les filtres updated_since et updated_until bornent la collecte des contacts modifiés. Prévoyez aussi le traitement des suppressions et des changements de droits.

Bloquer une seconde création après une réponse perdue

Notre fonction ensurePerson utilise trois décisions : aucune correspondance, création en attente et ID confirmé. Elle enregistre l’attente avant le POST. Après un timeout, elle conserve cet état et refuse une seconde création jusqu’au rapprochement. Après une réponse confirmée, un second passage renvoie le même ID sans envoyer un nouveau POST.

Le programme garde ce registre en mémoire pour isoler la décision. En production, il faut un stockage durable, une réservation atomique et une procédure de rapprochement. Un crash après le succès distant mais avant la confirmation locale doit laisser un dossier récupérable. Ne supprimez pas l’état d’attente uniquement pour « débloquer la file ».

Décider après le rapprochement

Le support rapproche le compte, la clé source et les ID candidats. Par exemple, si l’envoi pour EXT-2048 a expiré, une fiche au nom d’Alex Martin ne suffit pas à confirmer la création. Vérifiez la référence source enregistrée dans le champ personnalisé. Cette décision évite que les équipes corrigent des commandes ou des factures réparties entre deux fiches.

  • Une fiche correspond à la référence source. Vérifiez le compte et le champ de correspondance, puis enregistrez l’ID avant de reprendre le rattachement du deal.
  • Plusieurs fiches correspondent ou la recherche est incertaine. Conservez l’état d’attente et transmettez au responsable CRM la référence source et les ID trouvés.
  • L’absence de création est confirmée. Autorisez une nouvelle tentative sous la même clé source et enregistrez la décision. Une recherche vide à elle seule ne suffit pas.

Distinguer authentification, validation et quotas

  • 401 : vérifier le mode d’authentification, la validité et le renouvellement. Répéter le même appel avec le même secret invalide ne corrige rien.
  • 403 : vérifier l’accès à l’objet et les permissions du compte. Ne pas élargir automatiquement les droits.
  • Erreur de validation : conserver les champs et la cause utile, corriger l’entrée puis préparer une nouvelle tentative contrôlée.
  • 429 : distinguer un pic d’appels du budget journalier partagé. Reporter le travail selon le diagnostic et les informations retournées, plutôt que relancer tous les workers.
  • Timeout sur une écriture : résultat inconnu, rapprochement avant nouvelle création.

Le témoin renvoie un 429 fictif avec Retry-After: 60 et vérifie que l’application reçoit l’erreur. Il ne prétend pas que Pipedrive envoie cet en-tête dans toutes les situations, ni qu’attendre soixante secondes restaure un budget quotidien. Les coûts par endpoint et les limites instantanées sont à relire dans la documentation des limites API.

Recevoir les événements sans confondre livraison et traitement

Un contrôleur Symfony de réception doit authentifier l’entrée selon le mécanisme configuré, vérifier le format et stocker durablement l’événement avant de confirmer sa réception. Le travail métier peut ensuite être confié à Messenger. Un succès HTTP de réception ne signifie pas que le deal est déjà synchronisé dans l’ERP.

Pour les webhooks généraux v2, le contrat contient notamment meta.id, meta.entity_id, meta.attempt, data et previous. Dédupliquez avec le compte et l’identité de l’événement ; l’identité de l’objet seule bloquerait ses modifications suivantes. Conservez ensuite une idempotence métier pour l’effet à produire. La documentation des webhooks v2 décrit le payload et l’authentification HTTP Basic configurable. N’inventez pas une signature HMAC commune à toutes les notifications.

Un événement plus ancien reçu après une correction manuelle ne doit pas écraser automatiquement cette correction. Le consommateur relit l’état nécessaire et applique la priorité d’écriture décidée pour le champ. Un test d’ordre inversé et un test de livraison répétée doivent faire partie de la recette. Le laboratoire SDK ne simule pas la livraison native des webhooks.

Exécuter le laboratoire et comprendre ses limites

Téléchargez le programme PHP complet, enregistrez-le comme demo.php dans un répertoire de travail, puis installez le paquet et lancez-le. Il n’utilise aucun secret ni service Symfony du site.

composer require pipedrive/pipedrive:19.2.1
php demo.php
{
    "sdk": "pipedrive/pipedrive:19.2.1",
    "checks": 20,
    "simulated_requests": 7,
    "external_http_calls": 0,
    "person_id": 42,
    "deal_id": 5071,
    "unconfirmed_creation": "blocked_pending_reconciliation"
}

Les vingt contrôles couvrent deux pages, le curseur transmis, les méthodes et chemins HTTP, la clé personnalisée, le rattachement du deal, la réutilisation d’une correspondance et le refus d’un second POST après timeout. L’exception 429 remonte sans retry automatique. Toute réponse différente dans un scénario contrôlé arrête le programme.

Ce résultat a été reproduit avec PHP 8.5 et le paquet 19.2.1. Le transport Guzzle intercepte les sept requêtes. Pour valider votre propre connecteur, vérifiez dans votre sandbox les droits du compte, les champs disponibles et la reprise après redémarrage avec votre stockage durable.

Préparer la recette de votre connecteur

  1. Identifier le compte et le mode d’accès ; vérifier les champs réellement disponibles.
  2. Créer une fiche témoin, conserver son ID et confirmer le rattachement du deal.
  3. Repasser la même clé source et vérifier l’absence de seconde création.
  4. Simuler une réponse perdue, puis faire réaliser le rapprochement par la procédure prévue.
  5. Tester pagination interrompue, permissions insuffisantes, budget épuisé et événement retardé.
  6. Vérifier les logs expurgés : corrélation, objet, décision et action suivante, sans token ni données personnelles superflues.

Deux signaux faibles méritent une revue : la hausse des recherches par email malgré des mappings censés exister, et la progression des états en attente après les redémarrages. Le premier suggère une perte d’identité ; le second peut révéler une fenêtre de confirmation mal protégée. Mesurez ces causes avant d’augmenter le nombre de workers. Une file plus rapide peut consommer le budget et multiplier les collisions.

Un repli doit suspendre les créations du périmètre concerné, conserver les correspondances et les événements déjà reçus, puis permettre un redémarrage par lot. Restaurer une version de code n’annule pas les fiches déjà créées dans Pipedrive. Le support doit savoir quel dossier vérifier et quelle confirmation autorise la suite.

Approfondir les règles CRM et ERP

Après avoir vérifié la requête et sa réponse, choisissez le contrôle métier qui manque à votre flux. La création d’un contact, la fusion d’organisations et la mise à jour d’un champ de référence exigent chacune une preuve différente.

Le transport ne suffit pas à prouver le parcours. Les implémentations de formulaire vers le lead et de rattrapage après panne ajoutent une persistance SQLite testée et un journal d’effets. Elles utilisent Python et un transport injectable : leurs règles de reprise peuvent être portées dans Symfony, sans prétendre partager le même SDK.

Conclusion : un SDK vérifié, une reprise décidée

Le client officiel donne un contrat concret pour préparer les appels v2. Les chemins versionnés, les modèles et les identifiants numériques peuvent être contrôlés avant toute ouverture de flux. Cette vérification évite de bâtir une intégration sur des exemples impossibles à reproduire.

Le registre de correspondance et la décision après timeout restent des responsabilités applicatives. Le laboratoire montre une politique conservatrice ; son passage en production demande un stockage durable, une coordination des écritures et une recette avec le compte cible.

Avant d’ajouter un nouveau flux, rejouez un contact déjà confirmé et une création dont la réponse a été perdue. La recette doit montrer quel ID est réutilisé et quel dossier reste à rapprocher.

Dawap vous accompagne pour intégrer Pipedrive à votre système d’information. Avec vos équipes et votre installateur ERP, nous définissons le premier échange, les règles de rattachement et les vérifications à réaliser avant la mise en service.

Portrait de Jérémy Chomel

Relier un premier flux à Pipedrive

Nous définissons les identifiants, les écritures permises et les scénarios de reprise avec vos équipes.

Articles recommandés

Pipedrive : objets, champs personnalisés et webhooks v2 Intégration API Pipedrive : utiliser les objets, champs et webhooks v2 Lire l'article
  • 7 septembre 2024
  • Lecture ~16 min

Réussir une première lecture ne suffit pas à fiabiliser un échange CRM. Ce guide explique les accès Pipedrive, les contacts et les affaires, puis les champs personnalisés, les curseurs et les quotas. Il relie les webhooks aux règles de reprise et aux décisions ERP, avec des exemples à adapter dans une sandbox.

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.

Préparer la reprise de votre flux Pipedrive

Définissons ensemble quels dossiers peuvent être rejoués et quelles écritures nécessitent un rapprochement.