{
"name": "Perpetuus Docs",
"generatedAt": "2026-07-10T16:24:39.475Z",
"baseUrl": "https://docs.perpetuus.com.br",
"apiBaseUrl": "https://api.perpetuus.com.br/api",
"pages": [
{
"title": "Autenticação e Multi-Tenancy",
"description": "Como se autenticar e usar headers de tenant na Perpetuus API.",
"url": "/docs/api/autenticacao",
"path": "api/autenticacao.mdx",
"markdown": "# Autenticação e Multi-Tenancy (/docs/api/autenticacao)\n\n\n\n\n\nTodas as requisições à Perpetuus API (exceto endpoints públicos de formulários e upload) exigem dois headers obrigatórios: **autenticação** e **identificação do tenant**.\n\n## Headers Obrigatórios [#headers-obrigatórios]\n\nPara que qualquer requisição HTTP seja aceita, configure os seguintes cabeçalhos:\n\n| Header | Descrição | Exemplo |\n| --------------- | ----------------------------------------------------------------- | ---------------------- |\n| `Authorization` | Token JWT ou Token de API de longa duração precedido por `Bearer` | `Bearer ppat_52b89...` |\n| `x-tenant-id` | Identificador único (slug) da sua organização no Perpetuus | `acme` |\n\n\n **Atenção:** Sem o cabeçalho `x-tenant-id`, a API retornará erro **400 Bad Request** com a mensagem `Header x-tenant-id é obrigatório`. Sem a autorização, retornará **401 Unauthorized**.\n\n\n***\n\n## Como Obter um Token de API [#como-obter-um-token-de-api]\n\n### 1. Pela Interface Gráfica (Recomendado) [#1-pela-interface-gráfica-recomendado]\n\nOs tokens de longa duração (Personal Access Tokens ou PATs) são ideais para scripts permanentes, integrações via Zapier/Make e painéis de BI.\n\n1. Acesse o Perpetuus CRM e vá em **Configurações** (ícone de engrenagem no menu lateral).\n2. Clique na aba **Organization** (Organização).\n3. Vá para a sub-aba **API**.\n4. Escolha o tempo de expiração desejado (`1 dia`, `30 dias`, `365 dias` ou `Sem Expiração`).\n5. Clique em **Gerar Token**.\n6. **Copie o token imediatamente**. Por motivos de segurança, ele não será exibido novamente.\n\n***\n\n### 2. Gerar Programaticamente (JWT de Sessão) [#2-gerar-programaticamente-jwt-de-sessão]\n\nSe você estiver desenvolvendo uma aplicação que interage com a conta de um usuário final em tempo real, pode gerar um JWT temporário enviando as credenciais de login:\n\n```bash\ncurl -X POST \"https://api.perpetuus.com.br/api/auth/local\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"identifier\": \"desenvolvedor@empresa.com\",\n \"password\": \"SenhaSegura123!\"\n }'\n```\n\nA resposta conterá o campo `jwt`, que expira em poucas horas:\n\n```json\n{\n \"jwt\": \"eyJhbGciOi...\",\n \"user\": {\n \"id\": 12,\n \"username\": \"desenvolvedor\",\n \"email\": \"desenvolvedor@empresa.com\"\n }\n}\n```\n\n***\n\n### 3. Criar Token de Longa Duração via API [#3-criar-token-de-longa-duração-via-api]\n\nCom o JWT temporário gerado no passo anterior, você pode chamar o endpoint `POST /users/generate-token` para obter um PAT de longa duração programaticamente:\n\n```bash\ncurl -X POST \"https://api.perpetuus.com.br/api/users/generate-token\" \\\n -H \"Authorization: Bearer JWT_TEMPORARIO\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"expiration\": \"365d\"\n }'\n```\n\nOs valores de expiração suportados no campo `expiration` são:\n\n* `1d` (1 dia)\n* `30d` (30 dias)\n* `365d` (365 dias)\n* `36500d` (Aproximadamente 100 anos / Sem Expiração)\n\n***\n\n## Exemplo Completo de Requisição [#exemplo-completo-de-requisição]\n\nAbaixo, veja um exemplo completo em cURL que lista os Boards da sua organização `acme`:\n\n```bash\ncurl -X GET \"https://api.perpetuus.com.br/api/boards\" \\\n -H \"Authorization: Bearer SEU_TOKEN_DE_API\" \\\n -H \"x-tenant-id: acme\"\n```\n"
},
{
"title": "APIs BETA",
"description": "Aviso de estabilidade para rotas avançadas com risco de breaking change.",
"url": "/docs/api/beta",
"path": "api/beta.mdx",
"markdown": "# APIs BETA (/docs/api/beta)\n\n\n\nAlgumas áreas da Perpetuus API estão publicadas como **BETA**:\n\n* [Automações](/docs/api/recursos/automacoes)\n* [Canais / WhatsApp](/docs/api/recursos/canais)\n* [Meta Lead Ads](/docs/api/recursos/meta-leads)\n* [Crescimento](/docs/api/recursos/crescimento) (e-mail, distribuição, filtros, pixels)\n\n## O que BETA significa [#o-que-beta-significa]\n\n1. **Contrato pode mudar** sem bump de major version no portal.\n2. **Efeitos colaterais reais** — publish, send-test, sync de templates, verify de pixel, inscrição de webhooks.\n3. Prefira **sandbox** / tenant de teste.\n4. Em cada operação da [API Reference](/reference), a descrição começa com o aviso **BETA**.\n\nAPIs estáveis (boards, cards, contatos, segmentos, campanhas, orçamentos…) **não** entram nessa política.\n"
},
{
"title": "Campos Dinâmicos (fields / fieldData)",
"description": "Como ler, gravar e filtrar dados de campos dinâmicos customizados associados a cards no Perpetuus CRM.",
"url": "/docs/api/campos-dinamicos",
"path": "api/campos-dinamicos.mdx",
"markdown": "# Campos Dinâmicos (fields / fieldData) (/docs/api/campos-dinamicos)\n\n\n\n\n\nOs Boards do Perpetuus CRM permitem a criação de campos dinâmicos por fase (ex: CNPJ, Valor da Proposta, Data de Fechamento). Para simplificar o consumo desses dados, a API expõe os campos em dois formatos: **Escrita facilitada** e **Leitura dupla**.\n\n***\n\n## Escrita (POST e PUT) [#escrita-post-e-put]\n\nAo criar ou atualizar um card, envie as informações em formato de objeto plano contendo os pares **`slug: valor`** dentro da propriedade `fields`. O backend descobre automaticamente em qual fase o campo reside e realiza a validação de tipo e obrigatoriedade.\n\n```json\n{\n \"data\": {\n \"title\": \"Empresa ACME\",\n \"fields\": {\n \"cnpj\": \"00.000.000/0001-00\",\n \"valor_estimado\": 45000.50,\n \"urgencia\": \"ALTA\"\n }\n }\n}\n```\n\n\n **Atualização Parcial (PUT):** Não é necessário enviar todos os campos dinâmicos no `PUT`. Envie apenas os slugs que deseja alterar. Os campos não declarados manterão seus valores intactos.\n\n\n***\n\n## Leitura (GET) [#leitura-get]\n\nNas requisições de leitura (`GET`), os dados são retornados em duas chaves distintas para acomodar necessidades simples e avançadas:\n\n### 1. Objeto Plano `fields` (Recomendado) [#1-objeto-plano-fields-recomendado]\n\nO objeto `fields` traz todos os campos dinâmicos preenchidos do card em um formato direto e desembrulhado. Ideal para integrações rápidas, Make, Zapier e envio de e-mails/templates.\n\n```json\n{\n \"documentId\": \"card_abc123\",\n \"title\": \"Empresa ACME\",\n \"fields\": {\n \"cnpj\": \"00.000.000/0001-00\",\n \"valor_estimado\": 45000.50,\n \"urgencia\": \"ALTA\"\n }\n}\n```\n\n### 2. Array Estruturado `fieldData` (Avançado) [#2-array-estruturado-fielddata-avançado]\n\nPara sistemas que precisam de metadados ricos (como o tipo do campo, label cadastrado ou a fase original em que o dado foi preenchido), inclua `fieldData` no parâmetro `populate`.\n\n```json\n{\n \"documentId\": \"card_abc123\",\n \"fieldData\": [\n {\n \"documentId\": \"data_record_01\",\n \"value\": {\n \"val\": \"00.000.000/0001-00\"\n },\n \"field\": {\n \"documentId\": \"field_cnpj\",\n \"name\": \"CNPJ da Empresa\",\n \"slug\": \"cnpj\",\n \"type\": \"text\"\n },\n \"phase\": {\n \"documentId\": \"phase_inbound\",\n \"name\": \"Entrada\"\n }\n }\n ]\n}\n```\n\n\n **Atenção ao Storage:** No array `fieldData`, o valor real está encapsulado sob a chave `value.val`. Certifique-se de navegar até esta propriedade ao ler o array cru.\n\n\n***\n\n## Filtrar por Campos Dinâmicos na API [#filtrar-por-campos-dinâmicos-na-api]\n\nPara filtrar a listagem de cards com base em um campo dinâmico customizado, filtre navegando pelo array `fieldData`:\n\n```bash\n# Filtrar cards cujo CNPJ seja exatamente '00.000.000/0001-00'\ncurl -G \"https://api.perpetuus.com.br/api/boards/BOARD_ID/cards\" \\\n -H \"Authorization: Bearer SEU_TOKEN\" \\\n -H \"x-tenant-id: acme\" \\\n --data-urlencode \"filters[fieldData][field][slug]=cnpj\" \\\n --data-urlencode \"filters[fieldData][value][val]=00.000.000/0001-00\"\n```\n"
},
{
"title": "Convenções e Padrões de Dados",
"description": "Padrões de requisições, envelopes de respostas e tratamento de IDs e tags na Perpetuus API.",
"url": "/docs/api/convencoes",
"path": "api/convencoes.mdx",
"markdown": "# Convenções e Padrões de Dados (/docs/api/convencoes)\n\n\n\n\n\nA Perpetuus API utiliza padrões consistentes em todos os seus módulos para garantir clareza nas integrações. Esta página detalha as principais convenções arquiteturais do sistema.\n\n## Identificadores Únicos (documentId) [#identificadores-únicos-documentid]\n\nEm conformidade com a arquitetura moderna de nosso motor de persistência, todos os registros acessíveis pela API expõem e utilizam identificadores únicos de string conhecidos como **`documentId`** (ex: `qt1a2b3c`, `pr9x8y7z`).\n\n\n **Atenção:** Evite o uso de chaves primárias numéricas internas (como `id: 42`). O `documentId` é o único identificador estável entre atualizações e migrações de dados, sendo obrigatório na URL de rotas customizadas.\n\n\n### Convenções de Parâmetros nas URLs [#convenções-de-parâmetros-nas-urls]\n\nNos endpoints que exigem parâmetros de caminho (path parameters), você encontrará principalmente as seguintes variáveis:\n\n* **`:boardId` / `:boardDocumentId`:** O `documentId` do quadro. Ex: `/boards/{boardId}/cards`.\n* **`:id`:** Usado no CRUD básico de recursos individuais. Ex: `/contacts/{id}` ou `/boards/{id}`.\n* **`:cardId` / `:membershipId`:** Parâmetros específicos em relacionamentos ou sub-recursos. Ex: `/teams/{id}/members/{membershipId}`.\n\n***\n\n## Envelopes de Resposta [#envelopes-de-resposta]\n\nA API responde utilizando dois formatos principais de estrutura de dados:\n\n### 1. Envelope Padrão (Tipo Strapi) [#1-envelope-padrão-tipo-strapi]\n\nUtilizado pela maioria dos endpoints de listagem de dados e CRUD. Segue a estrutura com chaves `data` (que pode ser um objeto ou uma lista de objetos) e `meta`.\n\n```json\n{\n \"data\": [\n {\n \"documentId\": \"card_9x8y7z\",\n \"title\": \"Proposta Comercial ACME\",\n \"createdAt\": \"2026-07-09T18:00:00Z\"\n }\n ],\n \"meta\": {\n \"pagination\": {\n \"page\": 1,\n \"pageSize\": 25,\n \"pageCount\": 1,\n \"total\": 1\n }\n }\n}\n```\n\n***\n\n### 2. Envelope Analítico (Tipo Report) [#2-envelope-analítico-tipo-report]\n\nUtilizado exclusivamente em endpoints de agregação e métricas de inteligência comercial, como o `GET /boards/{boardId}/report`. Estes payloads retornam dados prontos para análise sem chaves internas de paginação.\n\n```json\n{\n \"boardId\": \"board_xyz\",\n \"summary\": {\n \"totalCards\": 120,\n \"wonValue\": 450000.00\n },\n \"phases\": [\n {\n \"documentId\": \"phase_abc\",\n \"name\": \"Proposta Enviada\",\n \"cardsCount\": 15\n }\n ],\n \"period\": {\n \"from\": \"2026-07-01\",\n \"to\": \"2026-07-09\"\n }\n}\n```\n\n***\n\n## Associações de Tags em Cards [#associações-de-tags-em-cards]\n\nAo criar ou atualizar cards via API (`POST` ou `PUT`), o campo `tags` é flexível: você pode enviar tanto o **`documentId`** da tag quanto o **slug** cadastrado no board.\n\n```json\n{\n \"data\": {\n \"title\": \"Novo Card\",\n \"tags\": [\"prioritario\", \"tag_doc_id_123\"]\n }\n}\n```\n\n* Se o slug de tag fornecido não existir previamente no board, a API retornará status **400 Bad Request** com a lista de tags válidas.\n* Na leitura de dados (`GET`), a associação de tags sempre retornará objetos estruturados contendo `documentId`, `name` e `slug`.\n"
},
{
"title": "Tratamento de Erros",
"description": "Estrutura padrão de respostas de erro da Perpetuus API.",
"url": "/docs/api/erros",
"path": "api/erros.mdx",
"markdown": "# Tratamento de Erros (/docs/api/erros)\n\n\n\n\n\nA Perpetuus API utiliza códigos de status HTTP padrão para indicar o sucesso ou falha de uma requisição de API. Em caso de erro, a API retorna um payload JSON estruturado contendo detalhes sobre o problema para facilitar o diagnóstico.\n\n## Estrutura do Erro JSON [#estrutura-do-erro-json]\n\nTodos os erros retornados pela API seguem este formato de envelope:\n\n```json\n{\n \"error\": {\n \"status\": 400,\n \"name\": \"ValidationError\",\n \"message\": \"x-tenant-id header is required\",\n \"details\": {}\n }\n}\n```\n\n* **`status`:** O código de status HTTP correspondente.\n* **`name`:** A classe ou categoria do erro (ex: `ValidationError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`).\n* **`message`:** Uma descrição clara do erro legível por humanos.\n* **`details`:** Detalhes adicionais específicos (como validação de campos ausentes ou chaves duplicadas).\n\n***\n\n## Tabela de Códigos de Status HTTP [#tabela-de-códigos-de-status-http]\n\n| Código | Nome do Erro | Causa Comum | Como Resolver |\n| ------- | --------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |\n| **400** | Bad Request | Parâmetros inválidos, payloads incorretos ou ausência do header `x-tenant-id` | Verifique o payload enviado e garanta que o header `x-tenant-id` esteja presente. |\n| **401** | Unauthorized | Token ausente, expirado ou inválido no header `Authorization` | Gere um novo token de API nas Configurações da Organização e verifique a expiração. |\n| **403** | Forbidden | Usuário ou token autenticado não possui permissão para o recurso ou o plano não dá direito à feature | Verifique os papéis de acesso do usuário ou contate o administrador sobre limites do plano contratado. |\n| **404** | Not Found | Registro com o `documentId` especificado não existe ou a URL está incorreta | Valide se o `documentId` (ex: de um card ou board) foi digitado corretamente e não foi excluído. |\n| **422** | Unprocessable Entity | Validação de negócio falhou (ex: tentar mover card para fase bloqueada ou preço abaixo do mínimo) | Revise as regras do board ou fluxo de automação para entender qual validação de negócio bloqueou a ação. |\n| **429** | Too Many Requests | Limite de taxa (Rate Limit) de requisições excedido para o token ou IP | Reduza a frequência das requisições e implemente uma estratégia de backoff exponencial. |\n| **500** | Internal Server Error | Erro inesperado nos servidores do Perpetuus | Tente novamente em alguns segundos. Se persistir, entre em contato com nosso suporte técnico. |\n\n***\n\n## Exemplo de Erro de Validação (400) [#exemplo-de-erro-de-validação-400]\n\nAo tentar criar um card sem preencher os campos dinâmicos obrigatórios definidos para a fase de entrada (Phase 0):\n\n```json\n{\n \"error\": {\n \"status\": 400,\n \"name\": \"ValidationError\",\n \"message\": \"Fields validation failed\",\n \"details\": {\n \"errors\": [\n {\n \"path\": [\"name\"],\n \"message\": \"O campo 'name' é obrigatório no formulário de entrada deste Board.\"\n }\n ]\n }\n }\n}\n```\n"
},
{
"title": "Visão Geral da API",
"description": "Introdução ao Guia Técnico da Perpetuus API.",
"url": "/docs/api",
"path": "api/index.mdx",
"markdown": "# Visão Geral da API (/docs/api)\n\n\n\n\n\nBem-vindo ao Guia Técnico da **Perpetuus API**. Toda a inteligência e funcionalidade que você encontra em nossa interface web — boards, cards, contatos, relatórios analíticos, automações e inteligência de atendimento — está acessível programaticamente.\n\nNossa API segue os princípios **RESTful**, consumindo e retornando payloads em formato **JSON** e utilizando códigos de status HTTP padrão para indicar o sucesso ou falha das operações.\n\n## Acesso e URL Base [#acesso-e-url-base]\n\nToda a interação com a API pública do Perpetuus deve ser direcionada para a URL base oficial:\n\n```text\nhttps://api.perpetuus.com.br/api\n```\n\n\n **Importante:** A Perpetuus API opera em modelo multi-tenant. Cada requisição precisa informar a qual organização (tenant) pertence. Veja os detalhes na página de [Autenticação](/docs/api/autenticacao).\n\n\n## Casos de Uso Comuns para Desenvolvedores [#casos-de-uso-comuns-para-desenvolvedores]\n\nCom a Perpetuus API, você pode integrar facilmente o CRM ao ecossistema da sua empresa:\n\n* **Sincronização de Leads (Inbound):** Capture contatos de formulários proprietários, landing pages externas ou sistemas parceiros e envie diretamente para uma fase específica de um Board.\n* **Integração de BI e ETL:** Extraia dados linha a linha de cards e logs de atividades para alimentar Power BI, Looker Studio ou bancos de dados analíticos locais.\n* **Automação Comercial:** Conecte o CRM a sistemas de faturamento e ERPs para iniciar e acompanhar cotações ou gerar orçamentos comerciais em PDF de forma programática.\n* **Agentes de IA:** Conecte LLMs e assistentes de voz ao CRM utilizando nosso protocolo unificado [MCP (Model Context Protocol)](/docs/api/mcp).\n\n## Próximos Passos [#próximos-passos]\n\n1. **[Autenticação e Multi-Tenancy](/docs/api/autenticacao):** Aprenda a obter o seu token de longa duração e configure os headers necessários.\n2. **[Convenções de URL e Dados](/docs/api/convencoes):** Entenda como a API mapeia os recursos usando `documentId` e quais os formatos padrão de resposta.\n3. **[API Reference](/reference):** Explore interativamente a especificação OpenAPI completa de cada endpoint com try-it-out.\n"
},
{
"title": "Agentes de IA (MCP)",
"description": "Como integrar a Perpetuus API com agentes de inteligência artificial através do Model Context Protocol (MCP).",
"url": "/docs/api/mcp",
"path": "api/mcp.mdx",
"markdown": "# Agentes de IA (MCP) (/docs/api/mcp)\n\n\n\nO Perpetuus CRM disponibiliza um **servidor MCP (Model Context Protocol)** autônomo.\nEle permite que agentes (Cursor, Claude Desktop e SDKs) leiam e editem o CRM com as\nmesmas permissões do seu usuário.\n\n## Setup rápido no Cursor [#setup-rápido-no-cursor]\n\n\n \n Gere um [token de API](/docs/guia/gerando-token) e anote o slug da organização.\n \n\n \n No repositório, entre em `perpetuus-crm-mcp`, rode `npm install`.\n \n\n \n Copie o JSON abaixo para `.cursor/mcp.json` (ajuste `cwd`, tenant e token).\n \n\n \n Reinicie o Cursor e peça: “liste meus boards no Perpetuus”.\n \n\n\n\n\n## Por que MCP? [#por-que-mcp]\n\n* **Interface unificada:** o agente lista boards, busca contatos, move cards e cria tarefas sem decorar paths REST.\n* **Segurança:** o MCP só fala com a API REST — tenant, RBAC e plano continuam no backend.\n* **Ciclo de vida separado:** deploy e auditoria independentes do runtime de mensagens.\n\n## Rodando localmente [#rodando-localmente]\n\n### STDIO (Cursor / VS Code) [#stdio-cursor--vs-code]\n\n```bash\nSTRAPI_URL=https://api.perpetuus.com.br \\\nMCP_CRM_TENANT_ID=sua-organizacao \\\nMCP_CRM_USER_TOKEN=seu_token_de_api \\\nnpx tsx src/stdio.ts\n```\n\n### HTTP (conexões remotas) [#http-conexões-remotas]\n\n```bash\nSTRAPI_URL=https://api.perpetuus.com.br \\\nMCP_CRM_TENANT_ID=sua-organizacao \\\nMCP_CRM_USER_TOKEN=seu_token_de_api \\\nMCP_CRM_HTTP_PORT=3031 \\\nnpx tsx src/http.ts\n```\n\n```bash\ncurl -fsS http://127.0.0.1:3031/health\n```\n\n## Catálogo de ferramentas [#catálogo-de-ferramentas]\n\n### Contatos [#contatos]\n\n* `crm.search_contacts`, `crm.get_contact`, `crm.create_contact`, `crm.update_contact`\n* `crm.add_contact_note`\n\n### Boards e pipeline [#boards-e-pipeline]\n\n* `crm.list_boards`, `crm.get_board_structure`\n* `crm.search_cards`, `crm.create_card`, `crm.update_card`, `crm.move_card_phase`\n\n### Analytics [#analytics]\n\n* `crm.get_board_report`, `crm.aggregate_card_field`\n\n\n A especificação completa das tools está no `README` do pacote `perpetuus-crm-mcp`.\n Para o contrato REST, use a [API Reference](/reference) ou baixe\n [`/export/docs.json`](/export/docs.json).\n\n"
},
{
"title": "Guia de Migração (Sunset Flat Routes)",
"description": "Como atualizar suas integrações das rotas legadas flat para as rotas canônicas baseadas em Boards no Perpetuus.",
"url": "/docs/api/migracao",
"path": "api/migracao.mdx",
"markdown": "# Guia de Migração (Sunset Flat Routes) (/docs/api/migracao)\n\n\n\n\n\nComo parte da padronização e da otimização de segurança de multi-tenancy na Perpetuus API, todas as rotas de CRUD direto sem escopo de Board (rotas flat) foram descontinuadas ou removidas.\n\n***\n\n## Por que migrar? [#por-que-migrar]\n\n* **Segurança de Dados:** As rotas aninhadas (ex: `/boards/{boardId}/cards`) garantem que o usuário e a API validem as permissões de acesso ao processo (Board) antes de ler ou escrever dados.\n* **Campos Dinâmicos e Validação:** O motor de validação de campos dinâmicos (`fields`) depende das definições de fase que pertencem a um Board. Rotas flat não suportam essa inteligência nativamente.\n* **Desempenho:** Consultas aninhadas reduzem o overhead de carregamento de registros órfãos ou de múltiplos boards simultaneamente.\n\n***\n\n## Tabela de Substituição de Endpoints [#tabela-de-substituição-de-endpoints]\n\nSe você possui integrações antigas, substitua as chamadas conforme a convenção abaixo:\n\n| Método | Endpoint Legado (Flat) | Novo Endpoint Canônico (Nested) |\n| ---------- | ---------------------- | ----------------------------------------- |\n| **GET** | `/api/cards` | `GET /api/boards/{boardId}/cards` |\n| **POST** | `/api/cards` | `POST /api/boards/{boardId}/cards` |\n| **GET** | `/api/cards/{id}` | `GET /api/boards/{boardId}/cards/{id}` |\n| **PUT** | `/api/cards/{id}` | `PUT /api/boards/{boardId}/cards/{id}` |\n| **DELETE** | `/api/cards/{id}` | `DELETE /api/boards/{boardId}/cards/{id}` |\n| **GET** | `/api/phases` | `GET /api/boards/{boardId}/phases` |\n| **GET** | `/api/fields` | `GET /api/boards/{boardId}/fields` |\n| **GET** | `/api/tags` | `GET /api/boards/{boardId}/tags` |\n\n\n **Descobrindo o `boardId`:** O parâmetro `{boardId}` exigido na URL corresponde ao **`documentId`** (string) do quadro. Você pode descobri-lo listando seus quadros via `GET /api/boards` ou copiando diretamente da URL do aplicativo web (ex: `app.perpetuus.com.br/boards/BOARD_ID`).\n\n\n***\n\n## Exemplo de Transição de Código (Criar Card) [#exemplo-de-transição-de-código-criar-card]\n\n### Antes (Legado) [#antes-legado]\n\n```javascript\n// POST /api/cards\nconst res = await fetch('https://api.perpetuus.com.br/api/cards', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer TOKEN',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n data: {\n title: 'Oportunidade Legada',\n board: 'board_document_id_123' // Enviava o board no corpo\n }\n })\n});\n```\n\n### Agora (Canônico e Seguro) [#agora-canônico-e-seguro]\n\n```javascript\n// POST /api/boards/board_document_id_123/cards\nconst res = await fetch('https://api.perpetuus.com.br/api/boards/board_document_id_123/cards', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer TOKEN',\n 'x-tenant-id': 'minha-empresa', // Header tenant obrigatório\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n data: {\n fields: {\n name: 'Oportunidade Nova (Inbound)' // Campos no objeto fields\n }\n }\n })\n});\n```\n"
},
{
"title": "Paginação e Filtros",
"description": "Como paginar grandes volumes de dados e filtrar recursos na Perpetuus API.",
"url": "/docs/api/paginacao-filtros",
"path": "api/paginacao-filtros.mdx",
"markdown": "# Paginação e Filtros (/docs/api/paginacao-filtros)\n\n\n\n\n\nOs endpoints que retornam listas de recursos (como cards, contatos, tarefas e produtos) suportam parâmetros unificados de paginação, ordenação e filtros.\n\n## Paginação [#paginação]\n\nA API utiliza paginação baseada em páginas (`page`) por padrão. Os parâmetros aceitos são:\n\n* `pagination[page]`: O número da página solicitada (padrão: `1`).\n* `pagination[pageSize]`: A quantidade de registros retornados por página (padrão: `25`, máximo: `100`).\n\n```bash\n# Solicitar página 2 com 50 itens por página\ncurl -G \"https://api.perpetuus.com.br/api/boards/BOARD_ID/cards\" \\\n -H \"Authorization: Bearer SEU_TOKEN\" \\\n -H \"x-tenant-id: acme\" \\\n --data-urlencode \"pagination[page]=2\" \\\n --data-urlencode \"pagination[pageSize]=50\"\n```\n\n***\n\n### Exemplo em JavaScript: Paginação em Loop [#exemplo-em-javascript-paginação-em-loop]\n\nPara integrações do tipo ETL (sincronização de dados de contatos ou cards para armazéns locais), utilize o padrão em loop abaixo para consumir todas as páginas disponíveis de forma segura:\n\n```javascript\nasync function fetchAllContacts(token, tenant) {\n const pageSize = 100;\n let page = 1;\n let allContacts = [];\n\n while (true) {\n const params = new URLSearchParams({\n 'pagination[page]': String(page),\n 'pagination[pageSize]': String(pageSize),\n 'sort': 'createdAt:asc'\n });\n\n const response = await fetch(`https://api.perpetuus.com.br/api/contacts?${params}`, {\n headers: {\n 'Authorization': `Bearer ${token}`,\n 'x-tenant-id': tenant\n }\n });\n\n if (!response.ok) {\n throw new Error(`Erro HTTP: ${response.status}`);\n }\n\n const payload = await response.json();\n const data = payload.data || [];\n allContacts = allContacts.concat(data);\n\n const pagination = payload.meta?.pagination;\n if (!pagination || allContacts.length >= pagination.total) {\n break;\n }\n \n page++;\n }\n\n return allContacts;\n}\n```\n\n***\n\n## Filtros [#filtros]\n\nA filtragem utiliza a notação de query do Strapi (parâmetros de array aninhados). Os principais operadores suportados são:\n\n| Operador | Significado | Exemplo de Query Parameter |\n| ------------ | ------------------------- | ------------------------------------------------------------------------------------------------- |\n| `$eq` | Igual a | `filters[email][$eq]=lead@cliente.com` |\n| `$ne` | Diferente de | `filters[active][$ne]=false` |\n| `$contains` | Contém (case-sensitive) | `filters[name][$contains]=Silva` |\n| `$containsi` | Contém (case-insensitive) | `filters[title][$containsi]=urgente` |\n| `$in` | Está na lista (array) | `filters[currentPhase][documentId][$in][0]=fase1&filters[currentPhase][documentId][$in][1]=fase2` |\n| `$gte` | Maior ou igual a | `filters[createdAt][$gte]=2026-07-01T00:00:00Z` |\n| `$lte` | Menor ou igual a | `filters[createdAt][$lte]=2026-07-09T23:59:59Z` |\n\n### Exemplo Prático de Filtro [#exemplo-prático-de-filtro]\n\nPara listar cards com o título contendo \"ACME\" e que estejam na fase com ID `phase_draft_123`:\n\n```bash\ncurl -G \"https://api.perpetuus.com.br/api/boards/BOARD_ID/cards\" \\\n -H \"Authorization: Bearer SEU_TOKEN\" \\\n -H \"x-tenant-id: acme\" \\\n --data-urlencode \"filters[title][$containsi]=ACME\" \\\n --data-urlencode \"filters[currentPhase][documentId]=$eq:phase_draft_123\"\n```\n\n## Ordenação (Sort) [#ordenação-sort]\n\nOrdene os resultados informando o atributo e a direção (`asc` para ascendente, `desc` para descendente):\n\n* `sort=createdAt:desc` (mais recentes primeiro)\n* `sort=dueDate:asc` (vencimento mais próximo primeiro)\n\nPara múltiplos critérios, envie um array ou separe por vírgula conforme o endpoint:\n`sort[0]=dueDate:asc&sort[1]=createdAt:desc`\n"
},
{
"title": "Leve para a IDE",
"description": "Baixe o OpenAPI e a documentação completa, e conecte o MCP no Cursor em minutos.",
"url": "/docs/api/para-ide",
"path": "api/para-ide.mdx",
"markdown": "# Leve para a IDE (/docs/api/para-ide)\n\n\n\nUse estes artefatos para colar a Perpetuus API no Cursor, Claude, ChatGPT ou no seu agente.\n\n## Downloads [#downloads]\n\n| Artefato | Para quê | Link |\n| ------------ | ------------------------------------------ | --------------------------- |\n| OpenAPI JSON | Contrato da API (Scalar, Postman, codegen) | [Baixar](/openapi.json) |\n| OpenAPI YAML | Mesmo contrato em YAML | [Baixar](/openapi.yaml) |\n| Docs (.md) | Documentação completa em Markdown | [Baixar](/export/docs.md) |\n| Docs (.json) | Páginas estruturadas para agentes | [Baixar](/export/docs.json) |\n\nBase URL: `https://api.perpetuus.com.br/api`\n\n## Conecte o MCP no Cursor [#conecte-o-mcp-no-cursor]\n\n\n \n Gere um [token de API](/docs/guia/gerando-token) e anote o slug da organização.\n \n\n \n No monorepo, entre em `perpetuus-crm-mcp` e rode `npm install`.\n \n\n \n Copie o JSON abaixo para `.cursor/mcp.json` (ajuste `cwd`, tenant e token).\n \n\n \n Reinicie o Cursor e peça: “liste meus boards no Perpetuus”.\n \n\n\n\n\n## Próximos passos [#próximos-passos]\n\n* [Agentes de IA (MCP) — detalhes](/docs/api/mcp)\n* [API Reference interativa](/reference)\n* [Integrações n8n / Zapier / Make](/docs/guia/integracoes-comuns)\n"
},
{
"title": "Perguntas frequentes",
"description": "Dúvidas comuns sobre a Perpetuus API.",
"url": "/docs/guia/faq",
"path": "guia/faq.mdx",
"markdown": "# Perguntas frequentes (/docs/guia/faq)\n\n\n\n## Preciso ser desenvolvedor para usar a API? [#preciso-ser-desenvolvedor-para-usar-a-api]\n\nNão necessariamente. Com [Zapier, Make ou n8n](/docs/guia/integracoes) você conecta o\nPerpetuus a outras ferramentas sem escrever código. Para capturar leads do site, o\n[formulário público](/docs/guia/formulario-publico) resolve sem backend.\n\n## Quem pode gerar tokens de API? [#quem-pode-gerar-tokens-de-api]\n\nQualquer usuário autenticado pode gerar um token **com as suas próprias permissões**.\nO token herda o papel do usuário na organização — um operador não consegue, via API,\nfazer nada além do que já faz na interface.\n\n## O token dá acesso a todas as minhas organizações? [#o-token-dá-acesso-a-todas-as-minhas-organizações]\n\nO token identifica o **usuário**; a organização é definida em cada requisição pelo\nheader `x-tenant-id`. Você só acessa organizações das quais é membro.\n\n## Existe limite de requisições? [#existe-limite-de-requisições]\n\nEndpoints sensíveis (geração de token, disparo de campanhas) têm rate limit reforçado.\nPara listagens, o `pageSize` máximo é **100** — use paginação para volumes maiores.\n\n## Posso disparar ações automáticas? [#posso-disparar-ações-automáticas]\n\nSim — o módulo de **Automações** do Perpetuus reage a eventos (card criado, fase\nalterada, mensagem recebida) e pode executar ações, incluindo chamadas HTTP para\nsistemas externos. Configure em **Automações** no app.\n\n## Como alimento meu BI (Power BI, Looker, Metabase)? [#como-alimento-meu-bi-power-bi-looker-metabase]\n\nUse `GET /boards/{boardId}/cards` para dados linha a linha e\n`GET /boards/{boardId}/report` para métricas agregadas. O passo a passo completo está\nem [Relatórios e BI](/docs/api/recursos/relatorios).\n\n## E se eu excluir algo por engano via API? [#e-se-eu-excluir-algo-por-engano-via-api]\n\nExclusões via API são definitivas, como na interface. Atenção especial a\n`DELETE /boards/{id}` (remove o board **e os cards**) e às operações em massa de\ncontatos. Teste sempre em um board de sandbox primeiro.\n\n## Onde vejo todos os endpoints? [#onde-vejo-todos-os-endpoints]\n\nNa [API Reference](/reference) — referência interativa com exemplos de request e\nresposta para todas as operações disponíveis.\n"
},
{
"title": "Capturando leads do seu site",
"description": "Use o formulário público do board para receber leads sem autenticação e sem código de backend.",
"url": "/docs/guia/formulario-publico",
"path": "guia/formulario-publico.mdx",
"markdown": "# Capturando leads do seu site (/docs/guia/formulario-publico)\n\n\n\nTodo board tem uma **fase de formulário** (a primeira coluna, de `order` 0). Os campos\ndela podem ser preenchidos publicamente — sem token, sem login — através dos endpoints\nde formulário público. É o jeito mais simples de transformar o formulário do seu site\nem cards no CRM.\n\n## Opção 1: link do formulário pronto [#opção-1-link-do-formulário-pronto]\n\nO Perpetuus já gera uma página de formulário para cada board. Em **Board → Fase de\nformulário → Compartilhar**, copie o link e use direto ou dentro de um iframe no seu site.\n\n## Opção 2: formulário próprio no seu site [#opção-2-formulário-próprio-no-seu-site]\n\nSe você quer manter o visual do seu site, envie os dados direto para a API pública:\n\n```html title=\"exemplo.html\"\n\n\n\n```\n\nOs nomes dos inputs devem corresponder aos **slugs dos campos** do formulário do board.\nPara descobrir a estrutura (campos, obrigatoriedade, textos), consulte:\n\n```bash\ncurl \"https://api.perpetuus.com.br/api/boards/SEU_BOARD_ID/public-form\"\n```\n\n## Rastreamento de origem [#rastreamento-de-origem]\n\nO formulário público aceita campos de rastreamento junto ao envio — `fbclid`, `gclid`\ne UTMs — que ficam anexados ao card. Assim você sabe de qual campanha veio cada lead.\n\n## Uploads [#uploads]\n\nCampos do tipo arquivo usam o endpoint `POST /boards/{boardId}/public-upload`\n(multipart). Veja os detalhes na [API Reference](/reference).\n\n## Dica [#dica]\n\nCombine com [automações](/docs/guia/faq#posso-disparar-acoes-automaticas) para\nnotificar o time no WhatsApp ou atribuir um responsável automaticamente a cada lead\nque chegar.\n"
},
{
"title": "Gerando um token de API",
"description": "Crie um token de longa duração pela interface do Perpetuus para usar em integrações.",
"url": "/docs/guia/gerando-token",
"path": "guia/gerando-token.mdx",
"markdown": "# Gerando um token de API (/docs/guia/gerando-token)\n\n\n\nPara integrações (Zapier, Make, scripts, BI), você precisa de um **token de API**.\nA forma mais simples é gerar pela interface.\n\n## Pela interface (recomendado) [#pela-interface-recomendado]\n\n\n \n Acesse **Configurações** no menu lateral (ícone de engrenagem).\n \n\n \n Clique em **Organização**.\n \n\n \n Vá na aba **API**.\n \n\n \n Escolha a expiração: 1 dia, 30 dias, 365 dias ou sem expiração.\n \n\n \n Clique em **Gerar Token**.\n \n\n \n **Copie o token e guarde em local seguro** — ele não será mostrado novamente.\n \n\n\nO caminho direto é `/settings/organization` → aba **API**.\n\n## Boas práticas de segurança [#boas-práticas-de-segurança]\n\n* Trate o token como uma **senha**: quem o possui pode agir no CRM em seu nome.\n* Guarde em variável de ambiente ou cofre de segredos — nunca em planilhas\n compartilhadas ou repositórios públicos.\n* Prefira expirações curtas para testes e renove tokens periodicamente.\n* Se um token vazar, gere um novo imediatamente.\n\n## Alternativa: gerar via API [#alternativa-gerar-via-api]\n\nPara automações de provisionamento, também é possível gerar tokens programaticamente —\nveja [Autenticação no Guia Técnico](/docs/api/autenticacao#gerando-tokens-via-api).\n\n## Próximo passo [#próximo-passo]\n\nCom o token em mãos, [crie seu primeiro card](/docs/guia/primeiro-card).\n"
},
{
"title": "O que você pode fazer",
"description": "Um panorama da Perpetuus API para quem está começando — sem precisar ser desenvolvedor.",
"url": "/docs/guia",
"path": "guia/index.mdx",
"markdown": "# O que você pode fazer (/docs/guia)\n\n\n\nO Perpetuus expõe **tudo que você vê no CRM** através de uma API REST: boards, cards,\ncontatos, segmentos, campanhas, tarefas, orçamentos e relatórios. Isso significa que\nqualquer ferramenta que fale HTTP — Zapier, Make, n8n, Google Sheets, seu site, seu\nBI — pode conversar com o seu CRM.\n\n## Casos de uso comuns [#casos-de-uso-comuns]\n\n| Quero... | Como |\n| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |\n| Enviar leads do meu site para um board | [Formulário público](/docs/guia/formulario-publico) (sem código) ou [criar cards via API](/docs/guia/primeiro-card) |\n| Conectar Zapier, Make ou n8n | [Integrações sem código](/docs/guia/integracoes) |\n| Alimentar um dashboard de BI (Power BI, Looker, Metabase) | [Relatórios e BI](/docs/api/recursos/relatorios) |\n| Importar/exportar contatos em massa | [Contatos](/docs/api/recursos/contatos) |\n| Deixar um agente de IA operar o CRM | [Agentes de IA (MCP)](/docs/api/mcp) |\n\n## Por onde começar [#por-onde-começar]\n\n\n \n Leva 1 minuto, direto pela interface do Perpetuus.\n \n\n \n Um passo a passo copiável, do token ao card no board.\n \n\n \n Autenticação, convenções e receitas completas por recurso.\n \n\n\n## Precisa de ajuda? [#precisa-de-ajuda]\n\nFale com o suporte pelo chat dentro do app ou escreva para\n[luis.santos@perpetuus.com.br](mailto:luis.santos@perpetuus.com.br).\n"
},
{
"title": "Integrações comuns (n8n, Zapier, Make)",
"description": "JSONs prontos para importar e criar um card no board com nome, e-mail e telefone.",
"url": "/docs/guia/integracoes-comuns",
"path": "guia/integracoes-comuns.mdx",
"markdown": "# Integrações comuns (n8n, Zapier, Make) (/docs/guia/integracoes-comuns)\n\n\n\nReceitas prontas para conectar ferramentas no-code à Perpetuus API. Todas usam o mesmo\nendpoint canônico:\n\n`POST https://api.perpetuus.com.br/api/boards/{boardId}/cards`\n\nAntes de importar:\n\n1. [Gere um token de API](/docs/guia/gerando-token)\n2. Anote o **slug** da organização (`x-tenant-id`) e o **documentId** do board\n3. Substitua `SEU_TOKEN`, `acme` e `SEU_BOARD_ID` nos JSONs abaixo\n\n## Payload base (criar card) [#payload-base-criar-card]\n\n\n\n## n8n — workflow importável [#n8n--workflow-importável]\n\nNo n8n: **⋯ → Import from File/URL** e cole o JSON. Depois edite as credenciais no nó HTTP Request.\n\n\n\n## Make — módulo HTTP [#make--módulo-http]\n\nNo Make: cenário → **HTTP → Make a request**. Use este JSON como espelho dos campos.\n\n\n\n## Zapier — Custom Request [#zapier--custom-request]\n\nNo Zapier: **Webhooks by Zapier → Custom Request**.\n\n\n\n## Headers comuns [#headers-comuns]\n\n| Header | Valor |\n| --------------- | ------------------- |\n| `Authorization` | `Bearer SEU_TOKEN` |\n| `x-tenant-id` | slug da organização |\n| `Content-Type` | `application/json` |\n\n## Próximos passos [#próximos-passos]\n\n* [Criar o primeiro card manualmente](/docs/guia/primeiro-card)\n* [Formulário público sem autenticação](/docs/guia/formulario-publico)\n* [API Reference interativa](/reference)\n* [Conectar agentes via MCP](/docs/api/mcp)\n"
},
{
"title": "Zapier, Make e outras ferramentas",
"description": "Conecte o Perpetuus a milhares de apps usando ferramentas de automação sem código.",
"url": "/docs/guia/integracoes",
"path": "guia/integracoes.mdx",
"markdown": "# Zapier, Make e outras ferramentas (/docs/guia/integracoes)\n\n\n\nQualquer ferramenta que faça **requisições HTTP** consegue conversar com a Perpetuus\nAPI. Nas plataformas de automação, procure pelo módulo genérico de HTTP:\n\n| Plataforma | Módulo |\n| ----------------- | ------------------------------------- |\n| Zapier | *Webhooks by Zapier* → Custom Request |\n| Make (Integromat) | *HTTP* → Make a Request |\n| n8n | *HTTP Request* |\n| Power Automate | *HTTP* |\n\n## Configuração base (vale para todas) [#configuração-base-vale-para-todas]\n\nEm todo request, configure:\n\n* **URL**: `https://api.perpetuus.com.br/api/...` (veja os endpoints na [API Reference](/reference))\n* **Headers**:\n * `Authorization`: `Bearer SEU_TOKEN` — [como gerar](/docs/guia/gerando-token)\n * `x-tenant-id`: slug da sua organização (ex.: `acme`)\n * `Content-Type`: `application/json` (para POST/PUT)\n\n## Receita: novo lead do anúncio → card no board [#receita-novo-lead-do-anúncio--card-no-board]\n\n1. **Gatilho**: novo lead na sua ferramenta de origem (formulário, planilha, anúncio).\n2. **Ação**: HTTP `POST https://api.perpetuus.com.br/api/boards/SEU_BOARD_ID/cards`\n3. **Corpo**:\n\n```json\n{\n \"data\": {\n \"fields\": {\n \"name\": \"{{nome_do_lead}}\",\n \"email\": \"{{email}}\",\n \"phone\": \"{{telefone}}\"\n },\n \"tags\": [\"origem-anuncio\"]\n }\n}\n```\n\n## Receita: registrar atividade quando o cliente responder [#receita-registrar-atividade-quando-o-cliente-responder]\n\n1. **Gatilho**: nova resposta/e-mail na sua ferramenta.\n2. **Ação**: HTTP `POST https://api.perpetuus.com.br/api/contact-activities/note`\n\n```json\n{\n \"contactId\": \"{{documentId_do_contato}}\",\n \"note\": \"Cliente respondeu: {{resumo}}\"\n}\n```\n\n## Receita: planilha semanal com os cards do funil [#receita-planilha-semanal-com-os-cards-do-funil]\n\n1. **Gatilho**: agendamento (ex.: toda segunda às 8h).\n2. **Ação**: HTTP `GET https://api.perpetuus.com.br/api/boards/SEU_BOARD_ID/cards?pagination[pageSize]=100`\n3. **Ação**: escrever as linhas de `data[]` na planilha. Cada card traz o objeto\n `fields` pronto (`{ \"email\": \"...\", \"valor_orcamento\": 25000 }`) — sem parsing extra.\n\n## Dicas [#dicas]\n\n* **IDs**: descubra o `documentId` do board com `GET /api/boards` (ou copie da URL do app).\n* **Teste primeiro** no [API Reference](/reference), que mostra exemplos de resposta\n reais de cada endpoint.\n* Para volumes grandes (importação de contatos), prefira os endpoints de\n [operações em massa](/docs/api/recursos/contatos#operações-em-massa).\n"
},
{
"title": "Criando seu primeiro card",
"description": "Do token ao card no board em 5 minutos, copiando e colando.",
"url": "/docs/guia/primeiro-card",
"path": "guia/primeiro-card.mdx",
"markdown": "# Criando seu primeiro card (/docs/guia/primeiro-card)\n\n\n\nEste passo a passo cria um card em um board do seu CRM usando apenas o terminal\n(ou qualquer ferramenta que faça requisições HTTP, como Postman e Insomnia).\n\n## O que você vai precisar [#o-que-você-vai-precisar]\n\n* Um **token de API** — [gere aqui](/docs/guia/gerando-token)\n* O **slug da sua organização** — visível na URL do app (ex.: `app.perpetuus.com.br/acme` → `acme`)\n\n## 1. Descubra o ID do seu board [#1-descubra-o-id-do-seu-board]\n\n```bash\ncurl \"https://api.perpetuus.com.br/api/boards\" \\\n -H \"Authorization: Bearer SEU_TOKEN\" \\\n -H \"x-tenant-id: acme\"\n```\n\nNa resposta, copie o `documentId` do board desejado:\n\n```json\n{\n \"data\": [\n {\n \"documentId\": \"bd1a2b3c\",\n \"name\": \"Funil de Vendas\",\n \"phases\": [\n {\n \"documentId\": \"ph0aaa\",\n \"name\": \"Formulário\",\n \"order\": 0,\n \"fields\": [\n { \"slug\": \"name\", \"label\": \"Nome\", \"required\": true },\n { \"slug\": \"email\", \"label\": \"E-mail\" },\n { \"slug\": \"phone\", \"label\": \"Telefone\" }\n ]\n }\n ]\n }\n ]\n}\n```\n\nRepare nos **`fields` da fase de `order` 0** (o formulário de entrada): são os campos\naceitos na criação do card. O campo `name` costuma ser obrigatório.\n\n## 2. Crie o card [#2-crie-o-card]\n\n```bash\ncurl -X POST \"https://api.perpetuus.com.br/api/boards/bd1a2b3c/cards\" \\\n -H \"Authorization: Bearer SEU_TOKEN\" \\\n -H \"x-tenant-id: acme\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"data\": {\n \"fields\": {\n \"name\": \"Meu primeiro lead via API\",\n \"email\": \"lead@cliente.com\",\n \"phone\": \"+5511999999999\"\n },\n \"description\": \"Criado seguindo o guia da documentação 🎉\"\n }\n }'\n```\n\nA resposta traz o card criado, com `documentId`, `title` e a fase em que ele entrou:\n\n```json\n{\n \"documentId\": \"cd9x8y7z\",\n \"title\": \"Meu primeiro lead via API\",\n \"currentPhase\": { \"documentId\": \"ph1ccc\", \"name\": \"Novo lead\" },\n \"fields\": {\n \"name\": \"Meu primeiro lead via API\",\n \"email\": \"lead@cliente.com\",\n \"phone\": \"+5511999999999\"\n }\n}\n```\n\nAbra o board no Perpetuus — o card está lá, na primeira coluna. ✅\n\n## Erros comuns [#erros-comuns]\n\n| Resposta | Causa | Solução |\n| ---------------------------------------- | ------------------------------ | ------------------------------------- |\n| `400 — Header x-tenant-id é obrigatório` | Faltou o header do tenant | Adicione `-H \"x-tenant-id: seu-slug\"` |\n| `401 — Autenticação obrigatória` | Token ausente/expirado | Gere um novo token |\n| `400 — Campo \"name\" é obrigatório` | O board exige `name` na Fase 0 | Inclua `name` em `fields` |\n| `400 — Validação de campos falhou` | Slug errado ou tipo inválido | Confira os slugs no passo 1 |\n\n## Próximos passos [#próximos-passos]\n\n* [Mover o card de fase e atualizar campos](/docs/api/recursos/cards)\n* [Conectar Zapier ou Make](/docs/guia/integracoes)\n* [Capturar leads do site sem código](/docs/guia/formulario-publico)\n"
},
{
"title": "Automações (BETA)",
"description": "Workflows, publish, runs e logs — API avançada com risco de breaking change.",
"url": "/docs/api/recursos/automacoes",
"path": "api/recursos/automacoes.mdx",
"markdown": "# Automações (BETA) (/docs/api/recursos/automacoes)\n\n\n\n\n **BETA — API avançada.** Estes endpoints podem mudar sem major version e têm efeitos\n colaterais (`publish`, `test` com `dryRun: false`). Use sandbox e trate breaking changes.\n\n\nAutomações reagem a eventos do CRM (`card.created`, `phase_changed`, `message.received`…)\ne executam ações (`task.create`, `http.request`, `channel.send_message`…).\n\n## Fluxo seguro [#fluxo-seguro]\n\n1. `POST /automations` — cria **inactive** (`active: true` é rejeitado no create)\n2. Edite o grafo / ações\n3. `POST /automations/{id}/validate-graph` — sem side-effect\n4. `POST /automations/{id}/publish` — cria versão publicada\n5. `POST /automations/{id}/toggle` — liga/desliga\n6. `POST /automations/{id}/test` com `dryRun: true` antes de qualquer teste real\n\n## Endpoints [#endpoints]\n\n| Método | Path | Notas |\n| -------------- | --------------------------- | -------------------------------- |\n| GET/POST | `/automations` | Listar / criar |\n| GET/PUT/DELETE | `/automations/{id}` | CRUD |\n| POST | `/automations/{id}/publish` | **Efeito colateral** |\n| POST | `/automations/{id}/test` | `dryRun` default `true` |\n| POST | `/automations/{id}/toggle` | Exige publish prévio para ativar |\n| GET | `/automations/{id}/runs` | Histórico |\n| GET | `/automation-logs` | Logs |\n\nReferência completa: [API Reference → Automações](/reference#tag/automacoes).\n"
},
{
"title": "Boards (Processos e Membros)",
"description": "Endpoints para gerenciar quadros, fases, permissões e membros de equipe no Perpetuus CRM.",
"url": "/docs/api/recursos/boards",
"path": "api/recursos/boards.mdx",
"markdown": "# Boards (Processos e Membros) (/docs/api/recursos/boards)\n\n\n\n\n\nOs **Boards** (ou quadros) definem os processos de negócio da organização (ex: Funil de Vendas, Suporte ao Cliente). Cada board contém fases (colunas), tags e campos dinâmicos customizados.\n\n***\n\n## Endpoints Principais [#endpoints-principais]\n\nPara ver a especificação completa de cada endpoint com todas as opções de parâmetros e respostas, acesse a [API Reference](/reference).\n\n### 1. Listar Boards [#1-listar-boards]\n\nRetorna os quadros ativos da organização. Operadores veem apenas os quadros dos quais são membros.\n\n* **Método:** `GET`\n* **Caminho:** `/boards`\n* **Exemplo de Chamada:**\n ```bash\n curl \"https://api.perpetuus.com.br/api/boards\" \\\n -H \"Authorization: Bearer SEU_TOKEN\" \\\n -H \"x-tenant-id: acme\"\n ```\n\n***\n\n### 2. Criar Board [#2-criar-board]\n\nCria um novo quadro de processo. É possível criar a partir de um template pré-configurado usando o parâmetro `template` (ex: `minimal-workflow`).\n\n* **Método:** `POST`\n* **Caminho:** `/boards`\n* **Payload de Exemplo:**\n ```json\n {\n \"data\": {\n \"name\": \"Suporte Nível 1\",\n \"boardType\": \"kanban\",\n \"color\": \"#10B981\",\n \"template\": \"minimal-workflow\"\n }\n }\n ```\n\n***\n\n### 3. Buscar Detalhes de um Board [#3-buscar-detalhes-de-um-board]\n\nRetorna a árvore completa do quadro, incluindo suas Fases (colunas), Tags configuradas e Campos Dinâmicos.\n\n* **Método:** `GET`\n* **Caminho:** `/boards/{id}`\n\n\n **Dica de Leitura:** Use este endpoint no início do seu fluxo de integração para mapear os `documentId` das fases e os `slugs` de campos customizados que você precisará usar ao enviar novos cards.\n\n\n***\n\n## Gestão de Membros e Editores do Board [#gestão-de-membros-e-editores-do-board]\n\nOs quadros possuem controle granular sobre quem pode ver e alterar os cards.\n\n### Listar Membros do Board [#listar-membros-do-board]\n\nRetorna a lista de colaboradores (memberships) que possuem acesso de leitura ou escrita no quadro.\n\n* **Método:** `GET`\n* **Caminho:** `/boards/{id}/members`\n\n### Adicionar Membro [#adicionar-membro]\n\n* **Método:** `POST`\n* **Caminho:** `/boards/{id}/members`\n* **Payload:**\n ```json\n {\n \"data\": {\n \"membershipId\": \"membership_doc_id_99\"\n }\n }\n ```\n\n### Remover Membro [#remover-membro]\n\n* **Método:** `DELETE`\n* **Caminho:** `/boards/{id}/members/{membershipId}`\n"
},
{
"title": "Canais e WhatsApp (BETA)",
"description": "Canais, templates HSM e vínculo com boards — API avançada.",
"url": "/docs/api/recursos/canais",
"path": "api/recursos/canais.mdx",
"markdown": "# Canais e WhatsApp (BETA) (/docs/api/recursos/canais)\n\n\n\n\n **BETA — API avançada.** Criar/apagar templates e sync alteram o provedor externo.\n Credenciais nunca voltam completas nas respostas.\n\n\n## Tipos de canal [#tipos-de-canal]\n\n`whatsapp` · `instagram` · `telegram` · `email` · `web` · `api`\n\n## Receitas [#receitas]\n\n### Criar canal WhatsApp [#criar-canal-whatsapp]\n\n```bash\ncurl -X POST \"https://api.perpetuus.com.br/api/chat-channels\" \\\n -H \"Authorization: Bearer SEU_TOKEN\" \\\n -H \"x-tenant-id: acme\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"data\": {\n \"name\": \"WhatsApp Comercial\",\n \"channelType\": \"whatsapp\",\n \"credentials\": {\n \"accessToken\": \"EAAB...\",\n \"phoneNumberId\": \"123\",\n \"businessAccountId\": \"456\"\n }\n }\n }'\n```\n\n### Vincular ao board [#vincular-ao-board]\n\n`POST /boards/{boardId}/chat-channels` com `{ \"data\": { \"chatChannel\": \"CHANNEL_ID\" } }`.\n\n### Templates HSM [#templates-hsm]\n\n* `GET/POST/DELETE /chat-channels/{id}/templates`\n* `POST .../templates/sync`\n* `POST .../templates/upload-handle` (multipart)\n\nReferência: [API Reference → Canais](/reference#tag/canais).\n"
},
{
"title": "Cards (Oportunidades e Leads)",
"description": "Endpoints para criar, atualizar, mover de fase e gerenciar cards no Perpetuus CRM.",
"url": "/docs/api/recursos/cards",
"path": "api/recursos/cards.mdx",
"markdown": "# Cards (Oportunidades e Leads) (/docs/api/recursos/cards)\n\n\n\n\n\nOs **Cards** representam os itens de trabalho que fluem pelo pipeline do seu Board, como oportunidades de venda, chamados de atendimento ou tarefas.\n\n***\n\n## Endpoints Canônicos [#endpoints-canônicos]\n\n\n **Atenção:** Todos os endpoints de cards são aninhados ao `boardId`. O `boardId` e o `{id}` do card informados na URL devem ser os seus respectivos `documentId` (string).\n\n\n### 1. Listar Cards de um Board [#1-listar-cards-de-um-board]\n\nRetorna todos os cards pertencentes a um quadro específico. Suporta filtros complexos, ordenação e paginação.\n\n* **Método:** `GET`\n* **Caminho:** `/boards/{boardId}/cards`\n* **Exemplo com paginação e relações:**\n ```bash\n curl -G \"https://api.perpetuus.com.br/api/boards/BOARD_ID/cards\" \\\n -H \"Authorization: Bearer SEU_TOKEN\" \\\n -H \"x-tenant-id: acme\" \\\n --data-urlencode \"pagination[pageSize]=25\" \\\n --data-urlencode \"populate[0]=assignees\" \\\n --data-urlencode \"populate[1]=tags\"\n ```\n\n***\n\n### 2. Criar Card no Board [#2-criar-card-no-board]\n\nCria um card na fase inicial do Board (Phase 0). Qualquer campo dinâmico obrigatório configurado para a primeira fase do quadro deve ser enviado no objeto `fields`.\n\n* **Método:** `POST`\n* **Caminho:** `/boards/{boardId}/cards`\n* **Payload de Exemplo:**\n ```json\n {\n \"data\": {\n \"title\": \"Lead ACME Corp\",\n \"description\": \"Originado via integração API\",\n \"fields\": {\n \"email\": \"contato@acme.com\",\n \"phone\": \"+5511999999999\",\n \"tamanho_empresa\": \"100-500\"\n },\n \"tags\": [\"prioritario\"],\n \"dueDate\": \"2026-12-31T18:00:00Z\"\n }\n }\n ```\n\n***\n\n### 3. Atualizar Card e Mover de Fase [#3-atualizar-card-e-mover-de-fase]\n\nAtualiza metadados, campos dinâmicos customizados ou move o card de estágio no pipeline utilizando a propriedade `currentPhase`.\n\n* **Método:** `PUT`\n* **Caminho:** `/boards/{boardId}/cards/{id}`\n* **Payload para atualizar dados e mover de fase:**\n ```json\n {\n \"data\": {\n \"title\": \"ACME Corp - Negociação Avançada\",\n \"value\": 150000.00,\n \"currentPhase\": \"phase_doc_id_negociacao\",\n \"fields\": {\n \"data_proposta\": \"2026-07-10\",\n \"status_proposta\": \"Apresentada\"\n }\n }\n }\n ```\n\n***\n\n### 4. Excluir Card [#4-excluir-card]\n\nRemove definitivamente um card do quadro. Esta ação é irreversível.\n\n* **Método:** `DELETE`\n* **Caminho:** `/boards/{boardId}/cards/{id}`\n"
},
{
"title": "Contatos (Gestão e Deduplicação)",
"description": "Endpoints para gerenciar a base de contatos, campos customizados, vinculação de cards e deduplicação automática.",
"url": "/docs/api/recursos/contatos",
"path": "api/recursos/contatos.mdx",
"markdown": "# Contatos (Gestão e Deduplicação) (/docs/api/recursos/contatos)\n\n\n\n\n\nA gestão de contatos centraliza os dados de pessoas e empresas parceiras. A API permite gerenciar esse cadastro garantindo a integridade dos dados através de uma inteligência ativa de não-duplicação.\n\n***\n\n## Endpoints Principais [#endpoints-principais]\n\n### 1. Criar Contato (com Deduplicação Ativa) [#1-criar-contato-com-deduplicação-ativa]\n\nCria um novo contato na organização. O Perpetuus aplica regras automáticas para evitar duplicados: se o e-mail ou telefone enviado já existir na organização, o sistema rejeitará ou fará o merge conforme a configuração.\n\n* **Método:** `POST`\n* **Caminho:** `/contacts`\n* **Payload de Exemplo:**\n ```json\n {\n \"data\": {\n \"name\": \"Lailton Santos\",\n \"email\": \"lailton@empresa.com\",\n \"phone\": \"+5511988887777\",\n \"customFields\": {\n \"cargo\": \"Gerente de TI\",\n \"setor\": \"Tecnologia\"\n }\n }\n }\n ```\n\n***\n\n### 2. Listar Contatos [#2-listar-contatos]\n\nRetorna a lista paginada de contatos. Suporta ordenação e filtragem avançada (ex: buscar contatos criados no último mês).\n\n* **Método:** `GET`\n* **Caminho:** `/contacts`\n* **Exemplo de busca por e-mail:**\n ```bash\n curl -G \"https://api.perpetuus.com.br/api/contacts\" \\\n -H \"Authorization: Bearer SEU_TOKEN\" \\\n -H \"x-tenant-id: acme\" \\\n --data-urlencode \"filters[email][$eq]=lailton@empresa.com\"\n ```\n\n***\n\n### 3. Cards Vinculados ao Contato [#3-cards-vinculados-ao-contato]\n\nRetorna todos os cards de qualquer quadro que estejam associados a este contato. Útil para renderizar o histórico comercial completo no painel do cliente.\n\n* **Método:** `GET`\n* **Caminho:** `/contacts/{id}/linked-cards`\n\n***\n\n## Operações em Massa (Bulk) [#operações-em-massa-bulk]\n\nPara importação de grandes bases ou integrações com sistemas legados, utilize os endpoints em massa. Eles processam requisições de forma otimizada para evitar limites de timeout.\n\n### 1. Criação/Edição em Lote [#1-criaçãoedição-em-lote]\n\n* **Método:** `POST`\n* **Caminho:** `/contacts/bulk`\n* **Payload:**\n ```json\n {\n \"contacts\": [\n {\n \"name\": \"Maria Silva\",\n \"email\": \"maria@empresa.com\",\n \"phone\": \"+5511977776666\"\n },\n {\n \"name\": \"Carlos Souza\",\n \"email\": \"carlos@empresa.com\"\n }\n ]\n }\n ```\n\n### 2. Exclusão em Lote [#2-exclusão-em-lote]\n\n* **Método:** `POST`\n* **Caminho:** `/contacts/bulk-delete`\n* **Payload:**\n ```json\n {\n \"documentIds\": [\"contact_doc_id_1\", \"contact_doc_id_2\"]\n }\n ```\n"
},
{
"title": "Crescimento (BETA)",
"description": "E-mail marketing, distribuição, filtros salvos e pixels de conversão.",
"url": "/docs/api/recursos/crescimento",
"path": "api/recursos/crescimento.mdx",
"markdown": "# Crescimento (BETA) (/docs/api/recursos/crescimento)\n\n\n\n\n **BETA — API avançada.** `send-test` envia e-mail real; create de conversão verifica\n APIs externas; filas ativas atribuem cards automaticamente.\n\n\n## E-mail marketing [#e-mail-marketing]\n\n| Endpoint | Uso |\n| --------------------------------- | -------------------- |\n| `GET/POST /email-templates` | CRUD de templates |\n| `POST /email-templates/preview` | Render sem envio |\n| `POST /email-templates/send-test` | **Envia de verdade** |\n| `POST /email-assets/upload` | Upload de imagens |\n\n## Distribuição [#distribuição]\n\n`POST /distribution-queues` com `name` + `board`. Filas `active` fazem round-robin entre `members`.\n\n## Filtros salvos [#filtros-salvos]\n\n`POST /board-saved-filters` exige `payload.version`. `scope: shared` só admin/manager.\n\n## Conversões / pixels [#conversões--pixels]\n\n`platform`: `meta` | `google_ga4`. Create já chama verify; use `POST .../verify` para revalidar.\n\nReferência: tags [E-mail marketing](/reference#tag/e-mail-marketing), [Distribuição](/reference#tag/distribuicao), [Filtros salvos](/reference#tag/filtros-salvos), [Conversões](/reference#tag/conversoes).\n"
},
{
"title": "Meta Lead Ads (BETA)",
"description": "Integrações Lead Ads, OAuth e roteamento de formulários para boards.",
"url": "/docs/api/recursos/meta-leads",
"path": "api/recursos/meta-leads.mdx",
"markdown": "# Meta Lead Ads (BETA) (/docs/api/recursos/meta-leads)\n\n\n\n\n **BETA — API avançada.** Create/update podem inscrever webhooks na página Facebook.\n Tokens são sensíveis. Callback OAuth e webhooks inbound **não** fazem parte do contrato público.\n\n\n## Fluxo [#fluxo]\n\n1. `POST /meta-lead/facebook-oauth/start` → redirecionar o usuário\n2. `POST /meta-lead/facebook-oauth/complete`\n3. `POST /meta-lead-integrations` (ou use a integração criada no OAuth)\n4. `POST /meta-lead-form-routes` mapeando form → board + `fieldMapping`\n\n## Form route (exemplo) [#form-route-exemplo]\n\n```json\n{\n \"data\": {\n \"name\": \"Form Contato → Funil\",\n \"metaLeadIntegrationDocumentId\": \"mli1a2b3c\",\n \"targetBoardDocumentId\": \"bd1a2b3c\",\n \"facebookFormId\": \"120000\",\n \"fieldMapping\": {\n \"mappings\": [\n { \"source\": \"email\", \"target\": \"email\" },\n { \"source\": \"full_name\", \"target\": \"name\" }\n ]\n }\n }\n}\n```\n\nReferência: [API Reference → Meta Lead Ads](/reference#tag/meta-lead-ads).\n"
},
{
"title": "Orçamentos, Produtos e PDFs",
"description": "Endpoints para gerenciar catálogo de produtos, emissão de cotações comerciais, cálculo de descontos e geração de PDFs.",
"url": "/docs/api/recursos/orcamentos-produtos",
"path": "api/recursos/orcamentos-produtos.mdx",
"markdown": "# Orçamentos, Produtos e PDFs (/docs/api/recursos/orcamentos-produtos)\n\n\n\n\n\nO Perpetuus CRM possui ferramentas comerciais nativas para emissão de orçamentos e propostas comerciais em PDF diretamente a partir do histórico de cards dos boards.\n\n***\n\n## Catálogo de Produtos e Categorias [#catálogo-de-produtos-e-categorias]\n\nAntes de emitir cotações comerciais, você deve estruturar seus produtos ou serviços.\n\n### 1. Criar Produto [#1-criar-produto]\n\n* **Método:** `POST`\n* **Caminho:** `/products`\n* **Payload:**\n ```json\n {\n \"data\": {\n \"name\": \"Plano Anual Enterprise\",\n \"sku\": \"PLANO-ENTERPRISE-ANUAL\",\n \"price\": 12000.00,\n \"minPrice\": 9600.00,\n \"productType\": \"digital\",\n \"billingType\": \"recurring\"\n }\n }\n ```\n\n\n **Piso de Preço (minPrice):** Se você tentar emitir um orçamento contendo um produto com valor unitário menor que o seu `minPrice` configurado, a API retornará status **400 Bad Request**, a menos que o token de API possua a permissão explícita de override de tabela.\n\n\n### 2. Listar Categorias de Produtos [#2-listar-categorias-de-produtos]\n\nPermite organizar e classificar o catálogo.\n\n* **Método:** `GET`\n* **Caminho:** `/product-categories`\n\n***\n\n## Módulo de Orçamentos (Quotes) [#módulo-de-orçamentos-quotes]\n\nCotações comerciais vinculadas a um card e a um contato.\n\n### 1. Criar Orçamento Comercial [#1-criar-orçamento-comercial]\n\nCria um orçamento para o card. O número do documento, o subtotal e o total geral são **calculados automaticamente pelo servidor**.\n\n* **Método:** `POST`\n\n* **Caminho:** `/quotes`\n\n* **Payload de Exemplo:**\n ```json\n {\n \"card\": \"card_doc_id_lead_xyz\",\n \"contact\": \"contact_doc_id_cliente\",\n \"discountType\": \"percentage\",\n \"discountValue\": 10.00,\n \"updateCardValue\": true,\n \"items\": [\n {\n \"name\": \"Licenças de Uso Software\",\n \"quantity\": 10,\n \"unitPrice\": 120.00\n },\n {\n \"product\": \"product_anual_enterprise\",\n \"quantity\": 1,\n \"unitPrice\": 11000.00\n }\n ]\n }\n ```\n\n* **`updateCardValue`:** Se definido como `true`, o valor total calculado do orçamento atualizará automaticamente a propriedade `value` do card vinculado no Kanban.\n\n***\n\n### 2. Ativar Orçamento [#2-ativar-orçamento]\n\nMarca este orçamento como `active` (ativo) e rebaixa automaticamente qualquer outro orçamento anteriormente ativo para o mesmo card para `draft` (rascunho).\n\n* **Método:** `POST`\n* **Caminho:** `/quotes/{id}/activate`\n\n### 3. Duplicar Orçamento [#3-duplicar-orçamento]\n\nCria uma nova versão de rascunho (`draft`) copiando os dados do orçamento original, gerando um novo número e incrementando a versão do documento.\n\n* **Método:** `POST`\n* **Caminho:** `/quotes/{id}/duplicate`\n\n### 4. Gerar PDF do Orçamento (Download) [#4-gerar-pdf-do-orçamento-download]\n\nGera e renderiza a proposta comercial em formato PDF estruturado para download.\n\n* **Método:** `GET`\n* **Caminho:** `/quotes/{id}/pdf`\n* **Parâmetro de Consulta:**\n * `templateId`: Opcional. `documentId` do PDF Template que deseja forçar no layout. Se omitido, usará o template padrão configurado no Board.\n"
},
{
"title": "Relatórios e Integração de BI",
"description": "Como consumir o endpoint de relatórios analíticos para alimentar Power BI, Looker Studio e dashboards externos.",
"url": "/docs/api/recursos/relatorios",
"path": "api/recursos/relatorios.mdx",
"markdown": "# Relatórios e Integração de BI (/docs/api/recursos/relatorios)\n\n\n\n\n\nPara alimentar painéis de Business Intelligence (BI) e dashboards gerenciais, o Perpetuus oferece um endpoint otimizado que retorna dados analíticos consolidados do seu funil.\n\n***\n\n## Endpoint Analítico [#endpoint-analítico]\n\nDiferente das listagens padrão de cards (que retornam dados linha a linha e exigem paginação), o endpoint de relatório consolida os dados financeiros e de conversão diretamente no servidor.\n\n### Obter Relatório de Conversão do Quadro [#obter-relatório-de-conversão-do-quadro]\n\nRetorna métricas agregadas por fase (SLA, quantidade de cards e valor acumulado) e um sumário consolidado do período selecionado.\n\n* **Método:** `GET`\n* **Caminho:** `/boards/{boardId}/report`\n* **Parâmetros de Consulta:**\n * `from`: Data inicial no formato `YYYY-MM-DD` (ex: `2026-07-01`).\n * `to`: Data final no formato `YYYY-MM-DD` (ex: `2026-07-10`).\n * `statsTodayStart`: Opcional. Data/hora ISO representando a meia-noite no fuso horário do usuário para cálculo preciso de cards atrasados (`overdueCount`).\n\n***\n\n## Exemplo de Requisição e Resposta [#exemplo-de-requisição-e-resposta]\n\n```bash\ncurl \"https://api.perpetuus.com.br/api/boards/BOARD_ID/report?from=2026-07-01&to=2026-07-10\" \\\n -H \"Authorization: Bearer SEU_TOKEN\" \\\n -H \"x-tenant-id: acme\"\n```\n\nA API retorna um payload em formato **Report** (analítico consolidado):\n\n```json\n{\n \"boardId\": \"board_sales_01\",\n \"summary\": {\n \"totalCards\": 145,\n \"activeValue\": 1250000.00,\n \"wonValue\": 450000.00,\n \"lostValue\": 85000.00,\n \"conversionRate\": 0.81\n },\n \"phases\": [\n {\n \"documentId\": \"phase_inbound\",\n \"name\": \"Leads Recebidos\",\n \"cardsCount\": 32,\n \"valueSum\": 160000.00,\n \"slaBreachedCount\": 2\n },\n {\n \"documentId\": \"phase_negotiation\",\n \"name\": \"Negociação\",\n \"cardsCount\": 12,\n \"valueSum\": 250000.00,\n \"slaBreachedCount\": 0\n }\n ],\n \"period\": {\n \"from\": \"2026-07-01\",\n \"to\": \"2026-07-10\"\n }\n}\n```\n\n***\n\n## Boas Práticas para Integrações de BI [#boas-práticas-para-integrações-de-bi]\n\nQuando estiver conectando a API do Perpetuus ao **Power BI**, **Looker Studio** ou **Metabase**, siga estas diretrizes:\n\n1. **Alimentação de Gráficos de Conversão e Funil:** Utilize o `GET /boards/{boardId}/report` para desenhar funis de conversão comerciais, SLAs de fase e métricas financeiras globais. Este endpoint consome poucos recursos e executa de forma quase instantânea.\n2. **Consultas Detalhadas e Gráficos de Vendedores:** Para agrupar vendas por vendedor (assignees), visualizar detalhes de cards individuais ou analisar campos customizados específicos, utilize a listagem de cards (`GET /boards/{boardId}/cards`) com paginação e o parâmetro `populate` configurado para trazer `assignees` e `fieldData`.\n3. **Cache de Consultas:** Evite fazer requisições em tempo real a cada atualização de página do usuário no dashboard. Configure o seu data warehouse (ou a ferramenta de BI) para realizar cargas de sincronização (ingestão agendada) em intervalos (ex: a cada 1 hora ou uma vez por dia).\n"
},
{
"title": "Segmentos e Campanhas (Marketing)",
"description": "Endpoints para gerenciar segmentos de contatos, construir filtros dinâmicos e controlar o disparo de campanhas omnichannel.",
"url": "/docs/api/recursos/segmentos-campanhas",
"path": "api/recursos/segmentos-campanhas.mdx",
"markdown": "# Segmentos e Campanhas (Marketing) (/docs/api/recursos/segmentos-campanhas)\n\n\n\n\n\nOs módulos de **Segmentos** e **Campanhas** permitem estruturar ações de relacionamento em massa (disparos de e-mail e mensagens de chat) com base em audiências segmentadas dinamicamente.\n\n***\n\n## Módulo de Segmentos (Filtros Dinâmicos) [#módulo-de-segmentos-filtros-dinâmicos]\n\nSegmentos são grupos dinâmicos de contatos cujos membros atendem a regras específicas (ex: \"Contatos com e-mail preenchido criados há menos de 30 dias\").\n\n### 1. Listar Segmentos [#1-listar-segmentos]\n\nRetorna a lista de segmentos cadastrados na organização.\n\n* **Método:** `GET`\n* **Caminho:** `/segments`\n\n### 2. Simular/Preview do Segmento [#2-simularpreview-do-segmento]\n\nPermite testar as regras de filtragem antes de salvar o segmento definitivamente, retornando uma prévia dos contatos elegíveis.\n\n* **Método:** `POST`\n* **Caminho:** `/segments/preview`\n* **Payload de Exemplo (Regra de filtro JSON):**\n ```json\n {\n \"rules\": {\n \"condition\": \"AND\",\n \"rules\": [\n {\n \"field\": \"email\",\n \"operator\": \"contains\",\n \"value\": \"@empresa.com\"\n }\n ]\n }\n }\n ```\n\n### 3. Obter Contagem do Segmento [#3-obter-contagem-do-segmento]\n\nRetorna a quantidade exata de contatos atualmente qualificados dentro daquele segmento.\n\n* **Método:** `GET`\n* **Caminho:** `/segments/{id}/count`\n\n***\n\n## Módulo de Campanhas (Disparos Omnichannel) [#módulo-de-campanhas-disparos-omnichannel]\n\nCampanhas gerenciam a fila de entrega em massa para uma audiência vinculada a um Canal e um Segmento.\n\n### 1. Criar Campanha [#1-criar-campanha]\n\nCria um rascunho de campanha informando o canal de disparo, a audiência (segmento) e a mensagem/template.\n\n* **Método:** `POST`\n* **Caminho:** `/campaigns`\n* **Payload de Exemplo:**\n ```json\n {\n \"data\": {\n \"name\": \"Campanha de Inverno 2026\",\n \"channel\": \"channel_whatsapp_01\",\n \"segment\": \"segment_leads_ativos_12\",\n \"template\": \"template_doc_id_123\",\n \"variables\": {\n \"cupom\": \"WINTER26\"\n }\n }\n }\n ```\n\n***\n\n### 2. Controlar Ciclo de Vida da Campanha [#2-controlar-ciclo-de-vida-da-campanha]\n\nUma campanha criada fica em estado `draft` (rascunho). Para operá-la, utilize os endpoints de disparo e controle:\n\n* **Disparar / Iniciar:** `POST /campaigns/{id}/trigger`\n* **Pausar Envios:** `POST /campaigns/{id}/pause`\n* **Retomar Envios:** `POST /campaigns/{id}/resume`\n* **Cancelar Disparo:** `POST /campaigns/{id}/cancel`\n\n***\n\n### 3. Obter Estatísticas da Campanha [#3-obter-estatísticas-da-campanha]\n\nRetorna as métricas de entrega em tempo real, incluindo quantidade de envios bem-sucedidos, falhas, taxa de abertura e leitura.\n\n* **Método:** `GET`\n* **Caminho:** `/campaigns/{id}/stats`\n* **Exemplo de Resposta:**\n ```json\n {\n \"campaignId\": \"camp_abc_123\",\n \"stats\": {\n \"totalAudience\": 450,\n \"sent\": 380,\n \"failed\": 2,\n \"pending\": 68,\n \"readRate\": 0.74\n }\n }\n ```\n"
},
{
"title": "Tarefas e Comentários",
"description": "Endpoints para gerenciar tarefas (tasks), prazos de conclusão, atividades diárias e comentários em cards.",
"url": "/docs/api/recursos/tarefas-comentarios",
"path": "api/recursos/tarefas-comentarios.mdx",
"markdown": "# Tarefas e Comentários (/docs/api/recursos/tarefas-comentarios)\n\n\n\n\n\nA produtividade das equipes e o registro de histórico de interações dentro do card são gerenciados pelas APIs de **Tarefas** e **Comentários**.\n\n***\n\n## Módulo de Tarefas (Tasks) [#módulo-de-tarefas-tasks]\n\nAs tarefas ajudam a organizar prazos de follow-up, lembretes de ligação e atividades pendentes.\n\n### 1. Listar Minhas Tarefas [#1-listar-minhas-tarefas]\n\nRetorna todas as tarefas atribuídas ao usuário autenticado, ordenadas por data de vencimento (`dueDate:asc`).\n\n* **Método:** `GET`\n* **Caminho:** `/tasks/my-tasks`\n\n### 2. Criar Tarefa [#2-criar-tarefa]\n\nAssocia uma tarefa a um card ou a um board. Se a propriedade `assignees` (membros responsáveis) for omitida, a tarefa é automaticamente atribuída ao criador do registro.\n\n* **Método:** `POST`\n* **Caminho:** `/tasks`\n* **Payload de Exemplo:**\n ```json\n {\n \"data\": {\n \"name\": \"Enviar contrato atualizado\",\n \"description\": \"Lembrar de anexar a proposta comercial revisada em PDF.\",\n \"dueDate\": \"2026-07-15T12:00:00Z\",\n \"type\": \"follow-up\",\n \"card\": \"card_doc_id_999\",\n \"assignees\": [\"membership_doc_id_vendedor\"]\n }\n }\n ```\n\n### 3. Atualizar Status da Tarefa [#3-atualizar-status-da-tarefa]\n\nAltera os dados de uma tarefa. Marcar um status de conclusão como `completed` atualizará a propriedade `completedAt` no servidor de forma automática.\n\n* **Método:** `PUT`\n* **Caminho:** `/tasks/{id}`\n* **Payload:**\n ```json\n {\n \"data\": {\n \"taskStatus\": \"completed\"\n }\n }\n ```\n\n***\n\n## Módulo de Comentários [#módulo-de-comentários]\n\nOs comentários registram anotações manuais dos vendedores ou notas geradas automaticamente pelo sistema (ex: histórico de movimentação de fase).\n\n### 1. Listar Comentários de um Card [#1-listar-comentários-de-um-card]\n\nRetorna os comentários associados a um card específico.\n\n* **Método:** `GET`\n* **Caminho:** `/comments`\n* **Parâmetro de Consulta:**\n * `filters[card][documentId]`: O `documentId` do card (filtro obrigatório para otimização de busca).\n\n```bash\ncurl -G \"https://api.perpetuus.com.br/api/comments\" \\\n -H \"Authorization: Bearer SEU_TOKEN\" \\\n -H \"x-tenant-id: acme\" \\\n --data-urlencode \"filters[card][documentId]=card_document_id_xyz\"\n```\n\n***\n\n### 2. Adicionar Comentário no Card [#2-adicionar-comentário-no-card]\n\nCria um novo comentário. Suporta menções a outros membros usando o `documentId` de seus memberships. O conteúdo pode ser enviado em texto puro ou em HTML sanitizado.\n\n* **Método:** `POST`\n* **Caminho:** `/comments`\n* **Payload de Exemplo:**\n ```json\n {\n \"data\": {\n \"card\": \"card_document_id_xyz\",\n \"content\": \"Reunião de alinhamento com a diretoria realizada hoje. Minuta da reunião.\",\n \"contentFormat\": \"html\",\n \"mentions\": [\"membership_id_diretor_comercial\"]\n }\n }\n ```\n\n\n **Restrições de Autoria:** As operações de edição (`PUT`) e exclusão (`DELETE`) de comentários só são permitidas para o usuário que foi o autor do comentário original. Qualquer tentativa de alteração por outro membro retornará erro **403 Forbidden**.\n\n"
},
{
"title": "Ferramentas (Tools) do Agent",
"description": "Guia de ferramentas (tools) do agent no Perpetuus CRM.",
"url": "/docs/guia/agents/ferramentas-tools",
"path": "guia/agents/ferramentas-tools.mdx",
"markdown": "# Ferramentas (Tools) do Agent (/docs/guia/agents/ferramentas-tools)\n\n\n\n\n\nAs ferramentas permitem que o agent execute ações no CRM durante a conversa.\n\n## Tools disponíveis [#tools-disponíveis]\n\n| Atualizar campo do card | Altera um campo do card vinculado à conversa |\n| ----------------------- | ------------------------------------------------ |\n| Mudar fase | Move o card para outra fase do pipeline |\n| Criar tarefa | Cria uma tarefa associada ao card |\n| Marcar intenção (tag) | Adiciona tag ao card conforme intenção detectada |\n| Passar para agente | Transfere a conversa para atendimento humano |\n| Agendar follow-up | Programa mensagem de retorno |\n\n## Seleção [#seleção]\n\nSelecione pelo menos uma ferramenta na aba Ferramentas . O agent só poderá usar as ferramentas habilitadas.\n\nUse \"Passar para agente\" quando o cliente pedir falar com um humano ou quando as proteções exigirem handoff.\n"
},
{
"title": "Introdução e Configuração de Agents",
"description": "Guia de introdução e configuração de agents no Perpetuus CRM.",
"url": "/docs/guia/agents/introducao-bots",
"path": "guia/agents/introducao-bots.mdx",
"markdown": "# Introdução e Configuração de Agents (/docs/guia/agents/introducao-bots)\n\n\n\n\n\nOs Agents são assistentes de IA que atendem conversas no chat, qualificam leads e executam ações no CRM (atualizar card, mudar fase, criar tarefa, etc.).\n\n## Onde encontrar [#onde-encontrar]\n\nAutomações Agents Tasks Agents Configure e gerencie seus assistentes de IA. + Novo Agent Agent Vendas Agent Suporte + Novo\n\n## O que cada card mostra [#o-que-cada-card-mostra]\n\n| Status | Ativo (verde) ou Inativo (cinza) |\n| ----------------- | ---------------------------------------- |\n| Conversas / Leads | Métricas do agent |\n| Modelo | gpt-4o, gpt-4o-mini, claude-3-5-sonnet |\n| Última atividade | Quando o agent foi usado pela última vez |\n\n## Ações no card [#ações-no-card]\n\nEditar, Analytics, Duplicar, Ativar/Desativar, Excluir (com confirmação).\n\n## Abas do AgentBuilder [#abas-do-agentbuilder]\n\nO AgentBuilder possui sete abas para configurar seu assistente de IA.\n\n| Básico | Nome (min. 3), Descrição, Modelo, Provider, Inbox |\n| ----------- | -------------------------------------------------------------- |\n| Prompt | System prompt (min. 10 caracteres) — instruções para o agent |\n| Ferramentas | Selecione ao menos uma tool (atualizar card, mudar fase, etc.) |\n| Template | Template de ativação (mensagem inicial WhatsApp) |\n| Proteções | Guardrails (tokens, temperatura, tópicos proibidos, handoff) |\n| Follow-ups | Mensagens automáticas com delay |\n| Eventos | Triggers e ações (condições, atualizar campos, mudar fase) |\n\n## Passo a passo [#passo-a-passo]\n\n1️⃣ Acesse Agents no menu (ícone robô). 2️⃣ Use `Novo Agent` para criar. 3️⃣ Na aba Básico , preencha Nome e escolha o Modelo. 4️⃣ Na aba Prompt , escreva as instruções do assistente. 5️⃣ Na aba Ferramentas , selecione ao menos uma ferramenta. 6️⃣ Configure Template, Proteções, Follow-ups e Eventos conforme necessário. 7️⃣ Clique em `Salvar e Ativar` ou `Testar Agent`.\n\nO agent deve estar vinculado a um canal (inbox) para atender conversas reais.\n\n⚠️ Importante: Prompt e pelo menos uma ferramenta são obrigatórios.\n"
},
{
"title": "Testar no Playground",
"description": "Guia de testar no playground no Perpetuus CRM.",
"url": "/docs/guia/agents/playground",
"path": "guia/agents/playground.mdx",
"markdown": "# Testar no Playground (/docs/guia/agents/playground)\n\n\n\n\n\nO Playground permite simular conversas com o agent antes de ativá-lo em produção.\n\n## Como usar [#como-usar]\n\n1️⃣ No AgentBuilder, clique em `Testar Agent` (ícone Play). 2️⃣ O modal do Playground abre. Digite mensagens como se fosse o cliente. 3️⃣ Veja as respostas do agent e as ferramentas que ele chama. 4️⃣ Acompanhe tokens usados e latência.\n\n## O que o Playground mostra [#o-que-o-playground-mostra]\n\nMensagens: Histórico da conversa simulado Tools chamadas: Quais ferramentas o agent tentou executar e com quais argumentos Métricas: Tokens consumidos e tempo de resposta\n\nO botão Testar Agent fica habilitado quando o formulário está válido. Ajuste o prompt e as ferramentas e teste novamente até o comportamento desejado.\n"
},
{
"title": "Proteções e Guardrails",
"description": "Guia de proteções e guardrails no Perpetuus CRM.",
"url": "/docs/guia/agents/protecoes-guardrails",
"path": "guia/agents/protecoes-guardrails.mdx",
"markdown": "# Proteções e Guardrails (/docs/guia/agents/protecoes-guardrails)\n\n\n\n\n\nOs Guardrails controlam o comportamento do agent e evitam respostas inadequadas.\n\n## Configurações principais [#configurações-principais]\n\n| Max Tokens | Limite de tokens por resposta (100–4000) |\n| ------------------- | -------------------------------------------------- |\n| Temperatura | Criatividade (0–1). Menor = mais previsível |\n| Tópicos proibidos | Assuntos que o agent deve evitar |\n| Palavras de handoff | Termos que disparam passagem para agente |\n| Campos obrigatórios | Dados que o agent deve coletar antes de qualificar |\n| Expiração | Tempo limite e ação (handoff, pause, close) |\n\nExemplo: Adicione \"falar com atendente\" em palavras de handoff para transferir quando o cliente solicitar.\n"
},
{
"title": "Template de Ativação e Follow-ups",
"description": "Guia de template de ativação e follow-ups no Perpetuus CRM.",
"url": "/docs/guia/agents/template-e-followups",
"path": "guia/agents/template-e-followups.mdx",
"markdown": "# Template de Ativação e Follow-ups (/docs/guia/agents/template-e-followups)\n\n\n\n\n\nO Template de Ativação é a mensagem inicial enviada quando o agent é acionado. Os Follow-ups são mensagens automáticas com atraso configurado.\n\n## Template de Ativação [#template-de-ativação]\n\nConfigure um template WhatsApp aprovado na Meta. O agent usará esse template como primeira mensagem na conversa. Defina as variáveis (ex: nome do contato) que serão preenchidas.\n\n## Follow-ups [#follow-ups]\n\nCada follow-up tem: Nome , Delay (minutos) , Template e variáveis. Exemplo: após 30 minutos sem resposta, enviar \"Está ainda aí? Posso ajudar em algo?\"\n\n## Event Triggers [#event-triggers]\n\nDefina condições e ações: ao detectar uma condição, o sistema pode atualizar campos, mudar fase, desativar o agent ou adicionar tags.\n\nAtenção: Templates devem estar aprovados no canal vinculado ao agent.\n"
},
{
"title": "Ações e Variáveis",
"description": "Guia de ações e variáveis no Perpetuus CRM.",
"url": "/docs/guia/automacoes/acoes-e-variaveis",
"path": "guia/automacoes/acoes-e-variaveis.mdx",
"markdown": "# Ações e Variáveis (/docs/guia/automacoes/acoes-e-variaveis)\n\n\n\n\n\nAs ações são o que a automação executa quando o gatilho dispara e as condições são atendidas. Muitas ações aceitam variáveis dinâmicas — placeholders que são substituídos pelo valor real na hora da execução (ex: nome do contato, telefone, título do card).\n\n## Ações por categoria [#ações-por-categoria]\n\n| Card | Mover, Criar, Atualizar campo, Definir vencimento, Adicionar/remover responsável, Adicionar/remover/definir tags | Mover para fase Ganho, atualizar valor, definir prazo |\n| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |\n| Contato | Criar, Atualizar, Vincular ao card | Criar lead ao receber mensagem, atualizar dados, vincular contato ao card |\n| Tarefa | Criar, Atualizar, Concluir | Criar follow-up ao mover card, marcar tarefa como feita |\n| Integração | HTTP Request, Enviar Mensagem (WhatsApp) | Chamar Zapier/Make/N8n, enviar WhatsApp ao contato |\n| Importante: As ações disponíveis dependem do gatilho. Por exemplo, gatilhos de Contato não oferecem \"Mover Card\" nem \"Enviar Mensagem\" (que exigem um card vinculado). | | |\n\n## Variáveis dinâmicas [#variáveis-dinâmicas]\n\nUse `\\{\\{caminho\\}\\}` em qualquer campo que aceite texto. O sistema substitui pelo valor real na execução.\n\n### Contexto (sempre disponível) [#contexto-sempre-disponível]\n\n`\\{\\{hoje\\}\\}` — Data atual (formato ISO) `\\{\\{agora\\}\\}` — Data e hora atuais `\\{\\{usuario_atual.name\\}\\}` — Nome do usuário que disparou (ou do sistema)\n\n### Card (quando o gatilho envolve card) [#card-quando-o-gatilho-envolve-card]\n\n`\\{\\{card.title\\}\\}` — Título do card `\\{\\{card.description\\}\\}` — Descrição `\\{\\{card.contact.name\\}\\}`, `\\{\\{card.contact.phone\\}\\}`, `\\{\\{card.contact.email\\}\\}` — Dados do contato vinculado `\\{\\{card.currentPhase.name\\}\\}` — Nome da fase atual `\\{\\{card.board.name\\}\\}` — Nome do board `\\{\\{card.fields.campo_slug\\}\\}` — Campo dinâmico (substitua pelo slug do campo)\n\n### Contato (gatilhos contact.\\*) [#contato-gatilhos-contact]\n\n`\\{\\{contact.name\\}\\}`, `\\{\\{contact.email\\}\\}`, `\\{\\{contact.phone\\}\\}` — Dados do contato\n\n### Saída de ações anteriores [#saída-de-ações-anteriores]\n\nQuando uma ação cria um card ou contato, as ações seguintes podem usar o resultado: `\\{\\{action_1.cardId\\}\\}` — ID do card criado pela ação 1 `\\{\\{action_2.contactId\\}\\}` — ID do contato criado pela ação 2 Use o seletor de variáveis no painel de configuração para ver as disponíveis conforme o contexto do fluxo.\n\nExemplo de mensagem: \"Olá, \\{\\{card.contact.name}}! Seu orçamento para \\{\\{card.title}} está pronto. Entraremos em contato em breve.\"\n"
},
{
"title": "Criando Automações: Canvas, Gatilhos e Condições",
"description": "Guia de criando automações: canvas, gatilhos e condições no Perpetuus CRM.",
"url": "/docs/guia/automacoes/criando-automacao-canvas",
"path": "guia/automacoes/criando-automacao-canvas.mdx",
"markdown": "# Criando Automações: Canvas, Gatilhos e Condições (/docs/guia/automacoes/criando-automacao-canvas)\n\n\n\n\n\nO editor em canvas permite montar o fluxo visualmente. O Gatilho dispara a automação; as Condições filtram quando executar; as Ações executam o que você configurou.\n\n## Layout do editor [#layout-do-editor]\n\n| Barra superior | Voltar, Nome e Descrição |\n| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |\n| Abas | Editor (canvas) e Histórico |\n| Canvas | Nós conectados: Gatilho (amarelo) → Condição (roxo) → Ações (azul). Clique em um nó para configurar. Use + na saída para adicionar o próximo. |\n| Canto superior direito | Testar e Salvar |\n\n## Tipos de gatilho [#tipos-de-gatilho]\n\n| Intervalo de Tempo | Periodicidade (minutos, horas, dias) |\n| ---------------------------------- | ------------------------------------- |\n| Card Criado | Novo card no board |\n| Card Movido (fase) | Card muda de fase |\n| Campo Atualizado | Campo específico alterado no card |\n| Responsável Alterado | Mudança no responsável do card |\n| Contato Criado/Atualizado | Mudança em contato no CRM |\n| Tarefa Criada/Atualizada/Concluída | Eventos de tarefa |\n| Mensagem Recebida | Nova mensagem no canal (ex: WhatsApp) |\n\n## Condições [#condições]\n\nAs condições refinam o disparo. Operadores: Igual a , Diferente de , Contém , Maior que , Menor que , Está vazio , Preenchido . Combine regras com E (AND) ou OU (OR) . Nos campos de valor, você pode usar variáveis `\\{\\{card.title\\}\\}`.\n\n## Passo a passo [#passo-a-passo]\n\n1️⃣ Clique em `Nova Automação`. 2️⃣ Preencha Nome (obrigatório) e Descrição . 3️⃣ Configure o Gatilho — tipo e filtros (board, fase, etc.). 4️⃣ (Opcional) Adicione nó de Condição e conecte ao gatilho. 5️⃣ Adicione nós de Ação e conecte à sequência. 6️⃣ Configure cada nó no painel lateral. Salve . ⚠️ Importante: Sem gatilho configurado a automação não pode ser salva.\n\nExemplo: Gatilho \"Card Movido\" + Condição \"Fase = Fechado Ganho\" + Ação \"Enviar mensagem WhatsApp\" ao contato.\n"
},
{
"title": "Histórico e Logs",
"description": "Guia de histórico e logs no Perpetuus CRM.",
"url": "/docs/guia/automacoes/historico-e-logs",
"path": "guia/automacoes/historico-e-logs.mdx",
"markdown": "# Histórico e Logs (/docs/guia/automacoes/historico-e-logs)\n\n\n\n\n\nA aba Histórico no detalhe da automação mostra todas as execuções para debug e auditoria.\n\n## Status de execução [#status-de-execução]\n\n| pending | Aguardando execução |\n| ------- | -------------------------------- |\n| running | Em execução |\n| success | Concluída com sucesso |\n| failed | Erro na execução |\n| skipped | Pulada (condições não atendidas) |\n\n## O que cada log mostra [#o-que-cada-log-mostra]\n\nEvento do gatilho, resultado das condições, resultado de cada ação, mensagem de erro (se houver) e tempo de execução.\n\n## Ativar e pausar [#ativar-e-pausar]\n\nNa listagem, use o botão Play para ativar e Pause para pausar a automação sem excluí-la.\n"
},
{
"title": "Introdução ao Módulo de Automações",
"description": "Guia de introdução ao módulo de automações no Perpetuus CRM.",
"url": "/docs/guia/automacoes/introducao-automacoes",
"path": "guia/automacoes/introducao-automacoes.mdx",
"markdown": "# Introdução ao Módulo de Automações (/docs/guia/automacoes/introducao-automacoes)\n\n\n\n\n\nAs Automações permitem automatizar rotinas do CRM com lógica Gatilho → Condições → Ações . Exemplo: quando um card entra na fase \"Fechado Ganho\", enviar mensagem WhatsApp ao contato. Todas as execuções rodam em nuvem, com histórico completo.\n\n## Como funciona o motor [#como-funciona-o-motor]\n\nGatilho: O que dispara a automação (ex: card movido para fase X). Condições (opcional): Filtros adicionais (ex: campo Valor > 1000). Ações: O que fazer — enviar mensagem, mover card, criar tarefa, HTTP Request, etc.\n\n## Onde encontrar [#onde-encontrar]\n\nAcesse /automations pelo menu ou pela aba Automações de um board específico. Boards Contatos Automações Automações Configure workflows e automações. + Nova Automação\n\n| Nome | Board | Status | Exec. | Última | … |\n| ---- | ----- | ------ | ----- | ------ | - |\n| — | — | — | — | — | — |\n\n## Colunas da listagem [#colunas-da-listagem]\n\n| Nome | Nome da automação (clique para editar) |\n| --------------- | -------------------------------------- |\n| Board | Board vinculado ou Global |\n| Status | Ativo ou Pausado |\n| Execuções | Quantidade de vezes executada |\n| Última execução | Data/hora da última execução |\n\n## Ações disponíveis [#ações-disponíveis]\n\nEnviar Mensagem (WhatsApp), Mover Card, Criar/atualizar Contato, Criar Tarefa, HTTP Request (Zapier, Make, N8n), Adicionar/remover Tags, Definir Responsável.\n\n## Passo a passo [#passo-a-passo]\n\n1️⃣ Acesse Automações no menu (ícone workflow). 2️⃣ Use `Nova Automação` para criar. 3️⃣ Clique em uma linha para abrir o editor em canvas. 4️⃣ Use Play/Pause para ativar ou pausar.\n\nAutomações podem ser globais (qualquer board) ou vinculadas a um board específico. O histórico de logs permite debug e auditoria.\n"
},
{
"title": "Automações: Condicionais e múltiplas ações",
"description": "Guia de automações: condicionais e múltiplas ações no Perpetuus CRM.",
"url": "/docs/guia/boards-pipelines/aba-automacoes-detalhes",
"path": "guia/boards-pipelines/aba-automacoes-detalhes.mdx",
"markdown": "# Automações: Condicionais e múltiplas ações (/docs/guia/boards-pipelines/aba-automacoes-detalhes)\n\n\n\n\n\n## Condições (IF) [#condições-if]\n\nAdicione condições ao gatilho: ex. \"Quando card entra em fase X E campo Valor > 1000\".\n\n## Múltiplas ações [#múltiplas-ações]\n\nUma automação pode executar várias ações em sequência: enviar e-mail + criar tarefa + mover fase.\n\n## Ordem de execução [#ordem-de-execução]\n\nAutomações do board são executadas na ordem definida. Cuidado com loops (mover fase que dispara outra automação).\n"
},
{
"title": "Aba Automações",
"description": "Guia de aba automações no Perpetuus CRM.",
"url": "/docs/guia/boards-pipelines/aba-automacoes",
"path": "guia/boards-pipelines/aba-automacoes.mdx",
"markdown": "# Aba Automações (/docs/guia/boards-pipelines/aba-automacoes)\n\n\n\n\n\nA aba Automações exibe as automações específicas deste board. Requer permissão `automation.list`.\n\n## Gatilhos comuns [#gatilhos-comuns]\n\nCard criado Card entra em fase Card atualizado Valor de campo alterado Data de vencimento próxima Card atribuído\n\n## Ações disponíveis [#ações-disponíveis]\n\nEnviar e-mail Atribuir a usuário Mover para outra fase Definir valor de campo Criar tarefa Enviar webhook\n\n## Como usar [#como-usar]\n\nClique na aba Automações . Crie uma nova automação ou edite uma existente. Configure Quando (gatilho) e Então (ação). Ative a automação.\n\nExemplo: \"Quando card entra em fase 'Fechado', enviar e-mail para o cliente com PDF da proposta.\"\n"
},
{
"title": "Board Kanban: Detalhes e uso avançado",
"description": "Guia de board kanban: detalhes e uso avançado no Perpetuus CRM.",
"url": "/docs/guia/boards-pipelines/aba-board-kanban-detalhes",
"path": "guia/boards-pipelines/aba-board-kanban-detalhes.mdx",
"markdown": "# Board Kanban: Detalhes e uso avançado (/docs/guia/boards-pipelines/aba-board-kanban-detalhes)\n\n\n\n\n\n## Filtros combinados [#filtros-combinados]\n\nA toolbar de filtros permite combinar várias camadas de refinamento: Busca por título: Mín. 2 caracteres com debounce — ideal para localizar um cliente rapidamente. Responsável: Veja só cards onde você (ou outro membro) é responsável — ideal para \"minha carteira\". Tags: Filtre por etiqueta (ex: só \"Urgente\" ou \"Qualificado\"). Fase: Mostre apenas cards de uma coluna específica. Intervalo de datas: Escolha o campo (criação, atualização ou vencimento) e use presets (7d, 30d, etc.) ou intervalo customizado. Filtros avançados: Monte condições sobre propriedades do card e campos dinâmicos das fases (operadores como igual, contém, maior que, etc.). Filtros salvos: Salve combinações, aplique com um clique, compartilhe com a equipe ou defina como filtro padrão ao abrir o board. Limpar: O botão X remove todos os filtros ativos de uma vez. Exemplo: Responsável = eu + Tag = Urgente + Vencimento = próximos 7 dias + Busca = \"joão\".\n\n## Clique vs Arrastar [#clique-vs-arrastar]\n\n| Clique no card | Abre o Modal do Card: coluna esquerda com título, descrição, tags, contato, responsáveis, vencimento, valor e histórico; abas centrais (Dados, Comentários, Orçamento, Documentos, Tarefas, Meet); seletor de fase na barra de abas. |\n| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Arrastar o card | Muda a fase. Se a fase destino tiver campos obrigatórios vazios, um formulário aparece antes de concluir o movimento. |\n\nAção Visual: Se você tentar mover um card para uma fase que exige dados sem preenchê-los, o sistema abrirá um formulário antes de completar o movimento.\n\n## Exemplos de uso [#exemplos-de-uso]\n\nVendedor: Filtre por \"Responsável = Eu\" para ver apenas suas oportunidades. Gerente: Remova o filtro de responsável para ver todo o pipeline da equipe. Busca rápida: Digite o nome do cliente no campo de busca para localizar o card sem rolar as colunas. Prazo: Use intervalo de datas em \"Vencimento\" com preset 7d para ver cards com prazo esta semana. Filtro salvo: Salve \"Minha carteira Urgente\" como padrão para abrir o board já filtrado. Mover com dados: Arraste um lead para \"Qualificação\"; se CNPJ e Prioridade forem obrigatórios, o formulário abrirá automaticamente.\n"
},
{
"title": "Aba Board (Kanban)",
"description": "Guia de aba board (kanban) no Perpetuus CRM.",
"url": "/docs/guia/boards-pipelines/aba-board-kanban",
"path": "guia/boards-pipelines/aba-board-kanban.mdx",
"markdown": "# Aba Board (Kanban) (/docs/guia/boards-pipelines/aba-board-kanban)\n\n\n\n\n\nA aba Board é a visualização padrão em colunas. Cada coluna é uma Fase do seu pipeline.\n\n## Como usar [#como-usar]\n\nVisualizar cards: Os cards aparecem nas colunas conforme a fase em que estão. Mover cards: Arraste e solte um card de uma coluna para outra para alterar a fase. Criar card: Clique no botão Adicionar card na barra de filtros (ou no botão flutuante no celular). Abrir card: Clique em um card para abrir o modal com detalhes, abas e histórico. Filtrar: Use a barra de filtros acima das colunas (veja abaixo).\n\n## Barra de filtros [#barra-de-filtros]\n\nAcima das colunas, a toolbar oferece: Busca por título: Digite no campo de busca (mín. 2 caracteres, com debounce). Filtros rápidos: Responsável , Tags e Fase . Intervalo de datas: Filtre por data de criação, atualização ou vencimento, com atalhos (7d, 30d, etc.). Filtros avançados: Popover com condições compostas sobre propriedades do card e campos dinâmicos das fases. Filtros salvos: Salve, aplique, compartilhe ou defina um filtro padrão ao abrir o board. Limpar filtros: Botão X remove todos os filtros ativos.\n\n## Elementos na tela [#elementos-na-tela]\n\nColunas (fases): Ordem da esquerda para a direita = fluxo do processo. Cards: Exibem título, valor (se ativado), responsável e tags.\n\nSe tentar mover um card para uma fase que exige campos obrigatórios, o sistema abrirá um formulário antes de concluir o movimento.\n"
},
{
"title": "Aba Distribuição",
"description": "Guia de aba distribuição no Perpetuus CRM.",
"url": "/docs/guia/boards-pipelines/aba-distribuicao",
"path": "guia/boards-pipelines/aba-distribuicao.mdx",
"markdown": "# Aba Distribuição (/docs/guia/boards-pipelines/aba-distribuicao)\n\n\n\n\n\nA aba Distribuição configura filas de distribuição (Distribution Queues) para atribuir automaticamente novos cards a membros da equipe. Requer permissão `chat-channel.list`.\n\n## Onde configurar [#onde-configurar]\n\nBoard → aba Distribuição (barra superior). Clique em New Queue (ou \"Nova Fila\") para criar uma fila.\n\n## Campos da fila e exemplos [#campos-da-fila-e-exemplos]\n\n| Nome | Identificação da fila | \"Comercial SP\", \"Suporte 24h\" |\n| ---------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |\n| Prioridade | Ordem entre filas. Menor número = maior prioridade. Se duas filas forem elegíveis, a de menor prioridade vence. | 1 = VIP; 2 = padrão; 3 = reserva |\n| Ativo | Liga ou desliga a fila. Desative para pausar sem excluir a configuração. | Switch ligado = fila ativa |\n| Membros | Quem pode receber cards. Distribuição em round-robin entre os selecionados. | Maria, João, Pedro — cada novo card vai para o próximo da lista |\n| Regras | Condições que o card precisa atender para entrar nesta fila. Sem regras = todos os cards elegíveis. | Prioridade = \"Alta\"; Origem contém \"Site\" |\n| Agenda | Dias da semana e horário (início–fim) em que a fila está ativa. Opcional. | Seg–Sex, 9h–18h; Sáb 9h–13h |\n\n## Regras — exemplos práticos [#regras--exemplos-práticos]\n\nPor campo: \"Prioridade\" igual a \"Alta\" → fila VIP recebe só leads de alta prioridade. Por texto: \"Origem\" contém \"Site\" → leads do site vão para fila específica. Por valor: \"Valor\" maior que 5000 → oportunidades grandes para equipe senior. Sem regras: Fila recebe qualquer card (útil como fila padrão). Você pode combinar várias condições em blocos (AND/OR). O sistema testa as filas na ordem de prioridade e atribui ao primeiro que coincidir.\n\n## Como usar [#como-usar]\n\nClique na aba Distribuição . Clique em New Queue (ou \"Nova Fila\"). Preencha Nome , Prioridade e selecione Membros . Adicione Regras (opcional) para filtrar quais cards entram na fila. Ative a Agenda (opcional) e defina dias/horários. Ligue o switch Ativo e salve.\n\nÚtil para distribuir leads de forma equilibrada entre vendedores, respeitando horário comercial. Crie uma fila \"Pós-expediente\" com agenda fora do horário principal como fallback.\n"
},
{
"title": "Flow: Formulário público e automações por fase",
"description": "Guia de flow: formulário público e automações por fase no Perpetuus CRM.",
"url": "/docs/guia/boards-pipelines/aba-flow-detalhes",
"path": "guia/boards-pipelines/aba-flow-detalhes.mdx",
"markdown": "# Flow: Formulário público e automações por fase (/docs/guia/boards-pipelines/aba-flow-detalhes)\n\n\n\n\n\n## Onde configurar o formulário público [#onde-configurar-o-formulário-público]\n\nToda a configuração fica na primeira fase do board. Para acessar: Abra o board e vá na aba Flow . Clique na coluna da primeira fase (ex: \"Lead\") — ou no ícone de engrenagem/menu ao lado do nome. Um modal abrirá com abas. Use Config , Campos e Formulário Público .\n\n## Passo a passo: Ativar o formulário público [#passo-a-passo-ativar-o-formulário-público]\n\nNa aba Config do modal da primeira fase, ative o toggle Formulário público . Salve. O formulário passará a aceitar submissões sem login.\n\n## Onde configurar os campos do formulário [#onde-configurar-os-campos-do-formulário]\n\nOs campos que aparecem no formulário público são os mesmos da primeira fase . Configure-os na aba Campos do mesmo modal: Na aba Campos , clique em Add Field . Crie os campos (Nome, E-mail, Telefone, etc.). Campos obrigatórios exigirão preenchimento antes de enviar. Salve. Os campos aparecerão automaticamente no formulário público.\n\n## Onde configurar e personalizar o formulário [#onde-configurar-e-personalizar-o-formulário]\n\nNa aba Formulário Público do modal da primeira fase, você personaliza:\n\n| Título do formulário | Texto exibido no topo (ex: \"Cadastre-se\") |\n| ----------------------- | -------------------------------------------------------------------------------------------------------- |\n| Descrição | Texto secundário abaixo do título |\n| Texto do botão | Ex: \"Enviar\", \"Cadastrar\" |\n| Cores | Fundo, card, campos, bordas, labels |\n| Logo (URL) | Imagem no topo do formulário |\n| URL de redirecionamento | Para onde o usuário vai após enviar (ex: página de agradecimento). Se vazio, mostra mensagem de sucesso. |\n\n## Onde copiar o link do formulário [#onde-copiar-o-link-do-formulário]\n\nNa mesma aba Formulário Público , role até a seção Compartilhamento . Você verá três opções: Link: Copie o link direto (ex: `https://app.perpetuus.com.br/public-forms/sua-org/seu-board`) para compartilhar em e-mails, redes sociais ou sites. iframe: Copie o código HTML para incorporar o formulário em qualquer página. Script: Código para embed avançado (padrão ou estilo WhatsApp). Use o botão de copiar (ícone 📋) ao lado de cada opção.\n\n## Automações na coluna da fase [#automações-na-coluna-da-fase]\n\nCada fase pode ter automações: ex. \"Quando card entra nesta fase, enviar notificação\". Configure na seção de automação da coluna (aba Automações do board ou na própria coluna, conforme a interface).\n\n## Slug do campo [#slug-do-campo]\n\nO slug é gerado automaticamente a partir do nome. Use-o em automações e integrações (ex: `valor_proposta`).\n"
},
{
"title": "Aba Flow (Fases e Campos)",
"description": "Guia de aba flow (fases e campos) no Perpetuus CRM.",
"url": "/docs/guia/boards-pipelines/aba-flow",
"path": "guia/boards-pipelines/aba-flow.mdx",
"markdown": "# Aba Flow (Fases e Campos) (/docs/guia/boards-pipelines/aba-flow)\n\n\n\n\n\nA aba Flow é o editor visual onde você configura as fases (colunas do pipeline) e os campos dinâmicos de cada fase. É o coração da configuração do board. Requer permissão `board.manage`.\n\n## Onde encontrar [#onde-encontrar]\n\nAbra um board → na barra de abas no topo, clique em Flow (entre Board/List e Pessoas).\n\n## O que você vê na tela [#o-que-você-vê-na-tela]\n\nCada coluna representa uma fase. Dentro da coluna: nome da fase, botão para editar configurações (engrenagem), lista de campos e botão Add Field . No final, o botão Add Phase para criar nova fase.\n\n## Como criar uma fase (passo a passo) [#como-criar-uma-fase-passo-a-passo]\n\nClique no botão Add Phase (ou \"Nova Fase\") — fica à direita da última coluna. Um modal abrirá. Preencha o Nome (obrigatório) — ex: \"Qualificação\", \"Proposta\", \"Fechado\". Preencha a Descrição (opcional) — ex: \"Lead qualificado com CNPJ e budget\". Se for a primeira fase e você quiser um formulário público para captar leads sem login: ative o toggle Formulário público . Um link será gerado para compartilhar em sites ou e-mails. Clique em Salvar/Criar. A nova coluna aparece no Flow e no Kanban.\n\n## Como criar um campo (passo a passo) [#como-criar-um-campo-passo-a-passo]\n\nNa coluna da fase desejada, clique em Add Field (ou \"Adicionar campo\") — geralmente no rodapé da coluna ou em um botão visível. Um modal/drawer abrirá. Preencha: Nome do campo (ex: \"CNPJ\"), Tipo (texto, número, data, select, etc.), Placeholder (opcional) e marque Obrigatório se necessário. Para tipo Select : adicione as opções uma a uma (ex: \"Alta\", \"Média\", \"Baixa\"). Salve . O campo aparecerá quando um card for movido para essa fase — ou ao abrir um card que já está nela.\n\n## Tipos de campo e exemplos de uso [#tipos-de-campo-e-exemplos-de-uso]\n\n| Texto | Nome do cliente, observações |\n| ----------------- | ------------------------------------------------------ |\n| Textarea | Descrição longa, notas da reunião |\n| E-mail / Telefone | Contato do lead |\n| Número | Quantidade, prazo em dias |\n| Data | Data da reunião, prazo de entrega |\n| Select | Prioridade (Alta/Média/Baixa), Origem (Site/Indicação) |\n| Checkbox | Aceitou proposta? Enviou contrato? |\n| CPF / CNPJ | Documento com validação automática |\n| Moeda | Valor da proposta, orçamento |\n\n## Exemplo prático: Pipeline de vendas [#exemplo-prático-pipeline-de-vendas]\n\nFase 1 Lead : campos Nome, E-mail, Telefone (obrigatórios para formulário público). Fase 2 Qualificação : CNPJ, Renda mensal (número), Prioridade (select: Alta/Média/Baixa). Fase 3 Proposta : Valor (moeda), Data da reunião (data). Fase 4 Fechado : Método de pagamento (select), Anexo contrato (se houver tipo arquivo).\n\n## Reordenar fases [#reordenar-fases]\n\nArraste a coluna da fase (pelo cabeçalho ou área de arraste) para alterar a ordem. A ordem no Flow = ordem no Kanban.\n\n## Configurar transições entre fases [#configurar-transições-entre-fases]\n\nEm cada fase, abra as configurações (ícone engrenagem) e defina Movimentos permitidos : de quais fases os cards podem vir e para quais podem ir. Ex: \"Qualificação\" pode receber de \"Lead\" e permitir ir para \"Proposta\" ou \"Perdido\". ⚠️ Importante: Campos obrigatórios bloqueiam o avanço do card — o usuário precisará preenchê-los antes de mover para a próxima fase. Se tentar arrastar sem preencher, um formulário aparecerá automaticamente.\n\nSlug: O slug do campo (ex: `valor_proposta`) é gerado a partir do nome. Use-o em automações, PDFs e integrações.\n"
},
{
"title": "Aba List",
"description": "Guia de aba list no Perpetuus CRM.",
"url": "/docs/guia/boards-pipelines/aba-list",
"path": "guia/boards-pipelines/aba-list.mdx",
"markdown": "# Aba List (/docs/guia/boards-pipelines/aba-list)\n\n\n\n\n\nA aba List mostra os mesmos cards do Kanban em formato de tabela : visão densa, ordenação por coluna e filtros combinados. Ideal para analisar vários cards de uma vez.\n\n## Onde encontrar [#onde-encontrar]\n\nAbra um board → na barra de abas no topo, clique em List (ao lado de Board, Flow, Pessoas, etc.).\n\n## Barra de filtros [#barra-de-filtros]\n\nA List usa a mesma toolbar do Kanban: Busca por título (mín. 2 caracteres) Filtros rápidos: Responsável, Tags, Fase Intervalo de datas (criação, atualização ou vencimento) Filtros avançados e filtros salvos Limpar filtros (botão X) Gerenciador de colunas: Exclusivo da List — escolha quais colunas exibir na tabela.\n\n## O que você pode fazer [#o-que-você-pode-fazer]\n\nVer todos os cards em tabela: Cada linha é um card. Colunas: Título, Fase, Responsável, Valor, Tags, Data de criação e campos dinâmicos. Ordenar: Clique no cabeçalho da coluna (ex: Valor, Data) para ordenar crescente ou decrescente. Escolher colunas: Use o Gerenciador de colunas para mostrar ou ocultar colunas. Paginar: No rodapé, ajuste itens por página (10, 25, 50) e navegue entre páginas. Abrir card: Clique na linha para abrir o modal do card (abas Dados, Comentários, Orçamento, etc.).\n\n## Quando usar List em vez do Kanban [#quando-usar-list-em-vez-do-kanban]\n\nComparar valores entre cards (ex: ordenar por Valor para ver os maiores). Contagem rápida por fase (a tabela agrupa visualmente). Trabalhar com muitos cards sem rolar colunas — a tabela é mais compacta. Exportar mentalmente dados para relatórios (visão tabular facilita).\n\n## Passo a passo [#passo-a-passo]\n\nClique na aba List . Use os filtros e o Gerenciador de colunas se quiser refinar a visualização. Clique no cabeçalho de uma coluna para ordenar. Clique em uma linha para abrir o modal do card.\n\nA lista e o Kanban mostram os mesmos dados — troque entre as abas conforme a necessidade (visualizar fluxo = Kanban; analisar/ordenar = List).\n"
},
{
"title": "Aba PDF Templates",
"description": "Guia de aba pdf templates no Perpetuus CRM.",
"url": "/docs/guia/boards-pipelines/aba-pdf-templates",
"path": "guia/boards-pipelines/aba-pdf-templates.mdx",
"markdown": "# Aba PDF Templates (/docs/guia/boards-pipelines/aba-pdf-templates)\n\n\n\n\n\nA aba PDF Templates lista os templates de documentos (cotações, orçamentos, faturas, contratos) vinculados a este board. Cada template define o layout do PDF gerado a partir dos dados do card, do contato e dos produtos adicionados.\n\n## Onde configurar [#onde-configurar]\n\nVer templates do board: Board → aba PDF Templates . Criar ou editar templates: Configurações → PDF Templates (ou acesse o PDF Builder diretamente). Gerar documento no card: Abra o card → aba Documentos (ou Orçamento).\n\n## Requisito: Módulo de produtos [#requisito-módulo-de-produtos]\n\nPara usar cotações com tabela de produtos e totais , ative o Módulo de produtos em Board → aba Settings → Módulo de produtos. É necessário ter um catálogo de produtos na organização.\n\n## Fluxo de uso (passo a passo) [#fluxo-de-uso-passo-a-passo]\n\nAdicionar produtos ao carrinho: No card, vá na aba Orçamento . Adicione itens ao carrinho (produtos do catálogo) e salve. Gerar documento: Vá na aba Documentos . Selecione um template no dropdown, clique em Gerar . O PDF é criado, arquivado no card e baixado. Templates sem produtos: Se o template não tiver blocos de Tabela de Produtos nem Totais, você pode gerar direto (ex: proposta simples com dados do contato e campos do card).\n\n## Blocos disponíveis no template [#blocos-disponíveis-no-template]\n\n| Logo | Logo da organização (configurada em Settings) | Cabeçalho padrão |\n| ---------------------- | --------------------------------------------------- | ---------------------------- |\n| Informações da empresa | Nome, CNPJ, endereço, telefone, e-mail | Dados automáticos da org |\n| Informações do contato | Cliente vinculado ao card: nome, CPF/CNPJ, endereço | \"Cliente: João Silva\" |\n| Tabela de produtos | Itens do carrinho (nome, SKU, qtd, preço, total) | Exige itens no carrinho |\n| Totais | Subtotal, desconto, impostos, frete, total | Exige itens no carrinho |\n| Texto rico | Parágrafos com variáveis `\\{\\{\\}\\}` | \"Prezado \\{\\{contact.name}}\" |\n| Assinatura | Linha de assinatura + nome do cliente/empresa | Rodapé do contrato |\n| Número de página | \"Página X de Y\" no rodapé | Rodapé |\n\n## Variáveis dinâmicas (Handlebars) [#variáveis-dinâmicas-handlebars]\n\nUse `\\{\\{caminho\\}\\}` no texto do template para inserir dados. O editor do PDF Builder oferece sugestões de variáveis.\n\n### Contato e card [#contato-e-card]\n\n| `\\{\\{contact.name\\}\\}` | João Silva |\n| ------------------------------------ | ------------------------------------------- |\n| `\\{\\{contact.email\\}\\}` | [joao@empresa.com](mailto:joao@empresa.com) |\n| `\\{\\{contact.phone\\}\\}` | (11) 99999-9999 |\n| `\\{\\{contact.document\\}\\}` | CPF/CNPJ do contato |\n| `\\{\\{card.title\\}\\}` | Título do card |\n| `\\{\\{card.fields.valor_proposta\\}\\}` | Campo dinâmico (use o slug do campo) |\n| `\\{\\{assignee.name\\}\\}` | Nome do responsável |\n| `\\{\\{organization.name\\}\\}` | Nome da empresa |\n| `\\{\\{today.date\\}\\}` | 08/03/2025 |\n\n### Orçamento (quote) [#orçamento-quote]\n\n`\\{\\{quote.total\\}\\}`, `\\{\\{quote.subtotal\\}\\}`, `\\{\\{quote.discountTotal\\}\\}`, `\\{\\{quote.currency\\}\\}`. Use o helper `\\{\\{currency valor quote.currency\\}\\}` para formatar moeda.\n\n## Vinculando templates ao board [#vinculando-templates-ao-board]\n\nAo criar um template em Configurações, defina o Escopo : Organização (disponível em todos os boards) ou Board (apenas neste board). Ou vincule o template diretamente a um board. Na aba PDF Templates do board você vê apenas os templates deste board.\n\n## Exemplos práticos [#exemplos-práticos]\n\nCotação de vendas: Logo + dados da empresa + dados do cliente + Tabela de produtos + Totais + Assinatura. Proposta simples (sem produtos): Logo + texto \"Prezado \\{\\{contact.name}}, segue nossa proposta...\" + campo `\\{\\{card.fields.valor_proposta\\}\\}` + Assinatura. Contrato: Blocos de texto com variáveis + Assinatura cliente e empresa. Relatório: Dados do card e contato + campos dinâmicos em colunas. ⚠️ Template com produtos: Se o template tiver blocos Tabela de Produtos ou Totais, você precisa adicionar itens no carrinho (aba Orçamento) antes de gerar. Caso contrário, aparecerá \"Nenhum item adicionado\".\n\nUse slugs curtos nos campos dinâmicos (ex: `valor_proposta`, `cnpj_cliente`) — facilitam variáveis em PDFs e automações.\n"
},
{
"title": "Aba Pessoas (Membros)",
"description": "Guia de aba pessoas (membros) no Perpetuus CRM.",
"url": "/docs/guia/boards-pipelines/aba-pessoas",
"path": "guia/boards-pipelines/aba-pessoas.mdx",
"markdown": "# Aba Pessoas (Membros) (/docs/guia/boards-pipelines/aba-pessoas)\n\n\n\n\n\nA aba Pessoas gerencia quem tem acesso ao board. Requer permissão `board.manage`.\n\n## Onde configurar [#onde-configurar]\n\n| Adicionar/remover membros, promover a Editor | Board → aba Pessoas |\n| -------------------------------------------- | ----------------------------------------- |\n| Restringir visualização só aos responsáveis | Board → aba Settings → Controle de acesso |\n| Restringir edição só aos responsáveis | Board → aba Settings → Controle de acesso |\n\n## Papéis [#papéis]\n\n| Membro | Ver e interagir com cards. Não altera fases nem campos. |\n| ------ | ------------------------------------------------------------------------------------------------------------------------------------ |\n| Editor | Tudo do Membro + criar fases, campos e automações. |\n| Owner | Criador do board, possui todos os direitos. Não é possível remover o owner; apenas transferir a propriedade (se o sistema permitir). |\n\n## Como usar [#como-usar]\n\nClique na aba Pessoas . Para adicionar: Selecione um usuário da organização no dropdown e confirme. Para promover a Editor: Clique no ícone de escudo ao lado do membro. Para remover: Use o botão de remover ao lado do membro.\n\n## Restrição por responsável [#restrição-por-responsável]\n\nEm Settings → Controle de acesso , ative \"Restringir visualização\" para que membros vejam apenas cards em que são responsáveis. Ou \"Restringir edição\" para que só o responsável possa editar. Útil para equipes de vendas.\n\n## Quem pode adicionar membros [#quem-pode-adicionar-membros]\n\nApenas Owner e Editores. Membros comuns não acessam a aba Pessoas.\n\nNota: As restrições \"só responsáveis veem seus cards\" e \"só responsáveis editam\" são configuradas na aba Settings.\n"
},
{
"title": "Aba Settings",
"description": "Guia de aba settings no Perpetuus CRM.",
"url": "/docs/guia/boards-pipelines/aba-settings",
"path": "guia/boards-pipelines/aba-settings.mdx",
"markdown": "# Aba Settings (/docs/guia/boards-pipelines/aba-settings)\n\n\n\n\n\nA aba Settings centraliza todas as configurações do board. Requer permissão `board.manage`. As alterações são salvas com o botão Salvar Alterações no topo do painel.\n\n## Onde configurar [#onde-configurar]\n\nBoard → aba Settings (última aba na barra superior).\n\n## Configurações Gerais [#configurações-gerais]\n\n| Nome do Board | Nome de exibição (ex: \"Funil de Vendas\"). Obrigatório. |\n| --------------- | --------------------------------------------------------------------------------------- |\n| Slug | Identificador da URL, gerado automaticamente a partir do nome. Somente leitura. |\n| Status do Board | Ativo = visível aos membros. Inativo = oculto da listagem principal; dados preservados. |\n\n## Controle de Acesso [#controle-de-acesso]\n\nUse esses switches para equipes de vendas onde cada vendedor atende sua própria carteira.\n\n| Restringir edição aos responsáveis | Apenas o responsável do card e editores do board podem modificar cards. Membros comuns não editam cards de outros. |\n| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |\n| Restringir visualização aos responsáveis | Apenas responsáveis veem detalhes do card. Membros ainda veem títulos no Kanban; ao clicar, o acesso pode ser bloqueado conforme a regra. |\n\nCombine com a aba Pessoas para definir quem é membro e editor. As restrições aplicam-se aos membros comuns.\n\n## Valor e Conversão [#valor-e-conversão]\n\n| Rastrear valores monetários | Exibe campo de valor nos cards (vendas, orçamentos, despesas). Habilita métricas de pipeline. |\n| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |\n| Moeda | Símbolo exibido (ex: BRL, USD). |\n| Fase Ganha (Won) | Cards nesta fase = oportunidade fechada com sucesso. Usado em métricas de conversão. |\n| Fase Perdida (Lost) | Cards nesta fase = oportunidade perdida. Usado em métricas de conversão. |\n| Você pode ter mais de uma fase de cada tipo (ex: \"Fechado\" e \"Renovado\" como Ganho). | |\n\n## Módulo de Produtos [#módulo-de-produtos]\n\n| Habilitar Módulo de Produtos | Permite carrinho de cotações e orçamentos nos cards. Exige catálogo de produtos na organização (Configurações → Produtos). |\n| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |\n| Atualizar valor do card automaticamente | Sincroniza o valor exibido no card com o total do orçamento ativo. Útil para pipelines de vendas. |\n\n## Visão Geral das Fases [#visão-geral-das-fases]\n\nResumo das fases configuradas (Lead, Qualificação, Proposta, etc.). Para criar ou editar fases, use o link Editar Fluxo ou vá na aba Flow .\n\n## Zona de Perigo [#zona-de-perigo]\n\nExcluir board: Remove o board e todos os dados (cards, fases, tags, documentos) de forma permanente. Para confirmar, é necessário digitar o nome exato do board. ⚠️ Atenção: A exclusão é irreversível. Exporte dados importantes antes de excluir.\n"
},
{
"title": "Aba Tags",
"description": "Guia de aba tags no Perpetuus CRM.",
"url": "/docs/guia/boards-pipelines/aba-tags",
"path": "guia/boards-pipelines/aba-tags.mdx",
"markdown": "# Aba Tags (/docs/guia/boards-pipelines/aba-tags)\n\n\n\n\n\nA aba Tags permite criar etiquetas para classificar e filtrar cards. Requer permissão `tag.list`.\n\n## Como usar [#como-usar]\n\nClique na aba Tags . Criar tag: Clique em \"Nova Tag\" (ou similar), informe nome e escolha uma cor. Editar/Excluir: Use os ícones na linha de cada tag. Usar nos cards: Ao abrir um card, atribua uma ou mais tags. Filtrar: No Kanban ou List, use o filtro por tag para ver apenas cards com certa etiqueta.\n\n## Cores disponíveis [#cores-disponíveis]\n\nVermelho, Laranja, Amarelo, Verde, Azul, Roxo, Rosa — escolha cores que facilitem a identificação rápida (ex: \"Urgente\" vermelho, \"Qualificado\" verde).\n\n## Nomenclatura e boas práticas [#nomenclatura-e-boas-práticas]\n\nUse nomes curtos e consistentes: \"Urgente\", \"Qualificado\", \"Retorno\". Evite tags muito específicas que gerem dezenas de variações. Tags para funil: Em vendas: \"Hot\", \"Warm\", \"Cold\" ou \"Lead\", \"Oportunidade\", \"Cliente\". Em suporte: \"Crítico\", \"Alto\", \"Médio\".\n\n## Excluir tag [#excluir-tag]\n\nAo excluir, os cards perdem a referência à tag. A ação não remove os cards.\n"
},
{
"title": "Como funcionam os Campos Dinâmicos (FieldData)",
"description": "Guia de como funcionam os campos dinâmicos (fielddata) no Perpetuus CRM.",
"url": "/docs/guia/boards-pipelines/campos-dinamicos",
"path": "guia/boards-pipelines/campos-dinamicos.mdx",
"markdown": "# Como funcionam os Campos Dinâmicos (FieldData) (/docs/guia/boards-pipelines/campos-dinamicos)\n\n\n\n\n\nUm dos diferenciais do Perpetuus é a flexibilidade de dados. Em vez de campos fixos, você cria campos customizados para cada etapa do seu processo.\n\n## O que são? [#o-que-são]\n\nCampos dinâmicos são formulários que você atrela às Fases de um Board . Na fase \"Qualificação\", você pode exigir \"CNPJ\", \"Renda Mensal\" e \"Prioridade\". Na fase \"Fechamento\", \"Método de Pagamento\" e \"Anexo de Contrato\".\n\n## Tipos Suportados [#tipos-suportados]\n\n| Texto Curto / Longo | Nome, descrição, observações |\n| ------------------- | ---------------------------- |\n| Select (Lista) | Prioridade, status, origem |\n| Data e Hora | Data de reunião, prazo |\n| CPF / CNPJ | Com validação nativa |\n| Moeda | Valor da proposta, orçamento |\n\nAviso: Use slugs curtos e descritivos (ex: `cpf_cliente`) — facilitam variáveis em PDFs e automações.\n"
},
{
"title": "Fases Ganho/Perdido e Métricas de Conversão",
"description": "Guia de fases ganho/perdido e métricas de conversão no Perpetuus CRM.",
"url": "/docs/guia/boards-pipelines/fases-ganho-perdido",
"path": "guia/boards-pipelines/fases-ganho-perdido.mdx",
"markdown": "# Fases Ganho/Perdido e Métricas de Conversão (/docs/guia/boards-pipelines/fases-ganho-perdido)\n\n\n\n\n\nO pipeline é a sequência de fases do seu board. Para que relatórios, dashboards e automações funcionem corretamente, é essencial marcar quais fases representam Ganho (Won) e Perdido (Lost) .\n\n## Onde configurar [#onde-configurar]\n\nNo board, aba Settings → seção de estados. Selecione qual fase é Ganho e qual é Perdido. Você pode ter mais de uma fase de cada tipo (ex: \"Fechado Ganho\" e \"Renovado\").\n\n## Fluxo típico [#fluxo-típico]\n\n1 Lead → Qualificação → Apresentação → Proposta 2 Resultado Ganho Oportunidade fechada Perdido Oportunidade perdida\n\n## O que isso habilita [#o-que-isso-habilita]\n\nMétricas: Taxa de conversão (Ganhos / Ganhos + Perdidos), tempo médio por fase, volume por coluna Automações: Gatilhos como \"Card entra em fase Ganho\" ou \"Perdido\" — ex: notificar equipe, enviar mensagem de boas-vindas ao cliente Visualização: Colunas de Ganho e Perdido destacadas no Kanban Relatórios: Funil, conversão e dashboards passam a refletir dados corretos\n\nAtenção: Sem essa configuração, o sistema não diferencia vendas fechadas de oportunidades perdidas — métricas e automações ficam incompletas.\n\nUse automações para notificar a equipe quando um card entrar em Ganho ou disparar um follow-up quando entrar em Perdido.\n"
},
{
"title": "Introdução: O que são Boards?",
"description": "Guia de introdução: o que são boards? no Perpetuus CRM.",
"url": "/docs/guia/boards-pipelines/introducao-boards",
"path": "guia/boards-pipelines/introducao-boards.mdx",
"markdown": "# Introdução: O que são Boards? (/docs/guia/boards-pipelines/introducao-boards)\n\n\n\n\n\nOs Boards (Quadros) representam os processos de negócio da sua empresa: funil de vendas, suporte, recrutamento ou projetos. Cada Board exibe seus itens em Fases (colunas) e Cards (oportunidades ou tarefas).\n\n## Estrutura visual [#estrutura-visual]\n\nLead Card A Card E Qualif. Card B Apres. Card C Fechado Card D\n\n## Estados de conclusão [#estados-de-conclusão]\n\nConfigure nas Settings quais fases representam Ganho (Won) e Perdido (Lost) . Isso permite métricas de conversão corretas.\n\n## Barra de abas [#barra-de-abas]\n\nAo abrir um board, você vê as abas no topo:\n\n| Board | Visão Kanban em colunas |\n| ------------- | ------------------------------ |\n| List | Mesmos cards em tabela |\n| Flow | Configurar fases e campos |\n| Pessoas | Membros e editores |\n| Tags | Etiquetas para cards |\n| Distribuição | Filas de atribuição automática |\n| Automações | Regras automáticas do board |\n| PDF Templates | Cotações e documentos |\n| Settings | Configurações gerais |\n"
},
{
"title": "Modal do Card",
"description": "Guia de modal do card no Perpetuus CRM.",
"url": "/docs/guia/boards-pipelines/modal-card",
"path": "guia/boards-pipelines/modal-card.mdx",
"markdown": "# Modal do Card (/docs/guia/boards-pipelines/modal-card)\n\n\n\n\n\nAo clicar em um card no Kanban ou na List, abre-se o modal de detalhes — o centro de trabalho do card.\n\n## Cabeçalho [#cabeçalho]\n\nModos de workspace: Card (padrão), Dual (card + chat lado a lado em telas xl+) e Chat (quando há conversa vinculada). Excluir e Fechar o modal.\n\n## Coluna esquerda (\\~25%) [#coluna-esquerda-25]\n\nInformações principais editáveis: Título e descrição Tags Contato vinculado Responsáveis (assignees) Data de vencimento Valor (se habilitado no board) Histórico de movimentação entre fases\n\n## Abas centrais [#abas-centrais]\n\n| Dados | Acordeão com campos de todas as fases do pipeline |\n| ----------- | -------------------------------------------------- |\n| Comentários | Timeline de comentários da equipe |\n| Orçamento | Carrinho de produtos (se módulo de produtos ativo) |\n| Documentos | PDFs gerados e arquivos do card |\n| Tarefas | Tarefas vinculadas ao card |\n| Meet | Reuniões Google Meet (se integração ativa) |\n\n## Barra de abas [#barra-de-abas]\n\nNa mesma linha das abas, o seletor de fase permite mover o card para outra coluna sem arrastar no Kanban.\n\n## Modo Dual e mobile [#modo-dual-e-mobile]\n\nDual (xl+): Painel de chat aparece ao lado das abas quando há conversa vinculada. Mobile: Abas com scroll horizontal; seletor de fase fica no rodapé do modal.\n\nUse o modo Dual para atender o cliente no chat enquanto preenche campos na aba Dados.\n"
},
{
"title": "Detalhe da Campanha e Log de Envios",
"description": "Guia de detalhe da campanha e log de envios no Perpetuus CRM.",
"url": "/docs/guia/campanhas/detalhe-e-logs",
"path": "guia/campanhas/detalhe-e-logs.mdx",
"markdown": "# Detalhe da Campanha e Log de Envios (/docs/guia/campanhas/detalhe-e-logs)\n\n\n\n\n\nA tela de detalhe mostra resumo, estatísticas e log de cada envio realizado.\n\n## Cards de informação [#cards-de-informação]\n\nSegmento: Nome e quantidade de contatos Canal: Tipo (WhatsApp) e Inbox Início: Data/hora do início do envio Conclusão: Data/hora do término\n\n## Estatísticas [#estatísticas]\n\n| Total | Contatos no segmento na hora do disparo |\n| --------- | -------------------------------------------------- |\n| Pendente | Aguardando envio |\n| Enviados | Mensagens entregues |\n| Falhas | Erros (número inválido, bloqueio, etc.) |\n| Ignorados | Contatos sem contato no canal ou regras de negócio |\n\n## Log de envios [#log-de-envios]\n\nA tabela mostra cada contato: Status (pending, sent, failed, skipped), Contato , Telefone , Enviado em e Erro (quando houver).\n\n## Reenviar falhas [#reenviar-falhas]\n\nSe a campanha Concluída ou Falhou tiver falhas, o botão `Reenviar Falhas (N)` aparece. Confirme para tentar reenviar apenas os contatos que falharam.\n\nDurante o envio, a tela atualiza automaticamente a cada 3 segundos.\n"
},
{
"title": "Estados da Campanha e Ações",
"description": "Guia de estados da campanha e ações no Perpetuus CRM.",
"url": "/docs/guia/campanhas/estados-e-acoes",
"path": "guia/campanhas/estados-e-acoes.mdx",
"markdown": "# Estados da Campanha e Ações (/docs/guia/campanhas/estados-e-acoes)\n\n\n\n\n\nCada campanha passa por diferentes estados. As ações disponíveis dependem do status atual.\n\n## Tabela de status e ações [#tabela-de-status-e-ações]\n\n| Rascunho | Criada, não disparada | Iniciar Envio, Excluir |\n| --------- | ------------------------- | --------------------------- |\n| Agendada | Com data/hora definida | Iniciar Envio, Excluir |\n| Enviando | Em execução | Pausar, Cancelar |\n| Pausada | Interrompida pelo usuário | Retomar, Cancelar |\n| Concluída | Todos enviados | Reenviar Falhas (se houver) |\n| Falhou | Erro geral | Reenviar Falhas |\n| Cancelada | Cancelada pelo usuário | - |\n\n## Passo a passo: Iniciar envio [#passo-a-passo-iniciar-envio]\n\n1️⃣ Abra a campanha (clique no nome na listagem ou no botão Editar). 2️⃣ Com status Rascunho ou Agendada , clique em `Iniciar Envio`. 3️⃣ Confirme no diálogo. O status mudará para Enviando . 4️⃣ Durante o envio, use `Pausar` para interromper ou `Cancelar` para encerrar.\n\nAtenção: Cancelar não pode ser desfeito. Os envios pendentes não serão realizados.\n"
},
{
"title": "Introdução ao Módulo de Campanhas",
"description": "Guia de introdução ao módulo de campanhas no Perpetuus CRM.",
"url": "/docs/guia/campanhas/introducao-campanhas",
"path": "guia/campanhas/introducao-campanhas.mdx",
"markdown": "# Introdução ao Módulo de Campanhas (/docs/guia/campanhas/introducao-campanhas)\n\n\n\n\n\nAs Campanhas permitem enviar mensagens em massa para grupos de contatos definidos por Segmentos . Use campanhas para promoções, comunicados, lembretes ou qualquer disparo via WhatsApp.\n\n## Onde encontrar [#onde-encontrar]\n\nBoards Contatos Segmentos Campanhas Configurações Campanhas Gerencie campanhas de disparo em massa. + Nova Campanha\n\n| Nome | Segmento | Canal | Status | Agend. |\n| ------------------ | ---------------- | -------- | --------- | --------- |\n| Black Friday | Clientes Ativos | WhatsApp | Concluída | — |\n| Lembrete Pagamento | Inadimplentes | WhatsApp | Agendada | 15/03 10h |\n| Novos Produtos | Lead Qualificado | WhatsApp | Rascunho | — |\n\n## Colunas da listagem [#colunas-da-listagem]\n\n| Nome | Nome da campanha (clique para ver detalhes) |\n| ----------- | ------------------------------------------------------------------- |\n| Segmento | Segmento de contatos alvo |\n| Canal | WhatsApp, E-mail, SMS |\n| Status | Rascunho, Agendada, Enviando, Pausada, Concluída, Falhou, Cancelada |\n| Agendamento | Data/hora do disparo (ou -) |\n| Progresso | Barra de envio (pendente/enviados/falhas) |\n| Ações | Editar, Excluir (apenas rascunho) |\n\n## Passo a passo: acessar Campanhas [#passo-a-passo-acessar-campanhas]\n\nAcesse o menu lateral esquerdo. Clique no item Campanhas (ícone megafone). Você verá a listagem de todas as campanhas. Use o botão `Nova Campanha` (canto superior direito) para criar.\n\nCrie primeiro um Segmento com os contatos desejados. Sem segmento não é possível criar campanha.\n\n## Formulário Nova Campanha [#formulário-nova-campanha]\n\nAo clicar em Nova Campanha , um modal abre com as seções abaixo: Nova Campanha Informações da Campanha Nome min. 3 caracteres Descrição opcional Público-alvo Segmento Selecione um segmento ▼ Canal e Mensagem Canal de Envio WhatsApp ▼ Template WhatsApp Selecione um template ▼ Variáveis contact.name, customField ou static Agendamento Data/hora vazio = disparo manual Cancelar Salvar Campanha\n\n## Passo a passo: criar campanha [#passo-a-passo-criar-campanha]\n\nClique em `Nova Campanha`. Preencha o Nome (obrigatório, mínimo 3 caracteres). (Opcional) Preencha a Descrição . Selecione o Segmento — mostra quantidade de contatos. Selecione o Canal de Envio (canal configurado e vinculado à organização). Selecione o Template WhatsApp (aprovado na Meta). Se o template tiver variáveis (ex: \\{\\{1}}), configure a origem em Variáveis da Mensagem . (Opcional) Agende data/hora. Se deixar em branco, o disparo será manual. Clique em `Salvar Campanha`. ⚠️ Importante: Segmento e Canal são obrigatórios. O canal deve estar vinculado ao Perpetuus Omnichannel. Certifique-se de que o canal está ativo — os templates são buscados da API do canal.\n"
},
{
"title": "Variáveis do Template e Canal",
"description": "Guia de variáveis do template e canal no Perpetuus CRM.",
"url": "/docs/guia/campanhas/variaveis-e-canal",
"path": "guia/campanhas/variaveis-e-canal.mdx",
"markdown": "# Variáveis do Template e Canal (/docs/guia/campanhas/variaveis-e-canal)\n\n\n\n\n\nTemplates WhatsApp aprovados na Meta podem conter variáveis dinâmicas (ex: nome do contato). Configure a origem de cada variável no formulário.\n\n## Tipos de origem (source) [#tipos-de-origem-source]\n\n| contact | Dado do contato (name, email, phone, etc.) |\n| ----------- | ------------------------------------------ |\n| customField | Campo personalizado do contato |\n| static | Valor fixo definido por você |\n\n## Canal de Envio [#canal-de-envio]\n\nO canal deve estar configurado no Perpetuus Omnichannel e vinculado à sua organização. O sistema lista canais disponíveis no ChannelCombobox . Se houver vinculação com Board, o ChannelBoardAlert exibe aviso.\n\n## Passo a passo: configurar variáveis [#passo-a-passo-configurar-variáveis]\n\n1️⃣ Selecione o template. Se ele tiver placeholders como `\\{\\{1\\}\\}`, `\\{\\{2\\}\\}`, a seção Variáveis aparece. 2️⃣ Para cada variável, escolha a origem: contact (path: name, email...), customField ou static . 3️⃣ Se static , preencha o valor fixo. 4️⃣ Salve a campanha. Os valores serão aplicados no envio.\n\nAtenção: Templates são gerenciados na Meta. O Perpetuus usa apenas templates já aprovados.\n"
},
{
"title": "Abas do Modal de Canal",
"description": "Guia de abas do modal de canal no Perpetuus CRM.",
"url": "/docs/guia/canais/abas-modal-canal",
"path": "guia/canais/abas-modal-canal.mdx",
"markdown": "# Abas do Modal de Canal (/docs/guia/canais/abas-modal-canal)\n\n\n\n\n\nAo clicar em um canal, um modal abre com quatro abas para configurar e gerenciar.\n\n## Tabela de abas [#tabela-de-abas]\n\n| Config | Ver e editar nome, tipo e credenciais (token, Phone ID, etc.) |\n| ------------ | -------------------------------------------------------------------- |\n| Preferências | Configurações adicionais do canal |\n| Boards | Vincular canal a boards e configurar mapeamento de campos |\n| Templates | Listar, sincronizar e gerenciar templates WhatsApp aprovados na Meta |\n\n## Passo a passo [#passo-a-passo]\n\n1️⃣ Clique em um card de canal na listagem. 2️⃣ O modal abre na aba Config . 3️⃣ Use as abas para alternar entre Config , Preferências , Boards e Templates . 4️⃣ Na Config , edite credenciais se o token expirar (ex: erro 401 ao buscar templates).\n\nA vinculação com Boards permite que conversas do canal criem ou atualizem cards automaticamente.\n"
},
{
"title": "Introdução ao Módulo de Canais",
"description": "Guia de introdução ao módulo de canais no Perpetuus CRM.",
"url": "/docs/guia/canais/introducao-canais",
"path": "guia/canais/introducao-canais.mdx",
"markdown": "# Introdução ao Módulo de Canais (/docs/guia/canais/introducao-canais)\n\n\n\n\n\nOs Canais conectam o Perpetuus aos canais de comunicação (WhatsApp, etc.) através do Perpetuus Omnichannel. Com um canal configurado, você pode receber conversas, disparar campanhas e usar templates aprovados na Meta.\n\n## Onde encontrar [#onde-encontrar]\n\nBoards Contatos Campanhas Canais Configurações Canais Configure canais de chat para sua organização. + Novo Canal WhatsApp Loja WhatsApp Suporte + Adicionar\n\n## O que cada card mostra [#o-que-cada-card-mostra]\n\n| Nome e Slug | Identificação do canal |\n| --------------------------- | ------------------------------------------- |\n| Status | Ativo ou Inativo |\n| Tipo | WhatsApp, Instagram (em breve), etc. |\n| Boards vinculados | Quantidade de boards ligados ao canal |\n| Perpetuus Omnichannel Inbox | Nome e ID do inbox no Perpetuus Omnichannel |\n\n## Passo a passo: acessar Canais [#passo-a-passo-acessar-canais]\n\nAcesse o menu lateral esquerdo. Clique no item Canais (ícone telefone). Você verá o grid de canais configurados. Use o botão `Novo Canal` (ou `Criar primeiro canal` se vazio) para adicionar. Clique em um card para abrir o modal e ver/editar o canal.\n\nUm canal é necessário para Campanhas WhatsApp e para receber conversas no módulo Chats.\n\n## Adicionando um Canal WhatsApp [#adicionando-um-canal-whatsapp]\n\nAo clicar em Novo Canal , um modal abre com o formulário abaixo: Novo Canal Nome ex: WhatsApp Loja Tipo WhatsApp ▼ Credenciais WhatsApp Telefone formato internacional Phone Number ID da Meta Business Account ID da Meta Access Token da Meta Cancelar Criar Canal\n\n## Passo a passo: criar canal WhatsApp [#passo-a-passo-criar-canal-whatsapp]\n\nClique em `Novo Canal`. Preencha o Nome (obrigatório, ex: \"WhatsApp Loja\"). Selecione o Tipo WhatsApp (único disponível atualmente). Preencha as credenciais da Meta: Telefone , Phone Number ID , Business Account ID , Access Token . Clique em `Criar Canal`. Na tela de sucesso, copie o Verify Token e a Callback URL — serão usados na configuração do webhook na Meta.\n\n## Onde obter as credenciais [#onde-obter-as-credenciais]\n\nAs credenciais vêm do painel da Meta: Meta Business Suite → WhatsApp → Configurações da API . O Access Token deve ter permissões de envio de mensagens. ⚠️ Importante: Guarde o Verify Token em local seguro. Ele é exibido apenas uma vez após a criação. Configure o webhook na Meta com a Callback URL e o Verify Token para que mensagens cheguem ao Perpetuus Omnichannel.\n"
},
{
"title": "Templates WhatsApp e Webhook",
"description": "Guia de templates whatsapp e webhook no Perpetuus CRM.",
"url": "/docs/guia/canais/templates-e-webhook",
"path": "guia/canais/templates-e-webhook.mdx",
"markdown": "# Templates WhatsApp e Webhook (/docs/guia/canais/templates-e-webhook)\n\n\n\n\n\nOs templates são mensagens pré-aprovadas na Meta e usadas em campanhas. O webhook permite que a Meta envie eventos (mensagens recebidas) para o Perpetuus Omnichannel.\n\n## Aba Templates [#aba-templates]\n\nNa aba Templates do modal do canal você pode: Sincronizar: Buscar templates atualizados da API da Meta/Perpetuus Omnichannel. Criar: Submeter novo template (processo na Meta). Excluir: Remover template da listagem local.\n\n## Erro 401 ao carregar templates [#erro-401-ao-carregar-templates]\n\nSe aparecer erro de autenticação, o Access Token pode ter expirado. Vá na aba Config e atualize o token com um novo gerado na Meta.\n\n## Configuração do webhook na Meta [#configuração-do-webhook-na-meta]\n\n1️⃣ Após criar o canal, copie Verify Token e Callback URL da tela de sucesso. 2️⃣ No painel da Meta (Configurações da API WhatsApp), configure o webhook com a Callback URL. 3️⃣ Informe o Verify Token quando solicitado. 4️⃣ Assine os eventos desejados (mensagens, etc.).\n\nSem webhook configurado, o canal pode enviar mas não receber mensagens. A Central de Ajuda do Perpetuus Omnichannel traz documentação detalhada.\n"
},
{
"title": "Vinculando Canal a Boards",
"description": "Guia de vinculando canal a boards no Perpetuus CRM.",
"url": "/docs/guia/canais/vinculando-canal-boards",
"path": "guia/canais/vinculando-canal-boards.mdx",
"markdown": "# Vinculando Canal a Boards (/docs/guia/canais/vinculando-canal-boards)\n\n\n\n\n\nVincule um canal a um ou mais Boards para que conversas recebidas criem ou atualizem cards automaticamente, com mapeamento de campos.\n\n## Onde configurar [#onde-configurar]\n\nNo modal do canal, aba Boards . Use o botão Adicionar vínculo (ou similar) para selecionar um board e definir o mapeamento.\n\n## Mapeamento de campos [#mapeamento-de-campos]\n\nConfigure como os dados do contato (nome, e-mail, telefone) e dados da conversa (source, etc.) são mapeados para os campos do card no board. Campos do contato: Nome, E-mail, Telefone, etc. Campos fixos do card: Título, fase inicial, etc.\n\n## Passo a passo [#passo-a-passo]\n\n1️⃣ Abra o canal e vá na aba Boards . 2️⃣ Clique em `Adicionar vínculo`. 3️⃣ Selecione o Board desejado. 4️⃣ Configure o mapeamento: campos do contato → campos do card. 5️⃣ Ative o vínculo com o switch e salve.\n\nAtenção: Cada board pode ter apenas um vínculo por canal. Revise o mapeamento antes de ativar.\n"
},
{
"title": "Criar Card e Vincular a Conversa",
"description": "Guia de criar card e vincular a conversa no Perpetuus CRM.",
"url": "/docs/guia/chats/criar-card-vincular",
"path": "guia/chats/criar-card-vincular.mdx",
"markdown": "# Criar Card e Vincular a Conversa (/docs/guia/chats/criar-card-vincular)\n\n\n\n\n\nConversas sem card vinculado podem receber um novo card criado a partir do chat, integrando o atendimento ao pipeline do board.\n\n## Quando criar um card [#quando-criar-um-card]\n\nSe uma conversa foi iniciada por um contato novo (ex.: WhatsApp) e o canal está vinculado a um board, o sistema pode criar o card automaticamente. Caso contrário, use o botão Criar Card no cabeçalho da conversa (visível quando não há card vinculado).\n\n## Passo a passo: Criar card [#passo-a-passo-criar-card]\n\n1️⃣ Abra uma conversa que ainda não tem card vinculado — o botão `Criar Card` aparece no cabeçalho. 2️⃣ Clique em `Criar Card`. 3️⃣ Selecione o Board e a Fase inicial. 4️⃣ Preencha os campos obrigatórios (título, etc.). 5️⃣ Confirme. O card será criado, vinculado à conversa e o painel de dados aparecerá à esquerda do chat.\n\n## Trocar card vinculado [#trocar-card-vinculado]\n\nSe a conversa está vinculada ao card errado, use o botão Trocar card no cabeçalho para escolher outro card do mesmo contato. Para abrir o card completo no kanban, use Abrir card no board .\n\n## Excluir contexto [#excluir-contexto]\n\nCom permissão adequada, o ícone de lixeira no cabeçalho remove o vínculo CRM da conversa sem apagar as mensagens do Perpetuus Omnichannel.\n\nA vinculação canal-board em Canais define o mapeamento automático. Configure em Canais → \\[Canal] → aba Boards.\n"
},
{
"title": "Introdução ao Módulo de Chats",
"description": "Guia de introdução ao módulo de chats no Perpetuus CRM.",
"url": "/docs/guia/chats/introducao-chats",
"path": "guia/chats/introducao-chats.mdx",
"markdown": "# Introdução ao Módulo de Chats (/docs/guia/chats/introducao-chats)\n\n\n\n\n\nO módulo de Chats exibe as conversas do Perpetuus Omnichannel integradas ao seu CRM. Responda clientes em tempo real enquanto visualiza e edita dados do card vinculado à conversa.\n\n## Onde encontrar [#onde-encontrar]\n\nBoards Contatos Chats Canais Lista de conversas \\[Filtros · Busca · Inbox] \\[↻ Atualizar · + Nova] Painel do card + Chat Dados do CRM à esquerda · Mensagens à direita\n\n## Pré-requisitos [#pré-requisitos]\n\nPerpetuus Omnichannel configurado: Variáveis Perpetuus Omnichannel\\_APP\\_URL e Perpetuus Omnichannel\\_PLATFORM\\_API\\_TOKEN no backend Canal ativo: Ao menos um canal (WhatsApp, etc.) configurado em Canais\n\n## Estados da tela [#estados-da-tela]\n\n| Chat não configurado | Mensagem para administrador com instruções de configuração. |\n| -------------------- | -------------------------------------------------------------- |\n| Nenhum canal | Link para configurar Canais. |\n| Lista vazia | Nenhuma conversa ainda. Use o botão (+) para iniciar uma nova. |\n| Conversa selecionada | Painel do card (se houver) + chat com histórico de mensagens. |\n\n## Passo a passo [#passo-a-passo]\n\n1️⃣ Acesse o menu lateral e clique em Chats (ícone de mensagem). 2️⃣ Se aparecer \"Chat não configurado\", solicite ao administrador que configure o Perpetuus Omnichannel. 3️⃣ Se aparecer \"Nenhum canal configurado\", clique em `Configurar Canais` e adicione um canal WhatsApp. 4️⃣ A lista de conversas aparece à esquerda, com título Conversas , botão de atualizar (↻) e botão + para nova conversa. 5️⃣ Clique em uma conversa na lista para abri-la à direita — com painel do card (desktop) e área de chat.\n\nVincule canais a Boards em Canais → \\[Canal] → aba Boards para que conversas criem cards automaticamente.\n"
},
{
"title": "Lista de Conversas e Filtros",
"description": "Guia de lista de conversas e filtros no Perpetuus CRM.",
"url": "/docs/guia/chats/lista-filtros-chats",
"path": "guia/chats/lista-filtros-chats.mdx",
"markdown": "# Lista de Conversas e Filtros (/docs/guia/chats/lista-filtros-chats)\n\n\n\n\n\nA coluna à esquerda concentra todas as conversas. Use os filtros, a busca local e o seletor de inbox para encontrar rapidamente o que precisa atender.\n\n## Cabeçalho da lista [#cabeçalho-da-lista]\n\nTítulo Conversas: Com badge de contagem de abertas, quando houver Atualizar (↻): Recarrega a lista; pulsa quando há mensagens novas em tempo real Nova conversa (+): Abre o diálogo para iniciar chat com um contato existente\n\n## Filtros disponíveis [#filtros-disponíveis]\n\n| Inbox | Botão compacto com ícone de caixa de entrada — dropdown com todas as inboxes ou um canal específico (WhatsApp Loja, etc.) |\n| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Busca local | Campo \"Buscar conversas...\" — filtra por nome, e-mail, telefone, ID ou título do card (sem alterar a URL) |\n| Status | Select compacto: Todos, Abertos, Resolvidos |\n| Atribuição | Select compacto: Todas, Minhas, Sem atribuição, Sem card. Usuários sem permissão canViewAllChats veem apenas Minhas, Sem atribuição e Sem card (sem a opção Todas) |\n| Não atendidas | Botão alternável — exibe somente conversas sem resposta do agente (`conversationType=unattended`) |\n\n## Outros elementos [#outros-elementos]\n\nItens da lista: Avatar, nome, preview da última mensagem, badge de não lidas e indicador de card vinculado Menu de contexto (clique direito): Resolver conversa · Marcar como não lida Rodapé com estatísticas: Contadores de Minhas, Com card e Abertas (visível quando há conversas carregadas) Scroll infinito: Role até o fim para carregar mais conversas\n\n## Passo a passo [#passo-a-passo]\n\n1️⃣ No cabeçalho, use o botão de inbox (ícone de caixa) para filtrar por canal ou ver todas as inboxes. 2️⃣ Digite no campo Buscar conversas... para localizar por nome do contato, telefone ou card. 3️⃣ Use o select de Status para ver Abertos ou Resolvidos. 4️⃣ Use o select de Atribuição — por exemplo Minhas ou Sem card . 5️⃣ Ative o botão Não atendidas para focar em conversas ainda sem resposta. 6️⃣ Clique em uma conversa para abri-la, ou use o botão + para iniciar uma nova. 7️⃣ Consulte o rodapé para um resumo rápido de Minhas, Com card e Abertas.\n\nOs filtros de status, atribuição, inbox e \"Não atendidas\" são salvos na URL. Você pode compartilhar o link para uma visualização filtrada.\n"
},
{
"title": "Painel de Dados do Card",
"description": "Guia de painel de dados do card no Perpetuus CRM.",
"url": "/docs/guia/chats/painel-dados-card",
"path": "guia/chats/painel-dados-card.mdx",
"markdown": "# Painel de Dados do Card (/docs/guia/chats/painel-dados-card)\n\n\n\n\n\nQuando uma conversa tem um card vinculado , o painel à esquerda do chat (desktop) exibe os dados do CRM. Edite campos, responsáveis, tags e mova entre fases sem sair do atendimento. No celular, o mesmo conteúdo abre em Sheet pelo botão de painel no cabeçalho.\n\n## Estrutura do painel [#estrutura-do-painel]\n\nTopo fixo — Mover card: Dropdown com a fase atual e fases disponíveis para avançar ou retroceder Accordion Detalhes do card: Tags, responsáveis, data de vencimento e campos de todas as fases do board (aberto por padrão) Accordion Tarefas e comentários: Lista de tarefas do card e comentários internos Accordion Documentos: Anexos vinculados ao card Accordion Orçamento: Carrinho de produtos (visível apenas se o board tiver produtos ativados) Histórico de movimentações: Registro de mudanças de fase no rodapé do painel\n\n## Edição e movimento [#edição-e-movimento]\n\nO painel tem paridade com o modal do card no board. Campos da fase atual e de fases anteriores são editáveis. Ao avançar de fase, campos obrigatórios da fase atual são validados; retroceder é sempre permitido.\n\n## Passo a passo [#passo-a-passo]\n\n1️⃣ Com uma conversa aberta que tenha card vinculado, o painel aparece à esquerda do chat no desktop (ou via Sheet no mobile). 2️⃣ No topo, use o dropdown Mover card para selecionar a fase de destino. 3️⃣ Expanda Detalhes do card para editar tags, responsáveis, vencimento e campos das fases. 4️⃣ Abra Tarefas e comentários para gerenciar pendências ou registrar notas internas. 5️⃣ Em Documentos , anexe ou consulte arquivos do card. 6️⃣ Se o board tiver produtos, use Orçamento para montar cotações. 7️⃣ Role até o fim para consultar o histórico de movimentações do card.\n\nAtenção: Campos obrigatórios da fase atual bloqueiam o avanço até que sejam preenchidos. Retroceder de fase não exige validação.\n"
},
{
"title": "Visualizando e Respondendo uma Conversa",
"description": "Guia de visualizando e respondendo uma conversa no Perpetuus CRM.",
"url": "/docs/guia/chats/visualizando-respondendo",
"path": "guia/chats/visualizando-respondendo.mdx",
"markdown": "# Visualizando e Respondendo uma Conversa (/docs/guia/chats/visualizando-respondendo)\n\n\n\n\n\nAo selecionar uma conversa, a área principal divide-se em dois painéis no desktop: dados do card à esquerda e chat à direita . No celular, o chat ocupa a tela inteira e o painel do card abre em uma folha lateral.\n\n## Layout da conversa [#layout-da-conversa]\n\nDesktop (lg+): CardDataPanel fixo à esquerda · ChatPanel à direita Mobile: Chat em tela cheia; botão com ícone PanelRightOpen no cabeçalho abre os dados do card em Sheet Voltar: Seta no cabeçalho (mobile) retorna à lista de conversas\n\n## Cabeçalho da conversa [#cabeçalho-da-conversa]\n\n| Avatar e nome | Identificação do contato e inbox de origem |\n| ------------------- | ------------------------------------------------------ |\n| Badge de status | Aberto, Pendente, Resolvido ou Adiado |\n| Trocar card | Vincula a conversa a outro card do mesmo contato |\n| Abrir card no board | Abre o modal do card no kanban |\n| Excluir contexto | Remove o vínculo CRM da conversa (requer permissão) |\n| Criar card | Aparece quando a conversa ainda não tem card vinculado |\n| Resolver / Reabrir | Altera o status da conversa entre aberta e resolvida |\n\n## Área de chat (ChatPanel) [#área-de-chat-chatpanel]\n\nControles de IA: Atalhos de automação ligados ao card (quando disponível) Mensagens: Histórico com scroll infinito e atualização em tempo real Indicador de digitação: Mostra quando o contato está digitando Campo de resposta: Texto multilinha com Enter para enviar Anexos: Ícone de clipe para imagens e documentos Emoji: Seletor de emojis Templates WhatsApp: Mensagens pré-aprovadas para respostas rápidas Áudio: Gravação e envio de mensagens de voz\n\n## Passo a passo [#passo-a-passo]\n\n1️⃣ Clique em uma conversa na lista à esquerda. 2️⃣ No desktop, confira o painel do card à esquerda e o chat à direita. No celular, use o ícone de painel para ver os dados do card. 3️⃣ Leia o histórico de mensagens; role para cima para carregar mensagens anteriores. 4️⃣ Digite no campo de texto e clique em `Enviar` (ou pressione Enter). 5️⃣ Use o ícone de clipe para anexar arquivos, o seletor de emoji ou o menu de Templates para respostas rápidas. 6️⃣ Para enviar áudio, use o botão de microfone , grave e confirme o envio. 7️⃣ Ao finalizar o atendimento, clique em `Resolver`. Para retomar depois, use `Reabrir`.\n\nAs mensagens atualizam em tempo real. O indicador de digitação ajuda a saber quando o cliente está respondendo.\n"
},
{
"title": "Criando um Novo Contato",
"description": "Guia de criando um novo contato no Perpetuus CRM.",
"url": "/docs/guia/gestao-contatos/cadastro-contatos",
"path": "guia/gestao-contatos/cadastro-contatos.mdx",
"markdown": "# Criando um Novo Contato (/docs/guia/gestao-contatos/cadastro-contatos)\n\n\n\n\n\nGuia passo a passo para o cadastro manual, com layout completo e regras de validação.\n\n## Layout do modal [#layout-do-modal]\n\nNovo Contato × Tipo Pessoa Empresa Alternar muda CPF/CNPJ \\* Nome (obrigatório) Digite o nome \\* E-mail ou Telefone (pelo menos um obrigatório) [exemplo@email.com](mailto:exemplo@email.com) ou +55… CPF/CNPJ (opcional, com validação) — Endereço, Cidade, Estado… (opcionais) Dados Adicionais (se configurados) Cancelar `Salvar`\n\n## Regras de validação [#regras-de-validação]\n\n| Nome | Obrigatório. Texto livre. |\n| ------------------ | ------------------------------------------------------------ |\n| E-mail ou Telefone | Pelo menos um obrigatório. Telefone normalizado para E.164. |\n| CPF | Se preenchido: validação algorítmica. Erro: \"CPF inválido\". |\n| CNPJ | Se preenchido: validação algorítmica. Erro: \"CNPJ inválido\". |\n\n## Passo a passo numerado [#passo-a-passo-numerado]\n\n1️⃣ Clique em `Novo Contato` (canto superior direito). 2️⃣ Escolha Pessoa ou Empresa — isso define se CPF ou CNPJ aparecerá. 3️⃣ Preencha o Nome (obrigatório). 4️⃣ Preencha E-mail ou Telefone (obrigatório pelo menos um). 5️⃣ (Opcional) Preencha CPF ou CNPJ — o sistema validará em tempo real. 6️⃣ (Opcional) Complete endereço e demais campos. 7️⃣ Clique em `Salvar`. ⚠️ Erro comum: Tentar salvar sem e-mail nem telefone. Mensagem: \"É necessário fornecer pelo menos email ou telefone\".\n\nO telefone é normalizado automaticamente para formato internacional (+55...).\n"
},
{
"title": "Campos Customizados e Dados Dinâmicos",
"description": "Guia de campos customizados e dados dinâmicos no Perpetuus CRM.",
"url": "/docs/guia/gestao-contatos/campos-customizados-contatos",
"path": "guia/gestao-contatos/campos-customizados-contatos.mdx",
"markdown": "# Campos Customizados e Dados Dinâmicos (/docs/guia/gestao-contatos/campos-customizados-contatos)\n\n\n\n\n\nO Perpetuus permite estender o cadastro de contatos com campos personalizados, adaptados à sua operação.\n\n## O que são Custom Fields? [#o-que-são-custom-fields]\n\nCampos customizados (Dados Adicionais) permitem armazenar informações extras por contato — origem do lead, interesse, última interação, etc. Eles são configurados por organização e podem sincronizar com campos de Boards.\n\n## Onde criar os campos [#onde-criar-os-campos]\n\nOs campos customizados são criados e configurados em: Configurações → Organização → aba Campos de Contato Acesse o menu lateral e clique em Configurações (ícone de engrenagem). Clique em Organização . Selecione a aba Campos de Contato . Use Adicionar campo para definir nome, slug, tipo (texto, número, data, seleção, etc.) e se é obrigatório.\n\n## Onde aparecem [#onde-aparecem]\n\nApós configurar, os campos aparecem como Dados Adicionais em: Modal de criar/editar contato Detalhe do contato (seção separada) Automações (contact.create, contact.update) Importação de contatos\n\n## Passo a passo: Preencher dados [#passo-a-passo-preencher-dados]\n\nAo criar ou editar contato, role até Dados Adicionais (campos definidos em Configurações > Organização). Preencha os campos conforme o tipo configurado. No detalhe do contato, os valores aparecem em seção separada.\n\nNota: As definições de campos ficam em Configurações > Organização > Campos de Contato. Sem campos criados ali, a seção Dados Adicionais não aparece nos formulários de contato.\n"
},
{
"title": "Inteligência de Não Duplicação (Deduplicação)",
"description": "Guia de inteligência de não duplicação (deduplicação) no Perpetuus CRM.",
"url": "/docs/guia/gestao-contatos/deduplicacao-contatos",
"path": "guia/gestao-contatos/deduplicacao-contatos.mdx",
"markdown": "# Inteligência de Não Duplicação (Deduplicação) (/docs/guia/gestao-contatos/deduplicacao-contatos)\n\n\n\n\n\nUm banco de dados com contatos repetidos gera confusão, abordagens duplas e métricas erradas. O Perpetuus possui um sistema de trava inteligente.\n\n## Chaves de unicidade [#chaves-de-unicidade]\n\nO sistema monitora 4 identificadores únicos dentro da sua organização: E-mail Telefone (normalizado para E.164) CPF CNPJ\n\n## Mensagens de erro exatas [#mensagens-de-erro-exatas]\n\n| E-mail | Já existe um contato com o email \"[exemplo@email.com](mailto:exemplo@email.com)\" nesta organização |\n| -------- | -------------------------------------------------------------------------------------------------- |\n| Telefone | Já existe um contato com o telefone \"+5511999999999\" nesta organização |\n| CPF | Já existe um contato com este CPF nesta organização |\n| CNPJ | Já existe um contato com este CNPJ nesta organização |\n\n## O que acontece ao tentar duplicar? [#o-que-acontece-ao-tentar-duplicar]\n\n⚠️ Erro de Cadastro: Já existe um contato com o email \"[joao@cliente.com](mailto:joao@cliente.com)\" nesta organização.\n\n## Cenário de teste [#cenário-de-teste]\n\nCadastre um contato com e-mail `teste@exemplo.com`. Tente criar outro contato com o mesmo e-mail. O sistema bloqueará e exibirá a mensagem de erro. Solução: Edite o contato existente ou use outro e-mail.\n\nImportante: A unicidade vale apenas dentro da sua organização. Outras empresas Perpetuus podem ter o mesmo e-mail em seus contatos.\n\nTelefones são normalizados (ex: 11999999999 → +5511999999999) antes da verificação.\n"
},
{
"title": "Equipes e Responsáveis (Ownership)",
"description": "Guia de equipes e responsáveis (ownership) no Perpetuus CRM.",
"url": "/docs/guia/gestao-contatos/equipes-responsaveis",
"path": "guia/gestao-contatos/equipes-responsaveis.mdx",
"markdown": "# Equipes e Responsáveis (Ownership) (/docs/guia/gestao-contatos/equipes-responsaveis)\n\n\n\n\n\nTodo contato tem um dono (Owner) e uma equipe (Team) vinculada. Isso é essencial para isolamento de dados e permissões.\n\n## Fluxo de auto-atribuição [#fluxo-de-auto-atribuição]\n\n1 Usuário cria novo contato 2 Sistema verifica: owner definido? Não → owner = usuário que está criando Sim → usa o definido 3 Sistema busca equipe do usuário (membership.team) 4 team = equipe do usuário 5 Contato criado com owner e team\n\n## Onde ver e alterar o responsável [#onde-ver-e-alterar-o-responsável]\n\nNo detalhe do contato (clique na linha da tabela), a seção Responsável mostra: Avatar e nome do responsável atual Nome da equipe vinculada Botão de transferir (⟷) — visível apenas para Admin e Manager\n\n## Passo a passo: Transferir responsável [#passo-a-passo-transferir-responsável]\n\nAbra o detalhe do contato (clique na linha da tabela). Localize a seção Responsável . Clique no ícone de Transferir (⟷). Selecione o novo responsável no diálogo. Confirme. O contato passará para a equipe do novo owner automaticamente. Ao transferir, o sistema: Atualiza a Equipe para a equipe do novo dono. Registra uma atividade no histórico: Responsável alterado de X para Y .\n\nNota: Operadores geralmente só veem contatos da própria equipe ou que criaram.\n\nImportante: Ao transferir, a equipe do contato é atualizada automaticamente para a equipe do novo responsável.\n"
},
{
"title": "Introdução ao Módulo de Contatos",
"description": "Guia de introdução ao módulo de contatos no Perpetuus CRM.",
"url": "/docs/guia/gestao-contatos/introducao-contatos",
"path": "guia/gestao-contatos/introducao-contatos.mdx",
"markdown": "# Introdução ao Módulo de Contatos (/docs/guia/gestao-contatos/introducao-contatos)\n\n\n\n\n\nNo Perpetuus, o módulo de Contatos é a base central do seu CRM. Toda interação com clientes e parceiros passa por aqui — WhatsApp, e-mail, formulários em Boards.\n\n## Onde encontrar [#onde-encontrar]\n\nBoards 👥 Contatos Configurações Contatos `+ Novo Contato`\n\n| — | — | — | — |\n| - | - | - | - |\n\n## Passo a passo [#passo-a-passo]\n\n1️⃣ Acesse o menu lateral esquerdo. 2️⃣ Clique no item Contatos (ícone 👥). 3️⃣ Você verá a listagem completa de contatos da sua organização. 4️⃣ Use o botão Novo Contato (canto superior direito) para cadastrar. 👆 Onde clicar: Contatos (menu) e `+ Novo Contato` (botão).\n\n## Pessoa vs Empresa [#pessoa-vs-empresa]\n\nCada contato pode ser Pessoa Física ou Empresa (Pessoa Jurídica) . Isso define quais campos de documento (CPF ou CNPJ) aparecem e são validados.\n\nContatos criados via WhatsApp, formulários ou importação aparecem aqui automaticamente.\n\nImportante: Cada contato é único por organização — não há \"vazamento\" entre clientes Perpetuus.\n"
},
{
"title": "Coloque sua Organização em Operação",
"description": "Guia de coloque sua organização em operação no Perpetuus CRM.",
"url": "/docs/guia/primeiros-passos/configuracao-inicial",
"path": "guia/primeiros-passos/configuracao-inicial.mdx",
"markdown": "# Coloque sua Organização em Operação (/docs/guia/primeiros-passos/configuracao-inicial)\n\n\n\n\n\nEste guia reúne, em ordem lógica, tudo que você precisa configurar para tirar o máximo do Perpetuus — da fundação à automação. Cada etapa explica o porquê e o como .\n\n## 1. Fundação: Equipe e Processo [#1-fundação-equipe-e-processo]\n\n### Convidar equipe [#convidar-equipe]\n\nOnde: Configurações → Organização (ou Equipes) Convide os membros e defina níveis de acesso (Admin, Manager, Membro). Crie Equipes para distribuição automática de leads: as filas na aba Distribuição dos boards usam equipes para atribuir cards.\n\n### Criar seu primeiro Board [#criar-seu-primeiro-board]\n\nOnde: Boards → Novo Board Configure as fases, os campos dinâmicos por fase e marque Ganho/Perdido nas Settings. Se quiser receber leads por formulário sem login, marque a primeira fase como formulário público e compartilhe o link gerado.\n\n### Canal WhatsApp [#canal-whatsapp]\n\nOnde: Canais → Novo Canal Conecte o WhatsApp via Meta/Perpetuus Omnichannel. Na aba Boards do canal, vincule ao board — assim, mensagens recebidas criam cards automaticamente na primeira fase.\n\nMínimo viável: Board + Canal + vínculo entre eles já permitem receber leads e operar. O restante evolui conforme a necessidade.\n\n## 2. CRM e Base de Contatos [#2-crm-e-base-de-contatos]\n\n### Segmentos [#segmentos]\n\nOnde: Segmentos → Novo Segmento Segmentos são grupos dinâmicos de contatos baseados em critérios (e-mail, tags, fase do card, etc.). Use-os para: Campanhas: Disparar WhatsApp ou e-mail só para quem atende aos filtros Automações: Acionar fluxos para contatos de um segmento Relatórios: Analisar por grupo específico Crie segmentos como \"Leads qualificados\", \"Clientes com tag VIP\" ou \"Contatos sem atividade em 30 dias\". O preview mostra em tempo real quantos contatos entram. Leia Introdução ao Módulo de Segmentos para detalhes.\n\n### Cadastro de contatos [#cadastro-de-contatos]\n\nImporte via planilha (Configurações ou módulo Contatos) ou deixe os leads chegarem por formulário público e WhatsApp. Contatos vinculados a cards têm histórico e dados sincronizáveis com os campos do board.\n\n## 3. Orçamentos e Documentos (PDF) [#3-orçamentos-e-documentos-pdf]\n\n### Produtos [#produtos]\n\nOnde: Produtos → Novo Produto Se você emite orçamentos ou propostas comerciais, cadastre o catálogo de produtos/serviços. Ative o módulo de produtos nas Settings do board para que a aba de Cotação apareça nos cards.\n\n### PDF Templates [#pdf-templates]\n\nOnde: Board → Settings → aba PDF Templates Os PDF Templates definem o layout dos orçamentos gerados. Use variáveis como `\\{\\{nome_cliente\\}\\}`, `\\{\\{produtos\\}\\}`, `\\{\\{total\\}\\}` para personalizar. Vincule cada template de cotações ao PDF Template escolhido. Sem PDF Template configurado, a geração de orçamento pode falhar ou ficar genérica.\n\nOrdem: Cadastre produtos primeiro; em seguida, crie o PDF Template e vincule às cotações do board.\n\n## 4. Automação e Escala [#4-automação-e-escala]\n\n### Automações de fase [#automações-de-fase]\n\nOnde: Board → aba Flow → selecione uma fase → Automações Defina o que acontece quando um card entra ou sai de uma fase: notificar equipe, atualizar campos, enviar mensagem, mudar responsável. Exemplo: \"Ao mover para Fechado Ganho, enviar PDF do orçamento por WhatsApp\".\n\n### Bots (opcional) [#bots-opcional]\n\nOnde: Bots no menu lateral Configure um bot de IA para pré-atendimento: responde sozinho, qualifica leads e pode criar/atualizar cards. Útil para escala e horário estendido.\n\n## Checklist Resumido [#checklist-resumido]\n\n| Convidar equipe e criar equipes | Configurações → Organização / Equipes | Alta |\n| -------------------------------------- | ------------------------------------- | ------------- |\n| Criar board com fases e campos | Boards → Novo Board | Alta |\n| Configurar canal WhatsApp | Canais → Novo Canal | Alta |\n| Vincular canal ao board | Canais → \\[Canal] → aba Boards | Alta |\n| Criar segmentos (campanhas, automação) | Segmentos → Novo Segmento | Média |\n| Cadastrar produtos | Produtos → Novo Produto | Se orçamentos |\n| Configurar PDF Templates | Board → Settings → PDF Templates | Se orçamentos |\n| Automações de fase | Board → Flow → \\[Fase] → Automações | Média |\n| Bot de IA (pré-atendimento) | Bots → Novo Bot | Opcional |\n\nEvolução: Comece com board + canal + vínculo. Depois adicione segmentos para campanhas, produtos e PDF Templates para orçamentos, e automações para ganhar tempo.\n"
},
{
"title": "Convidar Usuários e Equipes",
"description": "Guia de convidar usuários e equipes no Perpetuus CRM.",
"url": "/docs/guia/primeiros-passos/convidar-equipe",
"path": "guia/primeiros-passos/convidar-equipe.mdx",
"markdown": "# Convidar Usuários e Equipes (/docs/guia/primeiros-passos/convidar-equipe)\n\n\n\n\n\nConfigure sua equipe para colaborar no Perpetuus.\n\n## Passo a passo: Convidar usuário [#passo-a-passo-convidar-usuário]\n\n1️⃣ Acesse Configurações → Organização (requer permissão Admin). 2️⃣ Vá na seção de usuários ou Equipes . 3️⃣ Clique em `Convidar Usuário`. 4️⃣ Insira o e-mail do colaborador e defina o nível de acesso (Admin, Manager, Membro). 5️⃣ Um e-mail será enviado com instruções de acesso.\n\n## Equipes [#equipes]\n\nAgrupe usuários em Equipes para facilitar a distribuição de leads e tarefas. As filas de distribuição (aba Distribuição dos boards) usam equipes para atribuir cards automaticamente.\n\nApenas administradores podem convidar usuários e gerenciar equipes.\n"
},
{
"title": "Dando os primeiros passos no Perpetuus",
"description": "Guia de dando os primeiros passos no perpetuus no Perpetuus CRM.",
"url": "/docs/guia/primeiros-passos/dando-os-primeiros-passos",
"path": "guia/primeiros-passos/dando-os-primeiros-passos.mdx",
"markdown": "# Dando os primeiros passos no Perpetuus (/docs/guia/primeiros-passos/dando-os-primeiros-passos)\n\n\n\n\n\nO Perpetuus é uma plataforma completa que une CRM, Gestão de Tarefas, Automação Omnichannel e Vendas em um único ecossistema. Este guia irá ajudá-lo a configurar sua organização e começar com o pé direito.\n\n## Estrutura da Plataforma [#estrutura-da-plataforma]\n\nO conceito central gira em torno de 3 pilares: Organização: Estrutura máxima onde sua empresa e faturamento residem. Boards (Quadros): Seus processos — Pipeline de Vendas, Helpdesk, Recrutamento ou Projeto ágil. Cards: Itens que trafegam nas fases dos Boards, com Campos Dinâmicos e histórico completo.\n\n## Próximos passos [#próximos-passos]\n\n1️⃣ Convide sua equipe em Configurações → Organização (ou Equipes). 2️⃣ Crie seu primeiro Board em Boards . 3️⃣ Configure um canal (WhatsApp) em Canais para atendimento. 4️⃣ Cadastre contatos em Contatos ou receba via formulários e WhatsApp.\n\nUse os artigos abaixo para detalhes de cada etapa.\n"
},
{
"title": "Organização, Boards e Cards",
"description": "Guia de organização, boards e cards no Perpetuus CRM.",
"url": "/docs/guia/primeiros-passos/estrutura-plataforma",
"path": "guia/primeiros-passos/estrutura-plataforma.mdx",
"markdown": "# Organização, Boards e Cards (/docs/guia/primeiros-passos/estrutura-plataforma)\n\n\n\n\n\nEntenda a hierarquia e os conceitos principais do Perpetuus.\n\n## Organização [#organização]\n\nA Organização é o topo. Cada organização tem seus próprios usuários, boards, contatos, configurações e faturamento. Dados são isolados entre organizações.\n\n## Boards (Quadros) [#boards-quadros]\n\nBoards representam processos: vendas, suporte, recrutamento, projetos. Cada board possui: Fases (colunas): Etapas do fluxo (ex: Lead, Qualificação, Fechado) Cards: Itens que atravessam as fases Campos dinâmicos: Formulários por fase Membros e permissões\n\n## Cards [#cards]\n\nUm card pode ser uma oportunidade de venda, um ticket de suporte, um candidato ou uma tarefa. Cada card pode estar vinculado a um Contato , ter responsável, tags, comentários, tarefas e histórico.\n\nO link público do board permite receber leads diretamente na primeira fase via formulário.\n"
},
{
"title": "Criando seu Primeiro Board",
"description": "Guia de criando seu primeiro board no Perpetuus CRM.",
"url": "/docs/guia/primeiros-passos/primeiro-board",
"path": "guia/primeiros-passos/primeiro-board.mdx",
"markdown": "# Criando seu Primeiro Board (/docs/guia/primeiros-passos/primeiro-board)\n\n\n\n\n\nUm board é o coração do seu processo. Siga os passos para criar o primeiro.\n\n## Passo a passo [#passo-a-passo]\n\n1️⃣ Acesse Boards no menu e clique em `Novo Board`. 2️⃣ Escolha um Template pronto (Vendas, Suporte, etc.) ou inicie do zero. 3️⃣ Defina o nome do board (ex: \"Pipeline de Vendas\"). 4️⃣ Na aba Flow , adicione as Fases (ex: Lead Recebido → Qualificação → Apresentação → Fechado Ganho / Perdido). 5️⃣ Para cada fase, configure os campos dinâmicos (CNPJ, Valor, Prioridade, etc.). 6️⃣ Marque quais fases são Ganho e Perdido nas Settings.\n\n## Link público [#link-público]\n\nSe a primeira fase for marcada como formulário público , um link será gerado. Compartilhe em sites, e-mails ou redes para receber leads sem login.\n\nVincule um canal WhatsApp ao board para criar cards automaticamente quando chegarem mensagens.\n"
},
{
"title": "Categorias de Produtos",
"description": "Guia de categorias de produtos no Perpetuus CRM.",
"url": "/docs/guia/produtos/categorias",
"path": "guia/produtos/categorias.mdx",
"markdown": "# Categorias de Produtos (/docs/guia/produtos/categorias)\n\n\n\n\n\nAs Categorias organizam o catálogo de produtos para facilitar a busca e a navegação em orçamentos.\n\n## Onde configurar [#onde-configurar]\n\nAcesse `Categorias` na página de Produtos ou vá para `/products/categories`.\n\n## Como usar [#como-usar]\n\n1️⃣ Crie categorias (ex: Eletrônicos, Serviços, Licenças). 2️⃣ Atribua cada produto a uma ou mais categorias. 3️⃣ Use as categorias para filtrar e agrupar no carrinho de cotações. As categorias ajudam a equipe a encontrar produtos rapidamente ao montar orçamentos nos cards.\n"
},
{
"title": "Criando um Novo Produto",
"description": "Guia de criando um novo produto no Perpetuus CRM.",
"url": "/docs/guia/produtos/criando-produto",
"path": "guia/produtos/criando-produto.mdx",
"markdown": "# Criando um Novo Produto (/docs/guia/produtos/criando-produto)\n\n\n\n\n\nO formulário de produto possui abas e campos que variam conforme o tipo selecionado.\n\n## Campos básicos [#campos-básicos]\n\n| Nome | Sim | Mín. 2 caracteres |\n| ----------------- | --- | -------------------------------- |\n| SKU | Sim | Código único (min. 2 caracteres) |\n| Tipo | Sim | Físico, Digital ou Serviço |\n| Preço | Sim | Valor ≥ 0 |\n| Preço promocional | Não | Preço de oferta |\n| Tipo de cobrança | - | Única ou Recorrente |\n| Imagem | Não | Foto principal |\n| Ativo | - | Disponível no catálogo |\n\n## Passo a passo [#passo-a-passo]\n\n1️⃣ Clique em `Novo Produto`. 2️⃣ Preencha Nome, SKU e escolha o Tipo. 3️⃣ Defina o Preço e (opcional) Preço promocional. 4️⃣ Complete as configurações específicas do tipo (Físico, Digital ou Serviço). 5️⃣ Salve o produto. ⚠️ Importante: O SKU deve ser único. Históricos de orçamentos passados não são afetados ao excluir um produto.\n"
},
{
"title": "Introdução ao Módulo de Produtos",
"description": "Guia de introdução ao módulo de produtos no Perpetuus CRM.",
"url": "/docs/guia/produtos/introducao-produtos",
"path": "guia/produtos/introducao-produtos.mdx",
"markdown": "# Introdução ao Módulo de Produtos (/docs/guia/produtos/introducao-produtos)\n\n\n\n\n\nO módulo de Produtos gerencia o catálogo de produtos e serviços da sua organização. Use-o para montar orçamentos e cotações nos cards dos boards.\n\n## Onde encontrar [#onde-encontrar]\n\nAcesse Produtos no menu lateral (ícone Pacote) ou vá direto para `/products`. Produtos Produtos Gerencie o catálogo de produtos e serviços. Categorias + Novo Produto\n\n| Img | Nome | SKU | Tipo | Preço | Status | Ações |\n| --- | ---- | --- | ---- | ----- | ------ | ----- |\n| — | — | — | — | — | — | — |\n\n## Colunas da listagem [#colunas-da-listagem]\n\n| Imagem | Foto do produto |\n| ------ | -------------------------- |\n| Nome | Nome do produto |\n| SKU | Código único |\n| Tipo | Físico, Digital ou Serviço |\n| Preço | Preço de venda |\n| Status | Ativo ou Inativo |\n\n## Passo a passo [#passo-a-passo]\n\n1️⃣ Acesse Produtos no menu principal. 2️⃣ Use `Novo Produto` para criar. 3️⃣ Use `Categorias` para organizar o catálogo. 4️⃣ Clique em Editar para alterar um produto existente.\n\nAtive o módulo de produtos nas Settings do board para usar o carrinho de cotações nos cards.\n"
},
{
"title": "Tipos de Produto",
"description": "Guia de tipos de produto no Perpetuus CRM.",
"url": "/docs/guia/produtos/tipos-produto",
"path": "guia/produtos/tipos-produto.mdx",
"markdown": "# Tipos de Produto (/docs/guia/produtos/tipos-produto)\n\n\n\n\n\nCada tipo de produto possui configurações específicas que aparecem no formulário.\n\n## Produto Físico [#produto-físico]\n\nPeso e dimensões (comprimento, largura, altura) Controle de estoque (ativar, quantidade, status: em estoque, esgotado, sob pedido) Permitir backorder\n\n## Produto Digital [#produto-digital]\n\nDownloadável (sim/não) Duração de acesso: vitalício, 12 meses, 6 meses, 3 meses, 1 mês ou customizado Dias de acesso (se customizado) Limite de downloads Arquivos para download\n\n## Produto Serviço [#produto-serviço]\n\nTipo de entrega: horas, sessões, projeto, ilimitado Unidades incluídas Preço por unidade Duração estimada\n\n## Cobrança Recorrente [#cobrança-recorrente]\n\nSe o tipo de cobrança for Recorrente, configure: intervalo (dia, semana, mês, ano), período de trial, períodos mínimo e máximo.\n\nEscolha o tipo correto desde o início — influencia o carrinho de cotações e os PDFs gerados.\n"
},
{
"title": "Uso em Orçamentos e Cotações",
"description": "Guia de uso em orçamentos e cotações no Perpetuus CRM.",
"url": "/docs/guia/produtos/uso-orcamentos",
"path": "guia/produtos/uso-orcamentos.mdx",
"markdown": "# Uso em Orçamentos e Cotações (/docs/guia/produtos/uso-orcamentos)\n\n\n\n\n\nOs produtos cadastrados aparecem no carrinho de cotações dentro dos cards do board, permitindo montar orçamentos e gerar PDFs.\n\n## Pré-requisitos [#pré-requisitos]\n\nMódulo de produtos ativado nas Settings do board Catálogo de produtos cadastrado\n\n## Onde usar [#onde-usar]\n\nNo modal do card ou no painel de dados do card (módulo Chats), abra a aba de Cotação (QuoteCartTab). Adicione produtos ao carrinho, ajuste quantidades e gere o PDF do orçamento.\n\n## Variáveis em PDF [#variáveis-em-pdf]\n\nTemplates de PDF podem usar variáveis dos produtos (nome, preço, quantidade, etc.) para montar orçamentos personalizados.\n\nConfigure os PDF Templates na aba PDF Templates do board e vincule aos templates de cotações.\n"
},
{
"title": "Criando um Novo Segmento",
"description": "Guia de criando um novo segmento no Perpetuus CRM.",
"url": "/docs/guia/segmentos/criando-segmento",
"path": "guia/segmentos/criando-segmento.mdx",
"markdown": "# Criando um Novo Segmento (/docs/guia/segmentos/criando-segmento)\n\n\n\n\n\nGuia passo a passo para criar um segmento, com nome, descrição e regras de filtragem.\n\n## Layout do formulário [#layout-do-formulário]\n\nNovo Segmento × Nome obrigatório, min. 3 caracteres Descrição opcional Regras de Filtragem \\[Categoria ▼] \\[Board ▼] \\[Campo ▼] \\[Op ▼] Valor \\[+ Add Filtro] \\[+ Add Grupo] Preview: 42 contatos Nome 1 │ Email 1 │ … Cancelar Salvar\n\n## Passo a passo numerado [#passo-a-passo-numerado]\n\n1️⃣ Clique em `Novo Segmento` (canto superior direito). 2️⃣ Preencha o Nome (obrigatório, mínimo 3 caracteres). 3️⃣ (Opcional) Preencha a Descrição para documentar o objetivo do segmento. 4️⃣ Configure as Regras de Filtragem (ao menos uma condição — veja próximo artigo). 5️⃣ Use o Preview para conferir se os contatos retornados estão corretos. 6️⃣ Clique em `Salvar`. ⚠️ Importante: Sem regras de filtragem, o segmento não terá contatos. Adicione ao menos uma condição.\n\nO preview atualiza em tempo real conforme você altera os filtros.\n"
},
{
"title": "Grupos Aninhados (AND/OR)",
"description": "Guia de grupos aninhados (and/or) no Perpetuus CRM.",
"url": "/docs/guia/segmentos/grupos-aninhados",
"path": "guia/segmentos/grupos-aninhados.mdx",
"markdown": "# Grupos Aninhados (AND/OR) (/docs/guia/segmentos/grupos-aninhados)\n\n\n\n\n\nPara critérios complexos, use grupos para combinar condições com lógicas diferentes.\n\n## Exemplo visual [#exemplo-visual]\n\nGRUPO 1 (E) E-mail contém @empresa.com Tag = VIP GRUPO 2 (E) Responsável = João Fase = Qualificado OR (entre grupos) Resultado: (empresa.com E VIP) OU (Responsável João E Qualificado)\n\n## Como criar grupos [#como-criar-grupos]\n\n1️⃣ Clique em `Add Grupo`. 2️⃣ Defina a lógica do grupo (E ou OU entre as condições internas). 3️⃣ Adicione filtros dentro do grupo. 4️⃣ A lógica entre grupos segue o AND/OR principal.\n\n## Boas práticas [#boas-práticas]\n\nUse grupos quando precisar misturar E e OU na mesma regra. Mantenha nomes curtos nos segmentos para fácil identificação. Teste sempre o preview após mudanças complexas.\n\nAtenção: Muitas condições encadeadas podem deixar o segmento lento. Priorize os critérios mais restritivos.\n"
},
{
"title": "Introdução ao Módulo de Segmentos",
"description": "Guia de introdução ao módulo de segmentos no Perpetuus CRM.",
"url": "/docs/guia/segmentos/introducao-segmentos",
"path": "guia/segmentos/introducao-segmentos.mdx",
"markdown": "# Introdução ao Módulo de Segmentos (/docs/guia/segmentos/introducao-segmentos)\n\n\n\n\n\nOs Segmentos são grupos dinâmicos de contatos baseados em critérios configuráveis. Use-os para campanhas, automações e segmentação da sua base.\n\n## Onde encontrar [#onde-encontrar]\n\nBoards Contatos Segmentos Config Segmentos Grupos dinâmicos de contatos. + Novo Segmento\n\n| Nome | Contatos | Status | Criado em | … |\n| ---- | -------- | ------ | --------- | - |\n| — | — | — | — | — |\n\n## Colunas da listagem [#colunas-da-listagem]\n\n| Nome | Nome do segmento |\n| --------- | ---------------------------------------------- |\n| Contatos | Quantidade de contatos que atendem aos filtros |\n| Status | Ativo / Inativo |\n| Criado em | Data de criação |\n| Ações | Editar, Excluir |\n\n## Passo a passo [#passo-a-passo]\n\n1️⃣ Acesse o menu lateral esquerdo. 2️⃣ Clique no item Segmentos (ícone alvo). 3️⃣ Você verá a listagem de todos os segmentos da sua organização. 4️⃣ Use o botão `Novo Segmento` (canto superior direito) para criar.\n\nSegmentos são dinâmicos — se um contato passar a atender os critérios, entra automaticamente no segmento.\n"
},
{
"title": "Preview ao Vivo e Uso em Campanhas",
"description": "Guia de preview ao vivo e uso em campanhas no Perpetuus CRM.",
"url": "/docs/guia/segmentos/preview-e-uso",
"path": "guia/segmentos/preview-e-uso.mdx",
"markdown": "# Preview ao Vivo e Uso em Campanhas (/docs/guia/segmentos/preview-e-uso)\n\n\n\n\n\nO preview mostra em tempo real quais contatos batem com os filtros. Na edição, use Recalcular Contagem para atualizar a contagem.\n\n## Preview ao vivo [#preview-ao-vivo]\n\nEnquanto você altera as regras de filtragem, a lista de contatos no preview é atualizada automaticamente. Assim você confere se o segmento está correto antes de salvar.\n\n## Passo a passo: Recalcular na edição [#passo-a-passo-recalcular-na-edição]\n\n1️⃣ Abra o segmento para edição (clique na linha da tabela ou no botão Editar). 2️⃣ Após alterar filtros, clique em `Recalcular Contagem`. 3️⃣ A contagem na listagem será atualizada.\n\n## Uso em Campanhas [#uso-em-campanhas]\n\nSegmentos são usados principalmente em: Campanhas: Ao criar ou editar uma campanha, escolha o segmento no seletor (ex: SegmentCombobox). Automações: Podem disparar ações para contatos de um segmento. Análises: Segmentar relatórios por grupo de contatos.\n\nComo segmentos são dinâmicos, uma campanha agendada usará sempre a contagem atual do segmento na hora da execução.\n"
},
{
"title": "Regras de Filtragem (Filter Builder)",
"description": "Guia de regras de filtragem (filter builder) no Perpetuus CRM.",
"url": "/docs/guia/segmentos/regras-filtragem",
"path": "guia/segmentos/regras-filtragem.mdx",
"markdown": "# Regras de Filtragem (Filter Builder) (/docs/guia/segmentos/regras-filtragem)\n\n\n\n\n\nO Filter Builder permite montar critérios para incluir contatos no segmento. Cada regra usa uma categoria, um campo e um operador.\n\n## Categorias disponíveis [#categorias-disponíveis]\n\n| Contato | Nome, E-mail, Telefone, CPF/CNPJ |\n| ------------------- | -------------------------------- |\n| Card (Propriedades) | Campos de um board específico |\n| Campo Personalizado | Custom fields dos contatos |\n| Responsável | Owner (dono do contato) |\n| Etiqueta (Tag) | Tags vinculadas ao contato |\n\n## Operadores por tipo [#operadores-por-tipo]\n\n| Texto | Igual a, Diferente de, Contém, Não contém, Começa com, Termina com, Vazio, Preenchido |\n| ------ | ------------------------------------------------------------------------------------- |\n| Número | Igual a, Diferente de, Maior que, Menor que |\n| Select | É, Não é, Está em, Não está em |\n| Data | Data exata, Depois de, Antes de, Entre |\n\n## Lógica entre condições [#lógica-entre-condições]\n\nUse E (AND) ou OU (OR) para combinar filtros: E: O contato deve atender todas as condições. OU: O contato deve atender pelo menos uma das condições.\n\n## Passo a passo: adicionar um filtro [#passo-a-passo-adicionar-um-filtro]\n\n1️⃣ Escolha a Categoria (ex: Contato). 2️⃣ Se for Card ou Campo de board, selecione o Board . 3️⃣ Escolha o Campo (ex: E-mail). 4️⃣ Selecione o Operador (ex: Contém). 5️⃣ Informe o Valor (ex: @empresa.com). 6️⃣ Clique em `Add Filtro` para mais condições ou `Add Grupo` para subgrupos.\n\nExemplo: E-mail contém `@gmail.com` E Tag = `Lead` → segmento de leads Gmail com tag Lead.\n"
},
{
"title": "Ações em Lote e Importação",
"description": "Guia de ações em lote e importação no Perpetuus CRM.",
"url": "/docs/guia/tarefas/acoes-lote-importacao",
"path": "guia/tarefas/acoes-lote-importacao.mdx",
"markdown": "# Ações em Lote e Importação (/docs/guia/tarefas/acoes-lote-importacao)\n\n\n\n\n\nNa visualização Lista, você pode selecionar várias tasks e executar ações em lote.\n\n## Seleção múltipla [#seleção-múltipla]\n\nUse o checkbox ao lado de cada linha para selecionar tasks. O checkbox no cabeçalho seleciona todas as linhas da página atual.\n\n## Ações em lote [#ações-em-lote]\n\nCom tasks selecionadas, as opções de ação em lote aparecem na barra inferior (ex: Excluir selecionadas).\n\n## Importação [#importação]\n\nO botão de importação permite carregar tasks em massa a partir de um arquivo. Siga o formato esperado (CSV ou similar) conforme indicado no diálogo.\n\nAtenção: A exclusão em lote não pode ser desfeita. Confirme antes de prosseguir.\n"
},
{
"title": "Criando e Editando uma Task",
"description": "Guia de criando e editando uma task no Perpetuus CRM.",
"url": "/docs/guia/tarefas/criando-editando-task",
"path": "guia/tarefas/criando-editando-task.mdx",
"markdown": "# Criando e Editando uma Task (/docs/guia/tarefas/criando-editando-task)\n\n\n\n\n\nO diálogo de adicionar/editar permite configurar todos os campos da tarefa.\n\n## Campos do formulário [#campos-do-formulário]\n\n| Nome | Sim | Título da tarefa (máx. 255 caracteres) |\n| ------------------ | --- | -------------------------------------------- |\n| Descrição | Não | Detalhes adicionais |\n| Data de Vencimento | Não | Quando a tarefa deve ser concluída |\n| Tipo | Sim | Reminder, Follow-up, Action, Other |\n| Status | Sim | Pendente, Em progresso, Concluída, Cancelada |\n| Board | Não | Board ao qual a task está relacionada |\n| Responsáveis | Não | Membros da equipe responsáveis |\n| Card | Não | Card vinculado (do board selecionado) |\n\n## Passo a passo [#passo-a-passo]\n\n1️⃣ Clique em `Add Task`. 2️⃣ Preencha o Nome (obrigatório). 3️⃣ Escolha Tipo e Status . 4️⃣ (Opcional) Defina vencimento, responsáveis, board e card. 5️⃣ Clique em Salvar.\n"
},
{
"title": "Introdução ao Módulo de Tasks",
"description": "Guia de introdução ao módulo de tasks no Perpetuus CRM.",
"url": "/docs/guia/tarefas/introducao-tasks",
"path": "guia/tarefas/introducao-tasks.mdx",
"markdown": "# Introdução ao Módulo de Tasks (/docs/guia/tarefas/introducao-tasks)\n\n\n\n\n\nO módulo de Tasks centraliza tarefas, lembretes e follow-ups da sua equipe. As tasks podem ser vinculadas a cards e boards, ou existir de forma independente.\n\n## Onde encontrar [#onde-encontrar]\n\nAgents Tasks Products Tasks Gerencie tarefas e lembretes. Lista Kanban + Add Task \\[Filtros: Board, Status, Tipo, Período...]\n\n| Nome | Tipo | Status | Vencimento | … |\n| ---- | ---- | ------ | ---------- | - |\n| — | — | — | — | — |\n\n## Visualizações [#visualizações]\n\nLista: Tabela com colunas, ordenação e seleção múltipla Kanban: Colunas por status (Pendente, Em progresso, Concluída, Cancelada)\n\n## Passo a passo [#passo-a-passo]\n\n1️⃣ Acesse Tasks no menu (ícone check-square). 2️⃣ Alternar entre Lista e Kanban com o toggle no topo. 3️⃣ Use `Add Task` para criar nova tarefa. 4️⃣ Use os filtros para encontrar tasks por board, status, tipo ou período.\n\nTasks vinculadas a cards aparecem também no painel do card no módulo Chats ou no modal do card no board.\n"
},
{
"title": "Lista e Filtros",
"description": "Guia de lista e filtros no Perpetuus CRM.",
"url": "/docs/guia/tarefas/lista-e-filtros",
"path": "guia/tarefas/lista-e-filtros.mdx",
"markdown": "# Lista e Filtros (/docs/guia/tarefas/lista-e-filtros)\n\n\n\n\n\nA visualização em lista permite filtrar e ordenar suas tarefas de forma rápida.\n\n## Colunas da tabela [#colunas-da-tabela]\n\n| Nome | Título da tarefa |\n| ------------ | -------------------------------------------- |\n| Tipo | Reminder, Follow-up, Action, Other |\n| Status | Pendente, Em progresso, Concluída, Cancelada |\n| Vencimento | Data e hora (edição rápida) |\n| Responsáveis | Quem deve executar |\n| Card | Card vinculado (se houver) |\n\n## Filtros disponíveis [#filtros-disponíveis]\n\n| Board | Board específico |\n| -------------- | --------------------------------------------- |\n| Status | Pendente, Em progresso, Concluída, Cancelada |\n| Tipo | Reminder, Follow-up, Action, Other |\n| Período | Atrasadas, Hoje, Esta semana, Este mês, Todas |\n| Minhas tarefas | Apenas onde sou responsável |\n\nUse \"Atrasadas\" para ver tasks com vencimento passado que ainda não foram concluídas.\n"
},
{
"title": "Visualização Kanban",
"description": "Guia de visualização kanban no Perpetuus CRM.",
"url": "/docs/guia/tarefas/visualizacao-kanban",
"path": "guia/tarefas/visualizacao-kanban.mdx",
"markdown": "# Visualização Kanban (/docs/guia/tarefas/visualizacao-kanban)\n\n\n\n\n\nA visualização Kanban agrupa as tasks por status em colunas, similar a um board.\n\n## Colunas [#colunas]\n\nPendente: Tasks aguardando início Em progresso: Tasks em andamento Concluída: Tasks finalizadas Cancelada: Tasks descartadas\n\n## Interação [#interação]\n\nClique em uma task para abrir o diálogo de edição Edição rápida: Altere data de vencimento e status diretamente no card Indicador de atraso: Tasks com vencimento passado são destacadas\n\n## Badges por tipo [#badges-por-tipo]\n\nCada task exibe um badge de tipo: Reminder (azul), Follow-up (roxo), Action (laranja), Other (cinza).\n\nA visualização Kanban é ideal para acompanhar o fluxo de trabalho visualmente.\n"
}
]
}