Documentação API PlugSend - Integração com Lovable

Documentação Oficial

Integração API WhatsApp
com Lovable

Guia completo para integrar a API PlugSend em seus projetos no Lovable, seguindo boas práticas de segurança e desenvolvimento.

Começar Agora

Índice

01 Informações da API 02 Boas Práticas de Segurança 03 Prompt: Sistema Kanban (Novo) 04 Integrar em Sistema Existente 05 Código de Referência 06 Solução de Problemas 07 Suporte

Informações da API

Endpoint Principal

POST https://plugsend.uazapi.com/send/text

Headers Obrigatórios

Header Valor
Content-Type application/json
token SEU_TOKEN_API

Body da Requisição (JSON)

{
  "number": "+5511999998888",
  "text": "Sua mensagem aqui",
  "linkPreview": true
}

Parâmetros

Campo Tipo Obrigatório Descrição
number string ✓ Sim Número com código do país (ex: +5511999998888)
text string ✓ Sim Mensagem a ser enviada
linkPreview boolean ✗ Não Exibir preview de links (padrão: true)

Exemplo com cURL

curl -X POST https://plugsend.uazapi.com/send/text \
  -H "Content-Type: application/json" \
  -H "token: SEU_TOKEN_AQUI" \
  -d '{
    "number": "+5511999998888",
    "text": "Olá! Esta é uma mensagem de teste.",
    "linkPreview": true
  }'

Boas Práticas de Segurança

⚠️ IMPORTANTE - Leia antes de começar

✗ Nunca exponha o Token da API no código fonte ou frontend

✗ Nunca salve credenciais em localStorage, sessionStorage ou cookies

✗ Nunca versione credenciais em repositórios Git (mesmo privados)

✗ Nunca compartilhe seu Token com terceiros

✓ Recomendações para Produção

Ambiente Recomendação
Desenvolvimento/Demo Pode usar chamada direta do front-end para testes rápidos (não versionado)
Produção SEMPRE criar um backend intermediário para proteger o Token

Onde Armazenar Credenciais com Segurança

RECOMENDADO

Variáveis de Ambiente (.env)

Armazene no backend usando arquivos .env (não versionados no Git)

RECOMENDADO

Supabase Edge Functions / Secrets

Use Supabase Secrets para armazenar e Edge Functions para consumir

RECOMENDADO

Serviços de Secrets (AWS, GCP, Azure)

AWS Secrets Manager, Google Secret Manager, Azure Key Vault

DEMO APENAS

Interface de Configuração (Temporário)

Aceitável apenas para demonstrações locais, nunca em produção ou código versionado

Arquitetura Recomendada para Produção

Frontend

(Lovable)

Seu Backend

(Token em .env)

API PlugSend

(WhatsApp)

Prompt Pronto • Criar sistema do zero

Sistema Kanban com Disparo Automático via WhatsApp

Atenção: Este é um exemplo de prompt para DEMONSTRAÇÃO da API. Para projetos em produção, implemente um backend para proteger seu Token usando variáveis de ambiente.

Copie o prompt abaixo e cole diretamente no Lovable para criar um sistema Kanban funcional com integração WhatsApp:

Crie um sistema KANBAN simples para DEMONSTRAÇÃO de integração com API WhatsApp.
Objetivo: Mostrar ao cliente como funciona o envio automático de mensagens ao mover cards.

⚠️ AVISO DE SEGURANÇA (exibir no rodapé da aplicação):
Este é um ambiente de DEMONSTRAÇÃO.
- Em produção, NUNCA exponha credenciais no frontend
- Use variáveis de ambiente (.env) no backend
- Nunca versione credenciais em repositórios Git
- Implemente um backend intermediário para chamadas à API

=== ESTRUTURA DO SISTEMA ===

TELA PRINCIPAL - KANBAN:
- 4 colunas fixas: "Novo Lead", "Em Contato", "Negociação", "Fechado"
- Cards dos contatos cadastrados aparecem aqui
- Arrastar card entre colunas
- Ao mover para "Fechado" (ou outra coluna configurada) → dispara mensagem WhatsApp

TELA DE CONFIGURAÇÕES:

A) Configuração da API (apenas para demo):
   - Campo: Token da API (com máscara tipo senha)
   - Campo: Código do País (padrão: +55)
   - Aviso: "⚠️ Em produção, use variáveis de ambiente no backend"
   - Botão salvar (temporário para demo)

B) Cadastro de Contatos (podem ser vários):
   - Campo: Nome do contato
   - Campo: Telefone (WhatsApp)
   - Botão adicionar
   - Lista dos contatos cadastrados com opção de excluir
   - Estes contatos viram cards no Kanban

C) Templates de Mensagem:
   - Selecionar qual coluna dispara mensagem
   - Campo para escrever o template (usar {nome} como placeholder)
   - Exemplo: "Olá {nome}! Parabéns, seu processo foi finalizado! 🎉"

=== ARMAZENAMENTO ===

Para DEMO: localStorage (apenas contatos e templates)
Para PRODUÇÃO: Supabase ou backend próprio (credenciais em variáveis de ambiente)

=== INTEGRAÇÃO API ===

Endpoint: POST https://plugsend.uazapi.com/send/text

Headers:
- Content-Type: application/json
- token: {TOKEN_API}

Body:
{
  "number": "NUMERO_COM_CODIGO_PAIS",
  "text": "MENSAGEM",
  "linkPreview": true
}

=== NORMALIZAÇÃO DO TELEFONE ===

Função obrigatória antes de enviar:
1. Remover caracteres especiais (espaços, hífens, parênteses)
2. Manter apenas números
3. Remover zeros à esquerda
4. Adicionar código do país (ex: +55) no início

Exemplos (com código +55):
- (11) 99999-8888 → +5511999998888
- 11999998888 → +5511999998888
- 011999998888 → +5511999998888

=== INTERFACE ===

- Design limpo e moderno
- Notificação ao enviar mensagem (sucesso/erro)
- Visual intuitivo para demonstração ao cliente
- Indicador de quais colunas enviam mensagem (ícone de WhatsApp)
- Exibir aviso de segurança no rodapé sobre proteção do Token

=== FLUXO DE USO ===

1. Usuário acessa Configurações
2. Cadastra Token da API e código do país (demo)
3. Adiciona contatos (nome + telefone)
4. Define qual coluna dispara mensagem e o template
5. Volta ao Kanban
6. Cards dos contatos aparecem na primeira coluna
7. Ao arrastar para coluna configurada → mensagem enviada automaticamente
Prompt de Alteração • Para sistemas já criados

Integrar WhatsApp em Sistema Existente

Quando usar: Você já tem um sistema criado no Lovable (CRM, agendamento, e-commerce, etc.) e quer adicionar disparo de WhatsApp em ações específicas do seu sistema.

Use este prompt base para solicitar ao Lovable que adicione a integração WhatsApp no seu sistema existente. Adapte os campos em [COLCHETES] conforme seu sistema:

Prompt Base (Copiar e Adaptar) 

Preciso adicionar integração com WhatsApp no meu sistema existente.

=== ONDE ADICIONAR O DISPARO ===

Adicionar envio de mensagem WhatsApp quando: [DESCREVA A AÇÃO/GATILHO]
Exemplo: "quando um pedido for marcado como 'Enviado'" ou "quando um agendamento for confirmado"

=== DADOS DISPONÍVEIS NO SISTEMA ===

O sistema já possui estes dados que podem ser usados na mensagem:
- [CAMPO 1]: ex: nome do cliente
- [CAMPO 2]: ex: telefone do cliente  
- [CAMPO 3]: ex: número do pedido
- [CAMPO 4]: ex: data do agendamento
(liste os campos relevantes do seu sistema)

=== SEGURANÇA DAS CREDENCIAIS ===

⚠️ IMPORTANTE: O Token da API deve ser protegido:

Para DEMONSTRAÇÃO apenas:
- Criar tela de configuração com campo Token da API e Código do País
- Exibir aviso: "Apenas para testes. Em produção, use variáveis de ambiente"

Para PRODUÇÃO (implementar uma das opções):
- OPÇÃO 1: Supabase Edge Function com credenciais em Supabase Secrets
- OPÇÃO 2: API Route própria (Next.js/Vercel) com credenciais em .env
- OPÇÃO 3: Backend intermediário com variáveis de ambiente

O frontend NUNCA deve ter acesso direto às credenciais em produção.

=== CONFIGURAÇÃO DA API ===

Criar seção de configurações com:
- Campo para Token da API com máscara de senha (apenas demo)
- Campo para Código do País (padrão: +55)
- Campo para template da mensagem com placeholders: {nome}, {pedido}, etc.
- Botão de teste para validar conexão
- Aviso visual sobre segurança em produção

=== ESPECIFICAÇÃO TÉCNICA DA API ===

Endpoint: POST https://plugsend.uazapi.com/send/text

Headers:
- Content-Type: application/json
- token: {TOKEN_API}

Body:
{
  "number": "TELEFONE_COM_CODIGO_PAIS",
  "text": "MENSAGEM_COM_PLACEHOLDERS_SUBSTITUIDOS",
  "linkPreview": true
}

=== NORMALIZAÇÃO DO TELEFONE (OBRIGATÓRIO) ===

Antes de enviar, criar função que:
1. Remove caracteres especiais (espaços, hífens, parênteses, pontos)
2. Mantém apenas números
3. Remove zeros à esquerda
4. Adiciona o código do país (ex: +55) no início

Exemplos de conversão (código +55):
- (11) 99999-8888 → +5511999998888
- 11999998888 → +5511999998888
- +55 11 99999-8888 → +5511999998888
- 011999998888 → +5511999998888

=== COMPORTAMENTO ESPERADO ===

1. Quando a ação [GATILHO] ocorrer:
   - Verificar se API está configurada
   - Normalizar telefone do cliente
   - Substituir placeholders no template pelos dados reais
   - Fazer chamada POST para API
   - Exibir notificação de sucesso ou erro

2. Tratamento de erros:
   - API não configurada → avisar usuário para configurar
   - Telefone inválido → mostrar erro específico
   - Falha na API → mostrar mensagem de erro retornada

=== INTERFACE ===

- Ícone de WhatsApp verde ao lado do botão/ação que dispara mensagem
- Toast/notificação ao enviar (sucesso verde / erro vermelho)
- Loading enquanto envia
- Na tela de configurações: botão "Testar Conexão"

Exemplos Prontos por Tipo de Sistema

Clique para expandir e copiar o exemplo que mais se parece com seu sistema:

🔐 Segurança das Credenciais - LEIA ANTES DE IMPLEMENTAR

❌ O QUE NUNCA FAZER

  • ✗ Salvar Token em localStorage/sessionStorage - Qualquer pessoa pode acessar via DevTools
  • ✗ Hardcode no código fonte - Será exposto no bundle JS público
  • ✗ Commit no Git - Mesmo deletando depois, fica no histórico
  • ✗ Variáveis VITE_* ou NEXT_PUBLIC_* - São expostas no frontend

✅ O QUE FAZER EM PRODUÇÃO

  • ✓ Supabase Edge Functions + Secrets - Credenciais ficam no servidor, nunca no cliente
  • ✓ API Routes (Next.js/Vercel) - Arquivo .env no servidor, API route como proxy
  • ✓ Backend próprio (Node, Python, PHP, etc) - Variáveis de ambiente no servidor
  • ✓ Serviços de Secrets (AWS, GCP, Azure) - Para infraestruturas maiores

⚠️ APENAS PARA DEMONSTRAÇÃO

A tela de configuração com campo de Token é aceitável apenas para:

  • • Demonstrações locais para clientes
  • • Testes rápidos de integração
  • • Ambiente de desenvolvimento pessoal

Nunca use em produção ou em código que será versionado/publicado.

Dicas para Adaptar ao Seu Sistema

  • → Liste todos os campos/dados que seu sistema já possui e que podem ser usados na mensagem
  • → Identifique os momentos/ações em que faz sentido disparar uma mensagem
  • → Use placeholders como {nome}, {telefone}, {pedido} para indicar dados dinâmicos
  • → Descreva onde na interface você quer que apareçam os controles (botões, ícones, configurações)
  • → Se seu sistema usa Supabase, peça para criar uma Edge Function para proteger as credenciais
  • → Mencione que precisa de aviso de segurança visível na interface sobre proteção de credenciais

Código de Referência

Caso precise implementar manualmente, aqui estão as funções essenciais:

Função de Normalização do Telefone

/**
 * Normaliza número de telefone para formato internacional
 * @param {string} phone - Número de telefone em qualquer formato
 * @param {string} countryCode - Código do país (ex: '+55')
 * @returns {object} - { success: boolean, number?: string, error?: string }
 */
function normalizePhoneNumber(phone, countryCode = '+55') {
  if (!phone) {
    return { success: false, error: 'Número não informado' };
  }
  
  // Remove tudo que não é número
  let normalized = phone.replace(/\D/g, '');
  
  if (!normalized) {
    return { success: false, error: 'Número inválido' };
  }
  
  // Remove zeros à esquerda
  normalized = normalized.replace(/^0+/, '');
  
  // Remove código do país se já existir (55 para Brasil)
  const countryDigits = countryCode.replace(/\D/g, '');
  if (normalized.startsWith(countryDigits)) {
    normalized = normalized.substring(countryDigits.length);
  }
  
  // Valida tamanho (DDD + 8 ou 9 dígitos)
  if (normalized.length < 10 || normalized.length > 11) {
    return { 
      success: false, 
      error: 'Número deve conter DDD + 8 ou 9 dígitos' 
    };
  }
  
  // Adiciona código do país
  return { success: true, number: countryCode + normalized };
}

Função de Envio de Mensagem

⚠️ Em produção, esta função deve estar no BACKEND, não no frontend.

/**
 * Envia mensagem via API WhatsApp PlugSend
 * ⚠️ ATENÇÃO: Em produção, mova esta função para o backend
 * e use variáveis de ambiente para as credenciais
 */
async function sendWhatsAppMessage(token, phone, message, countryCode = '+55') {
  // Normaliza o telefone
  const phoneResult = normalizePhoneNumber(phone, countryCode);
  
  if (!phoneResult.success) {
    return { success: false, error: phoneResult.error };
  }
  
  try {
    const response = await fetch(
      'https://plugsend.uazapi.com/send/text',
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'token': token
        },
        body: JSON.stringify({
          number: phoneResult.number,
          text: message,
          linkPreview: true
        })
      }
    );
    
    const data = await response.json();
    
    if (response.ok) {
      return { success: true, data };
    } else {
      return { success: false, error: data.message || 'Erro no envio' };
    }
    
  } catch (error) {
    return { success: false, error: 'Erro de conexão: ' + error.message };
  }
}

Exemplo em PHP (Backend)

<?php
// Exemplo de envio via PHP (use em backend)

function enviarWhatsApp($token, $telefone, $mensagem, $codigoPais = '+55') {
    // Normaliza o telefone
    $telefone = preg_replace('/\D/', '', $telefone);
    $telefone = ltrim($telefone, '0');
    $telefone = $codigoPais . $telefone;

    $data = array(
        'number' => $telefone,
        'text' => $mensagem,
        'linkPreview' => true
    );

    $response = wp_remote_post('https://plugsend.uazapi.com/send/text', array(
        'method' => 'POST',
        'headers' => array(
            'Content-Type' => 'application/json',
            'token' => $token
        ),
        'body' => json_encode($data)
    ));

    return $response;
}
?>

Solução de Problemas

Erro: "Unauthorized" ou "Invalid Token"

  • ✓ Verifique se o Token da API está correto
  • ✓ Verifique se não há espaços extras no token
  • ✓ Certifique-se que o header é token (não apikey)

Erro: "Invalid phone number"

  • ✓ Verifique se o número está com código do país (ex: +5511999998888)
  • ✓ Certifique-se de remover zeros à esquerda do DDD
  • ✓ Use a função de normalização antes de enviar

Mensagem não chega no WhatsApp

  • ✓ Verifique se o número tem WhatsApp ativo
  • ✓ Verifique se a instância está conectada
  • ✓ Verifique se não há bloqueio do destinatário

Erro de CORS no navegador

  • ⚠ Alguns navegadores bloqueiam requisições cross-origin
  • ✓ Para produção, use um backend intermediário
  • ✓ Use Supabase Edge Functions ou API Routes

Precisa de Ajuda?

Suporte direto via WhatsApp para sanar qualquer tipo de dúvida sobre nossa API.

Chamar no WhatsApp Visitar Site

© 2024 PlugSend API - Todos os direitos reservados

Desenvolvido por Plugins Tech

Copiado para a área de transferência!