Serviços Externos e Integrações

Supabase

Proposito

Database, autenticação, storage, e edge functions.

Componentes Usados

Componente	Uso
PostgreSQL	Banco de dados principal (66+ migrations)
RLS	Isolamento multi-tenant
Auth	Email/password authentication
Storage	Media de templates (bucket template-media)
pg_cron	Jobs agendados (segments, campaigns)

Configuração

• Project ref: osytjlchrelbuphsvfax
• Regiao: sa-east-1 (Sao Paulo)
• Plano: Pro

Clients

Client	Env Vars	Uso
Browser	NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY	Client components
Server	NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY + cookies	API routes, server components
Admin	NEXT_PUBLIC_SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY	Webhooks, cron, automações (bypass RLS)

pg_cron Jobs

Job	Intervalo	Função
recalculate_all_segments	5 minutos	Recalcula membros de segmentos dinâmicos
execute-scheduled-campaigns	1 minuto	Executa campanhas agendadas

Storage

• Bucket: template-media (público)
• Limite: 100MB por arquivo
• Tipos: JPEG, PNG, WebP, MP4, PDF
• Path: {accountId}/{uuid}.{ext}
• URL pública: supabase.storage.from("template-media").getPublicUrl(path)

Arquivos Relevantes

Arquivo	Descrição
src/lib/supabase/client.ts	Browser client
src/lib/supabase/server.ts	Server client
src/lib/supabase/admin.ts	Admin client (service role)
src/lib/supabase/middleware.ts	Session management

---

Upstash Redis

Proposito

Rate limiting e controle de concorrência (execution limiter).

Configuração

• Regiao: sa-east-1 (mesmo que Supabase para latencia mínima)
• Protocolo: REST API (não TCP — funciona em serverless)
• Prefix: x17:rl (rate limiting), x17:exec:active (execution limiter)

Uso 1: Rate Limiting (src/lib/api/rate-limit.ts)

Sliding window rate limiter via @upstash/ratelimit.

Presets:

Preset	Limite	Janela
webhook	100 req	1 min
api	30 req	1 min
auth	5 req	1 min
callback	20 req	1 min
ai	20 req	1 hora
send	60 req	1 min

Funcoes:

rateLimit(key, limit, windowMs)         // Custom
rateLimitByPreset(key, preset)          // Preset
rateLimitResponse(remaining, limit)     // 429 response
rateLimitHeaders(limit, remaining, reset) // X-RateLimit-* headers

Fallback: Se Redis não configurado, permite todas as requests (não bloqueia).

Uso 2: Execution Limiter (src/lib/automations/execution-limiter.ts)

Controla execuções concorrentes de automações por account.

• Key: x17:exec:active:{accountId}
• Max: 10 execuções concorrentes
• TTL: 300 segundos (auto-cleanup)

Environment Variables

UPSTASH_REDIS_REST_URL     # URL da REST API
UPSTASH_REDIS_REST_TOKEN   # Token de autenticação

---

Meta / Facebook (WhatsApp Cloud API)

Proposito

API oficial do WhatsApp para envio/recebimento de mensagens.

Versão da API

• Graph API: v23.0
• Base URL: https://graph.facebook.com/v23.0

Funcionalidades

Feature	Endpoint
Enviar mensagem	POST /{phoneNumberId}/messages
Submeter template	POST /{wabaId}/message_templates
Listar templates	GET /{wabaId}/message_templates
Deletar template	DELETE /{wabaId}/message_templates
Registrar phone	POST /{phoneNumberId}/register
Subscribé webhooks	POST /{wabaId}/subscribed_apps
Embedded Signup	OAuth flow + debug_token

Webhook

• Endpoint: /api/whatsapp/webhook
• Verificação: HMAC-SHA256 com FACEBOOK_APP_SECRET
• Rate limit: 100 req/min por IP
• Eventos processados: messages (inbound), statuses (delivered/read/failed), message_template_status_update

Environment Variables

FACEBOOK_APP_ID            # App ID
FACEBOOK_APP_SECRET        # App Secret (HMAC + OAuth)
FACEBOOK_CONFIG_ID         # Embedded Signup Config ID
WHATSAPP_VERIFY_TOKEN      # Webhook verification token
ENCRYPTION_KEY             # AES-256 para tokens

Arquivos

Arquivo	Descrição
src/lib/whatsapp/meta-api.ts	MetaWhatsAppApi client
src/lib/whatsapp/facebook-sdk.ts	OAuth + Embedded Signup
src/lib/whatsapp/encryption.ts	Token encryption
src/app/api/whatsapp/webhook/route.ts	Webhook handler

Documentação detalhada: whatsapp-integration

---

VPS - Claude Max Proxy

Proposito

Proxy para a API da Anthropic (Claude). Permite usar o Claude Opus sem expor a API key no frontend.

Arquitetura

• Servidor: VPS dedicado com FastAPI (Python)
• Endpoint: {VPS_API_URL}/v1/messages
• Modelo padrão: claude-opus-4-6
• Timeout: 30 segundos
• Retries: 2

Uso

chatWithClaude(messages, systemPrompt?, model?)  // Chat genérico
generateCopy(prompt, context?)                    // Copywriting WhatsApp
suggestReply(history, personality?)                // Sugestao de resposta
analyzeBrand(html, url)                            // Análise de marca (scraping)

Environment Variables

VPS_API_URL    # URL base da VPS
VPS_API_KEY    # API key (enviado como X-Api-Key header)

Arquivo

Arquivo	Descrição
src/lib/vps/client.ts	VPS client com retry logic
src/lib/constants.ts	VPS_CONFIG (endpoint, model, timeout)

---

ASAAS (Billing/Payments)

Proposito

Gateway de pagamento brasileiro para assinaturas.

Métodos de Pagamento

• PIX (QR code)
• Boleto bancário
• Cartão de crédito

Modelo de Dados

interface Subscription {
  asaas_customer_id: string    // ID do cliente no ASAAS
  asaas_subscription_id: string // ID da assinatura
  plan: "free" | "starter" | "pro" | "enterprise"
  billing_type: "CREDIT_CARD" | "PIX" | "BOLETO"
  cycle: "MONTHLY" | "YEARLY"
  value_cents: number
  status: "pending" | "active" | "past_due" | "suspended" | "cancelled"
}

interface BillingHistory {
  asaas_payment_id: string
  pix_qr_code: string | null
  pix_payload: string | null
  invoice_url: string | null
}

Webhook

• Endpoint: /api/cron/billing-suspension (cron de verificação)
• Processa notificações de pagamento do ASAAS
• Suspende contas com pagamento atrasado

---

E-Commerce Integrations

Plataformas Suportadas

Plataforma	Auth	Arquivos
Shopify	OAuth 2.0	src/lib/integrations/shopify/ (client, oauth, normalizer, webhooks)
Yampi	OAuth 2.0 + Token Manager	src/lib/integrations/yampi/ (client, oauth, token-manager, normalizer, webhooks)
Nuvemshop	OAuth 2.0	src/lib/integrations/nuvemshop/ (client, oauth, normalizer, webhooks)
WooCommerce	API Key	src/lib/integrations/woocommerce/ (client, normalizer, webhooks)
Hotmart	Webhook	src/lib/integrations/hotmart/ (client, normalizer, webhooks)
Kiwify	Webhook	src/lib/integrations/kiwify/ (client, normalizer, webhooks)

Estrutura por Plataforma

Cada integração segue o padrão:

src/lib/integrations/{platform}/
  client.ts       # Client HTTP para a API da plataforma
  oauth.ts        # (se OAuth) Fluxo de autorização
  normalizer.ts   # Normaliza dados para formato x17
  webhooks.ts     # Processa webhooks da plataforma

Arquivo compartilhado:

• src/lib/integrations/trigger-data-builder.ts - Constroi triggerData padronizado para automações
• src/lib/integrations/recovery-tracker.ts - Rastreamento de recuperação de carrinhos

Fluxo de Webhook E-Commerce

1. Plataforma envia webhook -> /api/integrations/{platform}/webhook
2. Verificação de assinatura (HMAC ou token)
3. Normalizar dados (normalizer.ts)
4. Upsert contato + pedido/carrinho no banco
5. emitEvent() com métrica aprópriada
6. dispatchTrigger() ou dispatchEventToAutomations()
7. Automações com trigger correspondente são executadas

Tokens

• Shopify: OAuth 2.0, token longo prazo (offline access)
• Yampi: OAuth 2.0, token com expiração (refresh automático via token-manager.ts)
• Nuvemshop: OAuth 2.0
• WooCommerce: API Key (consumer_key + consumer_secret)
• Hotmart: Webhook-only (sem API client com token)
• Kiwify: Webhook-only (sem API client com token)

Todos os tokens são criptografados com a mesma função encrypt() de src/lib/whatsapp/encryption.ts.

---

17track (Rastreamento de Envios)

Proposito

API de rastreamento de envios para acompanhar pedidos em transito.

Modelo de Dados

interface ShipmentTracking {
  tracking_number: string
  carrier_code: number | null
  carrier_name: string | null
  status: "not_found" | "info_received" | "in_transit" | "expired" |
          "available_for_pickup" | "out_for_delivery" | "delivery_failure" |
          "delivered" | "exception" | "pending"
  tracking_url: string | null
  estimated_delivery: string | null
}

interface TrackingSettings {
  api_key_encrypted: string | null  // AES-256-GCM
  webhook_secret: string | null
  is_active: boolean
  auto_register: boolean
  quota_total: number
  quota_used: number
}

Eventos Emitidos

• Shipment Created
• Shipment In Transit
• Shipment Out For Delivery
• Shipment Delivered
• Shipment Exception

---

Audit Logging (src/lib/api/audit.ts)

Proposito

Registrar ações de usuários para compliance e debugging.

Implementação

function logAudit(params: {
  accountId: string
  userId?: string
  action: "create" | "update" | "delete" | "restore" | "login" | "export"
  entityType: string
  entityId?: string
  changes?: Record<string, unknown>
  ip?: string
})

• Fire-and-forget: Usa createAdminClient() + .then() internamente
• Nunca bloqueia: Chamado SEM await — não afeta latencia da response
• Tabela: audit_logs (account_id, user_id, action, entity_type, entity_id, changes, ip_address)

---

Error Handling (src/lib/errors.ts)

Hierarquia

Error
  +-- AppError (code, statusCode, details)
        |-- AuthError (401)
        |-- NotFoundError (404)
        |-- ValidationError (422)
        |-- WhatsAppError (502)
        +-- VPSError (502)

API Response Formatting

formatApiError(error)
  -> AppError:   { code, message, details }, status
  -> ZodError:   { code: "VALIDATION_ERROR", message, details: flatten() }, 422
  -> Unknown:    { code: "INTERNAL_ERROR", message: "Erro interno" }, 500

Response Helpers (src/lib/api/response.ts)

success<T>(data, status=200)   // { data: T }
created<T>(data)               // { data: T }, 201
noContent()                    // null, 204
error(err)                     // { error: { code, message } }, status
withErrorHandling(handler)     // try/catch wrapper

---

Environment Variables Completas

Supabase

NEXT_PUBLIC_SUPABASE_URL
NEXT_PUBLIC_SUPABASE_ANON_KEY
SUPABASE_SERVICE_ROLE_KEY

WhatsApp/Facebook

FACEBOOK_APP_ID
FACEBOOK_APP_SECRET
FACEBOOK_CONFIG_ID
WHATSAPP_VERIFY_TOKEN
ENCRYPTION_KEY

Redis

UPSTASH_REDIS_REST_URL
UPSTASH_REDIS_REST_TOKEN

VPS

VPS_API_URL
VPS_API_KEY

Cron

CRON_SECRET

Admin

PLATFORM_ADMIN_EMAILS

Integrações (variam por plataforma)

SHOPIFY_API_KEY
SHOPIFY_API_SECRET
NUVEMSHOP_APP_ID
NUVEMSHOP_APP_SECRET
YAMPI_CLIENT_ID
YAMPI_CLIENT_SECRET
# (Hotmart e Kiwify: webhook-only, sem keys de API)