⛰️ Stratégie de Migration V1 vers V2 | PINPO Academy

ℹ️ IMPORTANT : La consultation des articles liés à votre méthode d'intégration est primordiale afin de bien comprendre comment réaliser votre migration.

Quelle stratégie de migration adopter ?

Phase 1 — Préparer (sans impact production)

Auditez votre code en listant tous les champs que vous lisez ou écrivez, en entrée et en sortie.
Créez un tableau de correspondance V1 → V2 spécifique à votre implémentation.
Développez la version V2 de votre code sur une branche séparée.

Phase 2 — Tester (environnement de test)

Envoyez des contacts de test via l'API V2 avec "test": true.
Configurez un webhook de test pointant vers un endpoint de capture (webhook.site, RequestBin, ou un endpoint dédié dans votre environnement de staging).
Comparez les payloads reçus avec ceux que vous receviez en V1. Vérifiez que chaque champ que vous utilisez est bien présent et au bon endroit.
Déroulez une conversation complète jusqu'à la fin de traitement et vérifiez la cohérence des données dans votre CRM de test.

Phase 3 — Basculer (production)Déployez le code V2 en production.

Mettez à jour les URLs d'import dans vos systèmes (une URL par agent).
Mettez à jour les webhooks dans Pinpo si nécessaire (les endpoints restent les mêmes, seul votre code de traitement change).
Surveillez les premières heures : taux d'erreur API, réception des webhooks, cohérence des données dans le CRM.

Phase 4 — Nettoyer

Supprimez le code V1 de votre codebase. Ne le conservez pas "au cas où" — un code mort est un code trompeur.
Mettez à jour votre documentation interne (schémas de données, runbooks, README).

Important : Ne maintenez pas les deux versions en parallèle en production. Un mix V1 entrée / V2 sortie (ou l'inverse) crée des incohérences de format et de nommage impossibles à déboguer proprement.

Que se passe-t-il si je ne migre pas ?

Lorsque Pinpo désactivera la V1 et que votre code n'est pas migré, voici ce qui se produira :

Composant	Impact
API d'import	Vos requêtes seront rejetées (erreur 400 ou 404). Plus aucun contact ne sera envoyé à Pinpo.
Webhook de sortie	Votre code de parsing lèvera des erreurs sur chaque champ renommé ou déplacé. Les données ne seront pas traitées.
CRM	Plus aucune qualification ne remontera. Vos commerciaux ne recevront plus de leads qualifiés.

🌟 - Bonnes pratiques

Auditez avant de coder. Un inventaire complet des champs utilisés prend 30 minutes et vous évite des heures de débogage.
Testez avec "test": true. Ce champ V2 est fait pour ça. Utilisez-le pour valider votre code sans polluer la production.
Déployez entrée et sortie en même temps. Migrer l'un sans l'autre crée un état intermédiaire incohérent.
Surveillez activement après le déploiement. Les premières 24 heures post-migration sont critiques. Gardez un œil sur les erreurs et les données dans le CRM.
Conservez les payloads bruts. Pendant la phase de migration, loguez les payloads JSON reçus en sortie. En cas de bug de mapping, vous pourrez les rejouer sans attendre une nouvelle qualification.
Communiquez avec votre équipe. Prévenez les commerciaux qu'une migration technique est en cours. Un bref délai dans la remontée des leads est normal pendant la bascule.
ID de l’agent. Les {{agentId}} sont présents sur la plateforme PINPO (Intégrations>Connexion via API KEY > ID de l’agent)