@natyapp/meta 1.6.6 → 1.7.0

package/docs/05-integracoes.md

@@ -0,0 +1,960 @@
+# 05 - Integrações com Sistemas Externos
+
+[⬅️ Voltar ao Índice](README.md)
+
+---
+
+## 📋 Sumário
+- [Visão Geral das Integrações](#-visão-geral-das-integrações)
+- [Meta WhatsApp Business API (Graph API)](#-meta-whatsapp-business-api-graph-api)
+- [Naty Meta API (Backend Proprietário)](#-naty-meta-api-backend-proprietário)
+- [Express.js (Integração Opcional)](#-expressjs-integração-opcional)
+- [Diagramas de Integração](#-diagramas-de-integração)
+- [Rate Limits e Throttling](#-rate-limits-e-throttling)
+- [Segurança e Autenticação](#-segurança-e-autenticação)
+
+---
+
+## 🌐 Visão Geral das Integrações
+
+O SDK Naty Meta integra-se com três sistemas principais:
+
+```mermaid
+graph TB
+    subgraph "SDK Naty Meta"
+        SDK[NatyMeta Core]
+    end
+    
+    subgraph "API Proprietária"
+        NATY[Naty Meta API<br/>Gestão de Conexões]
+    end
+    
+    subgraph "API Meta/Facebook"
+        GRAPH[Meta Graph API v18.0<br/>WhatsApp Business]
+        OAUTH[Meta OAuth API<br/>Token Management]
+    end
+    
+    subgraph "Framework Web (Opcional)"
+        EXPRESS[Express.js<br/>Webhook Server]
+    end
+    
+    SDK -->|CRUD Conexões<br/>CRUD Webhooks<br/>CRUD Logs| NATY
+    SDK -->|Envio Mensagens<br/>Upload/Download Mídia| GRAPH
+    SDK -->|Refresh Tokens| OAUTH
+    SDK -->|Registra Rotas<br/>Webhook Routes| EXPRESS
+    
+    EXPRESS -->|Recebe Webhooks| GRAPH
+    
+    style SDK fill:#4CAF50,color:#fff
+    style NATY fill:#2196F3,color:#fff
+    style GRAPH fill:#FF9800,color:#fff
+    style OAUTH fill:#FFC107
+    style EXPRESS fill:#9C27B0,color:#fff
+```
+
+---
+
+## 📱 Meta WhatsApp Business API (Graph API)
+
+### Informações Gerais
+
+| Propriedade | Valor |
+|-------------|-------|
+| **Base URL** | `https://graph.facebook.com/v18.0` |
+| **Protocolo** | HTTPS (REST API) |
+| **Autenticação** | Bearer Token (OAuth 2.0) |
+| **Formato** | JSON |
+| **Documentação Oficial** | [developers.facebook.com/docs/whatsapp](https://developers.facebook.com/docs/whatsapp/cloud-api) |
+
+### Endpoints Utilizados
+
+#### 1. Envio de Mensagens
+
+```
+POST /{phone-number-id}/messages
+```
+
+**Headers:**
+```http
+Authorization: Bearer {access_token}
+Content-Type: application/json
+```
+
+**Body (Texto simples):**
+```json
+{
+  "messaging_product": "whatsapp",
+  "recipient_type": "individual",
+  "to": "5511999999999",
+  "type": "text",
+  "text": {
+    "preview_url": false,
+    "body": "Olá! Esta é uma mensagem de teste."
+  }
+}
+```
+
+**Body (Botões):**
+```json
+{
+  "messaging_product": "whatsapp",
+  "to": "5511999999999",
+  "type": "interactive",
+  "interactive": {
+    "type": "button",
+    "body": {
+      "text": "Escolha uma opção:"
+    },
+    "action": {
+      "buttons": [
+        {
+          "type": "reply",
+          "reply": {
+            "id": "opt_1",
+            "title": "Opção 1"
+          }
+        },
+        {
+          "type": "reply",
+          "reply": {
+            "id": "opt_2",
+            "title": "Opção 2"
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+**Response (Sucesso):**
+```json
+{
+  "messaging_product": "whatsapp",
+  "contacts": [
+    {
+      "input": "5511999999999",
+      "wa_id": "5511999999999"
+    }
+  ],
+  "messages": [
+    {
+      "id": "wamid.HBgNNTUxMTk4ODg4ODg4OBUCABIYIDNBNjdGMzQ5QzE5MEFCMTY1MjU0"
+    }
+  ]
+}
+```
+
+**Códigos de Erro Comuns:**
+
+| Código | Erro | Significado |
+|--------|------|-------------|
+| 400 | `invalid_parameter` | Parâmetro inválido no payload |
+| 401 | `invalid_token` | Access token inválido ou expirado |
+| 403 | `rate_limit_issues` | Limite de mensagens atingido |
+| 404 | `resource_not_found` | Phone number ID não encontrado |
+| 429 | `too_many_requests` | Rate limit excedido |
+| 500 | `internal_error` | Erro interno da Meta |
+
+---
+
+#### 2. Upload de Mídia
+
+```
+POST /{phone-number-id}/media
+```
+
+**Headers:**
+```http
+Authorization: Bearer {access_token}
+Content-Type: multipart/form-data
+```
+
+**Body:**
+```
+--boundary
+Content-Disposition: form-data; name="file"; filename="image.jpg"
+Content-Type: image/jpeg
+
+[binary data]
+--boundary
+Content-Disposition: form-data; name="messaging_product"
+
+whatsapp
+--boundary--
+```
+
+**Response:**
+```json
+{
+  "id": "1234567890"
+}
+```
+
+---
+
+#### 3. Download de Mídia (Obter URL)
+
+```
+GET /{media-id}
+```
+
+**Headers:**
+```http
+Authorization: Bearer {access_token}
+```
+
+**Response:**
+```json
+{
+  "url": "https://mmg.whatsapp.net/d/f/AqFmkQ...",
+  "mime_type": "image/jpeg",
+  "sha256": "e7b6c8f9a2d3...",
+  "file_size": 52431,
+  "id": "1234567890"
+}
+```
+
+⚠️ **Nota:** A URL tem validade de ~5 minutos.
+
+---
+
+#### 4. Download de Mídia (Binário)
+
+```
+GET {media-url}
+```
+
+**Headers:**
+```http
+Authorization: Bearer {access_token}
+```
+
+**Response:** Binary data (arquivo)
+
+---
+
+#### 5. Informações da Conta
+
+```
+GET /{phone-number-id}
+```
+
+**Headers:**
+```http
+Authorization: Bearer {access_token}
+```
+
+**Response:**
+```json
+{
+  "verified_name": "Minha Empresa LTDA",
+  "display_phone_number": "+55 11 99999-9999",
+  "quality_rating": "GREEN",
+  "id": "123456789012345",
+  "name_status": "APPROVED",
+  "status": "CONNECTED"
+}
+```
+
+---
+
+#### 6. Exchange Token (Refresh)
+
+```
+POST /oauth/access_token
+```
+
+**Query Parameters:**
+```
+grant_type=fb_exchange_token
+&client_id={app-id}
+&client_secret={app-secret}
+&fb_exchange_token={short-lived-token}
+```
+
+**Response:**
+```json
+{
+  "access_token": "EAAxxxxxxxxxxxx",
+  "token_type": "bearer",
+  "expires_in": 5184000
+}
+```
+
+---
+
+### Rate Limits
+
+| Tier | Limite Diário | Requisitos |
+|------|---------------|------------|
+| **Tier 1** | 1.000 mensagens/dia | Número recém-registrado |
+| **Tier 2** | 10.000 mensagens/dia | Envio de 1.000 msgs em 7 dias |
+| **Tier 3** | 100.000 mensagens/dia | Envio de 10.000 msgs em 7 dias |
+| **Unlimited** | Sem limite | Aprovação manual Meta (enterprise) |
+
+**Recomendação:** Implementar throttling na aplicação para evitar atingir limites.
+
+---
+
+### Webhooks da Meta
+
+A Meta envia webhooks para os eventos:
+
+**Eventos Suportados:**
+- `messages` - Mensagem recebida
+- `message_status` - Status de entrega (sent, delivered, read, failed)
+- `account_update` - Atualização na conta (quality rating, limites)
+- `phone_number_quality_update` - Mudança no quality rating
+
+**Payload de Webhook (Mensagem Recebida):**
+
+<details>
+<summary>Ver payload completo (clique para expandir)</summary>
+
+```json
+{
+  "object": "whatsapp_business_account",
+  "entry": [
+    {
+      "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
+      "changes": [
+        {
+          "value": {
+            "messaging_product": "whatsapp",
+            "metadata": {
+              "display_phone_number": "5511999999999",
+              "phone_number_id": "123456789012345"
+            },
+            "contacts": [
+              {
+                "profile": {
+                  "name": "João Silva"
+                },
+                "wa_id": "5511888888888"
+              }
+            ],
+            "messages": [
+              {
+                "from": "5511888888888",
+                "id": "wamid.HBgNNTUxMTk4ODg4ODg4OBUCABIYIDNBNjdGMzQ5QzE5MEFCMTY1MjU0",
+                "timestamp": "1709740800",
+                "type": "text",
+                "text": {
+                  "body": "Olá, preciso de ajuda!"
+                }
+              }
+            ]
+          },
+          "field": "messages"
+        }
+      ]
+    }
+  ]
+}
+```
+</details>
+
+**Webhook Verification (GET Request):**
+
+```http
+GET /webhooks?hub.mode=subscribe&hub.challenge=CHALLENGE_TOKEN&hub.verify_token=YOUR_VERIFY_TOKEN
+```
+
+**Resposta esperada:**
+```
+CHALLENGE_TOKEN
+```
+
+---
+
+## 🔧 Naty Meta API (Backend Proprietário)
+
+### Informações Gerais
+
+| Propriedade | Valor |
+|-------------|-------|
+| **Base URL** | `process.env.API_META` (ex: `https://api.meta.naty.app/v1`) |
+| **Protocolo** | HTTPS (REST API) |
+| **Autenticação** | Header `x-access-token: {appToken}` |
+| **Formato** | JSON |
+
+### Endpoints Utilizados
+
+#### 1. Validação de App Token
+
+```
+POST /validate/validateAppToken
+```
+
+**Headers:**
+```http
+Content-Type: application/json
+```
+
+**Body:**
+```json
+{
+  "appToken": "naty_app_token_xyz"
+}
+```
+
+**Response (Sucesso):**
+```json
+{
+  "valid": true,
+  "data": {
+    "appId": "app_123",
+    "companyId": "company_abc"
+  }
+}
+```
+
+**Response (Falha):**
+```json
+{
+  "valid": false,
+  "error": "Invalid token"
+}
+```
+
+---
+
+#### 2. CRUD de Conexões
+
+**Criar Conexão:**
+```
+POST /connection
+```
+
+**Headers:**
+```http
+x-access-token: {appToken}
+Content-Type: application/json
+```
+
+**Body:**
+```json
+{
+  "companyId": "abc123",
+  "phoneNumberId": "123456789012345",
+  "accessToken": "EAAxxxxxxxxxxxx",
+  "appId": "123456789",
+  "appSecret": "abcdef1234567890",
+  "accountId": "987654321",
+  "businessId": "456789123",
+  "phoneNumber": "+5511999999999"
+}
+```
+
+**Response:**
+```json
+{
+  "id": "conn_xyz789",
+  "companyId": "abc123",
+  "phoneNumberId": "123456789012345",
+  "isActive": true,
+  "createdAt": "2026-02-06T10:00:00.000Z"
+}
+```
+
+---
+
+**Buscar Conexão:**
+```
+GET /connection?companyId={companyId}&phoneNumberId={phoneNumberId}
+```
+
+**Headers:**
+```http
+x-access-token: {appToken}
+```
+
+**Response:**
+```json
+{
+  "_id": "65e1234567890abcdef",
+  "id": "conn_xyz789",
+  "companyId": "abc123",
+  "phoneNumberId": "123456789012345",
+  "accessToken": "EAAxxxxxxxxxxxx",
+  "appId": "123456789",
+  "appSecret": "abcdef1234567890",
+  "isActive": true,
+  "createdAt": "2026-02-06T10:00:00.000Z",
+  "updatedAt": "2026-02-06T10:30:00.000Z"
+}
+```
+
+---
+
+**Atualizar Conexão:**
+```
+PUT /connection/{connectionId}
+```
+
+**Headers:**
+```http
+x-access-token: {appToken}
+Content-Type: application/json
+```
+
+**Body:**
+```json
+{
+  "accessToken": "EAAyyyyyyyyyy"
+}
+```
+
+---
+
+**Deletar Conexão (Soft Delete):**
+```
+DELETE /connection/{connectionId}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Connection marked as inactive"
+}
+```
+
+---
+
+#### 3. CRUD de Webhooks
+
+**Criar Webhook:**
+```
+POST /webhook
+```
+
+**Body:**
+```json
+{
+  "companyId": "abc123",
+  "connection": {
+    "url": "https://myapp.com/webhooks/connections",
+    "active": true
+  },
+  "messages": {
+    "url": "https://myapp.com/webhooks/messages",
+    "active": true
+  }
+}
+```
+
+---
+
+**Buscar Webhook:**
+```
+GET /webhook?companyId={companyId}
+```
+
+**Response:**
+```json
+{
+  "id": "wh_abc123",
+  "companyId": "abc123",
+  "connection": {
+    "url": "https://myapp.com/webhooks/connections",
+    "active": true
+  },
+  "messages": {
+    "url": "https://myapp.com/webhooks/messages",
+    "active": true
+  },
+  "isActive": true
+}
+```
+
+---
+
+#### 4. CRUD de Mensagens
+
+**Salvar Mensagem:**
+```
+POST /message
+```
+
+**Body:**
+```json
+{
+  "companyId": "abc123",
+  "phoneNumberId": "123456789012345",
+  "sender": "5511888888888",
+  "message": {
+    "id": "wamid.xxx",
+    "type": "text",
+    "timestamp": "1709740800",
+    "text": { "body": "Olá!" }
+  }
+}
+```
+
+---
+
+**Buscar Mensagens:**
+```
+GET /messages?companyId={companyId}&phoneNumberId={phoneNumberId}&limit=50
+```
+
+**Response:**
+```json
+{
+  "messages": [
+    {
+      "id": "msg_123",
+      "companyId": "abc123",
+      "sender": "5511888888888",
+      "message": { "type": "text", "text": { "body": "Olá!" } },
+      "createdAt": "2026-02-06T10:00:00.000Z"
+    }
+  ],
+  "total": 150,
+  "page": 1
+}
+```
+
+---
+
+#### 5. Logs
+
+**Criar Log:**
+```
+POST /logs
+```
+
+**Body:**
+```json
+{
+  "type": "Access",
+  "owner": "app_123",
+  "url": "/messages",
+  "method": "POST",
+  "remoteIP": "192.168.1.100",
+  "objectData": { "messageId": "wamid.xxx" }
+}
+```
+
+---
+
+**Criar Log de Erro:**
+```
+POST /logs/error
+```
+
+**Body:**
+```json
+{
+  "connectionId": "conn_xyz789",
+  "errorFrom": "send_message",
+  "statusCode": 401,
+  "error": {
+    "message": "Invalid token",
+    "stack": "Error: Invalid token\n    at ..."
+  }
+}
+```
+
+---
+
+### Códigos de Status
+
+| Código | Significado |
+|--------|-------------|
+| 200 | Sucesso |
+| 201 | Recurso criado |
+| 400 | Bad request (payload inválido) |
+| 401 | Unauthorized (appToken inválido) |
+| 404 | Recurso não encontrado |
+| 500 | Erro interno do servidor |
+
+---
+
+## ⚙️ Express.js (Integração Opcional)
+
+### Propósito
+
+O SDK pode integrar-se a uma aplicação Express existente para:
+- Registrar rotas de webhook automaticamente
+- Receber webhooks da Meta
+- Processar eventos e emitir para a aplicação
+
+### Integração
+
+**Arquivo:** [`src/routes/webhooks/index.ts`](../src/routes/webhooks/index.ts)
+
+```typescript
+import express from 'express';
+import { NatyMeta } from '@natyapp/meta';
+
+const app = express();
+app.use(express.json());
+
+// Integrar SDK ao Express
+const sdk = new NatyMeta();
+await sdk.connect({
+  appToken: 'seu-app-token',
+  app: app,                    // Passa instância Express
+  pathname: '/webhooks'        // Base path
+});
+
+// Rotas registradas automaticamente:
+// - GET  /webhooks/messages
+// - POST /webhooks/messages
+// - GET  /webhooks/connections
+// - POST /webhooks/connections
+
+app.listen(3000, () => {
+  console.log('Servidor rodando na porta 3000');
+});
+```
+
+### Rotas Expostas
+
+#### 1. POST /webhooks/messages
+
+**Recebe:** Mensagens enviadas por clientes.
+
+**Handler:** [`src/routes/webhooks/methods/messages.ts`](../src/routes/webhooks/methods/messages.ts)
+
+**Comportamento:**
+1. Valida payload da Meta
+2. Cria `WhatsappMessage` entity
+3. Instancia `WhatsappResponse` para resposta
+4. Emite evento `'message'`
+5. Retorna 200 OK
+
+---
+
+#### 2. GET /webhooks/messages
+
+**Recebe:** Verificação inicial da Meta.
+
+**Query Params:**
+- `hub.mode=subscribe`
+- `hub.challenge={token}`
+- `hub.verify_token={verify_token}`
+
+**Comportamento:**
+1. Valida `hub.verify_token`
+2. Retorna `hub.challenge`
+
+---
+
+#### 3. POST /webhooks/connections
+
+**Recebe:** Verificação de conexão WhatsApp.
+
+**Comportamento:**
+1. Extrai `connectionId` do payload
+2. Busca conexão na Naty API
+3. Obtém info da conta na Meta API
+4. Emite evento `'connection'`
+5. Retorna 200 OK
+
+---
+
+#### 4. GET /webhooks/connections
+
+**Recebe:** Verificação inicial (similar a messages).
+
+---
+
+## 📊 Diagramas de Integração
+
+### Diagrama de Sequência - Envio de Mensagem
+
+```mermaid
+sequenceDiagram
+    participant App as Aplicação
+    participant SDK as SDK Naty
+    participant Naty as Naty API
+    participant Meta as Meta Graph API
+    participant WA as WhatsApp
+    participant Client as Cliente Final
+    
+    App->>SDK: send_text({ to, message })
+    
+    SDK->>Naty: GET /connection<br/>(buscar credenciais)
+    Naty-->>SDK: { accessToken, appId, appSecret }
+    
+    SDK->>Meta: POST /oauth/access_token<br/>(refresh token)
+    Meta-->>SDK: { access_token: newToken }
+    
+    SDK->>Naty: PUT /connection<br/>(salvar novo token)
+    
+    SDK->>Meta: POST /{phoneNumberId}/messages<br/>{ to, type: 'text', text }
+    Meta->>WA: Processa mensagem
+    WA->>Client: Entrega via WhatsApp
+    Meta-->>SDK: { messages: [{ id }] }
+    
+    SDK->>Naty: POST /logs<br/>(registrar operação)
+    
+    SDK-->>App: Either.right({ id })
+```
+
+---
+
+### Diagrama de Sequência - Recebimento de Mensagem
+
+```mermaid
+sequenceDiagram
+    participant Client as Cliente Final
+    participant WA as WhatsApp
+    participant Meta as Meta Webhook
+    participant Express as Express/Webhook
+    participant SDK as SDK Events
+    participant App as Aplicação
+    
+    Client->>WA: Envia mensagem
+    WA->>Meta: Processa
+    
+    Meta->>Express: POST /webhooks/messages<br/>{ entry: [...] }
+    
+    Express->>Express: Parse payload
+    Express->>SDK: emit('message', data)
+    
+    SDK->>App: Listener recebe evento
+    
+    App->>App: Processa lógica<br/>(chatbot, IA, etc.)
+    
+    App->>SDK: whatsappResponse.send_text()
+    SDK->>Meta: POST /messages
+    Meta->>WA: Envia resposta
+    WA->>Client: Recebe resposta
+    
+    Express-->>Meta: 200 OK
+```
+
+---
+
+## ⏱ Rate Limits e Throttling
+
+### Limites da Meta
+
+| Recurso | Limite |
+|---------|--------|
+| **Mensagens** | Varia por Tier (1k - 100k/dia) |
+| **API Calls** | ~200 requisições/hora por token |
+| **Upload Mídia** | 100 MB/dia por número |
+| **Webhook Retries** | 3 tentativas com exponential backoff |
+
+### Estratégias de Throttling
+
+**1. Queue de Mensagens (Recomendado)**
+
+```typescript
+import PQueue from 'p-queue';
+
+// Fila com limite de 10 mensagens/segundo
+const queue = new PQueue({ 
+  interval: 1000, 
+  intervalCap: 10 
+});
+
+// Adicionar envios à fila
+const sendthrottled = (to: string, message: string) => {
+  return queue.add(() => whatsapp.send_text({ to, message }));
+};
+
+// Uso
+await sendThrottled('5511999999999', 'Mensagem 1');
+await sendThrottled('5511888888888', 'Mensagem 2');
+// ...
+```
+
+**2. Retry com Exponential Backoff**
+
+```typescript
+async function sendWithRetry(to: string, message: string, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    const result = await whatsapp.send_text({ to, message });
+    
+    if (result.isRight()) {
+      return result;
+    }
+    
+    // Se erro 429 (rate limit), aguardar antes de retry
+    if (result.value.statusCode === 429) {
+      const waitTime = Math.pow(2, i) * 1000; // 1s, 2s, 4s
+      console.log(`Rate limit hit. Waiting ${waitTime}ms...`);
+      await new Promise(resolve => setTimeout(resolve, waitTime));
+    } else {
+      return result; // Outro erro, não retry
+    }
+  }
+  
+  return left(new Error('Max retries exceeded'));
+}
+```
+
+---
+
+## 🔒 Segurança e Autenticação
+
+### Hierarquia de Credenciais
+
+```mermaid
+graph TD
+    A[appToken<br/>Naty Platform] --> B[companyId<br/>Tenant]
+    B --> C1[Connection 1<br/>accessToken Meta]
+    B --> C2[Connection 2<br/>accessToken Meta]
+    
+    C1 --> D1[phoneNumberId 1<br/>WhatsApp Number]
+    C2 --> D2[phoneNumberId 2<br/>WhatsApp Number]
+    
+    style A fill:#E3F2FD
+    style B fill:#BBDEFB
+    style C1 fill:#90CAF9
+    style C2 fill:#90CAF9
+    style D1 fill:#64B5F6,color:#fff
+    style D2 fill:#64B5F6,color:#fff
+```
+
+### Boas Práticas
+
+1. **Nunca commitar tokens:**
+   ```bash
+   # .env
+   NATY_APP_TOKEN=seu_token_aqui
+   API_META=https://api.meta.naty.app/v1
+   ```
+
+2. **Rotacionar tokens periodicamente:**
+   - Tokens Meta expiram em 60 dias
+   - Refresh automático implementado pelo SDK
+
+3. **Validar webhooks da Meta:**
+   ```typescript
+   // Verificar se requisição vem da Meta
+   const validateWebhook = (req: Request) => {
+     const signature = req.headers['x-hub-signature-256'];
+     // Validar HMAC SHA256 com app secret
+     // (Implementado internamente no SDK)
+   };
+   ```
+
+4. **HTTPS obrigatório:**
+   - Webhooks devem usar HTTPS
+   - Certificado SSL válido
+
+5. **Logging de acessos:**
+   - Todas operações são logadas automaticamente
+   - Logs contêm IP, timestamp, ação
+
+---
+
+## 🔗 Próximos Passos
+
+Com as integrações compreendidas, explore:
+
+- **[Entidades](06-entidades.md)** - Estrutura de dados detalhada
+- **[Guia Prático](07-guia-pratico.md)** - Exemplos práticos de integração
+- **[Troubleshooting](08-troubleshooting.md)** - Resolver problemas de integração
+
+---
+
+[⬅️ Anterior: Fluxos Funcionais](04-fluxos-funcionais.md) | [⬆️ Voltar ao Índice](README.md) | [➡️ Próximo: Entidades](06-entidades.md)