Opérations CRM HubSpot

Que fait Opérations CRM HubSpot ?

Utilisez cette compétence pour lire et, avec confirmation explicite, modifier les données CRM HubSpot via l'API v3 : fiches contacts, recherche de contacts, vues du pipeline des affaires et changements d'étape. Il s'agit d'une compétence outil pour un seul fournisseur de CRM (HubSpot). Construire des applications ou des workflows HubSpot relève du développement d'applications ; cette compétence prend en charge le flux de travail courant de l'agent : répondre « qui est ce contact ? », « qu'y a-t-il dans le pipeline ? » et appliquer un changement d'étape confirmé.

Contrat de fonctionnement

1. Découverte en lecture seule avant toute mutation. Listez et recherchez des contacts, consultez les affaires et pipelines librement. Le script crm-cli fourni effectue des lectures sans rien écrire.
2. Confirmez la cible, le périmètre et le chemin de retour arrière avant d'agir. Déplacer une affaire vers une nouvelle étape modifie un pipeline partagé utilisé par les rapports de revenus : cela nécessite une directive humaine explicite nommant l'affaire et l'étape cible, ainsi qu'une prévisualisation --dry-run et une confirmation --yes via crm-cli. Les changements d'étape sont réversibles mais laissent un historique d'audit — confirmez avant d'agir.
3. Respectez des lectures bornées. HubSpot pagine avec limit ; ne paginez jamais au-delà de ce dont la tâche a besoin. crm-cli --limit plafonne chaque liste et recherche.
4. Limitez les preuves. Citez des noms courts, des emails, des montants et des libellés d'étape ; ne déversez jamais des enregistrements complets, des tokens ou des payloads bruts dans le chat.
5. Connaissez le modèle d'objet. Les contacts et les affaires sont des objets distincts avec des maps de propriétés ; les transitions d'étape doivent utiliser un ID d'étape provenant du pipeline de l'affaire (pipelines list), pas un libellé d'étape.

Le script crm-cli

scripts/crm-cli est une CLI pensée pour l'agent, utilisant uniquement la bibliothèque standard, qui interagit avec l'API CRM v3 de HubSpot. Il couvre l'ensemble du périmètre : enregistrements, recherche et vues de pipeline.

crm/scripts/crm-cli --help                                # aucun token ou réseau nécessaire
crm/scripts/crm-cli --json --limit 20 contacts list
crm/scripts/crm-cli --json contacts get --id 51
crm/scripts/crm-cli --json contacts search --query "ada"
crm/scripts/crm-cli --json --limit 20 deals list
crm/scripts/crm-cli --json deals list --pipeline default --stage appointmentscheduled
crm/scripts/crm-cli --json pipelines list
crm/scripts/crm-cli deals update-stage --id 901 --stage closedwon --dry-run   # prévisualisation
crm/scripts/crm-cli deals update-stage --id 901 --stage closedwon --yes       # confirmé

Codes de sortie : 0 succès, 1 erreur API ou échec de vérification, 2 erreur d'utilisation. Les changements d'étape sont protégés : sans --dry-run ou --yes, le script refuse avec le code 1 et n'appelle jamais l'API. Les lectures sont bornées par --limit (par défaut 20, max 100).

Boucle de fonctionnement

1. Délimitez la question : s'agit-il d'une recherche (qui/qu'est-ce qui est dans le CRM) ou d'un changement (déplacer une affaire) ? Localisez l'objet avec contacts search/contacts list ou deals list.
2. Lisez avec bornes : contacts get pour un seul enregistrement, deals list pour la vue pipeline (éventuellement filtrée par pipeline et étape), pipelines list pour résoudre les libellés d'étape en IDs.
3. Triez la réponse : faites correspondre la question à une preuve (détails du contact, montant/étape de l'affaire, distribution du pipeline).
4. Agissez avec confirmation : uniquement sur directive humaine, prévisualisée avec --dry-run et confirmée avec --yes.
5. Vérifiez : relisez l'affaire (deals list --stage <cible>) et confirmez que l'étape a changé.

Enregistrements, recherche, vues de pipeline

• Fiches contacts (/objects/contacts) : liste (GET) ou récupération d'un seul (GET par ID) ; la CLI résume le prénom/nom, l'email, l'entreprise et la date de création. La recherche (POST /objects/contacts/search) trouve des contacts par texte de requête, bornée par --limit.
• Vues du pipeline des affaires (/objects/deals) : liste des affaires avec montant, pipeline et étape, éventuellement filtrées sur un pipeline ou une étape. pipelines list (/pipelines/deals) renvoie les pipelines avec leurs IDs d'étapes et leurs libellés — utilisez l'ID d'étape pour filtrer ou mettre à jour.
• Changements d'étape (PATCH /objects/deals/{id}) : une mutation protégée qui définit la propriété dealstage. Prévisualisez l'étape cible avec --dry-run, confirmez avec --yes, et vérifiez avec une lecture ultérieure. Seuls les déplacements d'étape sont dans le périmètre ; les autres modifications de propriétés d'affaire relèvent du développement d'application.

Modèle d'accès

• Les tokens d'accès d'application privée HubSpot (pat_...) sont délimités par objet et par accès lecture/écriture. Les lectures nécessitent crm.objects.contacts.read et crm.objects.deals.read ; les mises à jour d'étape nécessitent crm.objects.deals.write.
• Les enregistrements portent une map properties indexée par les noms de propriétés (ex. dealstage, dealname, amount). Les valeurs des propriétés sont des chaînes ; la CLI résume les champs utilisés par cette compétence.
• Les tokens sont des identifiants : stockez dans HUBSPOT_TOKEN, jamais dans le code, le chat ou les commits. En cas de fuite, révoquez le token dans les paramètres de l'application privée.

Aiguillage vers les références

À charger quand	Référence
Sources, tableaux de périmètre, procédure d'actualisation	references/00-source-index.md
Points d'accès, pagination, modèle d'objet, mises à jour d'étape, erreurs	references/01-hubspot-crm-operations.md

Artefacts inclus

• scripts/crm-cli : CLI bornée, uniquement bibliothèque standard (contacts list/get/search, deals list/update-stage, pipelines list ; --json ; --limit ; mutations protégées par --dry-run/--yes).
• tests/test_crm_cli.py : 13 tests déterministes contre une API HubSpot factice, incluant la protection des mutations et le contrat de lecture seule.
• references/ : index des sources daté + référence des opérations CRM HubSpot.
• evals/evals.json : six cas d'évaluation de la qualité des sorties pour des exécutions d'agent.

Périmètre de vérification

Affirmation	Preuve minimale
Un contact existe	crm-cli contacts search --query ... --json ou contacts get renvoie l'enregistrement
Une vue du pipeline est exacte	crm-cli deals list --json renvoie les affaires avec les IDs d'étape et le filtre appliqué
Un libellé d'étape correspond à un ID	crm-cli pipelines list --json renvoie la map des étapes du pipeline
Un changement d'étape a bien eu lieu	crm-cli deals update-stage --yes sort avec le code 0 et un deals list --stage ultérieur montre l'affaire
Une mutation peut être exécutée sans risque	crm-cli deals update-stage --dry-run affiche l'affaire exacte et l'étape cible

Limites strictes

• Ne déplacez jamais une affaire sans une directive humaine, une prévisualisation --dry-run et une confirmation --yes — les changements de pipeline alimentent les rapports de revenus et l'historique d'audit.
• Ne prétendez jamais qu'un enregistrement est manquant si le token peut manquer de portée sur l'objet ; vérifiez d'abord le modèle d'accès.
• Ne paginez jamais les lectures au-delà de --limit ; ne déversez jamais des enregistrements complets, des tokens ou des payloads bruts dans le chat.
• Cette compétence utilise l'API CRM HubSpot. Elle ne construit pas d'applications HubSpot ni ne couvre d'autres CRM.

Quand ne pas utiliser

• Construire des applications HubSpot, des automatisations de workflow ou des objets personnalisés — cela relève du développement d'applications HubSpot ; voir backend-engineering pour la conception de services.
• Marketing, séquences et automatisation d'emails dans HubSpot — cela relève de la surface Marketing HubSpot, pas de l'API CRM couverte par cette compétence.
• Autres CRM (Salesforce, Pipedrive, Zoho) — chacun a sa propre API et ses propres outils ; cette compétence couvre HubSpot.
• Stratégie CRM, conception de processus de vente ou méthodologie de pipeline — cela relève du travail d'organisation/de stratégie, pas d'une opération API.