Après une maintenance, le récepteur de webhooks répond de nouveau. Plusieurs ventes gagnées restent à rapprocher et un commercial ne voit toujours pas le numéro de commande. Le risque est de recréer une commande alors que l’ERP l’a déjà enregistrée et que seul le retour vers Pipedrive manque.
Retrouvez d’abord les affaires gagnées modifiées pendant la période concernée. Enregistrez les observations et le point de reprise ensemble. Puis, pour chaque affaire, relisez son état et cherchez la commande existante avant d’autoriser une création. L’exemple téléchargeable reproduit ce parcours avec des réponses simulées et un journal SQLite.
Dans une intégration Pipedrive avec l’ERP, décidez avec l’ADV comment retrouver la commande et qui peut débloquer un dossier. Le même rapprochement peut servir aux autres flux du CRM vers les applications métier.
Déterminer ce que le récepteur a réellement perdu
En cas d’échec initial, Pipedrive prévoit trois nouvelles tentatives après 3, 30 et 150 secondes. Dix échecs en première tentative peuvent suspendre la souscription pendant 30 minutes. Les notifications émises pendant la suspension sont perdues. Pipedrive supprime également un webhook après trois jours consécutifs sans livraison réussie. Consulter les règles de livraison des webhooks v2.
La première vérification porte donc sur la souscription, ses droits, les réponses du récepteur et la période d’indisponibilité. Un service qui répond 2XX avant d’avoir stocké la notification peut avoir accusé réception d’un événement qu’il a ensuite perdu. À l’inverse, une commande peut exister dans l’ERP alors que seul le retour vers le CRM manque.
Pour qui lancer un rattrapage borné
Le parcours vise une panne identifiée sur le flux des ventes gagnées. Il ne reconstruit pas un miroir exhaustif du CRM. Les objets supprimés ou archivés, les changements de permissions et les affaires repassées à perdu demandent des campagnes et des règles spécifiques. Une absence de ligne dans une collecte filtrée ne prouve pas que l’objet n’a jamais existé.
Si vous ignorez la période de perte, commencez par comparer les références connues des deux systèmes et les journaux d’exécution. L’article sur la réconciliation entre source et cible aide à construire cette comparaison sans confondre les compteurs de pages, d’objets et de documents métier.
Fixer une fenêtre de lecture et garder ses bornes
L’API Deals v2 permet de filtrer sur updated_since et updated_until. Dans la référence officielle Deals, la borne basse inclut l’instant donné et la borne haute l’exclut. Les dates utilisent un fuseau explicite au format RFC3339.
L’exemple collecte du 5 novembre à 00 h UTC inclus au 6 novembre à 00 h UTC exclu. Il lit le statut courant won et trie sur update_time. Une affaire gagnée plus tôt peut apparaître si elle a été modifiée pendant cette fenêtre. Gardez les mêmes bornes et le même filtre sur toutes les pages.
query = {
"status": "won",
"updated_since": start,
"updated_until": end,
"sort_by": "update_time",
"sort_direction": "asc",
"limit": 100,
}
if cursor:
query["cursor"] = cursor
response = api.request("GET", "/api/v2/deals", query=query)L’API peut rendre une affaire visible tardivement ou faire évoluer son update_time pendant la lecture. Par exemple, si une modification déplace l’affaire après la borne haute, alors la fenêtre suivante pourra la récupérer. Prévoyez une réconciliation périodique pour les écarts persistants. Le collecteur de l’archive impose un début égal au checkpoint courant. Une lecture de recouvrement doit donc passer par un traitement distinct qui conserve ce checkpoint.
Séparer les progressions de chaque flux
Le checkpoint de l’exemple utilise une clé locale pour un compte Pipedrive et un filtre. En production, identifiez la progression par société, connexion et périmètre du flux. Si une autre connexion ou un nouveau filtre entre en service, alors définissez sa fenêtre initiale et rapprochez ses données avec l’ERP avant d’enregistrer un checkpoint.
Conservez la version du filtre et les bornes dans le journal d’exécution. Par exemple, après le remplacement d’une connexion OAuth, vérifiez qu’elle donne accès à un dossier connu de chaque pipeline attendu. Si la nouvelle connexion ne voit qu’un sous-ensemble des affaires, alors une page vide peut faire avancer le point de reprise en laissant des ventes de côté.
Parcourir les pages sans sauter les objets simultanés
Plusieurs deals peuvent partager le même horodatage de modification. Enregistrer simplement le dernier timestamp reçu, puis repartir strictement après lui, risque d’écarter les autres objets portant cet instant. Le curseur opaque fourni par l’API sert à poursuivre la même collecte ; il ne doit pas être fabriqué à partir d’un ID ou d’une date.
Le code suit additional_data.next_cursor jusqu’à une valeur nulle. Il refuse une réponse dont les métadonnées de pagination manquent, un curseur vide ou répété et un nombre de pages dépassant la limite locale. Ces refus sont des échecs de collecte : aucun ne doit être transformé en « dernière page » par commodité.
additional = response.get("additional_data")
if not isinstance(additional, dict) or "next_cursor" not in additional:
raise ReviewRequired("Pagination metadata absent")
cursor = additional["next_cursor"]
if cursor is None:
break
if not isinstance(cursor, str) or not cursor or cursor in seen_cursors:
raise ReviewRequired("Invalid or repeated cursor")Borner la mémoire et la promotion des pages
Le collecteur conserve les pages en mémoire, avec une limite de 20 pages et 100 affaires demandées par page. Si le plafond est atteint avant le dernier curseur, alors réduisez la durée de la fenêtre et repartez depuis le même début. Pour une reprise volumineuse, enregistrez les pages dans une table de préparation liée à l’exécution. Rendez-les visibles au consommateur après validation de la dernière page et du checkpoint.
Les lignes reçues sont aussi contrôlées : identifiant entier, statut attendu et date dans la fenêtre. Une observation inattendue provoque un arrêt et conserve le checkpoint précédent. Le support peut alors examiner le contrat plutôt que publier un nouveau point de reprise sur une collecte incohérente.
Valider ensemble l’inbox et le point de reprise
Après réception de toutes les pages, une transaction SQLite écrit les observations dans l’inbox et avance le checkpoint. La clé d’observation combine deal_id et update_time. Si deux lignes portent la même clé mais des données différentes, la transaction est annulée. Cette idempotence concerne la capture. Le consommateur tient un journal d’écriture distinct pour la commande et pour le retour CRM.
Cette transaction vérifie que le checkpoint n’a pas été avancé par un autre collecteur depuis le début de la lecture. Deux exécutions ne peuvent donc pas considérer simultanément leur progression comme acquise. Si une insertion ou ce contrôle échoue, l’ensemble est annulé.
La transaction du collecteur suit cet ordre. Le dernier point de reprise reste exploitable si l’écriture s’interrompt avant le COMMIT.
- Ouvrir une transaction avec
BEGIN IMMEDIATEet relirewon-checkpoint. - Vérifier les conflits, puis insérer les observations dans
inbox. - Écrire la borne haute dans
metaet valider les deux écritures ensemble. Exécuter unROLLBACKen cas d’erreur.
Distinguer capture et acceptation métier
Le checkpoint atteste l’enregistrement de la fenêtre dans l’inbox. Pour la supervision, comparez trois états de sortie par affaire. Elle peut être capturée, rapprochée avec une commande confirmée, ou en attente d’une décision. La file de travail doit garder le motif d’attente et l’identité du responsable qui peut agir.
La persistance doit vivre hors du répertoire public, avec sauvegarde et accès limités. L’archive contient le code, jamais une base client. Pour remplacer SQLite par PostgreSQL ou une autre base, conserver les contraintes d’unicité et la frontière transactionnelle importe davantage que reproduire exactement les noms des tables.
La journalisation du collecteur doit conserver la fenêtre d’entrée, la dernière page validée et la sortie de la transaction. Par exemple, si la deuxième page renvoie 429, enregistrez le statut et la borne de reprise. La file de traitement ne reçoit alors aucune des observations de cette exécution. Dans le rapport, comptez séparément les lignes reçues et les nouvelles clés ajoutées à l’inbox.
Rapprocher les effets ERP avant toute nouvelle commande
L’inbox peut contenir un deal observé plusieurs fois au cours de sa vie. Son consommateur doit relire l’état utile et retrouver le document accepté. Un événement ancien ne doit pas rétablir automatiquement une décision commerciale abandonnée entre-temps. Le programme de commande associé refuse notamment une affaire qui n’est plus gagnée au moment du traitement.
Le rapprochement cherche ensuite une commande par sa référence externe, selon les capacités réelles de l’ERP. Si elle existe et correspond à la version attendue, il reste à confirmer le retour CRM. Si elle existe avec une autre version, la reprise s’arrête : créer une seconde commande ou écraser la première serait une nouvelle décision métier.
Le simulateur ERP fourni démontre une clé externe unique et une recherche fiable. Ces propriétés sont un contrat de démonstration, pas une garantie de toute API ERP. Lorsque la cible ne permet pas de retrouver un résultat de manière certaine, une réponse perdue doit aller en vérification manuelle. L’article du deal Pipedrive à la facture ERP montre le journal de commande et le retour de statut.
Consommer l’inbox avec un document accepté
Le consommateur recover_orders charge le document accepté depuis un registre serveur. Dans le scénario 5071, l’ERP simulé enregistre la commande puis perd la réponse. Le premier passage retourne needs_verification. Le second retrouve DEMO-5071 et confirme le retour CRM. Le deal 5072 reste needs_accepted_document. Au total, une seule commande figure dans l’ERP simulé.
Paradoxalement, une création peut avoir réussi alors que le suivi de l’affaire affiche encore un échec. Donnez la priorité au rapprochement par référence externe. Si l’ERP confirme l’écriture mais que le retour CRM reste incertain, vérifiez le champ de suivi dans Pipedrive avant de débloquer cet effet. Le journal conserve des clés distinctes pour les deux écritures.
Limiter la reprise sans épuiser les autres intégrations
Une panne peut créer un retard important, mais toutes les intégrations du compte continuent à partager son budget API. Le modèle de limitation officiel distingue notamment le budget journalier et les limites de fréquence. Une attente courte ne résout pas automatiquement un budget journalier épuisé.
Le client fourni impose un plafond de requêtes par instance. Pour régler l’ordonnanceur réel, estimez le coût en tokens par endpoint REST et contrôlez les en-têtes de limite de fréquence. Si un token atteint sa limite de fréquence, utilisez la fenêtre de réinitialisation documentée. Si le budget quotidien de la société est épuisé, différez la reprise jusqu’au renouvellement de ce budget. Réservez une capacité au flux courant.
Une erreur 429 sur la deuxième page laisse le point de reprise inchangé. Relancez la fenêtre après résolution de la cause, avec une seule exécution par flux. Pour vérifier les opérations de lecture et les paramètres de connexion, retrouvez les objets, quotas et webhooks de l’API Pipedrive.
Rejouer une panne dans le laboratoire local
Téléchargez les implémentations et leurs tests, extrayez l’archive et lancez les commandes avec Python 3.11 ou supérieur. Le bloc reconciliation affiche deux pages, deux observations SQLite et zéro commande confirmée à l’étape de collecte. Le bloc inbox_consumer détaille ensuite le résultat de chaque dossier.
python3 demo.py
python3 test_integration.py -vLes 48 tests de l’archive couvrent cinq parcours. Pour le rattrapage, ils vérifient la limite de pages, la borne haute exclue, le curseur répété, les métadonnées manquantes et le contenu de l’inbox après un échec. Le cas de réponse ERP perdue vérifie aussi qu’un seul retour CRM est envoyé après rapprochement.
| Épreuve | Résultat attendu |
|---|---|
| Deux pages, même horodatage | Les deux affaires sont conservées avant l’avancement du checkpoint. |
| 429 sur la deuxième page | L’inbox et le checkpoint restent dans leur état antérieur. |
| Fenêtre dont la fin égale le checkpoint courant | Le collecteur retourne zéro et ne refait aucun appel. |
| Même ID et même horodatage, contenu différent | Un conflit annule la transaction. |
| Réponse perdue après enregistrement de la commande | La reprise retrouve la commande par sa référence. Le nombre de commandes reste à une. |
Sur un compte de recette autorisé, faites modifier une affaire pendant la pagination et mesurez son délai de visibilité. Vérifiez les droits de lecture et le retour de statut. Pour un connecteur PHP, notre tutoriel SDK Pipedrive pour Symfony détaille les appels et les erreurs à gérer.
Plan d’action pour rouvrir le flux après la panne
Délimiter la panne à partir des écritures confirmées
Avant de redémarrer les consommateurs, vérifiez les droits de la souscription et la capacité du récepteur à stocker une notification. Partez du dernier checkpoint confirmé. Si vous ne disposez que de journaux HTTP, alors rapprochez quelques affaires des entrées durables et des commandes ERP pour fixer une borne exploitable avec l’ADV. Consignez les périodes et les comptes dont la couverture reste incertaine.
Produisez un rapport par affaire avec la référence du document accepté, la référence de commande recherchée, le résultat ERP et le retour CRM. Le commerce vérifie les affaires encore gagnées. L’ADV tranche les écarts de document. Le support prend en charge les réponses perdues. Convenez d’un délai avant escalade si l’une de ces responsabilités reste sans réponse.
Réouvrir les consommateurs par lots contrôlés
Validez un premier lot, contrôlez les effets dans la cible, puis ouvrez les suivants. Conservez un mécanisme de pause qui bloque les nouvelles créations tout en gardant l’inbox et les preuves déjà obtenues. Si le lot pilote fait remonter une commande à la référence attendue mais au montant différent, suspendez la création pour cette affaire et demandez à l’ADV de vérifier la version acceptée.
Avant de clôturer la panne, comparez la file de reprise et le flux courant. Une nouvelle notification pour une vente déjà rapprochée doit retrouver la même référence de commande. Le seuil de reprise peut porter sur le nombre de dossiers incertains et le délai depuis leur capture. L’instrumentation doit montrer ces deux mesures au support et à l’ADV.
- Vérifier la souscription, ses droits et le stockage du récepteur avant la reprise métier.
- Fixer la première fenêtre depuis une borne fiable et conserver sa fin sur toutes les pages.
- Arrêter le run sans avancer le checkpoint si la pagination ou le budget bloque la collecte.
- Comparer les références ERP avant toute nouvelle commande et isoler les dossiers ambigus.
- Conserver les preuves, surveiller le flux courant et organiser ensuite le recouvrement des observations tardives.
Vérifier le devis et les écritures à reprendre
Si une commande reste à créer, vérifiez les références et les montants du devis accepté avant de reprendre le parcours du deal Pipedrive à la facture ERP. Le document accepté fixe les lignes et les montants que l’ADV peut engager.
Pour reprendre une écriture dont la réponse manque, le formulaire Pipedrive avec journal durable montre la réservation d’un effet, la vérification de l’ID distant et la reprise des étapes suivantes. Le même principe s’applique au retour CRM lorsque l’écriture ERP a déjà été confirmée.
Conclusion sur les critères de reprise
Avant de rouvrir le flux, vérifiez que l’inbox contient les observations de la fenêtre et que le checkpoint correspond à sa borne haute. Pour chaque dossier, consignez la commande confirmée ou le motif qui retient encore la décision.
Validez un premier lot avec l’ADV en comparant les documents ERP et les retours Pipedrive. Mettez les écarts restants en attente avec une référence et un responsable. L’équipe pourra traiter les prochains lots en conservant les mêmes contrôles.
Pour cadrer une intégration Pipedrive avec supervision, Dawap peut vous aider à établir le rapprochement, à vérifier les capacités de recherche de l’ERP et à tester la procédure de reprise avec vos équipes.
