@oficialapi/sdk 7.0.0 → 9.0.0

package/README.md

@@ -341,32 +341,35 @@ await sdk.whatsapp.sendDocument({
 
 #### Enviar Pedido com Opções de Pagamento
 
+> **⚠️ Nota Importante:** O status do pedido deve ser `pending` ao usar `sendOrderDetails`. Use `sendOrderStatus` para atualizar o status após o pagamento.
+
+**Exemplo 1: Pedido Digital com PIX**
+
 ```typescript
 await sdk.whatsapp.sendOrderDetails({
-  token: 'sk_live_...',
+  token: 'sk_live_9999999999999999999999999',
   sender: '5511999999999',
-  headerText: 'Confirmação de Pedido', // Opcional
+  headerText: 'Confirmação de Pedido',
   bodyText: 'Seu pedido #12345 está pronto para pagamento!',
-  footerText: 'Obrigado por comprar conosco!', // Opcional
-  reference_id: 'pedido_12345_1704067200', // ID único do pedido
-  type: 'digital-goods', // ou 'physical-goods'
+  footerText: 'Obrigado por comprar conosco!',
+  reference_id: 'pedido_12345_1704067200',
+  type: 'digital-goods',
   currency: 'BRL',
   total_amount: {
-    value: 50000, // Valor em centavos (500.00)
-    offset: 100, // Fator de ajuste (sempre 100 para BRL)
-    description: 'Total do pedido' // Opcional
+    value: 50000,
+    offset: 100
   },
   order: {
-    status: 'pending',
+    status: 'pending', // OBRIGATÓRIO: deve ser 'pending' para review_and_pay
     items: [
       {
         retailer_id: '1234567',
-        name: 'Produto 1',
+        name: 'Cake',
         amount: {
           value: 50000,
           offset: 100
         },
-        quantity: 2
+        quantity: 1
       }
     ],
     subtotal: {
@@ -377,39 +380,248 @@ await sdk.whatsapp.sendOrderDetails({
       value: 0,
       offset: 100,
       description: 'Sem impostos'
+    }
+  },
+  payment_settings: [
+    {
+      type: 'pix_dynamic_code',
+      pix_dynamic_code: {
+        code: '00020101021226700014br.gov.bcb.pix2548pix.example.com...',
+        merchant_name: 'Minha Empresa Ltda',
+        key: '39580525000189',
+        key_type: 'CNPJ'
+      }
+    }
+  ]
+}, accessToken);
+```
+
+**Exemplo 2: Pedido Digital com Link de Pagamento**
+
+```typescript
+await sdk.whatsapp.sendOrderDetails({
+  token: 'sk_live_9999999999999999999999999',
+  sender: '5511999999999',
+  bodyText: 'Sua fatura está disponível para pagamento!',
+  reference_id: 'fatura_67890_1704067200',
+  type: 'digital-goods',
+  currency: 'BRL',
+  total_amount: {
+    value: 150000,
+    offset: 100
+  },
+  order: {
+    status: 'pending',
+    items: [
+      {
+        retailer_id: 'item_001',
+        name: 'Serviço Premium',
+        amount: {
+          value: 150000,
+          offset: 100
+        },
+        quantity: 1
+      }
+    ],
+    subtotal: {
+      value: 150000,
+      offset: 100
     },
-    shipping: { // Opcional
-      value: 1000,
-      offset: 100,
-      description: 'Frete'
+    tax: {
+      value: 0,
+      offset: 100
+    }
+  },
+  payment_settings: [
+    {
+      type: 'payment_link',
+      payment_link: {
+        uri: 'https://pagamento.exemplo.com/fatura/67890'
+      }
+    }
+  ]
+}, accessToken);
+```
+
+**Exemplo 3: Pedido Digital com Boleto**
+
+```typescript
+await sdk.whatsapp.sendOrderDetails({
+  token: 'sk_live_9999999999999999999999999',
+  sender: '5511999999999',
+  bodyText: 'Sua inscrição está confirmada! Efetue o pagamento via boleto.',
+  reference_id: 'inscricao_11111_1704067200',
+  type: 'digital-goods',
+  currency: 'BRL',
+  total_amount: {
+    value: 29900,
+    offset: 100
+  },
+  order: {
+    status: 'pending',
+    items: [
+      {
+        retailer_id: 'curso_001',
+        name: 'Curso de Programação',
+        amount: {
+          value: 29900,
+          offset: 100
+        },
+        quantity: 1
+      }
+    ],
+    subtotal: {
+      value: 29900,
+      offset: 100
     },
-    discount: { // Opcional
-      value: 5000,
+    tax: {
+      value: 0,
+      offset: 100
+    }
+  },
+  payment_settings: [
+    {
+      type: 'boleto',
+      boleto: {
+        digitable_line: '03399026944140000002628346101018898510000008848'
+      }
+    }
+  ]
+}, accessToken);
+```
+
+**Exemplo 4: Pedido Físico com Múltiplas Formas de Pagamento (PIX + Link)**
+
+```typescript
+await sdk.whatsapp.sendOrderDetails({
+  token: 'sk_live_9999999999999999999999999',
+  sender: '5511999999999',
+  bodyText: 'Seu pedido está pronto! Escolha a forma de pagamento:',
+  reference_id: 'pedido_completo_22222_1704067200',
+  type: 'physical-goods',
+  currency: 'BRL',
+  total_amount: {
+    value: 262400, // subtotal (259900) + tax (0) + shipping (2500) - discount (0)
+    offset: 100
+  },
+  order: {
+    status: 'pending',
+    catalog_id: '1234567890',
+    items: [
+      {
+        retailer_id: 'produto_001',
+        name: 'Camiseta Básica',
+        amount: {
+          value: 79000,
+          offset: 100
+        },
+        quantity: 2
+      },
+      {
+        retailer_id: 'produto_002',
+        name: 'Calça Jeans',
+        amount: {
+          value: 101900,
+          offset: 100
+        },
+        quantity: 1
+      }
+    ],
+    subtotal: {
+      value: 259900,
+      offset: 100
+    },
+    tax: {
+      value: 0,
+      offset: 100
+    },
+    shipping: {
+      value: 2500,
       offset: 100,
-      description: 'Desconto',
-      discount_program_name: 'Promoção'
+      description: 'Frete via SEDEX'
     }
   },
-  payment_settings: [ // Opcional, máximo 2 métodos
+  payment_settings: [
     {
       type: 'pix_dynamic_code',
       pix_dynamic_code: {
         code: '00020101021226700014br.gov.bcb.pix2548pix.example.com...',
-        merchant_name: 'Minha Empresa Ltda',
-        key: '39580525000189',
-        key_type: 'CNPJ' // CPF, CNPJ, EMAIL, PHONE ou EVP
+        merchant_name: 'Minha Loja Virtual',
+        key: 'minhaloja@email.com',
+        key_type: 'EMAIL'
       }
     },
     {
       type: 'payment_link',
       payment_link: {
-        uri: 'https://pagamento.exemplo.com/pedido/123'
+        uri: 'https://minhaloja.com/pagar/22222'
       }
     }
   ]
 }, accessToken);
 ```
 
+**Exemplo 5: Pedido com Desconto (Black Friday)**
+
+```typescript
+await sdk.whatsapp.sendOrderDetails({
+  token: 'sk_live_9999999999999999999999999',
+  sender: '5511999999999',
+  bodyText: 'Black Friday! Seu pedido com desconto especial:',
+  reference_id: 'black_friday_33333_1704067200',
+  type: 'digital-goods',
+  currency: 'BRL',
+  total_amount: {
+    value: 39900, // subtotal (49900) + tax (0) + shipping (0) - discount (10000)
+    offset: 100
+  },
+  order: {
+    status: 'pending',
+    items: [
+      {
+        retailer_id: 'bf_001',
+        name: 'Pacote Premium',
+        amount: {
+          value: 49900,
+          offset: 100
+        },
+        quantity: 1
+      }
+    ],
+    subtotal: {
+      value: 49900,
+      offset: 100
+    },
+    tax: {
+      value: 0,
+      offset: 100
+    },
+    discount: {
+      value: 10000,
+      offset: 100,
+      description: 'Desconto Black Friday 20%',
+      discount_program_name: 'Black Friday 2024'
+    }
+  },
+  payment_settings: [
+    {
+      type: 'pix_dynamic_code',
+      pix_dynamic_code: {
+        code: '00020101021226700014br.gov.bcb.pix2548pix.example.com...',
+        merchant_name: 'Black Friday Loja',
+        key: '5511999999999',
+        key_type: 'PHONE'
+      }
+    }
+  ]
+}, accessToken);
+```
+
+**Importante:**
+- O `total_amount.value` deve ser igual a: `subtotal + tax + shipping - discount`
+- O status do pedido deve ser `pending` ao usar `sendOrderDetails`
+- Use `sendOrderStatus` para atualizar o status após o pagamento
+
 #### Atualizar Status do Pedido
 
 ```typescript
@@ -556,16 +768,506 @@ await sdk.whatsapp.createTemplate({
   ]
 }, accessToken);
 
-// Upload de mídia para template ou uso em mensagens
-const file = new File(['...'], 'image.jpg', { type: 'image/jpeg' });
+#### Upload de Mídia
+
+O método `uploadMedia` é usado para fazer upload de arquivos (imagens, vídeos, áudios, documentos) que serão usados em templates ou enviados via `sendAudio`, `sendVideo`, `sendDocument` ou `sendSticker`.
+
+**Exemplo 1: Upload de imagem sem filename (opcional)**
+
+```typescript
+// Em ambiente Node.js
+import fs from 'fs';
+
+const fileBuffer = fs.readFileSync('./imagem.jpg');
+const uploadResult = await sdk.whatsapp.uploadMedia({
+  token: 'sk_live_...',
+  file: fileBuffer
+  // filename é opcional - não será enviado se não fornecido
+}, accessToken);
+
+const mediaId = uploadResult.data.handle; // "4::aW1hZ2UtMTIzNDU2Nzg5MGCE..."
+```
+
+**Exemplo 2: Upload de imagem com filename**
+
+```typescript
+// Em ambiente Node.js
+import fs from 'fs';
+
+const fileBuffer = fs.readFileSync('./imagem.jpg');
+const uploadResult = await sdk.whatsapp.uploadMedia({
+  token: 'sk_live_...',
+  file: fileBuffer,
+  filename: 'minha_imagem.jpg' // Opcional: nome do arquivo
+}, accessToken);
+
+const mediaId = uploadResult.data.handle;
+```
+
+**Exemplo 3: Upload de vídeo (Node.js)**
+
+```typescript
+import fs from 'fs';
+
+const videoBuffer = fs.readFileSync('./video.mp4');
+const uploadResult = await sdk.whatsapp.uploadMedia({
+  token: 'sk_live_...',
+  file: videoBuffer,
+  filename: 'meu_video.mp4'
+}, accessToken);
+
+// Use o mediaId para enviar o vídeo
+await sdk.whatsapp.sendVideo({
+  token: 'sk_live_...',
+  sender: '5511999999999',
+  mediaId: uploadResult.data.handle,
+  caption: 'Confira este vídeo!'
+}, accessToken);
+```
+
+**Exemplo 4: Upload de documento PDF (Node.js)**
+
+```typescript
+import fs from 'fs';
+
+const pdfBuffer = fs.readFileSync('./documento.pdf');
+const uploadResult = await sdk.whatsapp.uploadMedia({
+  token: 'sk_live_...',
+  file: pdfBuffer,
+  filename: 'documento_importante.pdf'
+}, accessToken);
+
+// Use o mediaId para enviar o documento
+await sdk.whatsapp.sendDocument({
+  token: 'sk_live_...',
+  sender: '5511999999999',
+  mediaId: uploadResult.data.handle,
+  filename: 'documento_importante.pdf',
+  caption: 'Aqui está o documento solicitado'
+}, accessToken);
+```
+
+**Exemplo 5: Upload de áudio (Node.js)**
+
+```typescript
+import fs from 'fs';
+
+const audioBuffer = fs.readFileSync('./audio.ogg');
+const uploadResult = await sdk.whatsapp.uploadMedia({
+  token: 'sk_live_...',
+  file: audioBuffer,
+  filename: 'mensagem_audio.ogg'
+}, accessToken);
+
+// Use o mediaId para enviar o áudio
+await sdk.whatsapp.sendAudio({
+  token: 'sk_live_...',
+  sender: '5511999999999',
+  mediaId: uploadResult.data.handle,
+  voice: true // true para mensagem de voz
+}, accessToken);
+```
+
+**Exemplo 6: Upload de sticker (Node.js)**
+
+```typescript
+import fs from 'fs';
+
+const stickerBuffer = fs.readFileSync('./sticker.webp');
+const uploadResult = await sdk.whatsapp.uploadMedia({
+  token: 'sk_live_...',
+  file: stickerBuffer,
+  filename: 'sticker.webp'
+}, accessToken);
+
+// Use o mediaId para enviar o sticker
+await sdk.whatsapp.sendSticker({
+  token: 'sk_live_...',
+  sender: '5511999999999',
+  mediaId: uploadResult.data.handle
+}, accessToken);
+```
+
+**Exemplo 7: Upload em ambiente Browser (Frontend)**
+
+```typescript
+// Em ambiente Browser
+const fileInput = document.querySelector('input[type="file"]');
+const file = fileInput.files[0];
+
 const uploadResult = await sdk.whatsapp.uploadMedia({
   token: 'sk_live_...',
   file: file,
-  filename: 'image.jpg'
+  filename: file.name // Opcional
+}, accessToken);
+
+const mediaId = uploadResult.data.handle;
+```
+
+**Exemplo 8: Upload usando Blob (Browser)**
+
+```typescript
+// Criar um Blob a partir de dados
+const blob = new Blob(['conteúdo do arquivo'], { type: 'text/plain' });
+
+const uploadResult = await sdk.whatsapp.uploadMedia({
+  token: 'sk_live_...',
+  file: blob,
+  filename: 'arquivo.txt'
+}, accessToken);
+
+const mediaId = uploadResult.data.handle;
+```
+
+**Exemplo 9: Upload para usar em template**
+
+```typescript
+import fs from 'fs';
+
+// Upload da imagem para usar no header do template
+const imageBuffer = fs.readFileSync('./logo.jpg');
+const uploadResult = await sdk.whatsapp.uploadMedia({
+  token: 'sk_live_...',
+  file: imageBuffer
+  // filename não é necessário para templates
+}, accessToken);
+
+// Use o handle no template
+await sdk.whatsapp.createTemplate({
+  token: 'sk_live_...',
+  name: 'product_launch',
+  category: 'MARKETING',
+  language: 'pt_BR',
+  components: [
+    {
+      type: 'HEADER',
+      format: 'IMAGE',
+      example: {
+        header_handle: [uploadResult.data.handle] // Use o handle aqui
+      }
+    },
+    {
+      type: 'BODY',
+      text: 'Confira nosso novo produto!'
+    }
+  ]
+}, accessToken);
+```
+
+**Notas importantes:**
+- O parâmetro `filename` é **opcional**. Se não fornecido, não será enviado ao servidor (a API da OficialAPI rejeita campos vazios).
+- O `mediaId` retornado está no formato `"4::aW1hZ2UtMTIzNDU2Nzg5MGCE..."` e deve ser usado diretamente nos métodos `sendAudio`, `sendVideo`, `sendDocument` ou `sendSticker`.
+- Para templates, use o `handle` retornado no campo `header_handle` ou `example.header_handle`.
+- Formatos suportados:
+  - **Imagens**: JPG, PNG, GIF, WEBP
+  - **Vídeos**: MP4, 3GP
+  - **Áudios**: OGG (codec OPUS para voz), MP3, M4A
+  - **Documentos**: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX
+  - **Stickers**: WEBP (até 500KB para animado, 100KB para estático)
+```
+
+**Mais exemplos de templates:**
+
+```typescript
+// Template de atualização de envio (UTILITY)
+await sdk.whatsapp.createTemplate({
+  token: 'sk_live_01JABCDEFGHIJKLMNOPQRSTUVWXYZ',
+  name: 'shipping_update',
+  category: 'UTILITY',
+  language: 'pt_BR',
+  components: [
+    {
+      type: 'BODY',
+      text: 'Ótima notícia! Seu pedido com código #{{1}} já está a caminho. Use o código de rastreio {{2}} para acompanhar.',
+      example: {
+        body_text: [
+          ['ORD12345', 'BR123456789']
+        ]
+      }
+    },
+    {
+      type: 'BUTTONS',
+      buttons: [
+        {
+          type: 'URL',
+          text: 'Rastrear',
+          url: 'https://rastreio.com/track/{{1}}',
+          example: ['ORD12345']
+        },
+        {
+          type: 'QUICK_REPLY',
+          text: 'Entendido'
+        }
+      ]
+    }
+  ],
+  allow_category_change: false
+}, accessToken);
+
+// Template de promoção sazonal (MARKETING)
+await sdk.whatsapp.createTemplate({
+  token: 'sk_live_01JABCDEFGHIJKLMNOPQRSTUVWXYZ',
+  name: 'seasonal_promotion',
+  category: 'MARKETING',
+  language: 'en_US',
+  components: [
+    {
+      type: 'HEADER',
+      format: 'TEXT',
+      text: 'Our {{1}} is on!',
+      example: {
+        header_text: ['Summer Sale']
+      }
+    },
+    {
+      type: 'BODY',
+      text: 'Shop now through {{1}} and use code {{2}} to get {{3}} off all merchandise.',
+      example: {
+        body_text: [
+          ['the end of August', '25OFF', '25%']
+        ]
+      }
+    },
+    {
+      type: 'FOOTER',
+      text: 'Use the buttons below to manage your marketing subscriptions'
+    },
+    {
+      type: 'BUTTONS',
+      buttons: [
+        {
+          type: 'QUICK_REPLY',
+          text: 'Unsubscribe from Promos'
+        },
+        {
+          type: 'QUICK_REPLY',
+          text: 'Unsubscribe from All'
+        }
+      ]
+    }
+  ],
+  allow_category_change: true
+}, accessToken);
+
+// Template com documento PDF (UTILITY)
+await sdk.whatsapp.createTemplate({
+  token: 'sk_live_01JABCDEFGHIJKLMNOPQRSTUVWXYZ',
+  name: 'order_confirmation_pdf',
+  category: 'UTILITY',
+  language: 'en_US',
+  components: [
+    {
+      type: 'HEADER',
+      format: 'DOCUMENT',
+      example: {
+        header_handle: ['4::aW1hZ2UtMTIzNDU2Nzg5MGCE...'],
+        header_text: ['order_receipt.pdf']
+      }
+    },
+    {
+      type: 'BODY',
+      text: 'Thank you for your order, {{1}}! Your order number is {{2}}. Tap the PDF linked above to view your receipt.',
+      example: {
+        body_text: [
+          ['Pablo', '860198-230332']
+        ]
+      }
+    },
+    {
+      type: 'BUTTONS',
+      buttons: [
+        {
+          type: 'PHONE_NUMBER',
+          text: 'Call Support',
+          phone_number: '15550051310'
+        },
+        {
+          type: 'URL',
+          text: 'Contact Support',
+          url: 'https://www.luckyshrub.com/support'
+        }
+      ]
+    }
+  ],
+  allow_category_change: false
 }, accessToken);
 
-// Use o mediaId retornado em sendAudio, sendVideo, sendDocument ou sendSticker
-const mediaId = uploadResult.data.handle; // Formato: "4::aW1hZ2UtMTIzNDU2Nzg5MGCE..."
+// Template de lançamento de produto com imagem (MARKETING)
+await sdk.whatsapp.createTemplate({
+  token: 'sk_live_01JABCDEFGHIJKLMNOPQRSTUVWXYZ',
+  name: 'product_launch',
+  category: 'MARKETING',
+  language: 'pt_BR',
+  components: [
+    {
+      type: 'HEADER',
+      format: 'IMAGE',
+      example: {
+        header_handle: ['4::aW1hZ2UtMTIzNDU2Nzg5MGCE...']
+      }
+    },
+    {
+      type: 'BODY',
+      text: 'Olá {{1}}! Nossa nova coleção {{2}} já está disponível!',
+      example: {
+        body_text: [
+          ['Maria', 'Verão 2025']
+        ]
+      }
+    },
+    {
+      type: 'BUTTONS',
+      buttons: [
+        {
+          type: 'URL',
+          text: 'Ver coleção',
+          url: 'https://loja.com/colecao'
+        },
+        {
+          type: 'QUICK_REPLY',
+          text: 'Compartilhar'
+        }
+      ]
+    }
+  ],
+  allow_category_change: true
+}, accessToken);
+
+// Template de cupom promocional (MARKETING)
+await sdk.whatsapp.createTemplate({
+  token: 'sk_live_01JABCDEFGHIJKLMNOPQRSTUVWXYZ',
+  name: 'coupon_promo',
+  category: 'MARKETING',
+  language: 'pt_BR',
+  components: [
+    {
+      type: 'HEADER',
+      format: 'TEXT',
+      text: '🎉 Oferta Especial!'
+    },
+    {
+      type: 'BODY',
+      text: 'Olá {{1}}! Use o código abaixo para get {{2}} de desconto em toda a loja.',
+      example: {
+        body_text: [
+          ['Maria', '25%']
+        ]
+      }
+    },
+    {
+      type: 'BUTTONS',
+      buttons: [
+        {
+          type: 'COPY_CODE',
+          text: 'Copiar código',
+          example: 'SUMMER25'
+        },
+        {
+          type: 'URL',
+          text: 'Ver loja',
+          url: 'https://loja.com'
+        }
+      ]
+    }
+  ],
+  allow_category_change: true
+}, accessToken);
+
+// Template com parâmetros nomeados (UTILITY)
+await sdk.whatsapp.createTemplate({
+  token: 'sk_live_01JABCDEFGHIJKLMNOPQRSTUVWXYZ',
+  name: 'order_confirmation',
+  category: 'UTILITY',
+  language: 'en_US',
+  components: [
+    {
+      type: 'BODY',
+      text: 'Thank you, {{first_name}}! Your order number is {{order_number}}.',
+      example: {
+        body_text_named_params: [
+          {
+            param_name: 'first_name',
+            example: 'Pablo'
+          },
+          {
+            param_name: 'order_number',
+            example: '860198-230332'
+          }
+        ]
+      }
+    }
+  ],
+  allow_category_change: false
+}, accessToken);
+
+// Template de atualização de entrega com localização (UTILITY)
+await sdk.whatsapp.createTemplate({
+  token: 'sk_live_01JABCDEFGHIJKLMNOPQRSTUVWXYZ',
+  name: 'order_delivery_update',
+  category: 'UTILITY',
+  language: 'en_US',
+  components: [
+    {
+      type: 'HEADER',
+      format: 'LOCATION'
+    },
+    {
+      type: 'BODY',
+      text: 'Good news {{1}}! Your order #{{2}} is on its way to the location above.',
+      example: {
+        body_text: [
+          ['Mark', '566701']
+        ]
+      }
+    },
+    {
+      type: 'FOOTER',
+      text: 'To stop receiving delivery updates, tap the button below.'
+    },
+    {
+      type: 'BUTTONS',
+      buttons: [
+        {
+          type: 'QUICK_REPLY',
+          text: 'Stop Delivery Updates'
+        }
+      ]
+    }
+  ],
+  allow_category_change: false
+}, accessToken);
+
+// Template de mensagem de boas-vindas simples (MARKETING)
+await sdk.whatsapp.createTemplate({
+  token: 'sk_live_01JABCDEFGHIJKLMNOPQRSTUVWXYZ',
+  name: 'welcome_message',
+  category: 'MARKETING',
+  language: 'pt_BR',
+  components: [
+    {
+      type: 'BODY',
+      text: 'Bem-vindo à nossa loja! Estamos felizes em ter você conosco.'
+    },
+    {
+      type: 'FOOTER',
+      text: 'Equipe da Loja'
+    },
+    {
+      type: 'BUTTONS',
+      buttons: [
+        {
+          type: 'QUICK_REPLY',
+          text: 'Ver ofertas'
+        },
+        {
+          type: 'QUICK_REPLY',
+          text: 'Falar no chat'
+        }
+      ]
+    }
+  ],
+  allow_category_change: true
+}, accessToken);
 ```
 
 ### Telegram