⭐Recomendado

Sync API

O endpoint /api/v1/integration/sync é a forma recomendada de integração. Permite criar/atualizar contato, lead, tags, interações e conversas em uma única requisição.

POST/api/v1/integration/syncsync:write

Sincronização unificada de dados

URLs da Integração

URL base da API

Text

https://dev-api-tools.helbioads.com

URL base da Integration API

Text

https://dev-api-tools.helbioads.com/api/v1/integration

Abrir Swagger

Como Funciona

1Você envia dados com um externalId (seu identificador único) ou protocol (do Magic Link)
2Se protocol fornecido: busca lead existente pelo protocolo. Senão, busca/cria contato por externalId, email, phone ou cpf
3O sistema busca ou cria o lead vinculado ao contato
4Tags são criadas (se não existirem) e vinculadas ao lead
5Interações e conversas são registradas no histórico
6Você recebe todos os dados criados/atualizados na resposta

Exemplo Rápido

Bash

curl -X POST "https://dev-api-tools.helbioads.com/api/v1/integration/sync" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "conversa_123",
    "contact": {
      "name": "João Silva",
      "email": "joao@email.com",
      "phone": "+5511999999999"
    },
    "tags": ["interessado", "premium"]
  }'

Vinculação por Protocolo (Magic Link)

Quando um usuário acessa um Magic Link, ele recebe um protocolo único (ex: ML-20251030-143052-A8F3D-META) que é incluído na mensagem enviada ao WhatsApp. Seu integrador pode extrair este protocolo e enviá-lo no campo protocol para vincular os dados ao lead existente.

Comportamento

protocol	externalId	Resultado
Válido e encontrado	Qualquer	Vincula ao lead existente, atualiza dados.`protocolLink` na resposta
Válido mas NÃO encontrado	Fornecido	Cria novo lead usando externalId (fluxo normal)
Válido mas NÃO encontrado	NÃO fornecido	Erro 400 - externalId obrigatório
NÃO fornecido	Fornecido	Fluxo normal (cria/atualiza por externalId)

Formatos de Protocolo

Formato	Exemplo
FULL	`ML-20251030-143052-A8F3D-META`
DATE_HASH	`ML-20251030-A8F3D-META`
SHORT	`ML-A8F3D-META`
TIMESTAMP	`ML-1730303452-META`

Exemplo com Protocolo

Vinculando dados de conversa a um lead existente via protocolo do Magic Link:

Bash

curl -X POST "https://dev-api-tools.helbioads.com/api/v1/integration/sync" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "ML-20251030-143052-A8F3D-META",
    "contact": {
      "name": "João Silva",
      "email": "joao@email.com"
    },
    "lead": {
      "status": "in_progress"
    },
    "conversation": {
      "channel": "WHATSAPP",
      "messages": [
        {
          "direction": "INBOUND",
          "content": "Olá, meu protocolo é ML-20251030-143052-A8F3D-META"
        }
      ]
    }
  }'

Resposta com Vinculação

Quando vinculado via protocolo, a resposta inclui o campo protocolLink:

JSON

{
  "success": true,
  "data": {
    "contact": {
      "id": "clx123abc...",
      "name": "João Silva",
      "email": "joao@email.com"
    },
    "lead": {
      "id": "clx456def...",
      "uuid": "a1b2c3d4-...",
      "status": "in_progress"
    },
    "protocolLink": {
      "linked": true,
      "protocol": "ML-20251030-143052-A8F3D-META",
      "magicLinkCaptureId": "clx789ghi...",
      "magicLinkId": 42,
      "magicLinkName": "Landing Page Produto X",
      "capturedAt": "2025-10-30T14:30:52.000Z",
      "source": "magic_link"
    }
  }
}

Buscar por Protocolo

Você também pode buscar dados completos de um lead pelo protocolo:

GET/api/v1/integration/sync/protocol/{protocol}sync:read

Buscar dados por protocolo do Magic Link

Bash

curl -X GET "https://dev-api-tools.helbioads.com/api/v1/integration/sync/protocol/ML-20251030-143052-A8F3D-META" \
  -H "Authorization: Bearer YOUR_API_KEY"

Protocolo nos Endpoints Individuais

Além do /sync, você também pode usar o campoprotocol nos endpoints individuaisPOST /leads ePOST /contacts. O comportamento é o mesmo: se o protocolo for encontrado, vincula ao registro existente; caso contrário, usa o externalId como fallback.

Exemplo: Lead com Protocolo

Bash

curl -X POST "https://dev-api-tools.helbioads.com/api/v1/integration/leads" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "ML-20251030-143052-A8F3D-META",
    "contact": {
      "name": "João Silva",
      "phone": "+5511999999999"
    },
    "status": "in_progress",
    "priority": "high",
    "notes": "Veio do WhatsApp com protocolo do Magic Link"
  }'

Exemplo: Contato com Protocolo

Bash

curl -X POST "https://dev-api-tools.helbioads.com/api/v1/integration/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "ML-20251030-143052-A8F3D-META",
    "name": "João Silva",
    "email": "joao@empresa.com",
    "phone": "+5511999999999"
  }'

Exemplo: Protocolo + externalId (Fallback)

Recomendado enviar ambos para garantir que o registro será criado mesmo se o protocolo não for encontrado:

Bash

curl -X POST "https://dev-api-tools.helbioads.com/api/v1/integration/leads" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "ML-20251030-A8F3D-META",
    "externalId": "whatsapp_789",
    "contact": {
      "name": "Maria Santos",
      "email": "maria@email.com"
    },
    "status": "open",
    "source": "whatsapp"
  }'

Parâmetros do Sync

Campo	Tipo	Descricao
`createContactIfNotFound`	boolean	Quando false, nao cria contato novo se nao encontrar referencia por protocol/externalId/email/phone. Retorna 404. Ex: `false`
`protocol`	string	Protocolo do Magic Link para vincular a lead existente. Quando fornecido e encontrado, vincula os dados ao lead criado pelo Magic Link ao invés de criar um novo. Ex: `ML-20251030-143052-A8F3D-META`
`externalId`obrigatório	string	Seu identificador único para esta conversa/lead. Obrigatório se protocol não for fornecido ou não encontrado. Ex: `chat_conversation_12345`
`action`	enum	Ação a executar: upsert (padrão), update, delete Ex: `upsert`
`contact`		Dados do contato associado ao lead
`lead`		Dados específicos do lead (oportunidade)
`tags`		Tags como strings (só nome) ou objetos completos com todos os campos. Cria tags se não existirem. Ex: `["interessado", {"name": "vip", "color": "#ff0000"}]`
`interactions`		Lista de interações a registrar no histórico do lead
`conversation`		Criar/atualizar conversa com mensagens
`metadata`	object	Dados extras para armazenar (não afeta comportamento) Ex: `{"channel": "whatsapp"}`

Campos do Contact

O objeto contact representa uma pessoa ou empresa. É usado para deduplicação: se já existir um contato com mesmo email, phone ou cpf, ele será atualizado.

Campo	Tipo	Descricao
`name`	string	Nome completo do contato Ex: `João Silva`
`email`	string	Email principal (usado para deduplicação) Ex: `joao@empresa.com`
`phone`	string	Telefone principal. Formato internacional recomendado Ex: `+5511999999999`
`mobilePhone`	string	Celular (quando diferente do principal)
`cpf`	string	CPF do contato (aceita com ou sem formatação) Ex: `123.456.789-00`
`cnpj`	string	CNPJ (pessoa jurídica) Ex: `12.345.678/0001-00`
`company`	string	Nome da empresa Ex: `Empresa ABC Ltda`
`jobTitle`	string	Cargo ou função Ex: `Gerente de Marketing`
`website`	string	Website pessoal ou da empresa
`address`	string	Endereço completo
`city`	string	Cidade Ex: `São Paulo`
`state`	string	Estado Ex: `SP`
`country`	string	País Ex: `Brasil`
`zipCode`	string	CEP Ex: `01310-100`
`customFields`	object	Campos customizados (qualquer estrutura JSON)

Campos do Lead

O objeto lead representa uma oportunidade de negócio. Um contato pode ter múltiplos leads.

Campo	Tipo	Descricao
`status`	enum	Status no funil Ex: `in_progress`
`priority`	enum	Prioridade Ex: `high`
`source`	enum	Origem do lead Ex: `chat`
`estimatedValue`	number	Valor estimado da oportunidade (BRL) Ex: `5000`
`saleDate`	string (ISO 8601)	Data/hora em que a venda ocorreu. Quando informada, é usada como timestamp nas conversões offline enviadas ao Google Ads e Meta Ads. Se omitida, usa a data de criação do lead. Ex: `2026-05-14T11:00:00.000Z`
`notes`	string	Notas e observações sobre o lead

Status do Lead

Valor	Descrição	Cor
`open`	Novo lead, ainda não trabalhado	Azul
`in_progress`	Lead em negociação ativa	Amarelo
`waiting`	Aguardando resposta/ação do cliente	Laranja
`closed_won`	Venda concluída com sucesso	Verde
`closed_lost`	Lead perdido/desqualificado	Vermelho

Prioridade do Lead

Valor	Descrição	SLA Resposta
`low`	Baixa prioridade	48-72 horas
`medium`	Prioridade normal	24-48 horas
`high`	Alta prioridade	4-24 horas
`urgent`	Urgente	Imediato (<4 horas)

Origem do Lead (source)

formmagic_linkapiimportmanualchatwhatsappphoneemailsocialreferralother

Campos da Tag

Tags podem ser enviadas como strings simples ["tag1", "tag2"] ou como objetos com todos os campos. Se a tag não existir, será criada automaticamente.

Campo	Tipo	Descricao
`name`obrigatório	string	Nome da tag Ex: `lead-qualificado`
`description`	string	Descrição detalhada
`color`	string	Cor hexadecimal Ex: `#10b981`
`orderNumber`	integer	Ordem de exibição (0+)
`kanban`	integer	Coluna do kanban (1-5)
`eventName`	string	Nome do evento para tracking
`categoryConversion`	string	Categoria de conversão
`isConversion`	boolean	Se é evento de conversão
`sendToMarketingPlatform`	boolean	Enviar para Meta/Google Ads

Categoria de Conversão

Usado para tracking de conversões em plataformas como Meta Ads e Google Ads.

Valor	Descrição
`DEFAULT`	Categoria padrão
`PURCHASE`	Compra realizada
`SIGNUP`	Cadastro/registro
`LEAD`	Lead qualificado
`PAGE_VIEW`	Visualização de página
`ADD_TO_CART`	Adição ao carrinho
`BEGIN_CHECKOUT`	Início de checkout
`SUBSCRIBE`	Assinatura
`CONTACT`	Contato realizado
`DOWNLOAD`	Download
`SUBMIT_FORM`	Envio de formulário
`BOOK_APPOINTMENT`	Agendamento
`REQUEST_QUOTE`	Solicitação de orçamento
`OTHER`	Outro

Interações

A propriedade interactions permite registrar eventos (ligações, notas, reuniões) diretamente no sync. Cada item é adicionado ao histórico do lead.

Campo	Tipo	Descricao
`type`obrigatório	enum	Tipo da interação Ex: `NOTE`
`title`	string	Título da interação Ex: `Contato realizado`
`description`	string	Descrição detalhada da interação
`metadata`	object	Metadados adicionais em JSON Ex: `{"duration": 300}`
`isInternal`	boolean	Se true, não visível para integradores externos

Tipos de Interação

Tipo	Descrição	Ícone
`NOTE`	Nota ou observação	📝
`CALL`	Ligação realizada/recebida	📞
`EMAIL`	Email enviado/recebido	📧
`MEETING`	Reunião agendada/realizada	📅
`COMMENT`	Comentário interno	💬
`TASK_CREATED`	Tarefa criada	📋
`TASK_COMPLETED`	Tarefa concluída	✅
`CUSTOM`	Tipo personalizado	🔧

Conversas e Mensagens

A propriedade conversation permite criar ou atualizar uma conversa com mensagens. Útil para integrar chatbots, WhatsApp e sistemas de atendimento.

Campos da Conversa

Campo	Tipo	Descricao
`channel`obrigatório	enum	Canal: WHATSAPP, EMAIL, CHAT, PHONE, SMS, FACEBOOK, INSTAGRAM, TELEGRAM, etc Ex: `WHATSAPP`
`externalId`	string	ID externo da conversa para deduplicação
`subject`	string	Assunto ou título da conversa
`messages`		Lista de mensagens (máx 100 por request)

Campos da Mensagem

Campo	Tipo	Descricao
`direction`obrigatório	enum	INBOUND (recebida), OUTBOUND (enviada) Ex: `INBOUND`
`type`	enum	Tipo: TEXT, IMAGE, AUDIO, VIDEO, FILE, etc Ex: `TEXT`
`content`obrigatório	string	Conteúdo da mensagem
`externalId`	string	ID da mensagem no seu sistema (deduplicação)
`metadata`	object	Metadados: mediaUrl, mimeType, fileSize, etc

Tipos de Mensagem

TEXTIMAGEAUDIOVIDEOFILELOCATIONTEMPLATEINTERACTIVESYSTEMNOTE

Exemplo: Venda Fechada

Use saleDate para registrar a data exata da venda. Esse valor é usado como timestamp nas conversões offline enviadas ao Google Ads e Meta Ads.

Bash

curl -X POST "https://dev-api-tools.helbioads.com/api/v1/integration/sync" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "venda_456",
    "contact": {
      "name": "Carlos Mendes",
      "phone": "+5511999999999"
    },
    "lead": {
      "status": "closed_won",
      "estimatedValue": 5000,
      "saleDate": "2026-05-14T11:00:00.000Z"
    },
    "tags": ["venda-fechada"]
  }'

Sincronizar sem criar contato novo

Esse modo e util quando o integrador so deve atualizar registros previamente conhecidos. Se o contato nao existir, a resposta sera 404 Contato nao encontrado para as referencias informadas.

Bash

curl -X POST "https://dev-api-tools.helbioads.com/api/v1/integration/sync" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "chat_conversation_12345",
    "createContactIfNotFound": false,
    "contact": {
      "phone": "+5511999999999"
    },
    "lead": {
      "status": "in_progress"
    }
  }'

Exemplo Completo

Exemplo com contato, lead, tags, interação e conversa em uma única requisição:

JSON

{
  "externalId": "chatbot_ticket_101",
  "action": "upsert",
  "contact": {
    "name": "Maria Santos",
    "email": "maria@empresa.com",
    "phone": "+5511988888888",
    "company": "Empresa ABC",
    "jobTitle": "Gerente de Marketing",
    "city": "São Paulo",
    "state": "SP",
    "customFields": {
      "segmento": "varejo",
      "cnae": "4761-0"
    }
  },
  "lead": {
    "status": "in_progress",
    "priority": "high",
    "source": "chat",
    "estimatedValue": 15000,
    "notes": "Cliente interessado em plano enterprise"
  },
  "tags": [
    "lead-qualificado",
    {
      "name": "enterprise",
      "color": "#8B5CF6",
      "isConversion": true,
      "categoryConversion": "LEAD"
    }
  ],
  "interactions": [
    {
      "type": "CALL",
      "title": "Ligação de qualificação",
      "description": "Conversamos sobre necessidades do cliente",
      "metadata": { "duration": 900 }
    }
  ],
  "conversation": {
    "channel": "WHATSAPP",
    "externalId": "whatsapp_5511988888888",
    "messages": [
      {
        "direction": "INBOUND",
        "content": "Olá! Gostaria de saber mais sobre o plano enterprise",
        "externalId": "msg_001"
      },
      {
        "direction": "OUTBOUND",
        "content": "Olá Maria! Claro, vou te explicar os benefícios...",
        "externalId": "msg_002"
      }
    ]
  },
  "metadata": {
    "source": "chatbot",
    "campaignId": "camp_abc123"
  }
}

Resposta de Sucesso

JSON

{
  "success": true,
  "message": "Sync completed successfully",
  "data": {
    "contact": {
      "id": "clx123abc...",
      "externalId": "chatbot_ticket_101",
      "name": "Maria Santos",
      "email": "maria@empresa.com",
      "phone": "+5511988888888"
    },
    "lead": {
      "id": "clx456def...",
      "status": "in_progress",
      "priority": "high",
      "tags": ["lead-qualificado", "enterprise"]
    },
    "tags": {
      "created": 1,
      "linked": 2
    },
    "interactions": {
      "created": 1
    },
    "conversation": {
      "id": "clx789ghi...",
      "messagesCreated": 2
    }
  }
}

Próximos Passos

Configurar Webhooks

Receba notificações em tempo real

Endpoints de Leads

CRUD completo para leads