# WP-CLI et HubSpot : synchroniser en masse une base de contacts en CLI

> Écrire une commande WP-CLI personnalisée qui pousse un export CSV volumineux vers HubSpot par lots, sans passer par l'import manuel de l'interface web.

- Auteur : WordPress Développement
- Publié le : 2022-12-23
- Mis à jour le : 2022-12-23
- Catégorie : Outils & workflow
- URL : https://www.wpmoderne.fr/outils/wp-cli-hubspot-synchroniser-contacts-masse/

## L’essentiel

- Traiter l'import par lots pour respecter les limites d'API
- Journaliser chaque échec plutôt que d'arrêter tout le traitement
- Éviter les doublons de contacts par vérification préalable

`wp hubspot sync-contacts --file=export.csv` — cette commande unique remplace aujourd'hui ce qui prenait auparavant une matinée entière à un membre de l'équipe marketing : importer manuellement, via l'interface web de HubSpot, un export de plusieurs milliers de contacts collectés par des formulaires WordPress sur un an, avec le risque constant de créer des doublons ou de dépasser le nombre d'onglets ouverts simultanément supportable par le navigateur.

Le client, un réseau national de franchises, collectait ses prospects via des formulaires WordPress installés sur chaque site local, mais centralisait son suivi commercial dans HubSpot. Le pont entre les deux devait être fiable, rejouable et surtout ne jamais dupliquer un contact déjà présent.

## Pourquoi une commande CLI plutôt qu'un import manuel

L'interface web de HubSpot gère très bien un import ponctuel de quelques centaines de contacts, mais devient pénible dès que l'opération doit être répétée régulièrement, avec des règles de dédoublonnage spécifiques (rapprocher par e-mail, mais aussi par numéro de téléphone en l'absence d'e-mail). Une commande WP-CLI personnalisée permet d'encoder ces règles une fois, puis de les rejouer en confiance.

## Structurer la commande

```
// mu-plugins/wpcli-hubspot-sync.php
WP_CLI::add_command( 'hubspot sync-contacts', function( $args, $assoc_args ) {
    $fichier = $assoc_args['file'] ?? null;
    if ( ! $fichier || ! file_exists( $fichier ) ) {
        WP_CLI::error( 'Fichier CSV introuvable.' );
    }

    $lignes = array_map( 'str_getcsv', file( $fichier ) );
    $entetes = array_shift( $lignes );
    $lots = array_chunk( $lignes, 500 );

    foreach ( $lots as $index_lot => $lot ) {
        $contacts = array_map( function( $ligne ) use ( $entetes ) {
            return array_combine( $entetes, $ligne );
        }, $lot );

        $resultat = envoyer_lot_hubspot( $contacts );

        WP_CLI::log( sprintf(
            'Lot %d/%d : %d succès, %d échecs',
            $index_lot + 1, count( $lots ), $resultat['succes'], $resultat['echecs']
        ) );
    }
} );
```

> L'essentiel à retenir : Traiter l'import par lots pour respecter les limites d'API ; Journaliser chaque échec plutôt que d'arrêter tout le traitement ; Éviter les doublons de contacts par vérification préalable

## Respecter les limites de l'API par lots

L'API de contacts de HubSpot accepte les créations et mises à jour par lots, avec une limite de contacts par requête. Traiter l'export en lots de cinq cents contacts, plutôt qu'un contact à la fois, réduit fortement le nombre de requêtes et le temps total de synchronisation, tout en restant sous les limites de débit imposées par l'API :

```
function envoyer_lot_hubspot( array $contacts ) : array {
    $reponse = wp_remote_post( 'https://api.hubapi.com/crm/v3/objects/contacts/batch/upsert', [
        'headers' => [
            'Authorization' => 'Bearer ' . getenv( 'HUBSPOT_TOKEN' ),
            'Content-Type'  => 'application/json',
        ],
        'body' => wp_json_encode( [ 'inputs' => formater_contacts( $contacts ) ] ),
        'timeout' => 30,
    ] );

    if ( is_wp_error( $reponse ) ) {
        return [ 'succes' => 0, 'echecs' => count( $contacts ) ];
    }

    $corps = json_decode( wp_remote_retrieve_body( $reponse ), true );
    return [
        'succes' => count( $corps['results'] ?? [] ),
        'echecs' => count( $contacts ) - count( $corps['results'] ?? [] ),
    ];
}
```

## Éviter les doublons avant l'envoi

Plutôt que de laisser HubSpot gérer seul le rapprochement, la commande interroge d'abord l'API pour vérifier l'existence d'un contact par adresse e-mail, et bascule sur une mise à jour plutôt qu'une création si une correspondance existe déjà. Ce contrôle préalable, plus coûteux en requêtes, s'est révélé indispensable après une première synchronisation qui avait généré près de deux cents doublons faute de cette vérification.

## Journaliser sans interrompre le traitement

Un lot en échec (contact avec une adresse e-mail malformée, par exemple) ne doit pas bloquer les lots suivants. Chaque échec est consigné dans un fichier journal séparé, avec la ligne CSV d'origine, pour un traitement manuel a posteriori sans avoir à rejouer l'ensemble du fichier :

- Un fichier `succes.log` listant les identifiants HubSpot créés ou mis à jour.
- Un fichier `echecs.csv` reprenant les lignes en échec avec le message d'erreur associé, réimportable après correction manuelle.

## En résumé

Automatiser cette synchronisation en CLI n'a pas seulement fait gagner du temps : elle a supprimé une source d'erreurs humaines récurrente liée à l'import manuel répétitif. Le traitement par lots de cinq cents contacts, couplé à une journalisation détaillée des échecs, reste la configuration qui a donné le meilleur équilibre entre vitesse et fiabilité sur ce projet.