Pular para o conteúdo principal

Atributos do Cliente

Atributos do Cliente são pares flexíveis de chave-valor que podem ser anexados a qualquer registro de cliente para armazenar metadados personalizados, configurações de configuração ou informações específicas do negócio que não se encaixam nos campos padrão do cliente.

Para categorização visual de clientes e links clicáveis, veja Atributos do Cliente. Para informações básicas sobre clientes, veja Clientes, Contatos, Sites e Serviços.

Ao contrário dos campos fixos do banco de dados, os atributos permitem que você estenda dinamicamente os registros de clientes sem modificar o esquema do banco de dados. Isso os torna ideais para armazenar dados específicos de implantação, parâmetros de integração ou flags de lógica de negócios personalizadas.

Propósito e Casos de Uso​

Casos de uso comuns para Atributos do Cliente incluem:

1. Dados de Integração

Armazene identificadores de sistemas externos ou chaves de API específicas para este cliente:

  • external_crm_id = "SF-12345" (ID do cliente Salesforce)
  • legacy_system_id = "OLD-CRM-789" (Referência de migração)
  • hubspot_contact_id = "12345678" (Integração HubSpot)

2. Lógica de Negócios Personalizada

Armazene flags ou configurações que controlam o comportamento específico do cliente:

  • billing_method = "quarterly" (Substituir a cobrança mensal padrão)
  • auto_provision = "true" (Ativar provisionamento automático de serviços)
  • support_tier = "premium" (Nível de suporte personalizado)
  • credit_limit = "10000" (Limite de crédito específico do cliente)

3. Dados de Conformidade e Regulatórios

Rastreie metadados relacionados à conformidade:

  • gdpr_consent_date = "2025-01-01" (Consentimento para processamento de dados)
  • tax_exempt = "true" (Status de isenção fiscal)
  • regulatory_entity = "FCC-123456" (Identificador regulatório)

4. Metadados Operacionais

Armazene informações operacionais:

  • preferred_contact_method = "email" (Preferência de comunicação)
  • account_manager = "<john.smith@company.com>" (Gerente de conta designado)
  • onboarding_date = "2025-01-15" (Rastreamento do ciclo de vida do cliente)
  • churn_risk_score = "0.23" (Análise preditiva)

5. Parâmetros de Provisionamento

Armazene configurações específicas de provisionamento:

  • radius_username_format = "email" (Formato RADIUS personalizado)
  • vlan_id = "100" (Configuração de rede)
  • ipv6_enabled = "true" (Flags de recurso)

Atributos vs. Campos Padrão​

Use Atributos Quando:

  • Os dados são específicos de implantação ou variam por instalação
  • Os requisitos mudam com frequência
  • Armazenar metadados específicos de integração
  • Prototipar novos recursos antes de adicionar campos ao banco de dados
  • Os dados não precisam de consultas complexas ou junções

Use Campos Padrão Quando:

  • Os dados são essenciais para o modelo de cliente (nome, email, endereço)
  • Busca, filtragem ou relatórios frequentes são necessários
  • Os dados têm restrições de integridade referencial
  • O desempenho é crítico para consultas em larga escala

Gerenciando Atributos via a UI​

Visualizando Atributos do Cliente​

Para visualizar atributos de um cliente:

  1. Navegue até a página de visão geral do cliente
  2. Clique na aba Atributos
  3. Você verá uma tabela de todos os atributos para este cliente, mostrando:
    • Nome do Atributo (chave)
    • Valor do Atributo
    • Data de Criação
    • Data da Última Modificação

Criando um Novo Atributo​

Para criar um novo atributo para um cliente:

  1. Navegue até a página de visão geral do cliente
  2. Clique na aba Atributos
  3. Clique no botão Adicionar Atributo
  4. Preencha os campos obrigatórios:
    • Nome do Atributo (obrigatório): A chave/nome para este atributo (ex: external_crm_id)
    • Valor do Atributo (obrigatório): O valor a ser armazenado (ex: SF-12345)
  5. Clique em Criar Atributo

Convenções de Nomenclatura:

  • Use letras minúsculas com underscores: external_system_id ✓
  • Evite espaços: external system id ✗
  • Mantenha os nomes descritivos, mas concisos
  • Use nomenclatura consistente entre clientes para os mesmos tipos de atributos

Editando um Atributo​

Para editar um atributo existente:

  1. Navegue até a página de visão geral do cliente
  2. Clique na aba Atributos
  3. Encontre o atributo que você deseja editar na tabela
  4. Clique no botão Editar (lápis)
  5. Modifique o nome ou valor do atributo
  6. Clique em Atualizar Atributo

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

Alterar o nome de um atributo cria um novo par chave-valor. Certifique-se de que isso não quebre integrações que dependem do nome original do atributo. :::

Deletando um Atributo​

Para deletar um atributo:

  1. Navegue até a página de visão geral do cliente
  2. Clique na aba Atributos
  3. Encontre o atributo que você deseja deletar na tabela
  4. Clique no botão Deletar (lixeira)
  5. Confirme a exclusão na janela pop-up

::: warning ::: title Aviso :::

Deletar atributos usados por integrações, fluxos de trabalho de provisionamento ou lógica de cobrança pode causar falhas. Verifique as dependências antes da exclusão. :::

Referência de Campo de Atributo​

Integração API​

Atributos podem ser gerenciados programaticamente via API:

Criar ou Atualizar um Atributo​

Endpoint: PUT /crm/attribute/

Permissão Necessária: create_customer_attribute

Corpo da Solicitação:

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

Resposta:

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

Atualizar um Atributo Existente​

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

Permissão Necessária: update_customer_attribute

Corpo da Solicitação:

{
  "attribute_value": "SF-54321"
}

Obter Atributo por ID​

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

Permissão Necessária: view_customer_attribute

Resposta:

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

Obter Todos os Atributos por ID do Cliente​

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

Permissão Necessária: view_customer_attribute

Resposta:

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

Deletar um Atributo​

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

Permissão Necessária: delete_customer_attribute

Resposta:

{
  "result": "success"
}

Operações em Lote de Atributos​

Gerenciando Múltiplos Atributos​

Para definir múltiplos atributos para um cliente de uma vez (ex: durante onboarding ou sincronização de integração):

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​

Embora os atributos não tenham endpoints de busca integrados, você pode filtrar clientes por atributo usando a API de busca de clientes com filtragem personalizada:

# Obter todos os clientes, depois filtrar por atributo no código da aplicação
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 com 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 frequentes baseadas em atributos, considere adicionar campos de banco de dados indexados ou implementar um endpoint de busca dedicado. :::

Melhores Práticas​

1. Convenções de Nomenclatura

  • Use snake_case: external_system_id ✓
  • Seja descritivo: billing_method ✓ vs method ✗
  • Evite palavras-chave reservadas ou caracteres especiais
  • Documente os significados dos atributos em seu guia de implantação

2. Tipos de Dados

  • Atributos armazenam valores como strings (máx. 150 caracteres)
  • Para booleanos, use "true"/"false" (minúsculas)
  • Para datas, use o formato ISO 8601: "2025-01-04 10:30:00"
  • Para grandes dados JSON, considere campos de banco de dados dedicados

3. Validação

  • Valide os valores dos atributos no código da aplicação antes de salvar
  • Use formatos de valor consistentes entre clientes
  • Documente os valores esperados para cada nome de atributo

4. Documentação

  • Mantenha um registro dos nomes e propósitos dos atributos
  • Documente quais sistemas/integrações dependem de atributos específicos
  • Inclua exemplos de valores válidos

5. Migração e Limpeza

  • Audite regularmente atributos não utilizados
  • Remova atributos obsoletos após migrações de sistema
  • Versione nomes de atributos ao alterar esquemas (ex: api_key_v2)

Exemplos de Fluxos de Trabalho​

Integração de Onboarding​

Ao migrar clientes de um sistema legado:

# Armazenar referência do sistema legado para depuração
PUT /crm/attribute/
{
  "customer_id": 123,
  "attribute_name": "legacy_crm_id",
  "attribute_value": "OLD-12345"
}

# Rastrear data da migração
PUT /crm/attribute/
{
  "customer_id": 123,
  "attribute_name": "migrated_date",
  "attribute_value": "2025-01-04"
}

Regras de Cobrança Personalizadas​

Substituir o ciclo de cobrança padrão para um cliente específico:

# Definir cobrança trimestral
PUT /crm/attribute/
{
  "customer_id": 123,
  "attribute_name": "billing_cycle",
  "attribute_value": "quarterly"
}

# Então no código de cobrança, verifique o atributo antes de processar
attributes = GET /crm/attribute/customer_id/123
billing_cycle = next(
    (a['attribute_value'] for a in attributes if a['attribute_name'] == 'billing_cycle'),
    'monthly'  # padrão
)

Flags de Recursos​

Ativar recursos beta para clientes específicos:

# Ativar provisionamento IPv6
PUT /crm/attribute/
{
  "customer_id": 123,
  "attribute_name": "feature_ipv6_enabled",
  "attribute_value": "true"
}

Permissões​

Operações de atributos requerem as seguintes permissões:

  • view_customer_attribute - Visualizar atributos
  • create_customer_attribute - Criar novos atributos
  • update_customer_attribute - Modificar atributos existentes
  • delete_customer_attribute - Remover atributos

Veja rbac para configuração de controle de acesso baseado em função.

Solução de Problemas​

Atributo Não Aparecendo na UI

  • Verifique se o atributo foi criado (verifique a resposta da API)
  • Atualize a página para recarregar os dados do cliente
  • Verifique se o usuário tem permissão view_customer_attribute

Não é Possível Atualizar Atributo

  • Certifique-se de que você tem permissão update_customer_attribute
  • Verifique se o attribute_id está correto
  • Verifique se o atributo pertence ao cliente especificado

Integração Falhando Após Exclusão de Atributo

  • Restaure o atributo com o valor anterior
  • Atualize o código de integração para lidar com atributos ausentes de forma adequada
  • Audite as dependências de atributos antes da exclusão

Valor do Atributo Truncado

  • Os valores dos atributos têm limite de 150 caracteres
  • Para dados mais longos, divida em múltiplos atributos ou use o campo de notas do cliente
  • Considere armazenar grandes dados em campos de banco de dados dedicados