Tags API

Endpoints para listar e criar tags. Tags são usadas para classificar leads e podem disparar eventos de conversão para plataformas de marketing.

GET/api/v1/integration/tagstags:read

Listar todas as tags do cliente

Exemplo

Bash

curl "https://dev-api-tools.helbioads.com/api/v1/integration/tags" \
  -H "Authorization: Bearer YOUR_API_KEY"

Resposta

JSON

{
  "success": true,
  "data": {
    "tags": [
      {
        "id": "clx123...",
        "name": "lead-qualificado",
        "description": "Lead pronto para contato comercial",
        "color": "#10b981",
        "orderNumber": 1,
        "kanban": 2,
        "isConversion": true,
        "categoryConversion": "LEAD",
        "sendToMarketingPlatform": true,
        "leadsCount": 45
      },
      {
        "id": "clx456...",
        "name": "cliente",
        "description": "Convertido em cliente",
        "color": "#3b82f6",
        "orderNumber": 2,
        "kanban": 5,
        "isConversion": true,
        "categoryConversion": "PURCHASE",
        "sendToMarketingPlatform": true,
        "leadsCount": 12
      }
    ]
  }
}

POST/api/v1/integration/tagstags:write

Criar nova tag

Body Parameters

Campo	Tipo	Descricao
`name`obrigatório	string	Nome da tag (único) Ex: `vip`
`description`	string	Descrição detalhada
`color`	string	Cor em hexadecimal Ex: `#8b5cf6`
`orderNumber`	number	Ordem de exibição (0+)
`kanban`	number	Coluna no Kanban (1-5)
`isConversion`	boolean	É evento de conversão?
`categoryConversion`	enum	Categoria: PURCHASE, LEAD, SIGNUP, etc
`eventName`	string	Nome do evento para tracking
`sendToMarketingPlatform`	boolean	Enviar para Meta/Google Ads

Bash

curl -X POST "https://dev-api-tools.helbioads.com/api/v1/integration/tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "cliente-vip",
    "description": "Clientes com alto ticket",
    "color": "#f59e0b",
    "kanban": 5,
    "isConversion": true,
    "categoryConversion": "PURCHASE",
    "sendToMarketingPlatform": true
  }'

Categorias de Conversão

As categorias de conversão são usadas para enviar eventos corretos para Meta Ads e Google Ads.

Valor	Descrição	Uso
`PURCHASE`	Compra realizada	E-commerce, vendas
`LEAD`	Lead qualificado	B2B, serviços
`SIGNUP`	Cadastro/registro	SaaS, apps
`CONTACT`	Contato realizado	Qualquer negócio
`ADD_TO_CART`	Adição ao carrinho	E-commerce
`BEGIN_CHECKOUT`	Início de checkout	E-commerce
`SUBSCRIBE`	Assinatura	Recorrência
`BOOK_APPOINTMENT`	Agendamento	Serviços
`REQUEST_QUOTE`	Solicitação de orçamento	B2B
`DOWNLOAD`	Download	Conteúdo, apps
`OTHER`	Outro	Customizado

Colunas do Kanban

O campo kanban define em qual coluna do quadro Kanban o lead aparecerá quando tiver esta tag.

Novo

Contato

Negociação

Proposta

Fechado