Aller au contenu principal

Attributs Client

Les Attributs Client sont des paires clé-valeur flexibles qui peuvent être attachées à n'importe quel enregistrement client pour stocker des métadonnées personnalisées, des paramètres de configuration ou des informations spécifiques à l'entreprise qui ne rentrent pas dans les champs clients standards.

Pour une catégorisation visuelle des clients et des liens cliquables, voir Tags Clients. Pour des informations de base sur les clients, voir Clients, Contacts, Sites & Services.

Contrairement aux champs de base de données fixes, les attributs vous permettent d'étendre dynamiquement les enregistrements clients sans modifier le schéma de la base de données. Cela les rend idéaux pour stocker des données spécifiques au déploiement, des paramètres d'intégration ou des indicateurs de logique métier personnalisée.

Objectif et Cas d'Utilisation​

Les cas d'utilisation courants pour les Attributs Client incluent :

1. Données d'Intégration

Stocker des identifiants de systèmes externes ou des clés API spécifiques à ce client :

  • external_crm_id = "SF-12345" (ID client Salesforce)
  • legacy_system_id = "OLD-CRM-789" (Référence de migration)
  • hubspot_contact_id = "12345678" (Intégration HubSpot)

2. Logique Métier Personnalisée

Stocker des indicateurs ou des paramètres qui contrôlent le comportement spécifique au client :

  • billing_method = "quarterly" (Remplacer la facturation mensuelle par défaut)
  • auto_provision = "true" (Activer la provision automatique des services)
  • support_tier = "premium" (Niveau de support personnalisé)
  • credit_limit = "10000" (Limite de crédit spécifique au client)

3. Données de Conformité et Réglementaires

Suivre les métadonnées liées à la conformité :

  • gdpr_consent_date = "2025-01-01" (Consentement au traitement des données)
  • tax_exempt = "true" (Statut d'exemption fiscale)
  • regulatory_entity = "FCC-123456" (Identifiant réglementaire)

4. Métadonnées Opérationnelles

Stocker des informations opérationnelles :

  • preferred_contact_method = "email" (Préférence de communication)
  • account_manager = "<john.smith@company.com>" (Responsable de compte assigné)
  • onboarding_date = "2025-01-15" (Suivi du cycle de vie client)
  • churn_risk_score = "0.23" (Analytique prédictive)

5. Paramètres de Provisioning

Stocker des configurations spécifiques au provisioning :

  • radius_username_format = "email" (Format RADIUS personnalisé)
  • vlan_id = "100" (Configuration réseau)
  • ipv6_enabled = "true" (Indicateurs de fonctionnalités)

Attributs vs. Champs Standards​

Utilisez des Attributs Lorsque :

  • Les données sont spécifiques au déploiement ou varient selon l'installation
  • Les exigences changent fréquemment
  • Stockage de métadonnées spécifiques à l'intégration
  • Prototypage de nouvelles fonctionnalités avant d'ajouter des champs de base de données
  • Les données n'ont pas besoin de requêtes complexes ou de jointures

Utilisez des Champs Standards Lorsque :

  • Les données sont essentielles au modèle client (nom, email, adresse)
  • Recherche, filtrage ou reporting fréquents requis
  • Les données ont des contraintes d'intégrité référentielle
  • La performance est critique pour des requêtes à grande échelle

Gestion des Attributs via l'UI​

Affichage des Attributs Client​

Pour afficher les attributs d'un client :

  1. Naviguez vers la page d'aperçu du client
  2. Cliquez sur l'onglet Attributs
  3. Vous verrez un tableau de tous les attributs pour ce client, montrant :
    • Nom de l'Attribut (clé)
    • Valeur de l'Attribut
    • Date de création
    • Date de dernière modification

Création d'un Nouvel Attribut​

Pour créer un nouvel attribut pour un client :

  1. Naviguez vers la page d'aperçu du client
  2. Cliquez sur l'onglet Attributs
  3. Cliquez sur le bouton Ajouter un Attribut
  4. Remplissez les champs requis :
    • Nom de l'Attribut (requis) : La clé/nome pour cet attribut (par exemple, external_crm_id)
    • Valeur de l'Attribut (requis) : La valeur à stocker (par exemple, SF-12345)
  5. Cliquez sur Créer un Attribut

Conventions de Nommage :

  • Utilisez des minuscules avec des underscores : external_system_id ✓
  • Évitez les espaces : external system id ✗
  • Gardez les noms descriptifs mais concis
  • Utilisez une nomenclature cohérente entre les clients pour les mêmes types d'attributs

Édition d'un Attribut​

Pour modifier un attribut existant :

  1. Naviguez vers la page d'aperçu du client
  2. Cliquez sur l'onglet Attributs
  3. Trouvez l'attribut que vous souhaitez modifier dans le tableau
  4. Cliquez sur le bouton Modifier (crayon)
  5. Modifiez le nom ou la valeur de l'attribut
  6. Cliquez sur Mettre à Jour l'Attribut

::: note ::: title Note :::

Changer le nom d'un attribut crée une nouvelle paire clé-valeur. Assurez-vous que cela ne casse pas les intégrations qui dépendent du nom d'attribut original. :::

Suppression d'un Attribut​

Pour supprimer un attribut :

  1. Naviguez vers la page d'aperçu du client
  2. Cliquez sur l'onglet Attributs
  3. Trouvez l'attribut que vous souhaitez supprimer dans le tableau
  4. Cliquez sur le bouton Supprimer (corbeille)
  5. Confirmez la suppression dans la fenêtre contextuelle

::: warning ::: title Avertissement :::

La suppression d'attributs utilisés par des intégrations, des flux de travail de provisioning ou de la logique de facturation peut provoquer des échecs. Vérifiez les dépendances avant de supprimer. :::

Référence des Champs d'Attributs​

Intégration API​

Les attributs peuvent être gérés par programme via l'API :

Créer ou Mettre à Jour un Attribut​

Point de terminaison : PUT /crm/attribute/

Permission Requise : create_customer_attribute

Corps de la Demande :

{
  "customer_id": 123,
  "attribute_name": "external_crm_id",
  "attribute_value": "SF-12345"
}

Réponse :

{
  "attribute_id": 456,
  "customer_id": 123,
  "attribute_name": "external_crm_id",
  "attribute_value": "SF-12345",
  "created": "2025-01-04 10:30:00",
  "last_modified": "2025-01-04 10:30:00"
}

Mettre à Jour un Attribut Existant​

Point de terminaison : PATCH /crm/attribute/attribute_id/{attribute_id}

Permission Requise : update_customer_attribute

Corps de la Demande :

{
  "attribute_value": "SF-54321"
}

Obtenir un Attribut par ID​

Point de terminaison : GET /crm/attribute/attribute_id/{attribute_id}

Permission Requise : view_customer_attribute

Réponse :

{
  "attribute_id": 456,
  "customer_id": 123,
  "attribute_name": "external_crm_id",
  "attribute_value": "SF-12345",
  "created": "2025-01-04 10:30:00",
  "last_modified": "2025-01-04 10:30:00"
}

Obtenir Tous les Attributs par ID de Client​

Point de terminaison : GET /crm/attribute/customer_id/{customer_id}

Permission Requise : view_customer_attribute

Réponse :

[
  {
    "attribute_id": 456,
    "customer_id": 123,
    "attribute_name": "external_crm_id",
    "attribute_value": "SF-12345",
    "created": "2025-01-04 10:30:00",
    "last_modified": "2025-01-04 10:30:00"
  },
  {
    "attribute_id": 457,
    "customer_id": 123,
    "attribute_name": "billing_method",
    "attribute_value": "quarterly",
    "created": "2025-01-04 10:35:00",
    "last_modified": "2025-01-04 10:35:00"
  }
]

Supprimer un Attribut​

Point de terminaison : DELETE /crm/attribute/attribute_id/{attribute_id}

Permission Requise : delete_customer_attribute

Réponse :

{
  "result": "success"
}

Opérations d'Attributs en Masse​

Gestion de Plusieurs Attributs​

Pour définir plusieurs attributs pour un client en une seule fois (par exemple, lors de l'intégration ou de la synchronisation d'intégration) :

import requests

customer_id = 123
attributes = [
    {"attribute_name": "external_crm_id", "attribute_value": "SF-12345"},
    {"attribute_name": "billing_method", "attribute_value": "quarterly"},
    {"attribute_name": "support_tier", "attribute_value": "premium"}
]

for attr in attributes:
    attr["customer_id"] = customer_id
    requests.put(
        "https://api.example.com/crm/attribute/",
        json=attr,
        headers={"Authorization": "Bearer YOUR_TOKEN"}
    )

Interroger les Clients par Attribut​

Bien que les attributs n'aient pas de points de terminaison de recherche intégrés, vous pouvez filtrer les clients par attribut en utilisant l'API de recherche de clients avec un filtrage personnalisé :

# Obtenez tous les clients, puis filtrez par attribut dans le code de l'application
customers = requests.get("https://api.example.com/crm/customer/").json()

for customer in customers:
    attributes = requests.get(
        f"https://api.example.com/crm/attribute/customer_id/{customer['customer_id']}"
    ).json()

    # Trouver des clients avec un attribut spécifique
    for attr in attributes:
        if attr['attribute_name'] == 'support_tier' and attr['attribute_value'] == 'premium':
            print(f"Client Premium : {customer['customer_name']}")

::: note ::: title Note :::

Pour des requêtes fréquentes basées sur des attributs, envisagez d'ajouter des champs de base de données indexés ou de mettre en œuvre un point de terminaison de recherche dédié. :::

Meilleures Pratiques​

1. Conventions de Nommage

  • Utilisez snake_case : external_system_id ✓
  • Soyez descriptif : billing_method ✓ vs method ✗
  • Évitez les mots-clés réservés ou les caractères spéciaux
  • Documentez les significations des attributs dans votre guide de déploiement

2. Types de Données

  • Les attributs stockent des valeurs sous forme de chaînes (max 150 caractères)
  • Pour les booléens, utilisez "true"/"false" (minuscules)
  • Pour les dates, utilisez le format ISO 8601 : "2025-01-04 10:30:00"
  • Pour de grandes données JSON, envisagez d'utiliser des champs de base de données dédiés à la place

3. Validation

  • Validez les valeurs des attributs dans le code de l'application avant de les enregistrer
  • Utilisez des formats de valeur cohérents entre les clients
  • Documentez les valeurs attendues pour chaque nom d'attribut

4. Documentation

  • Maintenez un registre des noms et des objectifs des attributs
  • Documentez quels systèmes/intégrations dépendent d'attributs spécifiques
  • Incluez des exemples de valeurs valides

5. Migration et Nettoyage

  • Auditez régulièrement les attributs inutilisés
  • Supprimez les attributs obsolètes après les migrations de système
  • Versionnez les noms d'attributs lors du changement de schémas (par exemple, api_key_v2)

Exemples de Flux de Travail​

Intégration d'Onboarding​

Lors de la migration de clients depuis un système hérité :

# Stocker la référence du système hérité pour le débogage
PUT /crm/attribute/
{
  "customer_id": 123,
  "attribute_name": "legacy_crm_id",
  "attribute_value": "OLD-12345"
}

# Suivre la date de migration
PUT /crm/attribute/
{
  "customer_id": 123,
  "attribute_name": "migrated_date",
  "attribute_value": "2025-01-04"
}

Règles de Facturation Personnalisées​

Remplacer le cycle de facturation par défaut pour un client spécifique :

# Définir la facturation trimestrielle
PUT /crm/attribute/
{
  "customer_id": 123,
  "attribute_name": "billing_cycle",
  "attribute_value": "quarterly"
}

# Puis dans le code de facturation, vérifier l'attribut avant de traiter
attributes = GET /crm/attribute/customer_id/123
billing_cycle = next(
    (a['attribute_value'] for a in attributes if a['attribute_name'] == 'billing_cycle'),
    'monthly'  # par défaut
)

Indicateurs de Fonctionnalités​

Activer des fonctionnalités bêta pour des clients spécifiques :

# Activer le provisioning IPv6
PUT /crm/attribute/
{
  "customer_id": 123,
  "attribute_name": "feature_ipv6_enabled",
  "attribute_value": "true"
}

Permissions​

Les opérations sur les attributs nécessitent les permissions suivantes :

  • view_customer_attribute - Voir les attributs
  • create_customer_attribute - Créer de nouveaux attributs
  • update_customer_attribute - Modifier des attributs existants
  • delete_customer_attribute - Supprimer des attributs

Voir rbac pour la configuration du contrôle d'accès basé sur les rôles.

Dépannage​

Attribut Non Apparaissant dans l'UI

  • Vérifiez que l'attribut a été créé (vérifiez la réponse de l'API)
  • Rafraîchissez la page pour recharger les données du client
  • Vérifiez que l'utilisateur a la permission view_customer_attribute

Impossible de Mettre à Jour l'Attribut

  • Assurez-vous d'avoir la permission update_customer_attribute
  • Vérifiez que l'attribute_id est correct
  • Vérifiez que l'attribut appartient au client spécifié

Échec de l'Intégration Après la Suppression d'un Attribut

  • Restaurez l'attribut avec la valeur précédente
  • Mettez à jour le code d'intégration pour gérer les attributs manquants de manière élégante
  • Auditez les dépendances des attributs avant la suppression

Valeur d'Attribut Troncée

  • Les valeurs des attributs ont une limite de 150 caractères
  • Pour des données plus longues, divisez en plusieurs attributs ou utilisez le champ de notes client
  • Envisagez de stocker de grandes données dans des champs de base de données dédiés