Ir al contenido

Enviar facturas y PDFs por WhatsApp ​

Tu cliente abre WhatsApp mucho antes que su correo. Si tu sistema genera una factura, una cotización o un comprobante, puede mandarlo en PDF a su WhatsApp en la misma petición, con un mensaje.

El envío ​

Los archivos van con multipart/form-data al mismo endpoint de siempre:

bash
curl -X POST "$ZAPPIO_API_URL/api/v1/messages" \
  -H "Authorization: Bearer $ZAPPIO_API_KEY" \
  -H "Idempotency-Key: factura-1042" \
  -F instance="$ZAPPIO_INSTANCE" \
  -F to=5215500000000 \
  -F type=document \
  -F file=@factura-1042.pdf \
  -F filename=factura-1042.pdf \
  -F caption="Hola Ana, aquí está tu factura 1042. ¡Gracias por tu compra!"
  • type=document acepta PDF, texto plano, CSV, ZIP, Word, Excel y PowerPoint, hasta 16 MB.
  • caption es el mensaje que acompaña al archivo (hasta 1024 caracteres); filename es el nombre que verá tu cliente.
  • La respuesta es 202 Accepted: el archivo se envía en segundo plano. Detalles en Multimedia.

Laravel ​

php
use Illuminate\Support\Facades\Http;

$response = Http::withToken(config('services.zappio.key'))
    ->withHeaders(['Idempotency-Key' => "factura-{$invoice->id}"])
    ->attach('file', file_get_contents($invoice->pdfPath()), "factura-{$invoice->id}.pdf")
    ->post(config('services.zappio.url').'/api/v1/messages', [
        'instance' => config('services.zappio.instance'),
        'to' => $invoice->customer_phone,
        'type' => 'document',
        'caption' => "Hola {$invoice->customer_name}, aquí está tu factura {$invoice->id}.",
    ])
    ->throw();

La configuración (services.zappio) está en Enviar WhatsApp desde Laravel.

Node.js ​

js
const { readFile } = require('node:fs/promises');

async function sendInvoice(invoice) {
  const form = new FormData();
  form.append('instance', process.env.ZAPPIO_INSTANCE);
  form.append('to', invoice.customerPhone);
  form.append('type', 'document');
  form.append('caption', `Hola ${invoice.customerName}, aquí está tu factura ${invoice.id}.`);
  form.append('file', new Blob([await readFile(invoice.pdfPath)], { type: 'application/pdf' }), `factura-${invoice.id}.pdf`);

  const res = await fetch(`${process.env.ZAPPIO_API_URL}/api/v1/messages`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.ZAPPIO_API_KEY}`, 'Idempotency-Key': `factura-${invoice.id}` },
    body: form, // fetch pone el Content-Type multipart con su boundary
  });
  const body = await res.json();
  if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
  return body.data.id;
}

Buenas prácticas ​

  • Idempotencia por documento (factura-1042): si tu proceso reintenta, el cliente no recibe la factura dos veces (Idempotencia).
  • Confirma la entrega. Guarda el msg_... y escucha message.delivered y message.read para saber que la factura llegó y fue vista (Webhooks).
  • Antes de enviar a un número nuevo, puedes revisar que tenga WhatsApp con POST /instances/{instance}/contacts/check (hasta 50 números por llamada, no cuenta como mensaje) (Números, perfil y presencia).
  • También imágenes, audio y video con el mismo endpoint: cambia type (Multimedia).

Pruébalo gratis

Crea tu cuenta: 50 mensajes de prueba, sin tarjeta. Después, $400 MXN al mes, IVA incluido, sin cobro por mensaje.