Ambiente de Desenvolvimento

Configure seu ambiente de desenvolvimento para construir integrações robustas com WhatsApp usando a API REST da ApiZap.

Pré-requisitos

Obrigatório: Você precisa de uma Chave API válida da ApiZap. Criar Chave API

Ferramentas de Desenvolvimento

Ferramenta de Teste de API

Postman, Insomnia ou curl para testar endpoints

Monitor de Requisições

Ferramentas para monitorar requisições da API

Biblioteca Cliente HTTP

Cliente HTTP da sua linguagem preferida

Editor de Código

VS Code, IntelliJ ou sua IDE preferida

Configuração do Ambiente

Configure variáveis de ambiente para diferentes estágios de deploy:

APIZAP_API_KEY=ak_dev_1234567890abcdef
APIZAP_BASE_URL=https://b0fe4081af63.ngrok-free.app/api/v1
REQUEST_TIMEOUT=30000
RETRY_ATTEMPTS=3

Segurança: Nunca commite chaves API no controle de versão. Use .gitignore e arquivos de configuração específicos do ambiente.

Configuração do Cliente HTTP

Configure clientes HTTP na sua linguagem de programação preferida para interagir com a API REST da ApiZap:

npm install axios dotenv
# ou
yarn add axios dotenv

Exemplos de Implementação de Cliente

const axios = require('axios');
require('dotenv').config();

class ApiZapClient {
  constructor() {
    this.client = axios.create({
      baseURL: process.env.APIZAP_BASE_URL,
      headers: {
        'Authorization': `ApiKey ${process.env.APIZAP_API_KEY}`,
        'Content-Type': 'application/json'
      },
      timeout: 30000
    });
  }

  async testConnection() {
    try {
      const response = await this.client.get('/api-keys');
      console.log('✅ Conexão bem-sucedida!');
      return response.data;
    } catch (error) {
      console.error('❌ Erro de conexão:', error.message);
      throw error;
    }
  }

  async sendMessage(messageData) {
    const response = await this.client.post('/messages', messageData);
    return response.data;
  }
}

const client = new ApiZapClient();

Melhores Práticas de Desenvolvimento

Manipulação de Erros e Lógica de Retry

Implementação de Retry

class ApiZapClient {
  async makeRequest(method, endpoint, data = null, retries = 3) {
    for (let attempt = 1; attempt <= retries; attempt++) {
      try {
        const response = await this.client.request({
          method,
          url: endpoint,
          data
        });
        return response.data;
      } catch (error) {
        if (error.response?.status >= 500) {
          // Erro interno do servidor - backoff exponencial
          const delay = Math.pow(2, attempt) * 1000;
          console.log(`Erro do servidor. Tentando novamente em ${delay}ms...`);
          await this.sleep(delay);
        } else if (attempt === retries) {
          throw error;
        }
      }
    }
  }

  sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

Melhores Práticas de Segurança

Proteção de Chaves API

Armazene chaves API em variáveis de ambiente, nunca no código. Use arquivos .env localmente e armazenamento seguro em produção.

Validação de Requisição

Valide todos os dados de entrada e implemente tratamento de erros robusto.

Tratamento de Erros

Implemente lógica de retry com backoff exponencial para erros temporários.

Logging

Registre todas as requisições e respostas da API para debug. Use logging estruturado com níveis apropriados.

Guia de Solução de Problemas

Erro 401 Não Autorizado

Causas:

Chave API inválida ou expirada
Formato incorreto do cabeçalho de autorização
Chave API não ativa

Soluções:

# Teste sua Chave API
curl -X GET "https://b0fe4081af63.ngrok-free.app/api/v1/api-keys" \
  -H "Authorization: ApiKey sua_api_key_aqui"

Verifique o formato: Authorization: ApiKey sua_chave
Verifique o status da Chave API no dashboard
Gere uma nova Chave API se necessário

Problemas de Conexão da Instância

Problemas Comuns:

QR code expirado
Sessão WhatsApp terminada
Status da instância desconectado

Soluções:

# Verificar status da instância
curl -X GET "https://b0fe4081af63.ngrok-free.app/api/v1/instances/{instanceId}" \
  -H "Authorization: ApiKey your_api_key_here"

# Obter novo código QR
curl -X GET "https://b0fe4081af63.ngrok-free.app/api/v1/instances/{instanceId}/qrcode" \
  -H "Authorization: ApiKey your_api_key_here"

Monitorar status da instância regularmente
Implementar lógica de reconexão automática

Problemas de Entrega de Mensagens

Possíveis Causas:

Formato de número de telefone inválido
Instância não conectada
Destinatário bloqueou seu número

Soluções:

Verificar formato do número de telefone (+5511999999999)
Verificar status da mensagem via API
Garantir que a instância esteja conectada e ativa
Monitorar status de entrega das mensagens