Comment utiliser l'API Import de leads Oplead ?

Cet article vous fournira des réponses détaillées aux questions fréquentes posées par les développeurs lors de l'intégration de l'API Oplead avec des formulaires sur des sites internet.

1. Comment utiliser l'API d'ajout de leads d’Oplead ?

Question : Quelles sont les étapes pour intégrer l'API d'ajout de leads dans Oplead depuis un formulaire sur un site internet ?

Réponse : Pour intégrer l'API d'ajout de leads dans Oplead, suivez les étapes suivantes :

1. Appel de l'URL : Envoyez les données du formulaire en POST à l'URL suivante : https://leadimport.oplead.com/addlead/
2. Format des Données : Les données peuvent être transmises en JSON, paires de clés/valeurs ou paires de clés/valeurs + fichier.
3. Content-Type : Utilisez le content-type correspondant (application/json, application/x-www-form-urlencoded, multipart/form-data).
4. Variables Obligatoires :
   • form : Nom du formulaire utilisé pour l’import.
   • token : Token unique fourni par Oplead (disponible dans l’onglet API Import de la plateforme ou dans la documentation API)
   • ctc_lastname : Nom du contact.
   • ctc_postcode : Code postal.
   • ctc_country : Pays.
   • ctc_email : Adresse email.

2. Quels sont les différents niveaux de tracking et leurs identifiants uniques ?

Question : Quels identifiants uniques "CNL_" devons-nous utiliser pour les canaux, sous-canaux et campagnes ?

Réponse : Chaque niveau a un identifiant unique "CNL_" que l'on peut retrouver dans la documentation de l'API Import (Paramétrage > Connecteurs).

Chaque niveau de tracking (canal, sous-canal, campagne) a un identifiant unique "CNL_". L'organisateur est la suivante :

1. 1. Canal : Un canal peut avoir plusieurs sous-canaux.
   2. Sous-Canal : Un sous-canal peut avoir plusieurs campagnes.
   3. Campagne : Chaque campagne est associée à un sous-canal.

Niveau de tracking obligatoire :

• Le canal est obligatoire dans Oplead.

Nécessité du sous-canal :

• Dépend du niveau de tracking souhaité.
  • Pour un formulaire sur un site internet, le canal et le sous-canal sont généralement suffisants.
  • Pour un formulaire sur une landing page, le canal, le sous-canal et la campagne peuvent être intéressants.

Question : Est-ce que nous avons besoin de "CNL_" sur le canal et le sous-canal, ou sur la campagne ça suffit ?

Réponse :

Dans Oplead, seul le canal est obligatoire.

La nécessité de fournir un sous-canal dépend du niveau de tracking souhaité :

• Depuis un formulaire sur un site internet : le canal et le sous-canal sont généralement suffisants.
• Depuis un formulaire sur une landing page : le canal, le sous-canal, et la campagne peuvent être nécessaires.

3. Comment formater les données à envoyer via l'API ?

Question : Quel format de données dois-je utiliser pour envoyer des leads à l'API d'Oplead ?

Réponse : Les données doivent être formatées selon l'un des formats suivants :

• JSON : application/json
• Paires de clés/valeurs : application/x-www-form-urlencoded
• Paires de clés/valeurs + fichier : multipart/form-data

Voici un exemple d'appel JSON :

{
  "mode": "test",
  "form": "FormContact",
  "token": "RAcWeCFUm1812=",
  "format": "json",
  "ctc_profile": "CPR_779",
  "ctc_civility": "mrs",
  "ctc_firstname": "Matthieu",
  "ctc_lastname": "Ruslan",
  "ctc_corporation": "WestSide",
  "ctc_address": "1 rue du monde",
  "ctc_address2": "Residence univers",
  "ctc_postcode": "12345",
  "ctc_city": "Cityland",
  "ctc_country": "fr",
  "ctc_gps": "2.123,1.892",
  "ctc_tel": "12323123123",
  "ctc_mobile": "234234234234",
  "ctc_email": "email@email.com",
  "ctc_consent": "TRUE",
  "ctc_marketing_info": "FALSE",
  "prj_request": "RTY_601",
  "prj_message": "Merci de me fournir un devis",
  "prj_channel": "CNL_7437",
  "prj_delay": "DLY_625",
  "prj_range": "RNG_984",
  "prj_id_external": "01262442-B10E-4F85-BF01-5EC3EB4CAF56"
}

4. Comment gérer les retours de l'API et les erreurs ?

Question : Comment interpréter les retours de l'API et gérer les erreurs éventuelles ?

Réponse : L'API retourne un statut et un message associés. Voici quelques statuts courants et leurs significations :

• OK : Demande effectuée avec succès.
• UnkownError : Erreur inconnue.
• InvalidEntity : Token ne correspondant pas à une entité OPLEAD.
• InvalidLead : Lead non valide.
• UserNotFound : Utilisateur non trouvé.
• LeadAlreadyExist : Lead déjà existant pour l'entité OPLEAD.
• EngineNoResponse : Moteur d'attribution OPLEAD inaccessible.
• NoSupportedContentType : Le content-type n'est pas valide.

En cas de succès, l'API retourne un identifiant de lead Oplead. En cas d'échec, un statut 400 est renvoyé avec un message d'erreur décrivant l'origine du problème.

5. Comment tester l'intégration sans créer de leads réels ?

Question : Comment puis-je tester l'intégration de l'API sans créer de leads réels dans Oplead ?

Réponse : Pour tester l'intégration, vous pouvez utiliser le mode test :

• Ajoutez "mode": "test" dans votre requête JSON.
• Assurez-vous de changer l'adresse email à chaque test, car Oplead dédoublonne les leads sur le critère de l'email. Si un lead avec la même adresse email est poussé sur l'API dans un délai inférieur à 24 heures, il sera considéré comme une mise à jour du lead existant.

Exemple d'appel en mode test :

{
  "mode": "test",
  "form": "FormContact",
  "token": "RAcWeCFUm1812=",
  "format": "json",
  "ctc_firstname": "Test",
  "ctc_lastname": "User",
  "ctc_email": "testuser@example.com",
  "prj_channel": "CNL_7437"
}

Important : Ne pas utiliser le même email pour les tests successifs.

6. Est-ce qu'on peut récupérer le contenu d'un email pour l'intégrer dans Oplead ?