Autenticação

A API do ZapFlare oferece dois métodos de autenticação:

1. API Keys - Para integrações e automações
2. Cookie Auth - Para o dashboard web

Obtendo uma API Key

1. Faça login no Dashboard
2. Navegue até API Keys
3. Clique em Gerar Nova Chave
4. Dê um nome descritivo para identificar o uso
5. Copie a chave gerada

Atenção

A API Key é exibida apenas uma vez! Certifique-se de copiá-la e armazená-la com segurança.

Usando a API Key

Todas as requisições à API devem incluir a API Key no header Authorization:

Authorization: Bearer SUA_API_KEY

Exemplo de Requisição

curl -X GET https://api.zapflare.io/v1/messages/list \
  -H "Authorization: Bearer zpk_live_abcdef123456..."

Exemplos em Diferentes Linguagens

Node.js

const axios = require('axios');

const apiKey = 'zpk_live_abcdef123456...';

const api = axios.create({
  baseURL: 'https://api.zapflare.io/v1',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
});

// Fazer requisição
api.get('/messages/list')
  .then(response => console.log(response.data))
  .catch(error => console.error(error));

Python

import requests

api_key = 'SUA_API_KEY'
base_url = 'https://api.zapflare.io/v1'

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

# Fazer requisição
response = requests.get(f'{base_url}/whatsapp/instances', headers=headers)
print(response.json())

PHP

<?php
$apiKey = 'SUA_API_KEY';
$baseUrl = 'https://api.zapflare.io/v1';

$headers = [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json'
];

$ch = curl_init($baseUrl . '/whatsapp/instances');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Go

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {
    apiKey := "SUA_API_KEY"
    baseURL := "https://api.zapflare.io/v1"
    
    client := &http.Client{}
    req, _ := http.NewRequest("GET", baseURL+"/whatsapp/instances", nil)
    req.Header.Add("Authorization", "Bearer "+apiKey)
    req.Header.Add("Content-Type", "application/json")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Erros de Autenticação

A API retorna erros específicos para problemas de autenticação:

401 Unauthorized

Retornado quando a API Key está ausente ou inválida:

{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

403 Forbidden

Retornado quando a API Key não tem permissão para acessar o recurso:

{
  "success": false,
  "error": {
    "code": "forbidden",
    "message": "You don't have permission to access this resource"
  }
}

Segurança das API Keys

Boas Práticas

1. Nunca exponha API Keys no código cliente (JavaScript frontend, apps móveis)
2. Use variáveis de ambiente para armazenar as chaves
3. Rotacione as chaves regularmente
4. Use chaves diferentes para desenvolvimento e produção
5. Monitore o uso das suas API Keys no dashboard

Exemplo com Variáveis de Ambiente

Node.js

// .env
ZAPFLARE_API_KEY=sua_api_key_aqui

// app.js
require('dotenv').config();

const apiKey = process.env.ZAPFLARE_API_KEY;

Python

# .env
ZAPFLARE_API_KEY=sua_api_key_aqui

# app.py
import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.getenv('ZAPFLARE_API_KEY')

Shell

# Exportar variável
export ZAPFLARE_API_KEY="sua_api_key_aqui"

# Usar em script
curl -H "Authorization: Bearer $ZAPFLARE_API_KEY" \
  https://api.zapflare.io/v1/whatsapp/instances

Limites de Taxa (Rate Limiting)

Para garantir a qualidade do serviço, a API implementa limites de taxa:

• Requisições por minuto: 60 (1 por segundo)
• Requisições por hora: 1000
• Burst máximo: 10 requisições simultâneas

Headers de resposta incluem informações sobre os limites:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640995200

Tratando Rate Limits

Quando o limite é excedido, a API retorna 429 Too Many Requests:

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after 60 seconds",
    "retryAfter": 60
  }
}

Gerenciando API Keys

Listar API Keys

GET /api-keys
Authorization: Bearer SUA_API_KEY

Criar Nova API Key

POST /api-keys
Content-Type: application/json
Cookie: auth-session=...

{
  "name": "Produção - Sistema X",
  "description": "Chave para o sistema de produção",
  "testMode": false
}

Resposta

{
  "success": true,
  "data": {
    "id": "key_abc123",
    "name": "Produção - Sistema X",
    "key": "zpk_live_abcdef123456...",
    "testMode": false,
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

Importante

A chave completa é exibida apenas uma vez! Guarde-a com segurança.

Revogar API Key

DELETE /api-keys/{keyId}
Cookie: auth-session=...

Cuidado

Revogar uma API Key é irreversível e todas as requisições usando essa chave falharão imediatamente.

Próximos Passos

• Criar sua primeira instância
• Configurar webhooks
• Enviar mensagens