> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiraa.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Clientes (Cliente 360)

> O cliente é o núcleo do CRM: dados, pipeline, anexos, tarefas, calendário de atividades, documentos e ações rápidas em todos os canais

O **Cliente** é a entidade central da Kiraa. Cada ficha é um **hub vivo**: dados de contato, pipeline, tags, custom fields, **anexos**, **tarefas vinculadas**, **calendário de atividades**, documentos com assinatura digital e **ações rápidas** em todos os canais — tudo numa tela só.

A diferença para um CRM tradicional: a ficha do cliente é onde você **vê** o que aconteceu, **dispara** o próximo passo e **aprende** o estado real do relacionamento. E é onde a IA escreve em tempo real (chamadas do agente de voz, conversas do agente WhatsApp, mudanças automáticas de etapa, automações).

Acesse em **CRM > Clientes**. Para visualizar em funil Kanban, use **CRM > [Board](/board)**.

***

## O que tem na ficha do cliente

A página `/clients/[id]` é organizada em **layout de cards em duas colunas** (não tabs no nível da página):

### Coluna esquerda

* **Anexos** — upload de documentos do cliente
* **Tarefas** — embed das tarefas vinculadas ([Tarefas](/tasks))
* **Atividades** — alterna entre **Calendário** mensal e **Lista** cronológica

### Coluna direita

* **Informações** — dados básicos
* **Pipeline / Etapa** — posição no funil
* **Ações rápidas** — discador, e-mail, SMS, WhatsApp, gerar documento
* **Compartilhamento** — permissões para outros usuários da equipe

***

## Informações básicas

* **Identificação** — nome, **código do cliente** (12 dígitos auto-gerado), empresa e notas.
* **Múltiplos contatos** — vários **telefones** e **e-mails**, cada um com rótulo opcional (ex: "Principal", "Comercial").
* **Origem** — Manual / Inbound / Campanha / Importação / API — indica como entrou na base.
* **Tags** — lista de strings para segmentação. Disparam triggers de [Automação](/automations) (`tag_added`).
* **Notas** — campo livre para contexto que não cabe em campos estruturados.

### Campos customizados

Sua organização define os custom fields no editor inline da ficha (sem sair da tela). Disponíveis em **9 tipos**:

| Tipo              | Uso comum                     |
| ----------------- | ----------------------------- |
| **Texto**         | Notas curtas, identificadores |
| **Número**        | Quantidades                   |
| **Data**          | Vencimentos, datas-chave      |
| **Seleção**       | Lista de opções fixa          |
| **Multi-seleção** | Múltiplas opções              |
| **URL**           | Links externos                |
| **Telefone**      | Telefones extras              |
| **E-mail**        | E-mails extras                |
| **Moeda**         | Valores monetários            |

<Tip>
  Custom fields podem ser marcados como **sensíveis (mask)** — campos como CPF, CNPJ ou número de cartão ficam **mascarados** na UI até você clicar para revelar.
</Tip>

Custom fields aparecem como variáveis em [templates](/files) (`{{cliente_cpf}}`) e disparam triggers de [Automação](/automations) (`custom_field_changed`).

***

## Anexos

Cada cliente tem uma seção dedicada para arquivos vinculados — contratos, comprovantes, documentos de identidade, planilhas de proposta, screenshots de conversas, etc.

<CardGroup cols={2}>
  <Card title="Tipos suportados" icon="file">
    PDF, DOC/DOCX, XLS/XLSX, PPT/PPTX, TXT, CSV, JPEG, PNG, WebP, ZIP
  </Card>

  <Card title="Limite por arquivo" icon="weight-hanging">
    15 MB
  </Card>

  <Card title="Upload" icon="upload">
    Drag-and-drop ou botão "Adicionar"
  </Card>

  <Card title="Audit trail" icon="clipboard-list">
    `attachment_uploaded` e `attachment_deleted` na timeline
  </Card>
</CardGroup>

**Metadata armazenada:** nome do arquivo, tamanho, tipo MIME, quem fez upload, quando.

**Download:** signed URL com TTL de 1 hora — links expiram para evitar exposição de arquivos sensíveis.

<Info>
  Os anexos ficam no Supabase Storage (bucket `client-attachments`), particionado por organização e cliente. Sem preview inline ainda — o arquivo é baixado pelo link assinado.
</Info>

***

## Tarefas embutidas

A seção **Tarefas** mostra as últimas 50 tarefas vinculadas ao cliente, ordenadas com **abertas primeiro**.

**Ações inline:**

* Marcar concluída
* Cancelar
* Reabrir
* Editar prazo

**Botão "Nova tarefa"** abre dialog com responsável + prazo, já vinculando ao cliente atual.

A seção é sincronizada com a página `/tasks` (mesma fonte). Toda mudança reflete em tempo real nas duas telas. Eventos de criação e conclusão também viram atividades `task_created` / `task_completed` na timeline.

<Tip>
  As tarefas podem ser criadas pelo agente de IA durante a conversa (via tool `create_task`), por automação (via bloco `Criar tarefa`), ou manualmente. Veja [Tarefas](/tasks) para detalhes.
</Tip>

***

## Calendário de atividades (timeline)

A seção de atividades tem **duas visões alternáveis**:

<Tabs>
  <Tab title="Calendário">
    Grade mensal com **pontos coloridos** nos dias que têm evento. Click no dia abre **popover** listando o que aconteceu.

    Ideal para entender padrões: quando o cliente costuma responder, há quantos dias está parado, distribuição de envios.
  </Tab>

  <Tab title="Lista">
    Timeline cronológica completa, com ícone por tipo de evento, autor, data e links contextuais (abrir sessão de chamada, baixar documento, etc.).

    Ideal para reconstruir conversa: ver o que foi dito/feito em sequência.
  </Tab>
</Tabs>

**Filtros:** tipo de evento, intervalo de datas, paginação até 500.

### 25+ tipos de evento rastreados

| Categoria                  | Eventos                                                                                                          |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Comunicação**            | `email_sent`, `sms_sent`, `whatsapp_sent`                                                                        |
| **Voz**                    | `call_inbound`, `call_outbound`, `call_campaign`, `call_attempt`, `call_failed`, `call_voicemail`, `call_dialer` |
| **Pipeline**               | `stage_change` (manual), `auto_stage_change` (IA pós-call), `pipeline_change`                                    |
| **Documentos**             | `document_generated`, `document_signature_requested`, `document_signed`                                          |
| **Tarefas**                | `task_created`, `task_completed`                                                                                 |
| **Anexos**                 | `attachment_uploaded`, `attachment_deleted`                                                                      |
| **Retornos**               | `callback_scheduled`, `callback_cancelled`                                                                       |
| **Agendamento (Calendar)** | `scheduling`, `rescheduling`, `cancellation`                                                                     |
| **Tags / outros**          | `tag_change`, `note`, `created`, `updated`, `imported`                                                           |

<Info>
  Toda atividade carrega `metadata.source` (`manual` / `agente` / `automation` / `campanha`) — feed humano único para qualquer cenário. Um e-mail enviado por automação aparece junto de um e-mail enviado pelo time, com a origem clara.
</Info>

### Adicionar nota

O botão **Nota** abre um formulário rápido para registrar qualquer informação manual. Notas viram atividade `note` na timeline e são úteis para contexto que não cabe em campos estruturados.

***

## Pipeline e etapa

* **Stepper visual** que mostra a etapa atual com cor da stage.
* **Quick-add** se o cliente ainda não está em pipeline (popover lista pipelines + stages disponíveis).
* **Toggle "Classificação automática por IA"** — habilita/desabilita classificação pós-chamada para esse cliente específico.

<Info>
  Cada cliente fica em **no máximo 1** pipeline/stage por vez. Para detalhes sobre classificação automática e descrições de stage, veja [Board e Pipelines](/board).
</Info>

Mudanças de etapa disparam triggers de [Automação](/automations) (`stage_entry`).

***

## Ações rápidas

No cabeçalho/lateral da ficha, um conjunto de botões usa templates e plugins conectados:

<CardGroup cols={2}>
  <Card title="Discador" icon="phone">
    Envia o cliente para a fila do discador. Se houver múltiplos telefones, pergunta qual usar.
  </Card>

  <Card title="E-mail" icon="envelope">
    Envia e-mail com template. Exige **Gmail** conectado em [Plugins](/plugins).
  </Card>

  <Card title="SMS" icon="message">
    Envia SMS com template ou texto livre. Exige **Twilio SMS** conectado.
  </Card>

  <Card title="WhatsApp" icon="whatsapp">
    Envia WhatsApp com template. Exige **WhatsApp** conectado.
  </Card>

  <Card title="Gerar documento" icon="file-pen">
    Gera PDF a partir de template, com 3 destinos: **Baixar / WhatsApp / ClickSign**.
  </Card>

  <Card title="Abrir conversa WhatsApp" icon="comments">
    Abre o chat dentro da plataforma usando o número do cliente que casa com integração ativa.
  </Card>
</CardGroup>

<Info>
  Botões dependentes de plugin ficam habilitados somente quando a integração correspondente está **Ativa** em [Plugins](/plugins). SMS/WhatsApp ficam desabilitados se o cliente não tiver telefone cadastrado.
</Info>

### Fluxo de envio (e-mail / SMS / WhatsApp / documento)

<Steps>
  <Step title="Selecionar template e destinatários">
    Escolha o template e marque quais e-mails/telefones usar.
  </Step>

  <Step title="Preencher variáveis">
    A plataforma lista os campos do template com **badge de origem** — **Do cliente**, **Customizado**, **Sistema** ou **Manual**. Os automáticos vêm preenchidos; os **Manual** você completa na hora.
  </Step>

  <Step title="Conferir preview">
    Veja como ficará antes de confirmar.
  </Step>

  <Step title="Enviar ou gerar">
    A ação é executada e registrada na [Atividade](/activity) e na timeline do cliente.
  </Step>
</Steps>

***

## Geração de documento + ClickSign

A geração de documento é integrada com **ClickSign** — você pode gerar um PDF a partir de template e mandar para assinatura digital sem trocar de ferramenta.

### Os 3 destinos

Ao gerar o documento, antes do "gerar" final você escolhe a aba:

<CardGroup cols={3}>
  <Card title="Baixar" icon="download">
    PDF é baixado direto no navegador.
  </Card>

  <Card title="WhatsApp" icon="whatsapp">
    PDF é enviado direto no chat do cliente. Escolha integração + legenda opcional.
  </Card>

  <Card title="Assinatura (ClickSign)" icon="signature">
    PDF é enviado para envelope com signatários e ordem definidas.
  </Card>
</CardGroup>

### Fluxo ClickSign — do template à assinatura

<Steps>
  <Step title="Template">
    Em **Templates > [Biblioteca](/files)**, crie template em **HTML** (editor) ou faça upload de **DOCX**. Use placeholders `{{chave}}` para variáveis dinâmicas.
  </Step>

  <Step title="Geração na ficha">
    Clique em **Gerar documento** na ficha do cliente. Escolha o template; as variáveis aparecem com badges. Preview ao vivo.
  </Step>

  <Step title="Render para PDF">
    HTML vira PDF via render headless; DOCX vira PDF via LibreOffice. O arquivo é salvo no storage da organização.
  </Step>

  <Step title="Configurar envelope">
    Adicione signers (cliente, empresa, signatários adicionais), define a **ordem**:

    * **Sequencial** — cada signer só recebe quando o anterior assinou.
    * **Paralela** — todos recebem ao mesmo tempo.

    Cada signer pode ter **qualificação** e **autenticação** configuradas.
  </Step>

  <Step title="Acompanhar status">
    Status flui automaticamente via webhook do ClickSign:

    * `running` (em curso)
    * `signed` (todos assinaram) ou `declined` (recusado)

    A timeline registra `document_signature_requested` no envio e `document_signed` na conclusão.
  </Step>
</Steps>

### Pré-requisitos

* **ClickSign** conectado em [Plugins](/plugins) com Access Token + ambiente (Sandbox para testes; Produção para uso real).
* **Signatários padrão da empresa** podem ser pré-configurados no plugin para reuso.

<Tip>
  Use **Sandbox** do ClickSign durante a configuração — assinaturas em sandbox não são juridicamente válidas, mas testam o fluxo end-to-end sem custo.
</Tip>

***

## Compartilhamento

Cada cliente pode ter **resource grants** — permissões para usuários específicos da equipe verem/editarem aquele cliente, mesmo que não sejam admins.

Acesse via dialog **Compartilhar** no cabeçalho da ficha.

***

## Importação em lote

Importe clientes em **Excel** (`.xlsx` / `.xls`) com colunas mapeáveis para nome, telefones, e-mails, empresa, tags, notas e **campos customizados**. Durante a importação, opcionalmente informe **pipeline** e **etapa**; sem etapa, o cliente entra na **primeira** da pipeline.

<Tip>
  Mantenha telefones no padrão internacional (ex: `+5511999999999`) para que inbound, campanhas e discagens cruzem corretamente o chamador com a ficha existente.
</Tip>

***

## Ações em lote na lista

Na tabela de **Clientes** (e no **Board**), ao selecionar múltiplas linhas/cartões, a barra de ações permite:

* **Criar campanha** — abre o fluxo de campanha com os clientes selecionados já como base.
* **Discador** — envia os clientes para a **fila do discador** e redireciona para **Operação > Discador**.
* **Disparar automação** (gatilho `manual`) — escolhe automação e dispara para os selecionados.

***

## Relação com ligações

Toda **sessão** (ligação) registrada na plataforma pode ficar vinculada a um cliente:

* Em **chamadas inbound**, a plataforma tenta localizar um cliente pelo telefone do chamador; se não existir, **cria um novo** e, se houver pipeline configurada no número, coloca na **primeira etapa** (veja [Números](/phone-numbers) e [Board](/board)).
* Em **campanhas de voz**, **discador** e **bloco Ligar de automações**, a sessão é associada automaticamente ao cliente.

Isso alimenta o **histórico de ligações** na timeline e a **classificação automática de etapas** após conversas com IA.

***

## Cliente como hub central

Toda feature da Kiraa escreve no cliente:

| Feature                | Como se conecta                                                 |
| ---------------------- | --------------------------------------------------------------- |
| **Agente de voz**      | Liga/atende, escreve atividades, classifica intent              |
| **Agente WhatsApp**    | Identifica pelo telefone, escreve atividades                    |
| **Tools (CRM Action)** | Movem cliente, criam tarefa, agendam retorno, adicionam tag     |
| **Automações**         | Run é por cliente; cada bloco lê/muta o cliente                 |
| **Campanhas**          | Itera lista de clientes; cada item vira call/envio com contexto |
| **Tarefas**            | Vinculadas via `client_id`, embed na ficha                      |
| **Retornos**           | Run aponta para o cliente; aparecem na timeline                 |
| **Documentos**         | Geração linkada via `client_id`                                 |
| **ClickSign**          | Envelope linkado via documento                                  |
| **Anexos**             | Storage particionado por cliente                                |

> **Princípio de design**: nada vive isolado. Toda ação grava em `client_activities` com `metadata.source` (manual / agente / automação / campanha) — feed humano único para qualquer cenário.

***

## Próximos passos

<CardGroup cols={2}>
  <Card title="Board e Pipelines" icon="table-columns" href="/board">
    Organize clientes em funis e ative classificação automática
  </Card>

  <Card title="Tarefas" icon="list-check" href="/tasks">
    Trabalho humano vinculado ao cliente, com prazo e responsável
  </Card>

  <Card title="Retornos" icon="arrow-rotate-left" href="/callbacks">
    Callbacks que o agente IA agenda durante a conversa
  </Card>

  <Card title="Automações" icon="diagram-project" href="/automations">
    Réguas reativas que disparam quando o cliente avança
  </Card>

  <Card title="Templates" icon="file-pen" href="/files">
    Crie templates usados pelos botões de envio e Gerar documento
  </Card>

  <Card title="Plugins" icon="plug" href="/plugins">
    Conecte Gmail, WhatsApp, Twilio, ClickSign e Google Calendar
  </Card>
</CardGroup>