🛠️ API - Qualifications (Unitaire) | PINPO Academy

ℹ️ Voici le lien de la documentation technique (Swagger) ⇒ https://api.pinpo.com/api#/Leads

Envoyer des données depuis vos outils vers Pinpo est la manière la plus flexible d’importer des leads dans PINPO. C'est la “porte d'entrée de vos qualifications” (ENTRY): vous poussez vos qualifications vers Pinpo pour que vos agents les traitent. Cette méthode est recommandée pour centraliser vos données depuis vos systèmes internes.

Pour ce faire, il vous suffit de cliquer sur le bouton Accéder dans la carte Connexion via API KEY.

Étape 1 : Sélectionner l'agent destinataire de votre qualification

En haut à droite de la section, un menu déroulant vous permet de choisir l'agent vers lequel les qualifications seront envoyés (par exemple : Sophie - Engager en temps réel). Chaque agent dispose de sa propre URL d'import et de son propre ID.

Étape 2 : Récupérer les informations pour l’appel HTTPS

La section Accès API affiche les trois informations nécessaires pour envoyer des contacts à Pinpo depuis votre système :

Champ	Description
API Key de production	Votre clé d'authentification. Elle est masquée par défaut. Cliquez sur l'icône œil (👁) pour la révéler, ou sur l'icône copier (📋) pour la copier dans le presse-papier.
URL d'import	L'endpoint vers lequel envoyer vos requêtes. L'URL inclut l'identifiant de l'agent sélectionné (par exemple : `https://api.pinpo.com/agents/{id_agent}/qualifications`). La liste des {{agentId}} est présente sur la plateforme PINPO (Intégrations>Connexion via API KEY > ID de l’agent)
ID de l'agent	L'identifiant unique de l'agent sélectionné. La liste des {{agentId}} est présente sur la plateforme PINPO (Intégrations>Connexion via API KEY > ID de l’agent)

Important : Votre API Key est une clé secrète. Ne la partagez jamais dans du code côté client, dans une URL publique ou dans un e-mail. Traitez-la comme un mot de passe.

Étape 3 : Récupérer un exemple de requête JSON

En bas de la page, un bloc affiche un exemple de requête JSON prêt à copier pour envoyer un contact à l'agent sélectionné.
Un menu déroulant vous permet de choisir le type d'exemple :

Minimal - Téléphone — Le payload minimum requis : uniquement le numéro de téléphone du contact.
Minimal - WhatsApp — Le payload minimum requis : uniquement le whatsAppUserId du contact (uniquement si vous ne détenez que celui-ci, le numéro de téléphone est recommandé)
Complet — Le payload complet contenant toutes les informations sur la qualification.

Exemple minimal :

{ "contact": { "phone": "+33606060606" } }

Cliquez sur l'icône copier (📋) en haut à droite du bloc de code pour copier l'exemple, puis adaptez-le à votre besoin.

Le lien Documentation dédiée sous le titre de la section vous redirige vers la documentation technique complète de l'API, avec l'ensemble des champs acceptés, les formats attendus et les codes de retour.

💡 Conseil : Commencez toujours par envoyer un contact de test via l'API avant de connecter votre flux de production. Vérifiez qu'il apparaît bien dans les Qualifications de test de l'agent, puis lancez une conversation de test pour vous assurer que les données sont correctement transmises.

Étape 4 : Envoyer la requête HTTPS

Vous avez désormais tous les éléments nécessaire à l’envoi de votre requête HTTP POST.
Consultez le schema dans la documentation technique afin de comprendre ce qui attendu dans chaque clé et chaque partie du JSON.
ℹ️ Au sujet de la réconciliation LES LEADS AVEC VOS IDs (ExternalId)
- Pour retrouver le qualification.externalId dans le webhook (SORTIE), il doit être présent au bon endroit lorsque vous utilisez la route API /agents/{agentId}/qualifications (ENTRÉE).
- Vous devez donc le transmettre dans la clé qualification.externalId afin qu'il apparaisse comme un qualification.externalId lorsque le lead vous revient via le Webhook.
- Plus généralement, si vous souhaitez qu'une valeur ou une clé soit visible en sortie (SORTIE), vous devez la transmettre en tant que customFields dans la route API /agents/{agentId}/qualifications (ENTRÉE).

Étape 5 : Traiter le retour HTTPS

Lorsque vous utilisez la route API /agents/{agentId}/qualifications pour importer des leads dans Pinpo, le qualificationId vous sera communiqué dans la réponse de votre requête POST comme mentionné dans la documentation technique : https://api.pinpo.com/api#/Qualifications/ImportQualificationController_execute
Il est PRIMORDIAL de traiter les différents codes et retours HTTP afin de s’assurer qu’en cas de rejet par l’API PINPO de votre tentative, votre workflow “sait comment gérer” les cas et vous alerte si besoin.

💡 RAPPEL :
**Règle #1 : Lorsque vous confiez un lead/prospect/contact à votre agent PINPO, le lead est importé immédiatement et le 1ᵉʳ message est envoyé immédiatement*.**

Il vous incombe d'envoyer le prospect au moment opportun.
*Par défaut, pour les prospects reçus par PINPO tard dans la nuit ou tôt le matin, le premier message est reporté au lendemain matin (ce comportement peut être personnalisé).

🌟 - Bonnes pratiques

Un agent = une URL d'import. Chaque agent possède son propre endpoint. Si vous envoyez des leads de natures différentes (acquisition, réactivation), assurez-vous de les router vers le bon agent via la bonne URL. La liste des {{agentId}} est présente sur la plateforme PINPO (Intégrations>Connexion via API KEY > ID de l’agent)
Transmettez un maximum de données. Le payload minimal (téléphone seul) fonctionne, mais plus vous enrichissez le contact (nom, prénom, email, source marketing, champs personnalisés), plus l'agent sera pertinent dans sa conversation.
Protégez votre API Key. Stockez-la dans une variable d'environnement ou un gestionnaire de secrets. Ne la codez jamais en dur dans votre code source.
Consultez la documentation. Le bouton Documentation en haut à droite de la page et le lien Documentation dédiée dans la section Accès API vous donnent accès à la référence technique complète. Lisez-la intégralement avant de développer votre intégration.
Testez avant la production. Utilisez le mode test pour valider votre intégration de bout en bout, puis basculez sur l'API Key de production une fois que tout fonctionne.