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/pipedriveLe 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
- Identifier le compte et le mode d’accès ; vérifier les champs réellement disponibles.
- Créer une fiche témoin, conserver son ID et confirmer le rattachement du deal.
- Repasser la même clé source et vérifier l’absence de seconde création.
- Simuler une réponse perdue, puis faire réaliser le rapprochement par la procédure prévue.
- Tester pagination interrompue, permissions insuffisantes, budget épuisé et événement retardé.
- 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.
- Pour choisir les données et les appels à exposer dans votre connecteur, consultez les objets, accès et limites de l’API Pipedrive.
- Si deux organisations fusionnent, vérifiez quel compte ERP doit porter la prochaine commande, même lorsque l’ID CRM est conservé.
- Quand un libellé change, vérifiez la correspondance entre l’option Pipedrive et le code ERP avant de reprendre les écritures.
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.