⛰️ ENTRÉE - Migration V1 vs 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.

La V2 de l'API Pinpo simplifie et restructure le format d'envoi des contacts. Si vous utilisez actuellement la V1, cet article vous guide pas à pas pour adapter vos appels au nouveau format.

Qu'est-ce qui change entre la V1 et la V2 ?

La V2 apporte quatre changements majeurs :

La déclaration de l'agent est obligatoire. En V1, le champ scenarioSelection était optionnel. En V2, chaque requête doit être envoyée à l'URL d'import spécifique de l'agent cible (https://api.pinpo.com/agents/{id_agent}/qualifications). Il n'est plus possible d'envoyer un contact sans préciser l'agent qui le traitera.
Une structure plus claire. Le payload est réorganisé autour de trois objets principaux : qualification, contact et salesperson. Les champs éparpillés à la racine en V1 sont désormais regroupés logiquement.
Des champs personnalisés simplifiés. Les trois tableaux scriptData, statsData et outputData (format nom/valeur) sont remplacés par un unique objet customFields avec des paires clé/valeur typées.
Des conventions de nommage harmonisées. Les noms de champs passent en lowercase (firstName → firstname, salesPerson → salesperson).

Comment mettre à jour le JSON V1 vers le JSON V2 ?

L'objet `qualification`

Les champs qui décrivaient la qualification à la racine du payload V1 sont regroupés dans l'objet qualification :

Champ V1	Champ V2	Notes
`externalId` (racine)	`qualification.externalId`	L'identifiant de la qualification dans votre système.
`providerName`	`qualification.source`	Renommé. La source marketing du contact.
`scenarioSelection`	(supprimé)	L'agent cible est désormais déterminé par l'URL d'import (qui contient l'ID de l'agent). Ce champ n'existe plus. En V2, la déclaration de l'agent est obligatoire : chaque requête doit être envoyée à l'URL spécifique de l'agent cible (`https://api.pinpo.com/agents/{id_agent}/qualifications`). En V1, le champ `scenarioSelection` était optionnel.
(n'existait pas)	`qualification.test`	Nouveau. Booléen. Si `true`, la qualification est créée en mode test (visible uniquement dans l'onglet Qualifications de test).

L'objet `contact`

Champ V1	Champ V2	Notes
`contact.firstName`	`contact.firstname`	Casse modifiée : camelCase → lowercase.
`contact.lastName`	`contact.lastname`	Casse modifiée : camelCase → lowercase.
`contact.phone`	`contact.phone`	Inchangé. Le format international avec `+` est recommandé (par exemple : `+33606060606`).
`contact.mail`	`contact.mail`	Inchangé.
`contact.externalId`	`contact.externalId`	Inchangé. L'identifiant du contact dans votre système.
`contact.gender`	`contact.gender`	Inchangé.

L'objet `salesperson`

Champ V1	Champ V2	Notes
`salesPerson.firstName`	`salesperson.firstname`	Renommé : `salesPerson` → `salesperson` (un seul mot) + lowercase.
`salesPerson.lastName`	`salesperson.lastname`	Idem.
`salesPerson.phone`	`salesperson.phone`	Inchangé.
`salesPerson.mail`	`salesperson.mail`	Inchangé.
`salesPerson.externalId`	`salesperson.externalId`	Inchangé.
`salesPerson.iCalUrl`	`salesperson.iCalUrl`	Inchangé.
(n'existait pas)	`salesperson.gender`	Nouveau. Le genre du commercial.

Les champs personnalisés (`customFields`)

C'est le changement le plus structurant. En V1, les données personnalisées étaient réparties dans trois tableaux distincts au format nom/valeur.
En V2, elles sont regroupées dans un unique objet qualification.customFields avec des paires clé/valeur.

Avant (V1) :

{
  "scriptData": [
    { "name": "location", "value": "Scranton" },
    { "name": "postalCode", "value": "18501" }
  ],
  "statsData": [
    { "name": "day", "value": "Monday" }
  ],
  "outputData": [
    { "name": "civility", "value": "Mr" }
  ]
}

Après (V2) :

{
  "qualification": {
    "customFields": {
      "location": "Scranton",
      "postalCode": "18501",
      "day": "Monday",
      "civility": "Mr"
    }
  }
}

Les champs supprimés

Champ V1	Statut en V2
`scenarioSelection`	Supprimé. L'agent est déterminé par l'URL d'import.
`product` (objet complet)	Supprimé. Si vous avez besoin de transmettre des informations produit, utilisez `qualification.customFields`.
`company` (objet complet)	Supprimé. Si vous avez besoin de transmettre des informations entreprise, utilisez `qualification.customFields`.

Exemple complet : Avant / Après

Payload JSON V1

{
  "contact": {
    "firstName": "John",
    "lastName": "Doe",
    "phone": "33606060606",
    "mail": "[email protected]",
    "externalId": "abcd1234",
    "gender": "male"
  },
  "externalId": "efghi56789",
  "providerName": "Facebook leads",
  "scenarioSelection": "kopij876f",
  "product": {
    "name": "Ream of Paper",
    "category": "new",
    "externalId": "120paperream"
  },
  "salesPerson": {
    "firstName": "Michael",
    "lastName": "Scott",
    "phone": "33707070707",
    "mail": "[email protected]",
    "externalId": "scrantonms111",
    "iCalUrl": "https://michaelscott.dundermifflin.ical.fr"
  },
  "company": {
    "name": "Dunder Mifflin Paper Company Inc",
    "externalId": "huih89hhgh"
  },
  "scriptData": [
    { "name": "location", "value": "Scranton" },
    { "name": "postalCode", "value": "18501" }
  ],
  "statsData": [
    { "name": "day", "value": "Monday" }
  ],
  "outputData": [
    { "name": "civility", "value": "Mr" }
  ]
}

Payload JSON V2 équivalent

{
  "qualification": {
    "externalId": "efghi56789",
    "source": "Facebook leads",
    "customFields": {
      "location": "Scranton",
      "postalCode": "18501",
      "day": "Monday",
      "civility": "Mr",
      "productName": "Ream of Paper",
      "productCategory": "new",
      "productExternalId": "120paperream",
      "companyName": "Dunder Mifflin Paper Company Inc",
      "companyExternalId": "huih89hhgh"
    }
  },
  "contact": {
    "firstname": "John",
    "lastname": "Doe",
    "phone": "+33606060606",
    "mail": "[email protected]",
    "externalId": "abcd1234",
    "gender": "male"
  },
  "salesperson": {
    "firstname": "Michael",
    "lastname": "Scott",
    "phone": "33707070707",
    "mail": "[email protected]",
    "externalId": "scrantonms111",
    "iCalUrl": "https://michaelscott.dundermifflin.ical.fr"
  }
}

Remarque : Les données de product et company ont été migrées dans qualification.customFields avec des noms de clés explicites (productName, companyName, etc.). Vous êtes libre de choisir les noms de clés qui correspondent à votre modèle de données.

Checklist de test migration

Étape	Action
1	Remplacer `providerName` par `qualification.source`.
2	Déplacer `externalId` (racine) dans `qualification.externalId`.
3	Supprimer `scenarioSelection` et utiliser l'URL d'import spécifique à l'agent.
4	Renommer `firstName` → `firstname` et `lastName` → `lastname` dans `contact`.
5	Renommer `salesPerson` → `salesperson` et appliquer le lowercase sur `firstname` / `lastname`.
6	Fusionner `scriptData`, `statsData` et `outputData` dans `qualification.customFields`.
7	Migrer les données de `product` et `company` dans `qualification.customFields`.
8	Ajouter le préfixe `+` au numéro de téléphone du contact (format international recommandé).
9	Tester l'appel en V2 avec `"test": true` pour valider le format sans déclencher de conversation réelle.
10	Vérifier la qualification de test dans Pinpo (données du contact, champs personnalisés, commercial assigné).
11	Passer `"test": false` (ou supprimer le champ) et basculer en production.

💡 Conseil : Utilisez le champ "test": true de la V2 pour valider votre nouveau format sans impacter vos données de production.
Envoyez quelques qualifications de test, vérifiez qu'elles apparaissent correctement dans l'onglet Qualifications de test, puis basculez en production une fois la migration validée.

🌟 - Bonnes pratiques

Migrez un agent à la fois. Ne basculez pas tous vos agents en V2 simultanément. Commencez par un agent secondaire, validez le fonctionnement de bout en bout, puis migrez les suivants.
Attention à la casse. Les erreurs les plus fréquentes lors de la migration sont des erreurs de casse : firstName au lieu de firstname, salesPerson au lieu de salesperson. Vérifiez chaque champ.
Profitez des customFields typés. En V2, les valeurs de customFields supportent les types number, boolean et date en plus de string. Utilisez-les pour transmettre des données structurées ("budget": 500000 plutôt que "budget": "500000").
Ne maintenez pas les deux versions en parallèle. Une fois la migration validée, basculez définitivement en V2 pour éviter les incohérences et simplifier la maintenance.
Consultez la documentation technique. La référence complète de l'API V2 est disponible dans la documentation en ligne (bouton Documentation sur la page Intégration API). En cas de doute sur un champ, c'est la source de vérité.
ID de l’agent. Les {{agentId}} sont présents sur la plateforme PINPO (Intégrations> Connexion via API KEY > ID de l’agent)