Visão Geral das Integrações

O BITIO se conecta com diversas APIs e serviços externos para fornecer funcionalidades completas de CRM, mídia paga e mensageria.

Mapa de Integrações

graph TB
    subgraph "BITIO Core"
        API[Lambda API]
        Worker[Worker EC2]
        N8N[n8n]
        DB[(PostgreSQL)]
    end

    subgraph "Integrações de Mídia"
        Meta[Meta Marketing API]
        Google[Google Ads API]
        GMB[Google My Business]
    end

    subgraph "Mensageria"
        WhatsApp[WhatsApp Business API]
        SNS[Amazon SNS]
    end

    subgraph "PDVs Parceiros"
        PDV1[PDV Sistema 1]
        PDV2[PDV Sistema 2]
        PDV3[PDV Sistema 3]
    end

    subgraph "Tracking"
        MetaPixel[Meta Pixel]
        GooglePixel[Google Pixel]
    end

    Worker --> Meta
    Worker --> Google
    Worker --> GMB
    Worker --> PDV1
    Worker --> PDV2
    Worker --> PDV3
    
    N8N --> WhatsApp
    API --> SNS
    
    API --> MetaPixel
    API --> GooglePixel
    
    Worker --> DB
    API --> DB

Categorias de Integração

1. APIs de Mídia e Reputação

Integração	Tecnologia	Frequência	Onde Roda
Meta Marketing API	OAuth 2.0 + REST API	Diária	Worker EC2
Google Ads API	OAuth 2.0 + gRPC/REST	Diária	Worker EC2
Google My Business API	OAuth 2.0 + REST	A cada 15-60 min	Worker EC2

2. PDVs Parceiros

Integração	Tecnologia	Frequência	Onde Roda
PDV Sistema 1	API REST/webhook	Configurável	Worker EC2 + SQS
PDV Sistema 2	API REST/CSV	Diária	Worker EC2 + SQS
PDV Sistema 3	Webhook/FTP	Tempo real	Worker EC2 + SQS

3. Rastreamento (Pixel)

Integração	Tecnologia	Onde
Meta Pixel	JavaScript SDK	Frontends públicos e redirecionador
Google Pixel	gtag.js	Frontends públicos e redirecionador

4. Mensageria

Canal	Tecnologia	Uso
WhatsApp	WhatsApp Business API via n8n	Campanhas, confirmações, bot
E-mail	Amazon SNS	E-mail marketing, notificações

Arquitetura de Mensageria

Fluxo de Campanhas WhatsApp

sequenceDiagram
    participant P as Painel Admin
    participant L as Lambda API
    participant SQS as SQS Queue
    participant W as Worker
    participant N8N as n8n
    participant WA as WhatsApp API
    participant C as Cliente

    P->>L: Criar campanha
    L->>SQS: Publicar mensagens
    W->>SQS: Consumir lote (10)
    W->>N8N: POST webhook/send-whatsapp
    N8N->>WA: Enviar mensagem
    WA->>C: Entregar mensagem
    WA->>N8N: Webhook status (delivered/read)
    N8N->>L: Atualizar status via API

Filas SQS por Finalidade

Fila	Propósito	Exemplo de payload
`whatsapp-campaigns`	Disparo de campanhas CRM	`{ campaignId, customerIds, templateName, variables }`
`whatsapp-inbound`	Mensagens recebidas (bot)	`{ customerId, phone, message, context }`
`email-campaigns`	E-mail marketing (SNS)	`{ campaignId, customerIds, subject, template }`
`reservation-confirmations`	Confirmação de reservas	`{ reservationId, customerId, action: confirm/cancel }`
`fidelity-rewards`	Cupons de fidelidade	`{ customerId, rewardId, milestone }`
`survey-followups`	Acompanhamento de pesquisa	`{ surveyResponseId, customerId, type: positive/negative }`

Segurança das Integrações

Armazenamento de Tokens OAuth

Todos os tokens de integração externa são armazenados em:

AWS Systems Manager Parameter Store (custo baixo) ou
AWS Secrets Manager (~$0.40/secreto/mês)

Rotação e Refresh

Tokens OAuth renovados automaticamente pelo Worker
Fallback manual via painel admin em caso de falha
Logs de integração para troubleshooting

Rate Limiting

Respeitamos limites de cada API externa
Retry exponential backoff em caso de rate limit
Circuit breaker para evitar cascata de falhas

Templates WhatsApp Business API

A Meta exige templates pré-aprovados para mensagens de marketing:

Template	Uso	Variáveis
`campanha_crm`	Campanhas de marketing	`{{nome_cliente}}`, `{{oferta}}`, `{{link}}`
`confirmacao_reserva`	Confirmação de reserva	`{{nome}}`, `{{data}}`, `{{hora}}`, `{{restaurante}}`
`cupom_fidelidade`	Cupom de fidelidade	`{{nome}}`, `{{beneficio}}`, `{{codigo_cupom}}`
`pesquisa_negativa`	Acompanhamento pós-pesquisa	`{{nome}}`, `{{restaurante}}`
`lembrete_reserva`	Lembrete de reserva	`{{nome}}`, `{{data}}`, `{{hora}}`

Configuração no n8n

// Exemplo de nó WhatsApp no n8n
{
  "to": "{{ $json.phone }}",
  "type": "template",
  "template": {
    "name": "campanha_crm",
    "language": {
      "code": "pt_BR"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "{{ $json.nome_cliente }}"
          },
          {
            "type": "text", 
            "text": "{{ $json.oferta }}"
          }
        ]
      }
    ]
  }
}

Monitoramento de Integrações

Métricas Principais

Taxa de sucesso por integração
Latência média de sincronização
Volume de dados processados
Erros por tipo (auth, rate limit, timeout)

Alertas Críticos

Token OAuth expirado
Rate limit atingido repetidamente
Fila SQS acumulando (>1000 mensagens)
Worker offline por >5 minutos

Dashboard de Saúde

// Exemplo de health check
export interface IntegrationHealth {
  name: string;
  status: 'healthy' | 'degraded' | 'down';
  lastSync: Date;
  errorRate: number;
  responseTime: number;
}

export const healthCheck = async (): Promise<IntegrationHealth[]> => {
  return [
    await checkMetaAds(),
    await checkGoogleAds(), 
    await checkGMB(),
    await checkWhatsApp(),
    await checkPDVs(),
  ];
};

Custos das Integrações

APIs Gratuitas

Meta Marketing API - Gratuita
Google Ads API - Gratuita
Google My Business API - Gratuita

Custos por Uso

WhatsApp Business API - ~$0.03-0.07 por conversa (24h)
Amazon SNS - $0.50 por milhão de e-mails
Provedor de PDV - A negociar com parceiros

Otimização de Custos

Campanhas agrupadas em janelas de 24h (WhatsApp)
E-mail via SNS em vez de provedores caros
Caching de dados de API quando possível

Roadmap de Integrações

Fase Atual (v1)

✅ Meta Marketing API
✅ Google Ads API
✅ Google My Business API
✅ WhatsApp Business API
✅ 2-3 PDVs prioritários

Futuro (v2+)

🔄 TikTok Ads API
🔄 iFood API (reputação)
🔄 Mercado Pago/PagSeguro (pagamentos)
🔄 Mais PDVs conforme demanda
🔄 Instagram Business API

Guias por Integração

Para documentação completa, consulte:

WhatsApp Business API + n8n

Mapa de Integrações​

Categorias de Integração​

1. APIs de Mídia e Reputação​

2. PDVs Parceiros​

3. Rastreamento (Pixel)​

4. Mensageria​

Arquitetura de Mensageria​

Fluxo de Campanhas WhatsApp​

Filas SQS por Finalidade​

Segurança das Integrações​

Armazenamento de Tokens OAuth​

Rotação e Refresh​

Rate Limiting​

Templates WhatsApp Business API​

Configuração no n8n​

Monitoramento de Integrações​

Métricas Principais​

Alertas Críticos​

Dashboard de Saúde​

Custos das Integrações​

APIs Gratuitas​

Custos por Uso​

Otimização de Custos​

Roadmap de Integrações​

Fase Atual (v1)​

Futuro (v2+)​

Guias por Integração​