Produits Pipedrive : fiabiliser les montants du devis

Le client accepte un devis de 216 € TTC. L’ERP affiche 216 € lui aussi, mais la commande contient une seule unité à 180 € au lieu de deux à 100 € avec une remise de 10 %. Le risque apparaît dès que le total sert de seule preuve. Une commande peut avoir le bon montant et la mauvaise quantité.

Conservez la version acceptée, puis rapprochez chaque ligne des références ERP. L’exemple Python montre le calcul sur une vente ponctuelle en euros, avec remise de ligne en pourcentage, taxe ajoutée au prix et arrondi au centime par ligne. Les tests utilisent des données fictives.

Dans une intégration de Pipedrive à l’ERP, convenez avec le commerce et l’ADV du document qui fixe les montants. Ce choix détermine quels champs transmettre et quelles vérifications ajouter aux échanges entre le CRM et les outils de gestion.

Figer le document qui fait autorité

Après acceptation, un commercial peut corriger une ligne, ajouter une remise ou préparer un avenant. Conservez l’identifiant de la décision, la révision, le document approuvé et son détail. Le passage du deal à l’état gagné déclenche la vérification du dossier. L’accord client doit rester rattaché à la version qu’il a acceptée.

Pour qui adopter ce contrôle

Si le CRM porte les lignes acceptées, alors transmettez la version figée avec les unités, les remises et le mode de taxe. Si l’ERP établit le document à partir d’une référence d’offre, alors transmettez cette référence et rapprochez le devis calculé par l’ERP de celui que le client accepte. Identifiez l’équipe qui peut modifier chaque donnée après accord.

Le programme reçoit une révision et un total de référence. Il vérifie le calcul. Pour contrôler aussi le contenu accepté, comparez les lignes par référence, quantité, unité, prix, remise et taxe avec le document archivé. La vérification de l’acceptation s’inscrit dans le parcours du deal à la facture ERP.

Paradoxalement, deux configurations peuvent produire le même net et la même taxe. Dans le scénario à 216 €, la ligne unique à 180 € passerait le contrôle du total. L’ADV doit alors comparer les quantités et la remise à la version approuvée avant d’envoyer la commande. Le registre de validation doit conserver la preuve de cette comparaison.

Le contrat d’entrée doit préciser comment identifier une ligne dans le document accepté et dans le payload CRM. Si le devis archivé ne conserve pas l’identifiant de rattachement, alors prévoyez une correspondance de lignes lors de son approbation. Une référence produit peut apparaître deux fois avec le même prix. Demandez à l’ADV de lever l’ambiguïté avant la mise en file de la commande.

Lire les lignes attachées à l’affaire

La référence Deal Products distingue le produit du catalogue et son rattachement à une affaire. La ligne attachée porte notamment quantité, prix et remise. Deux lignes peuvent utiliser le même produit sans constituer un doublon : elles peuvent correspondre à deux lots ou conditions distinctes.

L’endpoint GET /api/v2/deals/{id}/products est paginé. Le champ id identifie le rattachement, product_id le produit et product_variation_id une éventuelle variante. Gardez l’ID du rattachement dans la sortie. Deux lignes du même produit doivent pouvoir conserver leurs quantités et conditions respectives. Consulter le schéma des lignes en API v2.

snapshot = quote_from_api(
    api,
    deal_id=5071,
    revision="devis-accepte-v1",
    sku_map={12: "ERP-SKU-A"},
    accepted_gross="216.00",
)

Contrôler aussi les remises du deal

La fonction quote_from_api relit la devise de l’affaire et interroge GET /api/v2/deals/{id}/discounts. Si la réponse contient une remise globale, alors le calcul est bloqué. Le contrat prend uniquement en charge les remises par ligne. Consulter la lecture des remises de l’affaire.

Les lignes dont is_enabled vaut false sont exclues. Si toutes les lignes sont désactivées, le document est refusé. Les variantes identifiées sont mises en attente. En cas de lecture directe du CRM, rattachez le payload à une révision de référence. Les produits, les remises et la devise proviennent de lectures séparées, qui peuvent avoir lieu pendant une modification.

Si le connecteur reçoit un webhook lors du passage à « gagné », utilisez-le pour retrouver le document accepté dans le registre. Le webhook déclenche la lecture. La pagination REST et l’obtention de la remise globale doivent toutes deux aboutir avant le calcul. En cas de délai dépassé au milieu de la lecture, reprenez depuis le même document de référence et vérifiez sa révision.

Rapprocher les produits avec une table approuvée

Une désignation commerciale n’est pas une référence de gestion. Elle peut être renommée, traduite ou abrégée. La table de correspondance relie un identifiant Pipedrive à une référence ERP approuvée dans le bon contexte : entreprise, catalogue, unité et, lorsque le besoin existe, variante.

L’exemple associe le produit 12 à ERP-SKU-A. Un produit inconnu bloque le devis. Il ne produit pas une ligne libre sans contrôle, ni une référence trouvée par ressemblance de libellé. Les données de démonstration n’incluent pas les unités multiples ; une conversion boîte/pièce ou heure/jour doit avoir une règle supplémentaire vérifiée.

Versionner les correspondances utilisées

Conservez la version du mapping avec le document converti. Par exemple, le produit 12 peut être vendu à la pièce et conditionné par boîte de dix dans la gestion. Enregistrez la règle d’unité appliquée lors de l’acceptation pour expliquer le passage de dix pièces à une boîte. Le cas d’une option Pipedrive renommée montre comment faire valider une correspondance lorsque son sens commercial évolue.

La bonne résolution d’un produit inconnu est donc une décision de référentiel. Le support peut préparer le dossier avec ID, ligne, libellé et proposition de correspondance, mais l’activation doit revenir à l’équipe qui possède le catalogue et les règles de gestion.

Calculer le net, la taxe et le total par ligne

Pour cette ligne fictive, le prix unitaire est de 100 €, la quantité de 2 et la remise de 10 %. Avec une taxe de 20 % ajoutée au prix, le net vaut 180 €, la taxe 36 € et le total 216 €. Le calcul utilise Decimal. Les valeurs du jeu d’essai sont fournies sous forme de chaînes. Sur un flux JSON réel, vérifiez la précision au décodage avant de convertir les montants.

quantity = Decimal("2")
price = Decimal("100.00")
discount = Decimal("10")
tax = Decimal("20")
net = cents(quantity * price * (1 - discount / 100))
tax_amount = cents(net * tax / 100)
gross = net + tax_amount

La fonction cents applique ROUND_HALF_UP à deux décimales. Elle arrondit d’abord le net de la ligne, puis sa taxe. Faites valider cet ordre avec l’équipe comptable et l’installateur ERP. Si l’ERP arrondit à l’échelle du document, alors reprenez les exemples avec cette règle avant de valider le flux.

Comparer l’arrondi de ligne au calcul attendu

Le dernier cas montre pourquoi il faut décider où arrondir. Arrondir d’abord le prix unitaire à 0,34 €, puis multiplier par trois produirait 1,02 €. Ajouter une tolérance générale d’un centime ferait disparaître le symptôme sans résoudre la différence de méthode.

Pour tester l’arrondi par document, prenez deux lignes fictives à 0,335 € chacune avec un taux de 0 %. Le contrat fourni arrondit chacune à 0,34 €, soit 0,68 € au total. Un arrondi unique après addition donne 0,67 €. Comparez les deux résultats au document ERP de recette pour déterminer quel niveau d’arrondi doit entrer dans le contrat.

Le calcul refuse quantités nulles ou négatives, prix négatifs, remises hors de l’intervalle accepté et valeurs non finies comme NaN. Les booléens sont refusés comme montants. Une validation des types JSON n’épuise pas la validation métier : true ne devient pas une quantité de 1 par accident.

Mettre en attente les conditions hors périmètre

Le calcul exige tax_method=exclusive et une remise de ligne en pourcentage. Il refuse les modes inclusive et none, ainsi que les remises en montant, les devises hors euro, les variantes et les fréquences récurrentes identifiées. Vérifiez aussi la devise des lignes au moment de qualifier le devis. L’exemple contrôle celle du deal.

Un échéancier demande un contrôle distinct. Le lecteur de démonstration ne lit pas /api/v2/deals/installments. Avant d’utiliser son contrat sur de vraies affaires, écartez celles qui ont des échéances de paiement ou définissez leur conversion avec l’ADV. Consulter l’API des échéances du deal.

Si le total calculé vaut 216 € et que le devis accepté indique 215,99 €, alors l’exemple bloque la conversion. Le dossier de rejet doit réunir la révision, le montant calculé, le montant attendu et la ligne à l’origine de l’écart si elle est connue. L’ADV peut ainsi corriger la règle avant qu’un écart de devis ne devienne un avoir.

Transmettre une version et préserver son acceptation

La sortie de quote_snapshot contient le deal, la révision, la devise, les lignes converties et le total. Le journal calcule une empreinte de cette sortie. Pour la traçabilité, conservez séparément les lignes sources et la version du mapping. Réutilisez le document converti déjà archivé lors d’une reprise. Une lecture des lignes courantes pourrait changer le contenu ou l’ordre pris en compte dans l’empreinte.

Après une réponse perdue, la reprise cherche d’abord le document par cette clé. Une commande correspondant à l’empreinte attendue peut être rapprochée. Une autre révision doit être traitée comme avenant ou conflit selon le métier, sans écrasement silencieux de la commande acceptée.

Le simulateur impose l’unicité de la référence dans SQLite. Vérifiez avec votre installateur que l’ERP accepte une référence externe et permet de la retrouver. En cas de timeout, appliquez le rapprochement après une panne. Si la preuve manque, confiez la décision à l’ADV. Pour les lectures, consultez les objets et champs de l’API Pipedrive ou le tutoriel SDK pour Symfony.

Plan d’action pour tester le premier flux

Téléchargez et extrayez l’archive de code et de tests, puis exécutez ces commandes avec Python 3.11 ou supérieur. Le bloc products de la sortie affiche 180 € de net, 36 € de taxe et 216 € de total.

python3 demo.py
python3 test_integration.py -v

Les 48 tests de l’archive couvrent cinq parcours. Pour le devis, ils vérifient les trois résultats du tableau, la pagination sur deux pages, les références inconnues, les rattachements en double et les refus de calcul. Un test fournit une remise globale à quote_from_api et vérifie que le document est retenu.

Pour la recette avec vos outils, choisissez un devis accepté de test. L’équipe commerciale vérifie la version et les lignes approuvées. L’ADV compare la sortie ERP par référence, unité et montant. Le support vérifie la traçabilité des rejets et la reprise après une réponse perdue. Validez les droits API et les règles de calcul dans l’environnement de recette autorisé.

Erreurs fréquentes à rechercher dans le connecteur existant

Pour chaque dossier rejeté, vérifiez quelle entrée a déclenché le blocage. La journalisation doit indiquer la référence, la révision et la règle en défaut. Dans la file de traitement, séparez les écarts de référentiel des montants à revoir. Les équipes concernées pourront agir sans relire tous les appels du connecteur.

Rejouez en recette une référence absente puis une taxe différente. Dans le premier scénario, le dossier doit rester en attente du catalogue. Dans le second, consignez le montant attendu et l’écart observé pour que l’ADV valide le calcul. Une nouvelle soumission du même dossier doit retrouver la décision en attente.

• Indexer les lignes par produit et perdre un second rattachement.
• Ignorer une remise globale ou une ligne désactivée.
• Appliquer une règle d’arrondi sans l’avoir confrontée au document cible.
• Lire le deal courant comme preuve de la version acceptée auparavant.
• Corriger automatiquement une différence de montant au lieu de la qualifier.

Déployer le premier contrat de conversion

Le premier lot couvre un catalogue réduit, une devise et un mode de taxe. Convenez d’un délai de traitement pour les devis placés en attente et attribuez chaque motif à un responsable. Une référence inconnue relève du référentiel. Une différence de prix ou de remise doit être revue avec la personne qui a approuvé le devis.

Suivez les rejets par motif, ainsi que la part des devis dont le détail a été rapproché. Dans ce contrat, le seuil d’écart accepté est de zéro centime. Avant d’élargir le flux, reproduisez un cas avec le même total et deux compositions différentes pour vérifier que la validation métier bloque le mauvais document.

1. Recevoir trois documents approuvés de la vente ou de la gestion avec leur détail de calcul.
2. Faire valider les références ERP et la règle d’arrondi avant de développer le mapping.
3. Refuser les variantes, remises et taxes qui ne sont pas couvertes par le premier contrat.
4. Comparer les documents produits dans les deux systèmes et conserver la révision acceptée.

Conclusion sur le contrôle du devis transmis

Pour chaque commande, le support doit pouvoir retrouver le devis accepté, l’identité des lignes et la version des règles appliquées. Une divergence de quantité, de référence ou de prix reste à expliquer même lorsque le montant total correspond.

Ouvrez le flux après comparaison du premier lot dans les deux outils. Pour les devis en attente, consignez le motif et la personne qui peut valider la correction. Lors d’une reprise, retrouvez d’abord la référence ERP et la révision déjà acceptée.

Pour cadrer votre intégration Pipedrive–ERP, Dawap peut vous aider à tester les lignes, les remises et les arrondis avec l’ADV et votre installateur ERP, puis à définir le traitement des écarts.