Portfolio
Retour aux projets

Liaison de l'API d'AVAYA call reporting avec celle de HUBSPOT

Novembre 2025
API Python Avaya Hubspot

Ce projet est un script d'automatisation en Python conçu pour synchroniser les données d'appels manqués d'un numéro depuis un serveur Avaya Call Reporting vers la plateforme CRM HubSpot. Le script s'exécute en boucle continue, interroge l'API Avaya pour les appels manqués récents, et crée les fiches contacts correspondantes dans HubSpot pour les numéros de téléphone non existants. Il intègre une gestion des logs et un système d'alerte par e-mail en cas d'échec critique.

Code Source

Objectif

L'objectif principal est d'automatiser le fait qu'aucun appel manqué enregistré par le système téléphonique de call reporting ne soit perdu.

Architecture et Composants

Le projet est structuré en quatre modules Python principaux et un fichier de configuration.

script.pyw (Point d'entrée)

Rôle : Point d'entrée principal. Fonctionnement : Il contient la boucle d'exécution principale (while True:). Il appelle séquentiellement les fonctions des autres modules pour :

  • Initialiser la gestion des logs (log.gestion_fichier()).
  • Se connecter à Avaya (call_report_numbers.session_avaya()).
  • Récupérer les appels (call_report_numbers.appels_manque()).
  • Traiter les numéros (call_report_numbers.traitement_dict()).
  • Se connecter à HubSpot (hub.session_hubspot()).
  • Vérifier l'existence des contacts (hub.fiche_existe()).
  • Créer les nouveaux contacts (hub.creation_contact()).
  • Marquer une pause (time.sleep(900)) avant de recommencer le cycle.

call_report_numbers.py (Interface Avaya)

Rôle : Module d'interface avec l'API Avaya Call Reporting.

  • Fonctionnalités clés :
    • Gestion de session : Initialise une session requests avec le jeton d'authentification (TOKEN).
    • Vérification de connexion : La fonction erreur_connexion_avaya() valide l'authentification (codes 200, 401, 403) avant de continuer.
    • Récupération des données : La fonction appels_manque() envoie une requête POST à l'endpoint des données historiques (/historic-data/{DATA_KEY}). Elle définit une plage de temps (par défaut, les 15 dernières minutes).
    • Traitement : traitement_dict() traite la réponse (format CSV/texte) pour extraire les numéros de téléphone et les nettoyer (suppression des caractères alphabétiques).

hubspot_api.py (Interface HubSpot)

Rôle : Module d'interface avec l'API HubSpot CRM.

  • Fonctionnalités clés :
    • Gestion de session : Initialise la connexion via le SDK hubspot-api-client ou des requêtes requests directes avec le TOKEN_HUBSPOT. Un test de connexion est effectué (/integrations/v1/me).
    • Vérification d'existence : fiche_existe() utilise l'endpoint de recherche (/crm/v3/objects/contacts/search) pour vérifier si des contacts existent déjà avec les numéros de téléphone (filtre CONTAINS_TOKEN).
    • Création de contacts : creation_contact() gère la création.
    • Cas unique : Une requête POST standard sur /crm/v3/objects/contacts.
    • Cas multiple : Utilisation de l'endpoint de création par lot (/batch/create) pour optimiser les performances.

gestion_log.py (Journalisation)

Rôle : Module de journalisation centralisé.

  • Fonctionnalités clés :
    • Initialisation : gestion_fichier() crée un sous-dossier logs/.
    • Fichiers journaliers : Crée un fichier log par jour (format AAAA-MM-JJ.txt).
    • Rotation des logs : Assure une purge automatique des anciens fichiers. Le script conserve au maximum 30 fichiers logs et supprime les plus anciens (basé sur le temps de création os.path.getctime).
    • Fonction d'écriture : write_log() est une fonction globale permettant à tous les modules d'écrire des messages horodatés dans le fichier du jour.

Configuration Requise (.env)

Le script nécessite un fichier .env à sa racine, contenant les variables d'environnement suivantes:

  • Avaya : -URL : L'URL de base de l'API Avaya Call Reporting. -TOKEN : Le jeton Bearer pour l'authentification Avaya. -DATA_KEY : L'identifiant du rapport spécifique (appels manqués) à interroger. -USER_KEY : L'identifiant de l'utilisateur API.
  • HubSpot : -URL_HUBSPOT : L'URL de base de l'API HubSpot. -TOKEN_HUBSPOT : Le jeton d'accès privé pour l'authentification HubSpot.

Gestion des Erreurs et Alertes

Le système est conçu pour gérer et alerter.

  • Erreurs Critiques (Bloquantes) :

    • Échec de connexion Avaya (ex: 401 Token invalide, 403 Interdit).
    • Échec de connexion HubSpot (ex: Token invalide, erreur réseau).
    • Erreur majeure de requête (ex: timeout HTTP, erreur de parsing JSON).
    • Action : Le script appelle sys.exit() pour s'arrêter. Avant de s'arrêter, il envoie un e-mail d'alerte.

  • Système d'Alerte E-mail :

    • Deux fonctions distinctes existent : envoi_mail_erreur_avaya() et envoi_erreur_mail_hubspot().
      Destinataire : Boite mail de la DSI. Contenu : L'e-mail contient un message d'erreur et attache automatiquement le fichier log du jour (AAAA-MM-JJ.txt) en pièce jointe.

Scénario d'Exécution (Cycle Continu)

Le script est conçu pour fonctionner en boucle continue (while True) afin de surveiller et de traiter les appels manqués quasiment en temps réel.

Initialisation du Cycle et Journalisation

  • Le script démarre un nouveau cycle de la boucle.
  • Il appelle la fonction log.gestion_fichier() qui vérifie que le dossier logs/ existe et s'assure que le fichier log du jour est prêt.
  • Toutes les actions suivantes seront consignées dans ce fichier journal.

Collecte et Traitement (Avaya)

  • Le script établit la session avec Avaya et récupère la liste des appels manqués récents.
  • Il identifie les numéros pertinents (ex: 01.xx... et 06.xx...).

Vérification et Action (HubSpot) : Le script se connecte à HubSpot pour interroger ces numéros.

  • Cas A : Le numéro n'existe pas

    • L'API HubSpot confirme qu'aucun contact ne correspond (Total = 0).

    • Action : Le script procède à la création d'une nouvelle fiche de contact.

    • Log : Le script écrit dans le journal une confirmation (ex: "Création du contact... | Status 201").

  • Cas B : Le numéro existe déjà

    • L'API HubSpot confirme qu'un contact possède déjà ce numéro (Total = 1).
    • Action : Le script ignore ce numéro afin d'éviter la création de doublons.
    • Log : Le script écrit dans le journal l'information.

Fin du Cycle et Pause

  • Une fois toutes les actions terminées, le script marque une pause de 15 minutes (conformément à time.sleep(900)).
  • Après cette pause, la boucle recommence et le script retourne à l'étape initiale pour un nouveau cycle de vérification.

Annexe : Comprendre les Codes de Réponse API

Chaque réponse est accompagnée d'un code numérique (code de statut HTTP) qui indique si la demande a réussi ou non.

Catégorie 2xx : Succès

  • 200 / 201 OK : La demande a été traitée avec succès (ex: Connexion réussie, récupération des appels terminée, contacts créés).

Catégorie 4xx : Erreur Client

Ces erreurs indiquent un problème dans la manière dont le script envoie la demande.

  • 400 Bad Request : Le serveur n'a pas compris la demande. Souvent dû à une syntaxe incorrecte, un paramètre manquant ou une valeur invalide.

    • Correction : Vérifier la structure et les données du payload.

  • 401 Unauthorized : L'authentification a échoué (Token manquant ou incorrect).

    • Correction : Vérifier les variables TOKEN dans le fichier .env.

  • 403 Forbidden : Authentification réussie mais permissions insuffisantes.

    • Correction : Vérifier les permissions de l'utilisateur API ou les "scopes" de l'application HubSpot.

  • 404 Not Found : La ressource ou l'URL n'existe pas.

    • Correction : Vérifier les URL et DATA_KEY dans le fichier .env.

  • 423 Locked (Spécifique HubSpot) : Ressource verrouillée temporairement (grand volume de données).

    • Correction : Attendre au moins 2 secondes avant de retenter.

  • 429 Too Many Requests : Limites de requêtes dépassées.

    • Note : La pause de 15 minutes empêche normalement cette erreur.

Catégorie 5xx : Erreur Serveur

  • 500 Internal Server Error : Problème interne au serveur distant (Avaya ou HubSpot).
    • Correction : Vérifier l'état de service ou contacter le support, le problème est souvent temporaire.

Dictionnaire

  • API (Application Programming Interface) : Interface permettant à différents programmes de communiquer.
  • CRM (Customer Relationship Management) : Logiciel de gestion de la relation client (HubSpot dans ce projet).
  • Script : Fichier contenant une série d'instructions pour automatiser une tâche.
  • Module : Fichier Python regroupant des fonctions spécifiques.
  • Point d'entrée : Script principal (script.py) qui gère le déroulement logique du programme.
  • Flux (Workflow) : Séquence ordonnée des étapes (ex: Connexion → Récupération → Traitement → Création).
  • Dépendances : Bibliothèques de code externes nécessaires au fonctionnement (ex: requests).
  • Requête (Request) : Demande envoyée par le script à l'API via HTTP.
  • Réponse (Response) : Information renvoyée par le serveur après traitement.
  • Codes de statut HTTP : Codes numériques indiquant le résultat de la requête.
  • Endpoint : URL spécifique sur un serveur pour exécuter une action précise.
  • Payload (Charge utile) : Données envoyées avec une requête pour que le serveur puisse l'exécuter.
  • Token : Chaîne de caractères unique utilisée pour l'authentification.
  • .env : Fichier de configuration stockant les variables sensibles hors du code source.
  • Scopes (Portées) : Permissions spécifiques accordées à un Token d'API.
  • Logs : Fichier enregistrant chronologiquement les événements, succès et erreurs.
  • Rotation des logs : Processus supprimant les anciens fichiers logs pour éviter la saturation.
  • Parsing : Analyse des données brutes pour en extraire les informations pertinentes.
  • Dédoublonner : Suppression des entrées en double.
  • Batch (Par lot) : Méthode groupant plusieurs opérations en une seule requête API.