Cards de oportunidade: como nascem e o que registrar
Cada cartão no Kanban representa um negócio em andamento. Este artigo mostra as formas de criar um card no SiteUp, quais campos do item_details preencher para que as métricas funcionem e como conviver com checklist, atividades, anexos e o resumo de chamadas VOIP.
Como um card nasce
A plataforma oferece quatro caminhos:
| Método | Quando usar | Onde aciona |
|---|---|---|
| Manual no quadro | Lead veio offline, indicação, lista | Botão + Novo card dentro de uma coluna |
| A partir de conversa | Cliente está atendido e demonstrou interesse | Modal Importar conversas ou ação rápida no painel da conversa |
| Em massa | Vários cards de uma vez (ex.: planilha) | BulkAddModal no quadro |
| Automático | Round-robin de atribuição quando a conta usa | Disparado no before_create se round_robin_distribution estiver ativo |
Quando o card vem de uma conversa, o item é criado já com conversation_display_id preenchido — a partir daí o card carrega contato, inbox, canal, atendente, status da conversa e última mensagem.
Campos do item_details
O conteúdo principal do card vive no JSONB item_details. Os campos mais usados:
| Campo | Obrigatório | Função |
|---|---|---|
title |
Sim | Identifica o negócio (validado no save) |
description |
Não | Detalhes longos |
value |
Recomendado | Valor previsto, somado no pipeline e enviado para Meta CAPI / Google Ads |
status |
Auto | open, won ou lost (legado também aceita variações) |
priority |
Opcional | low, medium, high, urgent — colore o PriorityCircle |
scheduled_at |
Opcional | Data/hora de agendamento; sincroniza com LeadAppointment e Google Calendar |
deadline_at |
Opcional | Prazo final para o negócio |
notes |
Auto | Lista de notas internas, com autor e timestamp |
custom_attributes |
Opcional | Lista de pares name/type/value cobrindo os atributos do funil |
offers |
Opcional | Itens do catálogo ou ofertas manuais associadas |
automations |
Opcional | Regras locais de mudança de status |
Outros campos do registro: assigned_agents (lista de agentes com avatar e timestamp), checklist, activities, stage_entered_at, timer_duration e timer_started_at.
Sobre o valor
O item_details.value é a base do pipeline. Ele é somado por etapa, exibido no card e enviado como conversionValue para Google Ads e como custom_data.value (BRL) para Meta CAPI quando o evento dispara. Cards sem valor não somam no total_value do funil.
Agendamento e Google Calendar
Quando você preenche scheduled_at, a plataforma cria ou atualiza um LeadAppointment vinculado ao item. Se o funil tem uma conexão Google Calendar configurada, o agendamento é sincronizado automaticamente, aparecendo na agenda do vendedor. Limpar scheduled_at remove o appointment.
Checklist com templates de etapa
Se a etapa atual tem checklist_templates, eles são copiados para o card automaticamente na criação e a cada mudança de etapa. Cada item carrega text, priority, required e completed. Itens com required: true bloqueiam a movimentação automática para outra etapa via regra de status (a regra só executa se todos os obrigatórios estiverem completos).
Anexos e notas
O card aceita anexos diretos (até 10 MB cada, MIMEs validados) e anexos vinculados a notas (até 40 MB, restritos a PNG, JPG e PDF). Notas e anexos são exibidos em abas dedicadas (KanbanAttachmentsTab, KanbanNotesTab) e contam para auditoria via activities.
Resumo VOIP no card
Em contas com a feature voip_wavoip habilitada, cada card mostra um resumo da última chamada do contato (disposition, duração, direção) e o lead profile/score retornados pelo serviço de Lead Scoring. Esse resumo só aparece se há dados úteis — caso contrário, o bloco fica oculto.
Vinculando múltiplas conversas
Cada item liga-se a uma conversa principal pelo conversation_display_id, mas o card mostra todas as conversas do contato no histórico. Os agendamentos, atividades, eventos de integração (Meta/Google) e mudanças ficam empilhados na timeline (activities).
Boas práticas
- Crie o card cedo: quanto mais rápido o negócio entra no Kanban, melhor a previsibilidade.
- Padronize o título: um formato como "Produto — Empresa" facilita busca.
- Preencha valor mesmo aproximado: ele alimenta integrações de conversão e pipeline.
Próximos passos
Com cards criados, siga para Movendo cards e automações. Para entender quando o follow-up automático dispara, leia Follow-up automático.