📚 API Documentation

WhatsApp API para desenvolvedores

v1.0

🔐 Autenticação

Todas as requisições devem incluir o header x-api-key com sua API Key.

curl -X POST "apizap.alphaassessoriadigital.com/client-api/?action=send-text" \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -d '{"jid": "5511999999999@s.whatsapp.net", "text": "Olá!"}'

📋 Formato de Resposta Padrão

Todos os endpoints de envio retornam respostas padronizadas com messageId para rastreamento.

{
  "success": true,
  "messageId": "3EB0B430F7A4D8C1E2F3",
  "remoteJid": "5511999999999@s.whatsapp.net",
  "timestamp": 1703847600
}

🧪 Testar API

Envie uma mensagem de teste para validar sua API Key e instância conectada.

🔑 API Key

📱 Número (com DDD)

💬 Mensagem

💬 Mensagens

POST /api/instances/:id/send-text ATUALIZADO ▼

Envia uma mensagem de texto simples. Valida automaticamente se o número existe no WhatsApp.

Parâmetro	Tipo	Descrição
`jid` *obrigatório	string	Número do destinatário (ex: 5511999999999@s.whatsapp.net)
`text` *obrigatório	string	Texto da mensagem
`validateNumber`	boolean	Validar se número existe no WhatsApp (padrão: true)

// Requisição
{
  "jid": "5511999999999@s.whatsapp.net",
  "text": "Olá! Esta é uma mensagem de teste."
}

// Resposta de Sucesso (200)
{
  "success": true,
  "messageId": "3EB0B430F7A4D8C1E2F3",
  "remoteJid": "5511999999999@s.whatsapp.net",
  "timestamp": 1703847600
}

POST /api/instances/:id/send-image ▼

Envia uma imagem com legenda opcional. Aceita URL ou base64.

Parâmetro	Tipo	Descrição
`jid` *obrigatório	string	Número do destinatário
`url`	string	URL da imagem (obrigatório se não usar base64)
`base64`	string	Imagem em base64 (obrigatório se não usar url)
`caption`	string	Legenda da imagem
`mimetype`	string	Tipo MIME (padrão: image/jpeg)
`validateNumber`	boolean	Validar se número existe (padrão: true)

// Requisição
{
  "jid": "5511999999999@s.whatsapp.net",
  "url": "https://exemplo.com/imagem.jpg",
  "caption": "Veja esta imagem!"
}

// Resposta de Sucesso (200)
{
  "success": true,
  "messageId": "3EB0B430F7A4D8C1E2F3",
  "remoteJid": "5511999999999@s.whatsapp.net",
  "timestamp": 1703847600
}

POST /api/instances/:id/send-video ▼

Envia um vídeo com legenda opcional. Aceita URL ou base64.

Parâmetro	Tipo	Descrição
`jid` *obrigatório	string	Número do destinatário
`url`	string	URL do vídeo
`base64`	string	Vídeo em base64
`caption`	string	Legenda do vídeo
`gifPlayback`	boolean	Enviar como GIF (loop)
`mimetype`	string	Tipo MIME (padrão: video/mp4)
`validateNumber`	boolean	Validar se número existe (padrão: true)

// Requisição
{
  "jid": "5511999999999@s.whatsapp.net",
  "url": "https://exemplo.com/video.mp4",
  "caption": "Confira este vídeo!",
  "gifPlayback": false
}

// Resposta de Sucesso (200)
{
  "success": true,
  "messageId": "3EB0B430F7A4D8C1E2F3",
  "remoteJid": "5511999999999@s.whatsapp.net",
  "timestamp": 1703847600
}

POST /api/instances/:id/send-audio ▼

Envia um áudio (pode ser como mensagem de voz). Aceita URL ou base64.

Parâmetro	Tipo	Descrição
`jid` *obrigatório	string	Número do destinatário
`url`	string	URL do áudio
`base64`	string	Áudio em base64
`ptt`	boolean	Enviar como mensagem de voz (push-to-talk)
`mimetype`	string	Tipo MIME (padrão: audio/mpeg)
`validateNumber`	boolean	Validar se número existe (padrão: true)

// Requisição
{
  "jid": "5511999999999@s.whatsapp.net",
  "url": "https://exemplo.com/audio.mp3",
  "ptt": true
}

// Resposta de Sucesso (200)
{
  "success": true,
  "messageId": "3EB0B430F7A4D8C1E2F3",
  "remoteJid": "5511999999999@s.whatsapp.net",
  "timestamp": 1703847600
}

POST /api/instances/:id/send-document ▼

Envia um documento (PDF, DOC, etc).

Parâmetro	Tipo	Descrição
`jid` *obrigatório	string	Número do destinatário
`url` *obrigatório	string	URL do documento
`filename`	string	Nome do arquivo
`mimetype`	string	Tipo MIME (ex: application/pdf)

// Requisição
{
  "jid": "5511999999999@s.whatsapp.net",
  "url": "https://exemplo.com/documento.pdf",
  "filename": "Contrato.pdf",
  "mimetype": "application/pdf"
}

// Resposta de Sucesso (200)
{
  "success": true,
  "messageId": "3EB0B430F7A4D8C1E2F3",
  "remoteJid": "5511999999999@s.whatsapp.net",
  "timestamp": 1703847600
}

POST /api/instances/:id/send-location ▼

Envia uma localização.

Parâmetro	Tipo	Descrição
`jid` *obrigatório	string	Número do destinatário
`latitude` *obrigatório	number	Latitude
`longitude` *obrigatório	number	Longitude
`name`	string	Nome do local
`address`	string	Endereço

// Requisição
{
  "jid": "5511999999999@s.whatsapp.net",
  "latitude": -23.5505,
  "longitude": -46.6333,
  "name": "São Paulo",
  "address": "Av. Paulista, 1000"
}

// Resposta de Sucesso (200)
{
  "success": true,
  "messageId": "3EB0B430F7A4D8C1E2F3",
  "remoteJid": "5511999999999@s.whatsapp.net",
  "timestamp": 1703847600
}

POST /api/instances/:id/send-contact ▼

Envia um cartão de contato.

Parâmetro	Tipo	Descrição
`jid` *obrigatório	string	Número do destinatário
`name` *obrigatório	string	Nome do contato
`phone` *obrigatório	string	Telefone do contato

// Requisição
{
  "jid": "5511999999999@s.whatsapp.net",
  "name": "Maria Silva",
  "phone": "+5511988888888"
}

// Resposta de Sucesso (200)
{
  "success": true,
  "messageId": "3EB0B430F7A4D8C1E2F3",
  "remoteJid": "5511999999999@s.whatsapp.net",
  "timestamp": 1703847600
}

POST /api/instances/:id/send-sticker ▼

Envia um sticker/figurinha.

Parâmetro	Tipo	Descrição
`jid` *obrigatório	string	Número do destinatário
`url` *obrigatório	string	URL do sticker (WebP)

// Requisição
{
  "jid": "5511999999999@s.whatsapp.net",
  "url": "https://exemplo.com/sticker.webp"
}

// Resposta de Sucesso (200)
{
  "success": true,
  "messageId": "3EB0B430F7A4D8C1E2F3",
  "remoteJid": "5511999999999@s.whatsapp.net",
  "timestamp": 1703847600
}

POST /api/instances/:id/send-reaction ▼

Envia uma reação (emoji) a uma mensagem.

Parâmetro	Tipo	Descrição
`jid` *obrigatório	string	JID do chat
`messageId` *obrigatório	string	ID da mensagem para reagir
`emoji` *obrigatório	string	Emoji da reação (vazio para remover)

// Requisição
{
  "jid": "5511999999999@s.whatsapp.net",
  "messageId": "3EB0B430A...",
  "emoji": "👍"
}

// Resposta de Sucesso (200)
{
  "success": true,
  "messageId": "3EB0B430F7A4D8C1E2F3",
  "remoteJid": "5511999999999@s.whatsapp.net",
  "timestamp": 1703847600
}

🎯 Mensagens Interativas

POST /api/instances/:id/send-buttons ▼

Envia uma mensagem com botões interativos. ✅ Funciona em Web, iOS e Android!

Parâmetro	Tipo	Descrição
`jid` *obrigatório	string	Número do destinatário
`text` *obrigatório	string	Texto principal da mensagem
`footer`	string	Texto do rodapé
`buttons` *obrigatório	array	Array de botões (quick_reply, cta_url, cta_call, cta_copy)

// Requisição
{
  "jid": "5511999999999@s.whatsapp.net",
  "text": "Escolha uma opção:",
  "footer": "Atendimento 24h",
  "buttons": [
    {
      "type": "quick_reply",
      "displayText": "✅ Sim",
      "id": "btn_sim"
    },
    {
      "type": "cta_url",
      "displayText": "🌐 Visitar Site",
      "url": "https://google.com"
    },
    {
      "type": "cta_call",
      "displayText": "📞 Ligar",
      "phoneNumber": "+5511999999999"
    },
    {
      "type": "cta_copy",
      "displayText": "📋 Copiar Código PIX",
      "copyCode": "00020126580014br.gov.bcb.pix..."
    }
  ]
}

// Resposta de Sucesso (200)
{
  "success": true,
  "messageId": "3EB0B430F7A4D8C1E2F3",
  "remoteJid": "5511999999999@s.whatsapp.net",
  "timestamp": 1703847600
}

POST /api/instances/:id/send-list ▼

Envia uma mensagem com lista de opções. ✅ Funciona em Web, iOS e Android!

Parâmetro	Tipo	Descrição
`jid` *obrigatório	string	Número do destinatário
`title`	string	Título da mensagem
`text` *obrigatório	string	Texto principal
`footer`	string	Texto do rodapé
`buttonText` *obrigatório	string	Texto do botão que abre a lista
`sections` *obrigatório	array	Seções com opções da lista

// Requisição
{
  "jid": "5511999999999@s.whatsapp.net",
  "title": "Menu Principal",
  "text": "Selecione uma opção abaixo:",
  "footer": "Atendimento 24h",
  "buttonText": "Ver Opções",
  "sections": [
    {
      "title": "Produtos",
      "rows": [
        { "title": "Produto A", "description": "Descrição do produto A", "rowId": "prod_a" },
        { "title": "Produto B", "description": "Descrição do produto B", "rowId": "prod_b" }
      ]
    },
    {
      "title": "Suporte",
      "rows": [
        { "title": "Falar com Atendente", "description": "Atendimento humano", "rowId": "human" }
      ]
    }
  ]
}

// Resposta de Sucesso (200)
{
  "success": true,
  "messageId": "3EB0B430F7A4D8C1E2F3",
  "remoteJid": "5511999999999@s.whatsapp.net",
  "timestamp": 1703847600
}

POST /api/instances/:id/send-carousel ▼

Envia um carrossel de cards com imagens e botões. Nota: Funciona apenas no celular.

Parâmetro	Tipo	Descrição
`jid` *obrigatório	string	Número do destinatário
`title`	string	Título do carrossel
`body`	string	Texto do corpo
`footer`	string	Rodapé
`cards` *obrigatório	array	Array de cards (máximo 10)

// Requisição
{
  "jid": "5511999999999@s.whatsapp.net",
  "title": "🛍️ Ofertas Especiais",
  "body": "Confira nossos produtos!",
  "footer": "Loja Virtual",
  "cards": [
    {
      "header": {
        "title": "Produto 1",
        "subtitle": "Descrição",
        "imageUrl": "https://exemplo.com/img1.jpg",
        "hasMediaAttachment": false
      },
      "title": "📱 Produto 1",
      "body": "Descrição do produto 1",
      "footer": "R$ 99,90",
      "buttons": [
        {
          "displayText": "🛒 Comprar",
          "urlButton": { "url": "https://minhaloja.com/produto1" }
        }
      ]
    },
    {
      "header": {
        "title": "Produto 2",
        "subtitle": "Descrição",
        "imageUrl": "https://exemplo.com/img2.jpg",
        "hasMediaAttachment": false
      },
      "title": "💻 Produto 2",
      "body": "Descrição do produto 2",
      "footer": "R$ 149,90",
      "buttons": [
        {
          "displayText": "🛒 Comprar",
          "urlButton": { "url": "https://minhaloja.com/produto2" }
        }
      ]
    }
  ]
}

// Resposta de Sucesso (200)
{
  "success": true,
  "messageId": "3EB0B430F7A4D8C1E2F3",
  "remoteJid": "5511999999999@s.whatsapp.net",
  "timestamp": 1703847600
}

POST /api/instances/:id/send-poll ▼

Envia uma enquete/votação para um contato ou grupo. Funciona no celular e desktop!

Parâmetro	Tipo	Descrição
`jid` *obrigatório	string	Número do destinatário
`name` *obrigatório	string	Pergunta da enquete
`options` *obrigatório	string[]	Lista de opções (mínimo 2, máximo 12)
`selectableCount`	number	Quantidade de opções selecionáveis (1 = única, 0 = múltipla). Padrão: 1

// Requisição
{
  "jid": "5511999999999@s.whatsapp.net",
  "name": "Qual sua linguagem favorita?",
  "options": ["JavaScript", "Python", "TypeScript", "Go"],
  "selectableCount": 1
}

// Resposta de Sucesso (200)
{
  "success": true,
  "messageId": "3EB0B430F7A4D8C1E2F3",
  "remoteJid": "5511999999999@s.whatsapp.net",
  "timestamp": 1703847600
}

🛍️ Catálogo de Produtos

POST /api/instances/:id/send-products ▼

Envia múltiplos produtos do catálogo do WhatsApp Business. Requer catálogo configurado.

Parâmetro	Tipo	Descrição
`jid` *obrigatório	string	Número do destinatário
`productIds` *obrigatório	string[]	Array de IDs dos produtos (máximo 30)
`catalogId`	string	ID do catálogo (opcional, usa o padrão da conta)
`title`	string	Título da mensagem
`body`	string	Texto da mensagem
`footer`	string	Rodapé da mensagem

// Requisição
{
  "jid": "5511999999999@s.whatsapp.net",
  "productIds": ["produto_001", "produto_002", "produto_003"],
  "title": "Ofertas da Semana",
  "body": "Confira nossos produtos em promoção!",
  "footer": "Válido até domingo"
}

// Resposta de Sucesso (200)
{
  "success": true,
  "messageId": "3EB0B430F7A4D8C1E2F3",
  "remoteJid": "5511999999999@s.whatsapp.net",
  "timestamp": 1703847600
}

POST /api/instances/:id/send-product ▼

Envia um único produto do catálogo com detalhes completos. Requer catálogo configurado.

Parâmetro	Tipo	Descrição
`jid` *obrigatório	string	Número do destinatário
`productId` *obrigatório	string	ID do produto no catálogo
`catalogId`	string	ID do catálogo (opcional)
`body`	string	Texto da mensagem
`footer`	string	Rodapé da mensagem

// Requisição
{
  "jid": "5511999999999@s.whatsapp.net",
  "productId": "produto_001",
  "body": "Olha esse produto incrível!",
  "footer": "Frete grátis"
}

// Resposta de Sucesso (200)
{
  "success": true,
  "messageId": "3EB0B430F7A4D8C1E2F3",
  "remoteJid": "5511999999999@s.whatsapp.net",
  "timestamp": 1703847600
}

GET /api/instances/:id/catalog ▼

Lista todos os produtos do seu catálogo.

Parâmetro	Tipo	Descrição
`limit`	number	Quantidade máxima de produtos (padrão: 100)
`cursor`	string	Cursor para paginação

// Resposta de Sucesso (200)
{
  "success": true,
  "jid": "5511999999999@s.whatsapp.net",
  "productsCount": 15,
  "products": [
    {
      "id": "produto_001",
      "name": "Camiseta Básica",
      "description": "Camiseta 100% algodão",
      "price": 4990,
      "currency": "BRL",
      "imageUrl": "https://..."
    }
  ],
  "nextPageCursor": "abc123..."
}

GET /api/instances/:id/catalog/:number ▼

Obtém o catálogo de outro número do WhatsApp Business.

Parâmetro	Tipo	Descrição
`number` *obrigatório	string	Número do WhatsApp Business (ex: 5511999999999)
`limit`	number	Quantidade máxima de produtos (padrão: 100)

// Resposta de Sucesso (200)
{
  "success": true,
  "jid": "5511888888888@s.whatsapp.net",
  "productsCount": 25,
  "products": [...]
}

POST /api/instances/:id/catalog/product ▼

Cria um novo produto no catálogo.

Parâmetro	Tipo	Descrição
`name` *obrigatório	string	Nome do produto
`description`	string	Descrição do produto
`price`	number	Preço em centavos (ex: 4990 = R$ 49,90)
`currency`	string	Moeda (padrão: BRL)
`imageUrl`	string	URL da imagem do produto
`url`	string	Link para o produto (site)
`retailerId`	string	ID interno do produto (SKU)
`isHidden`	boolean	Ocultar produto do catálogo público

// Requisição
{
  "name": "Camiseta Premium",
  "description": "Camiseta 100% algodão, várias cores",
  "price": 7990,
  "currency": "BRL",
  "imageUrl": "https://exemplo.com/camiseta.jpg",
  "url": "https://minhaloja.com/camiseta-premium",
  "retailerId": "SKU-001",
  "isHidden": false
}

// Resposta de Sucesso (200)
{
  "success": true,
  "product": { "id": "produto_new", "name": "Camiseta Premium" }
}

PUT /api/instances/:id/catalog/product/:productId ▼

Atualiza um produto existente no catálogo.

Parâmetro	Tipo	Descrição
`productId` *obrigatório	string	ID do produto (na URL)
`name`	string	Novo nome do produto
`price`	number	Novo preço em centavos

// Requisição
{
  "price": 5990,
  "description": "Promoção! Camiseta com 25% de desconto"
}

// Resposta de Sucesso (200)
{
  "success": true,
  "product": { "id": "produto_001", "name": "Camiseta Premium" }
}

DELETE /api/instances/:id/catalog/product/:productId ▼

Remove um produto do catálogo.

Parâmetro	Tipo	Descrição
`productId` *obrigatório	string	ID do produto a ser removido

// Resposta de Sucesso (200)
{
  "success": true,
  "deletedProductId": "produto_001"
}

GET /api/instances/:id/catalog/collections ▼

Lista as coleções do catálogo (categorias de produtos).

Parâmetro	Tipo	Descrição
`limit`	number	Quantidade máxima de coleções (padrão: 50)

// Resposta de Sucesso (200)
{
  "success": true,
  "collectionsCount": 3,
  "collections": [
    { "id": "colecao_001", "name": "Roupas Masculinas", "productsCount": 12 },
    { "id": "colecao_002", "name": "Acessórios", "productsCount": 8 }
  ]
}

POST /api/instances/:id/catalog/collection ▼

Cria uma nova coleção no catálogo com produtos selecionados.

Parâmetro	Tipo	Descrição
`name` *obrigatório	string	Nome da coleção
`productIds` *obrigatório	string[]	Array de IDs dos produtos para incluir

// Requisição
{
  "name": "Promoções de Verão",
  "productIds": ["produto_001", "produto_002", "produto_003"]
}

// Resposta de Sucesso (200)
{
  "success": true,
  "collection": { "id": "colecao_new", "name": "Promoções de Verão" }
}

DELETE /api/instances/:id/catalog/collection/:collectionId ▼

Remove uma coleção do catálogo. Os produtos não são deletados, apenas removidos da coleção.

Parâmetro	Tipo	Descrição
`collectionId` *obrigatório	string	ID da coleção a ser removida (na URL)

// Resposta de Sucesso (200)
{
  "success": true,
  "deletedCollectionId": "colecao_001"
}