API de Mensagens v1

A API de mensagens permite enviar mensagens através da plataforma ZapFlare.

Base URL

https://api.zapflare.io/v1

Autenticação

Todas as requisições devem incluir um dos headers:

Authorization: Bearer SUA_API_KEY

ou

X-API-Key: SUA_API_KEY

Endpoints Disponíveis

1. Enviar Mensagem de Texto

Envia uma mensagem de texto simples para um número WhatsApp.

POST /messages/send

Corpo da Requisição

{
  "to": "5511999999999",
  "text": "Sua mensagem aqui"
}

Parâmetros

Campo	Tipo	Obrigatório	Descrição
to	string	Sim	Número do destinatário com código do país (sem + ou espaços)
text	string	Sim	Texto da mensagem

Resposta de Sucesso (200)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "queued",
    "timestamp": "2024-01-15T15:30:00.000Z",
    "mode": "production"
  }
}

Notas Importantes:

• Se você estiver usando uma API Key de teste, a mensagem será prefixada com [TEST]
• O campo mode indicará se a mensagem foi enviada em modo test ou production

2. Listar Mensagens (Em Desenvolvimento)

⚠️ ATENÇÃO: Este endpoint retorna dados simulados e não está conectado ao banco de dados real.

GET /messages/list?page=1&limit=10

Parâmetros de Query

Campo	Tipo	Padrão	Descrição
page	number	1	Número da página
limit	number	10	Quantidade de resultados por página

3. Verificar Status da Mensagem (Em Desenvolvimento)

⚠️ ATENÇÃO: Este endpoint retorna dados simulados e não está conectado ao banco de dados real.

GET /messages/status/{messageId}

Tratamento de Erros

Estrutura de Erro

{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Descrição do erro"
  }
}

Códigos de Erro Comuns

Código	HTTP Status	Descrição
unauthorized	401	API Key não fornecida ou inválida
invalid_api_key	401	API Key inválida
forbidden	403	Sem permissão para esta operação
invalid_request	400	Campos obrigatórios faltando
rate_limit_exceeded	429	Limite de requisições excedido
server_error	500	Erro interno do servidor

Limites

• API Keys de Teste: Máximo de 100 mensagens por dia
• API Keys de Produção: Limites baseados no plano contratado

Exemplo de Código

JavaScript/Node.js

const axios = require('axios');

const API_KEY = 'sua_api_key_aqui';
const API_URL = 'https://api.zapflare.io/v1';

async function enviarMensagem(numero, texto) {
  try {
    const response = await axios.post(
      `${API_URL}/messages/send`,
      {
        to: numero,
        text: texto
      },
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );
    
    console.log('Mensagem enviada:', response.data);
    return response.data;
  } catch (error) {
    console.error('Erro:', error.response?.data || error.message);
    throw error;
  }
}

// Usar
enviarMensagem('5511999999999', 'Olá! Esta é uma mensagem de teste.');

cURL

curl -X POST https://api.zapflare.io/v1/messages/send \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "text": "Olá! Esta é uma mensagem de teste."
  }'

Python

import requests

API_KEY = 'sua_api_key_aqui'
API_URL = 'https://api.zapflare.io/v1'

def enviar_mensagem(numero, texto):
    headers = {
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }
    
    data = {
        'to': numero,
        'text': texto
    }
    
    response = requests.post(
        f'{API_URL}/messages/send',
        json=data,
        headers=headers
    )
    
    if response.status_code == 200:
        print('Mensagem enviada:', response.json())
        return response.json()
    else:
        print('Erro:', response.json())
        response.raise_for_status()

# Usar
enviar_mensagem('5511999999999', 'Olá! Esta é uma mensagem de teste.')

Observações Importantes

1. Instâncias WhatsApp: A API key já está vinculada ao seu tenant/usuário. Não é necessário especificar uma instância.

2. Formato de Números:

   • Sempre inclua o código do país
   • Não use caracteres especiais (+, -, espaços, parênteses)
   • Exemplo correto: 5511999999999

3. Segurança:

   • Nunca exponha sua API Key no código frontend
   • Use variáveis de ambiente para armazenar a API Key
   • Sempre use HTTPS

4. Status da API: A maioria dos endpoints ainda está em desenvolvimento. Atualmente, apenas o envio de mensagens de texto está funcional.