@oficialapi/sdk 5.0.0 → 6.0.0

package/README.md

@@ -39,6 +39,14 @@ const accessToken = tokenResponse.access_token;
 
 ### WhatsApp
 
+> **⚠️ Nota Importante:** Alguns métodos requerem upload prévio da mídia para obter o `mediaId` antes de enviar. Isso se aplica a:
+> - `sendAudio` - Use `uploadMedia` primeiro para obter o `mediaId`
+> - `sendVideo` - Use `uploadMedia` primeiro para obter o `mediaId`
+> - `sendDocument` - Use `uploadMedia` primeiro para obter o `mediaId`
+> - `sendSticker` - Use `uploadMedia` primeiro para obter o `mediaId`
+>
+> O método `sendMedia` ainda aceita `fileUrl` diretamente para imagens e outros tipos de mídia.
+
 #### Enviar Mensagem de Texto
 
 ```typescript
@@ -88,23 +96,22 @@ await sdk.whatsapp.sendTemplate({
 await sdk.whatsapp.sendButtons({
   token: 'sk_live_...',
   sender: '5511999999999',
-  messageText: 'Escolha uma opção:',
+  text: 'Escolha uma opção:',
   buttons: [
     {
-      type: 'reply',
-      reply: {
-        id: 'option1',
-        title: 'Opção 1'
-      }
+      id: 'option1',
+      title: 'Opção 1'
     },
     {
-      type: 'reply',
-      reply: {
-        id: 'option2',
-        title: 'Opção 2'
-      }
+      id: 'option2',
+      title: 'Opção 2'
     }
-  ]
+  ],
+  // Opcional: incluir mídia (imagem) no topo da mensagem
+  media: {
+    type: 'image',
+    url: 'https://example.com/image.jpg'
+  }
 }, accessToken);
 ```
 
@@ -114,7 +121,9 @@ await sdk.whatsapp.sendButtons({
 await sdk.whatsapp.sendList({
   token: 'sk_live_...',
   sender: '5511999999999',
-  messageText: 'Escolha um produto:',
+  headerText: 'Escolha um produto:',
+  bodyText: 'Selecione uma opção abaixo:',
+  footerText: 'Equipe de Vendas', // Opcional
   buttonText: 'Ver Produtos',
   sections: [
     {
@@ -177,33 +186,45 @@ await sdk.whatsapp.sendLocation({
 #### Enviar Áudio
 
 ```typescript
+// Áudio básico (requer upload prévio da mídia)
 await sdk.whatsapp.sendAudio({
   token: 'sk_live_...',
   sender: '5511999999999',
-  audioUrl: 'https://example.com/audio.ogg'
+  mediaId: '1013859600285441', // ID da mídia após upload
+  voice: false // Opcional: false para áudio básico
+}, accessToken);
+
+// Mensagem de voz (arquivo .ogg codec OPUS)
+await sdk.whatsapp.sendAudio({
+  token: 'sk_live_...',
+  sender: '5511999999999',
+  mediaId: '1013859600285441',
+  voice: true // true para mensagem de voz
 }, accessToken);
 ```
 
 #### Enviar Vídeo
 
 ```typescript
+// Requer upload prévio da mídia para obter o mediaId
 await sdk.whatsapp.sendVideo({
   token: 'sk_live_...',
   sender: '5511999999999',
-  videoUrl: 'https://example.com/video.mp4',
-  caption: 'Veja este vídeo!'
+  mediaId: '1166846181421424', // ID da mídia após upload
+  caption: 'Veja este vídeo!' // Opcional
 }, accessToken);
 ```
 
 #### Enviar Documento
 
 ```typescript
+// Requer upload prévio da mídia para obter o mediaId
 await sdk.whatsapp.sendDocument({
   token: 'sk_live_...',
   sender: '5511999999999',
-  documentUrl: 'https://example.com/document.pdf',
-  filename: 'documento.pdf',
-  caption: 'Aqui está o documento'
+  mediaId: '1376223850470843', // ID da mídia após upload
+  filename: 'documento.pdf', // Opcional
+  caption: 'Aqui está o documento' // Opcional
 }, accessToken);
 ```
 
@@ -213,25 +234,66 @@ await sdk.whatsapp.sendDocument({
 await sdk.whatsapp.sendOrderDetails({
   token: 'sk_live_...',
   sender: '5511999999999',
-  orderId: 'ORDER123',
-  orderItems: [
-    {
-      item_code: 'ITEM001',
-      description: 'Produto 1',
-      quantity: 2,
-      price: 50.00
-    }
-  ],
-  orderTotal: 100.00,
+  headerText: 'Confirmação de Pedido', // Opcional
+  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'
   currency: 'BRL',
-  paymentMethods: [
+  total_amount: {
+    value: 50000, // Valor em centavos (500.00)
+    offset: 100, // Fator de ajuste (sempre 100 para BRL)
+    description: 'Total do pedido' // Opcional
+  },
+  order: {
+    status: 'pending',
+    items: [
+      {
+        retailer_id: '1234567',
+        name: 'Produto 1',
+        amount: {
+          value: 50000,
+          offset: 100
+        },
+        quantity: 2
+      }
+    ],
+    subtotal: {
+      value: 50000,
+      offset: 100
+    },
+    tax: {
+      value: 0,
+      offset: 100,
+      description: 'Sem impostos'
+    },
+    shipping: { // Opcional
+      value: 1000,
+      offset: 100,
+      description: 'Frete'
+    },
+    discount: { // Opcional
+      value: 5000,
+      offset: 100,
+      description: 'Desconto',
+      discount_program_name: 'Promoção'
+    }
+  },
+  payment_settings: [ // Opcional, máximo 2 métodos
     {
-      type: 'PIX',
-      name: 'PIX'
+      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
+      }
     },
     {
-      type: 'CREDIT_CARD',
-      name: 'Cartão de Crédito'
+      type: 'payment_link',
+      payment_link: {
+        uri: 'https://pagamento.exemplo.com/pedido/123'
+      }
     }
   ]
 }, accessToken);
@@ -243,19 +305,24 @@ await sdk.whatsapp.sendOrderDetails({
 await sdk.whatsapp.sendOrderStatus({
   token: 'sk_live_...',
   sender: '5511999999999',
-  orderId: 'ORDER123',
-  status: 'SHIPPED',
-  messageText: 'Seu pedido foi enviado!'
+  bodyText: 'Seu pedido foi enviado!',
+  footerText: 'Obrigado!', // Opcional
+  reference_id: 'pedido_12345_1704067200', // Mesmo ID usado em sendOrderDetails
+  order_status: 'shipped', // pending, processing, partially-shipped, shipped, completed, canceled
+  status_description: 'Sua encomenda foi despachada pelos Correios', // Opcional
+  payment_status: 'captured', // Opcional: pending, captured, failed
+  payment_timestamp: 1722445231 // Opcional: timestamp do pagamento em segundos
 }, accessToken);
 ```
 
 #### Enviar Sticker
 
 ```typescript
+// Requer upload prévio da mídia para obter o mediaId
 await sdk.whatsapp.sendSticker({
   token: 'sk_live_...',
   sender: '5511999999999',
-  stickerUrl: 'https://example.com/sticker.webp'
+  mediaId: '798882015472548' // ID da mídia após upload (.webp até 500KB para animado, 100KB para estático)
 }, accessToken);
 ```
 
@@ -265,7 +332,9 @@ await sdk.whatsapp.sendSticker({
 await sdk.whatsapp.sendLocationRequest({
   token: 'sk_live_...',
   sender: '5511999999999',
-  messageText: 'Por favor, compartilhe sua localização'
+  bodyText: 'Por favor, compartilhe sua localização para entregarmos seu pedido.',
+  headerText: 'Confirme sua entrega', // Opcional (máximo 60 caracteres)
+  footerText: 'Sua privacidade é importante' // Opcional (máximo 60 caracteres)
 }, accessToken);
 ```
 
@@ -275,9 +344,15 @@ await sdk.whatsapp.sendLocationRequest({
 await sdk.whatsapp.sendCtaUrl({
   token: 'sk_live_...',
   sender: '5511999999999',
-  messageText: 'Confira nosso site!',
-  buttonText: 'Acessar',
-  url: 'https://example.com'
+  bodyText: 'Confira nosso site!',
+  buttonText: 'Acessar', // Máximo 20 caracteres
+  url: 'https://example.com',
+  header: { // Opcional: cabeçalho com mídia
+    type: 'image', // ou 'video', 'document', 'text'
+    link: 'https://example.com/banner.jpg' // Para image/video/document
+    // ou text: 'Título' para tipo text
+  },
+  footerText: 'Ofertas válidas até 30/11' // Opcional (máximo 60 caracteres)
 }, accessToken);
 ```
 
@@ -287,20 +362,23 @@ await sdk.whatsapp.sendCtaUrl({
 await sdk.whatsapp.sendMediaCarousel({
   token: 'sk_live_...',
   sender: '5511999999999',
-  cards: [
+  bodyText: 'Confira nossas ofertas da semana!', // Obrigatório
+  cards: [ // 2 a 10 cartões
     {
-      card_index: 0,
-      media: { link: 'https://example.com/image1.jpg' },
-      title: 'Produto 1',
-      description: 'Descrição do produto 1',
-      actions: [{ type: 'link', value: 'https://example.com/product1' }]
+      cardIndex: 0,
+      headerType: 'image', // ou 'video'
+      headerLink: 'https://example.com/image1.jpg',
+      bodyText: 'Oferta especial!', // Máximo 160 caracteres
+      buttonText: 'Comprar agora', // Máximo 20 caracteres
+      url: 'https://example.com/product1'
     },
     {
-      card_index: 1,
-      media: { link: 'https://example.com/image2.jpg' },
-      title: 'Produto 2',
-      description: 'Descrição do produto 2',
-      actions: [{ type: 'link', value: 'https://example.com/product2' }]
+      cardIndex: 1,
+      headerType: 'image',
+      headerLink: 'https://example.com/image2.jpg',
+      bodyText: 'Novo lançamento!',
+      buttonText: 'Ver detalhes',
+      url: 'https://example.com/product2'
     }
   ]
 }, accessToken);
@@ -326,8 +404,10 @@ console.log(media.data.size); // Tamanho em bytes
 ```typescript
 await sdk.whatsapp.replyMessage({
   token: 'sk_live_...',
-  messageId: 'wamid.xxx',
-  messageText: 'Esta é uma resposta!'
+  sender: '5511999999999', // Obrigatório
+  messageText: 'Esta é uma resposta!',
+  replyMessageId: 'wamid.xxx', // Opcional: ID da mensagem a responder
+  preview_url: false // Opcional: se true, mostra preview de URLs no texto
 }, accessToken);
 ```
 
@@ -336,8 +416,9 @@ await sdk.whatsapp.replyMessage({
 ```typescript
 await sdk.whatsapp.reactMessage({
   token: 'sk_live_...',
-  messageId: 'wamid.xxx',
-  emoji: '👍'
+  sender: '5511999999999', // Obrigatório
+  emoji: '👍', // Emoji da reação
+  message_id: 'wamid.xxx' // Opcional: ID da mensagem específica a reagir
 }, accessToken);
 ```
 
@@ -364,13 +445,16 @@ await sdk.whatsapp.createTemplate({
   ]
 }, accessToken);
 
-// Upload de mídia para template
+// Upload de mídia para template ou uso em mensagens
 const file = new File(['...'], 'image.jpg', { type: 'image/jpeg' });
-await sdk.whatsapp.uploadMedia({
+const uploadResult = await sdk.whatsapp.uploadMedia({
   token: 'sk_live_...',
   file: file,
   filename: 'image.jpg'
 }, accessToken);
+
+// Use o mediaId retornado em sendAudio, sendVideo, sendDocument ou sendSticker
+const mediaId = uploadResult.data.handle; // Formato: "4::aW1hZ2UtMTIzNDU2Nzg5MGCE..."
 ```
 
 ### Telegram

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oficialapi/sdk",
-  "version": "5.0.0",
+  "version": "6.0.0",
   "description": "SDK oficial da OficialAPI - Integração completa com WhatsApp, Telegram, Facebook, Instagram e WebChat",
   "main": "dist/index.js",
   "module": "dist/index.mjs",