@oficialapi/sdk 4.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/dist/index.d.mts

@@ -87,19 +87,22 @@ interface SendWhatsAppTemplateParams {
 interface SendWhatsAppButtonsParams {
     token: string;
     sender: string;
-    messageText: string;
+    text: string;
     buttons: Array<{
-        type: 'reply';
-        reply: {
-            id: string;
-            title: string;
-        };
+        id: string;
+        title: string;
     }>;
+    media?: {
+        type: string;
+        url: string;
+    };
 }
 interface SendWhatsAppListParams {
     token: string;
     sender: string;
-    messageText: string;
+    headerText: string;
+    bodyText: string;
+    footerText?: string;
     buttonText: string;
     sections: Array<{
         title: string;
@@ -112,13 +115,16 @@ interface SendWhatsAppListParams {
 }
 interface ReplyWhatsAppParams {
     token: string;
-    messageId: string;
+    sender: string;
     messageText: string;
+    replyMessageId?: string;
+    preview_url?: boolean;
 }
 interface ReactWhatsAppParams {
     token: string;
-    messageId: string;
+    sender: string;
     emoji: string;
+    message_id?: string;
 }
 interface CreateTemplateParams {
     token: string;
@@ -149,47 +155,113 @@ interface UploadMediaParams {
 interface SendOrderDetailsParams {
     token: string;
     sender: string;
-    orderId: string;
-    orderItems: Array<{
-        item_code: string;
-        description: string;
-        quantity: number;
-        price: number;
-    }>;
-    orderTotal: number;
+    headerText?: string;
+    bodyText: string;
+    footerText?: string;
+    reference_id: string;
+    type: 'digital-goods' | 'physical-goods';
     currency: string;
-    paymentMethods: Array<{
-        type: 'PIX' | 'CREDIT_CARD' | 'DEBIT_CARD' | 'BANK_TRANSFER';
-        name: string;
+    total_amount: {
+        value: number;
+        offset: number;
+        description?: string;
+    };
+    order: {
+        status: 'pending' | 'processing' | 'partially-shipped' | 'shipped' | 'completed' | 'canceled';
+        catalog_id?: string;
+        items: Array<{
+            retailer_id: string;
+            name: string;
+            amount: {
+                value: number;
+                offset: number;
+                description?: string;
+            };
+            quantity: number;
+            sale_amount?: {
+                value: number;
+                offset: number;
+                description?: string;
+            };
+        }>;
+        subtotal: {
+            value: number;
+            offset: number;
+            description?: string;
+        };
+        tax: {
+            value: number;
+            offset: number;
+            description?: string;
+        };
+        shipping?: {
+            value: number;
+            offset: number;
+            description?: string;
+        };
+        discount?: {
+            value: number;
+            offset: number;
+            description?: string;
+            discount_program_name?: string;
+        };
+        expiration?: {
+            timestamp: string;
+            description: string;
+        };
+    };
+    payment_settings?: Array<{
+        type: 'pix_dynamic_code' | 'payment_link' | 'boleto' | 'offsite_card_pay';
+        pix_dynamic_code?: {
+            code: string;
+            merchant_name: string;
+            key: string;
+            key_type: 'CPF' | 'CNPJ' | 'EMAIL' | 'PHONE' | 'EVP';
+        };
+        payment_link?: {
+            uri: string;
+        };
+        boleto?: {
+            digitable_line: string;
+        };
+        offsite_card_pay?: {
+            last_four_digits: string;
+            credential_id: string;
+        };
     }>;
 }
 interface SendOrderStatusParams {
     token: string;
     sender: string;
-    orderId: string;
-    status: 'PENDING' | 'CONFIRMED' | 'PROCESSING' | 'SHIPPED' | 'DELIVERED' | 'CANCELLED';
-    messageText?: string;
+    bodyText: string;
+    footerText?: string;
+    reference_id: string;
+    order_status: 'pending' | 'processing' | 'partially-shipped' | 'shipped' | 'completed' | 'canceled';
+    status_description?: string;
+    payment_status?: 'pending' | 'captured' | 'failed';
+    payment_timestamp?: number;
 }
 interface SendWhatsAppAudioParams {
     token: string;
     sender: string;
-    audioUrl: string;
+    mediaId: string;
+    voice?: boolean;
 }
 interface SendWhatsAppStickerParams {
     token: string;
     sender: string;
-    stickerUrl: string;
+    mediaId: string;
 }
 interface SendWhatsAppVideoParams {
     token: string;
     sender: string;
-    videoUrl: string;
+    mediaId: string;
     caption?: string;
 }
 interface SendWhatsAppDocumentParams {
     token: string;
     sender: string;
-    documentUrl: string;
+    mediaId: string;
     filename?: string;
     caption?: string;
 }
@@ -246,30 +318,34 @@ interface SendWhatsAppLocationParams {
 interface SendWhatsAppLocationRequestParams {
     token: string;
     sender: string;
-    messageText: string;
+    bodyText: string;
+    headerText?: string;
+    footerText?: string;
 }
 interface SendWhatsAppCtaUrlParams {
     token: string;
     sender: string;
-    messageText: string;
+    bodyText: string;
     buttonText: string;
     url: string;
+    header?: {
+        type: 'text' | 'image' | 'video' | 'document';
+        text?: string;
+        link?: string;
+    };
+    footerText?: string;
 }
 interface SendWhatsAppMediaCarouselParams {
     token: string;
     sender: string;
+    bodyText: string;
     cards: Array<{
-        card_index: number;
-        media: {
-            link?: string;
-            id?: string;
-        };
-        title: string;
-        description: string;
-        actions: Array<{
-            type: 'link';
-            value: string;
-        }>;
+        cardIndex: number;
+        headerType: 'image' | 'video';
+        headerLink: string;
+        bodyText: string;
+        buttonText: string;
+        url: string;
     }>;
 }
 interface DownloadWhatsAppMediaParams {