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 ?
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 ?
Comment mettre à jour le JSON V1 vers le JSON V2 ?
L'objet `qualification`
L'objet `qualification`
Les champs qui décrivaient la qualification à la racine du payload V1 sont regroupés dans l'objet qualification :
L'objet `contact`
L'objet `contact`
L'objet `salesperson`
L'objet `salesperson`
Les champs personnalisés (customFields)
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 valeurs supportent désormais plusieurs types : string, number, boolean et date (format ISO 8601). En V1, toutes les valeurs étaient des chaînes de caractères.
Les champs supprimés
Les champs supprimés
Exemple complet : Avant / Après
Exemple complet : Avant / Après
Payload 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 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
Checklist de test migration
💡 Conseil : Utilisez le champ **"test": true*** de la V2 pour valider votre nouveau format* sans impacter vos données de production. Envoyez quelques contacts de test, vérifiez qu'ils 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 :
firstNameau lieu defirstname,salesPersonau lieu desalesperson. Vérifiez chaque champ.Profitez des customFields typés. En V2, les valeurs de
customFieldssupportent les typesnumber,booleanetdateen plus destring. Utilisez-les pour transmettre des données structurées ("budget": 500000plutô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é.