Saltar al contenido principal

Atributos del Cliente

Los Atributos del Cliente son pares clave-valor flexibles que se pueden adjuntar a cualquier registro de cliente para almacenar metadatos personalizados, configuraciones o información específica del negocio que no encaja en los campos estándar del cliente.

Para la categorización visual de clientes y enlaces clicables, consulte Etiquetas de Cliente. Para información básica del cliente, consulte Clientes, Contactos, Sitios y Servicios.

A diferencia de los campos de base de datos fijos, los atributos le permiten extender dinámicamente los registros de clientes sin modificar el esquema de la base de datos. Esto los hace ideales para almacenar datos específicos de implementación, parámetros de integración o banderas de lógica de negocio personalizadas.

Propósito y Casos de Uso​

Los casos de uso comunes para los Atributos del Cliente incluyen:

1. Datos de Integración

Almacenar identificadores de sistemas externos o claves API específicas para este cliente:

  • external_crm_id = "SF-12345" (ID de cliente de Salesforce)
  • legacy_system_id = "OLD-CRM-789" (Referencia de migración)
  • hubspot_contact_id = "12345678" (Integración de HubSpot)

2. Lógica de Negocio Personalizada

Almacenar banderas o configuraciones que controlan el comportamiento específico del cliente:

  • billing_method = "quarterly" (Anular la facturación mensual predeterminada)
  • auto_provision = "true" (Habilitar la provisión automática de servicios)
  • support_tier = "premium" (Nivel de soporte personalizado)
  • credit_limit = "10000" (Límite de crédito específico del cliente)

3. Datos de Cumplimiento y Regulatorios

Rastrear metadatos relacionados con el cumplimiento:

  • gdpr_consent_date = "2025-01-01" (Consentimiento para el procesamiento de datos)
  • tax_exempt = "true" (Estado de exención fiscal)
  • regulatory_entity = "FCC-123456" (Identificador regulatorio)

4. Metadatos Operacionales

Almacenar información operacional:

  • preferred_contact_method = "email" (Preferencia de comunicación)
  • account_manager = "<john.smith@company.com>" (Gerente de cuenta asignado)
  • onboarding_date = "2025-01-15" (Seguimiento del ciclo de vida del cliente)
  • churn_risk_score = "0.23" (Análisis predictivo)

5. Parámetros de Provisión

Almacenar configuraciones específicas de provisión:

  • radius_username_format = "email" (Formato RADIUS personalizado)
  • vlan_id = "100" (Configuración de red)
  • ipv6_enabled = "true" (Banderas de características)

Atributos vs. Campos Estándar​

Use Atributos Cuando:

  • Los datos son específicos de la implementación o varían según la instalación
  • Los requisitos cambian con frecuencia
  • Almacenar metadatos específicos de integración
  • Prototipar nuevas características antes de agregar campos de base de datos
  • Los datos no necesitan consultas complejas o uniones

Use Campos Estándar Cuando:

  • Los datos son fundamentales para el modelo de cliente (nombre, correo electrónico, dirección)
  • Se requiere búsqueda, filtrado o informes frecuentes
  • Los datos tienen restricciones de integridad referencial
  • El rendimiento es crítico para consultas a gran escala

Gestión de Atributos a través de la UI​

Visualización de Atributos del Cliente​

Para ver los atributos de un cliente:

  1. Navegue a la página de resumen del cliente
  2. Haga clic en la pestaña Atributos
  3. Verá una tabla de todos los atributos para este cliente, mostrando:
    • Nombre del Atributo (clave)
    • Valor del Atributo
    • Fecha de Creación
    • Fecha de Última Modificación

Creación de un Nuevo Atributo​

Para crear un nuevo atributo para un cliente:

  1. Navegue a la página de resumen del cliente
  2. Haga clic en la pestaña Atributos
  3. Haga clic en el botón Agregar Atributo
  4. Complete los campos requeridos:
    • Nombre del Atributo (requerido): La clave/nombre para este atributo (por ejemplo, external_crm_id)
    • Valor del Atributo (requerido): El valor a almacenar (por ejemplo, SF-12345)
  5. Haga clic en Crear Atributo

Convenciones de Nomenclatura:

  • Use minúsculas con guiones bajos: external_system_id ✓
  • Evite espacios: external system id ✗
  • Mantenga los nombres descriptivos pero concisos
  • Use nombres consistentes entre clientes para los mismos tipos de atributos

Edición de un Atributo​

Para editar un atributo existente:

  1. Navegue a la página de resumen del cliente
  2. Haga clic en la pestaña Atributos
  3. Encuentre el atributo que desea editar en la tabla
  4. Haga clic en el botón Editar (lápiz)
  5. Modifique el nombre o valor del atributo
  6. Haga clic en Actualizar Atributo

::: note ::: title Nota :::

Cambiar el nombre de un atributo crea un nuevo par clave-valor. Asegúrese de que esto no rompa las integraciones que dependen del nombre original del atributo. :::

Eliminación de un Atributo​

Para eliminar un atributo:

  1. Navegue a la página de resumen del cliente
  2. Haga clic en la pestaña Atributos
  3. Encuentre el atributo que desea eliminar en la tabla
  4. Haga clic en el botón Eliminar (papelera)
  5. Confirme la eliminación en la ventana emergente

::: warning ::: title Advertencia :::

Eliminar atributos utilizados por integraciones, flujos de trabajo de provisión o lógica de facturación puede causar fallos. Verifique las dependencias antes de la eliminación. :::

Referencia de Campo de Atributos​

Integración de API​

Los atributos se pueden gestionar programáticamente a través de la API:

Crear o Actualizar un Atributo​

Endpoint: PUT /crm/attribute/

Permiso Requerido: create_customer_attribute

Cuerpo de la Solicitud:

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

Respuesta:

{
  "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"
}

Actualizar un Atributo Existente​

Endpoint: PATCH /crm/attribute/attribute_id/{attribute_id}

Permiso Requerido: update_customer_attribute

Cuerpo de la Solicitud:

{
  "attribute_value": "SF-54321"
}

Obtener Atributo por ID​

Endpoint: GET /crm/attribute/attribute_id/{attribute_id}

Permiso Requerido: view_customer_attribute

Respuesta:

{
  "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"
}

Obtener Todos los Atributos por ID de Cliente​

Endpoint: GET /crm/attribute/customer_id/{customer_id}

Permiso Requerido: view_customer_attribute

Respuesta:

[
  {
    "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"
  }
]

Eliminar un Atributo​

Endpoint: DELETE /crm/attribute/attribute_id/{attribute_id}

Permiso Requerido: delete_customer_attribute

Respuesta:

{
  "result": "success"
}

Operaciones de Atributos en Masa​

Gestión de Múltiples Atributos​

Para establecer múltiples atributos para un cliente a la vez (por ejemplo, durante la incorporación o sincronización de integración):

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"}
    )

Consultando Clientes por Atributo​

Aunque los atributos no tienen puntos finales de búsqueda integrados, puede filtrar clientes por atributo utilizando la API de búsqueda de clientes con filtrado personalizado:

# Obtener todos los clientes, luego filtrar por atributo en el código de la aplicación
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()

    # Encontrar clientes con un atributo específico
    for attr in attributes:
        if attr['attribute_name'] == 'support_tier' and attr['attribute_value'] == 'premium':
            print(f"Cliente premium: {customer['customer_name']}")

::: note ::: title Nota :::

Para consultas frecuentes basadas en atributos, considere agregar campos de base de datos indexados o implementar un punto final de búsqueda dedicado. :::

Mejores Prácticas​

1. Convenciones de Nomenclatura

  • Use snake_case: external_system_id ✓
  • Sea descriptivo: billing_method ✓ vs method ✗
  • Evite palabras clave reservadas o caracteres especiales
  • Documente los significados de los atributos en su guía de implementación

2. Tipos de Datos

  • Los atributos almacenan valores como cadenas (máx. 150 caracteres)
  • Para booleanos, use "true"/"false" (minúsculas)
  • Para fechas, use el formato ISO 8601: "2025-01-04 10:30:00"
  • Para datos JSON grandes, considere campos de base de datos dedicados en su lugar

3. Validación

  • Valide los valores de los atributos en el código de la aplicación antes de guardar
  • Use formatos de valor consistentes entre clientes
  • Documente los valores esperados para cada nombre de atributo

4. Documentación

  • Mantenga un registro de los nombres y propósitos de los atributos
  • Documente qué sistemas/integraciones dependen de atributos específicos
  • Incluya ejemplos de valores válidos

5. Migración y Limpieza

  • Audite regularmente los atributos no utilizados
  • Elimine atributos obsoletos después de migraciones del sistema
  • Versione los nombres de atributos al cambiar esquemas (por ejemplo, api_key_v2)

Ejemplos de Flujos de Trabajo​

Integración de Incorporación​

Al migrar clientes de un sistema heredado:

# Almacenar referencia del sistema heredado para depuración
PUT /crm/attribute/
{
  "customer_id": 123,
  "attribute_name": "legacy_crm_id",
  "attribute_value": "OLD-12345"
}

# Rastrear fecha de migración
PUT /crm/attribute/
{
  "customer_id": 123,
  "attribute_name": "migrated_date",
  "attribute_value": "2025-01-04"
}

Reglas de Facturación Personalizadas​

Anular el ciclo de facturación predeterminado para un cliente específico:

# Establecer facturación trimestral
PUT /crm/attribute/
{
  "customer_id": 123,
  "attribute_name": "billing_cycle",
  "attribute_value": "quarterly"
}

# Luego en el código de facturación, verifique el atributo antes de procesar
attributes = GET /crm/attribute/customer_id/123
billing_cycle = next(
    (a['attribute_value'] for a in attributes if a['attribute_name'] == 'billing_cycle'),
    'monthly'  # predeterminado
)

Banderas de Características​

Habilitar características beta para clientes específicos:

# Habilitar provisión IPv6
PUT /crm/attribute/
{
  "customer_id": 123,
  "attribute_name": "feature_ipv6_enabled",
  "attribute_value": "true"
}

Permisos​

Las operaciones de atributos requieren los siguientes permisos:

  • view_customer_attribute - Ver atributos
  • create_customer_attribute - Crear nuevos atributos
  • update_customer_attribute - Modificar atributos existentes
  • delete_customer_attribute - Eliminar atributos

Consulte rbac para la configuración de control de acceso basado en roles.

Solución de Problemas​

Atributo No Aparece en la UI

  • Verifique que el atributo fue creado (verifique la respuesta de la API)
  • Actualice la página para recargar los datos del cliente
  • Verifique que el usuario tenga el permiso view_customer_attribute

No se Puede Actualizar el Atributo

  • Asegúrese de tener el permiso update_customer_attribute
  • Verifique que el attribute_id sea correcto
  • Verifique que el atributo pertenezca al cliente especificado

Integración Fallando Después de la Eliminación de Atributo

  • Restaure el atributo con el valor anterior
  • Actualice el código de integración para manejar atributos faltantes de manera adecuada
  • Audite las dependencias de atributos antes de la eliminación

Valor del Atributo Truncado

  • Los valores de los atributos tienen un límite de 150 caracteres
  • Para datos más largos, divídalos en múltiples atributos o use el campo de notas del cliente
  • Considere almacenar datos grandes en campos de base de datos dedicados