Automatización de WhatsApp para E-commerce: La Guía Técnica (API REST)

¿Tus clientes escriben por WhatsApp y no reciben respuesta? Descubre cómo una solución multiagente evita mensajes perdidos, mejora tiempos de respuesta y convierte más ventas.
CONTÁCTANOS

En e-commerce cada minuto cuenta: confirmaciones de pago, avisos de envío, recordatorios de carrito abandonado, soporte en vivo… y casi todo eso hoy ocurre en WhatsApp.

En lugar de atender todo “a mano”, puedes automatizar estos flujos conectando tu tienda online con una API REST de WhatsApp como WhatzMeAPI, que expone endpoints HTTP para enviar y recibir mensajes desde tu propio código.

En esta guía veremos cómo diseñar e implementar esa integración de forma técnica y ordenada, usando como referencia la documentación oficial en Postman:
👉 https://documenter.getpostman.com/view/4045446/2s847PJ9PF

---

1. Arquitectura básica: E-commerce + API REST de WhatsApp

A nivel alto, la arquitectura típica para automatizar WhatsApp en un e-commerce luce así:

1. Cliente
   • Navega tu tienda, compra, paga, abandona el carrito o abre un ticket de soporte.
2. Plataforma de E-commerce / Backend
   • WooCommerce, Shopify (con app personalizada), VTEX, Magento, Laravel, Node, Spring, etc.
   • Genera eventos: orden_creada, pago_confirmado, pedido_enviado, carrito_abandonado.
3. Servicio de Integración WhatsApp (tu microservicio)
   • Servicio propio (por ejemplo, en Node.js, PHP o Java) que:
     • Recibe esos eventos del e-commerce (webhooks o colas).
     • Construye el mensaje (plantilla + variables).
     • Llama a la API REST de WhatsApp (WhatzMeAPI) vía HTTP.
4. WhatzMeAPI (API REST de WhatsApp)
   • Valida tu API key, procesa el mensaje y lo envía al número del cliente a través de WhatsApp.
5. Webhooks de recepción
   • Cuando el cliente responde, WhatzMeAPI envía la información a tu endpoint de webhook para que actualices tu CRM, tickets, etc.

---

2. Requisitos técnicos para empezar

Para trabajar con WhatzMeAPI en un proyecto de e-commerce necesitarás:

• Cuenta activa en WhatzMeAPI y acceso al panel.
• Token o API Key para autenticar tus peticiones HTTP.
• Base URL de tu instancia (por ejemplo, https://tu-instancia.whatzmeapi.com), indicada en la doc.
• Número de WhatsApp vinculado, generalmente mediante un QR desde el panel.
• Un backend donde implementar la lógica (PHP, Node.js, Java, .NET, etc.).
• Un endpoint público para webhooks, con HTTPS, donde recibirás mensajes entrantes y eventos (entregado, leído, etc.).
• Buen manejo de:
  • JSON
  • HTTP (códigos 2xx, 4xx, 5xx)
  • Logs y tratamiento de errores

La referencia formal de endpoints, parámetros y ejemplos la tienes en:
👉 https://documenter.getpostman.com/view/4045446/2s847PJ9PF programaenlinea.net

---

3. Casos de uso clave en E-commerce

Antes de tocar código, define qué quieres automatizar. Algunos flujos típicos:

1. Confirmaciones de pedido
   • Evento: orden creada o pago confirmado.
   • Mensaje: “Hola, {{nombre}} 👋 Tu pedido #{{orden}} por ${{total}} se registró correctamente. Te avisaremos en cuanto salga a envío.”
2. Actualizaciones de envío
   • Estado: preparando envío, en tránsito, entregado.
   • Incluye: número de guía, link de rastreo y fecha estimada.
3. Recuperación de carrito abandonado
   • Detectas carritos sin completar después de X minutos/horas.
   • Mensaje con link directo al carrito, cupón de descuento opcional.
4. Notificaciones de soporte
   • Apertura de ticket.
   • Cambios de estado del ticket.
   • Cierre de caso y encuesta de satisfacción.
5. Promociones segmentadas (con opt-in)
   • Ofertas por categoría.
   • Recordatorios de “últimas piezas” o “termina tu compra con 10% OFF”.

Cada caso de uso se traduce en un endpoint concreto de la API (generalmente “enviar mensaje”) + una plantilla de texto que rellenas con datos de tu base.

---

4. Integración paso a paso con la API REST (WhatzMeAPI)

4.1. Autenticación y headers

En la documentación de WhatzMeAPI verás qué header usar para tu token (por ejemplo Authorization: Bearer <TOKEN> o x-api-key: <TOKEN> según la versión).

En todos tus requests:

• Usa HTTPS.
• Incluye Content-Type: application/json.
• Envía la API key solo desde el backend (nunca desde el frontend del navegador).

4.2. Enviar un mensaje transaccional

Un flujo típico:

1. Tu e-commerce genera el evento orden_pagada.
2. Tu backend arma el payload JSON con:
   • número de WhatsApp del cliente (incluyendo país),
   • tipo de mensaje (texto, imagen, etc.),
   • contenido (plantilla + variables).
3. Tu servicio llama al endpoint de envío de mensajes de WhatzMeAPI (consultar ruta específica en Postman).
4. Analizas la respuesta (id de mensaje, estado inicial, errores).

Ejemplo genérico de request (estructura orientativa):

POST https://tu-instancia.whatzmeapi.com/api/messages/send
Content-Type: application/json
Authorization: Bearer TU_API_KEY

{
  "to": "5215555555555",
  "type": "text",
  "message": "Hola Ana 👋, tu pedido #12345 ha sido confirmado. Gracias por comprar con nosotros."
}

Nota: Nombres de campos (to, type, message) son ilustrativos; verifica en la documentación oficial cuáles debes usar exactamente.

4.3. Plantillas reutilizables

Para mantener orden y consistencia:

• Define plantillas como objetos reutilizables en tu código o en BD:
  • plantilla_confirmacion_pago
  • plantilla_envio_en_camino
  • plantilla_carrito_abandonado
• Incluye placeholders: {{nombre}}, {{id_orden}}, {{total}}, {{url_tracking}}.
• En tiempo de ejecución, reemplaza placeholders con datos reales antes de llamar a la API.

Si WhatzMeAPI soporta plantillas registradas o tipos de mensaje específicos (como botones, etc.), también vendrán en la documentación de Postman.

4.4. Webhooks para respuestas y estados

Configura en el panel de WhatzMeAPI tu URL de webhook, por ejemplo:

https://mi-dominio.com/webhooks/whatsapp

Ahí recibirás:

• Mensajes entrantes (cliente responde “Tengo una duda”, “Quiero cambiar dirección”, etc.).
• Eventos de entrega y lectura (delivered, read).
• Errores (número inválido, sesión no vinculada, etc.).

Tu endpoint debe:

1. Validar la firma o token del webhook si existe.
2. Registrar el contenido en tu BD (historial de chat).
3. Disparar lógica:
   • Crear o actualizar ticket de soporte.
   • Notificar a un agente humano.
   • Activar un flujo de chatbot.

---

5. Buenas prácticas técnicas en producción

5.1. Manejo de errores y reintentos

• Loggea siempre:
  • Request (sin incluir credenciales)
  • Response (código HTTP, cuerpo, timestamps).
• Implementa reintentos con backoff para errores 5xx (problemas temporales).
• Para errores 4xx (token inválido, número malformado):
  • Marca el mensaje como fallido.
  • Guarda el motivo en BD para diagnóstico.

5.2. Idempotencia

Para notificaciones críticas (ej. confirmación de pago):

• Usa un idempotency key (por ejemplo, id de orden).
• Antes de enviar, revisa si ya existe un mensaje exitoso para esa orden.
• Evitas duplicar mensajes si tu e-commerce reintenta el webhook o el job.

5.3. Seguridad

• Nunca expongas la API Key en el front; guárdala en variables de entorno.
• Limita acceso al endpoint de webhook:
  • IP allowlist (si el proveedor expone su rango).
  • Secret token en headers.
• Asegura HTTPS con certificados válidos.

5.4. Escalabilidad

Cuando tu volumen crece:

• Separa el microservicio de mensajería del resto del backend.
• Usa colas (RabbitMQ, Kafka, SQS, etc.) para encolar eventos como:
  • pedido_confirmado
  • pedido_enviado
  • carrito_abandonado_detectado
• Un worker consume la cola y llama a WhatzMeAPI, evitando saturar tu API principal.

---

6. Cumplimiento con políticas de WhatsApp Business

Aunque trabajes con un proveedor como WhatzMeAPI, las reglas de WhatsApp Business sobre opt-in, tipos de mensajes y ventanas de tiempo siguen aplicando.

Puntos clave:

• Obtén consentimiento (opt-in) para mensajes promocionales.
• Usa principalmente mensajes transaccionales (estado de pedido, pagos, envíos).
• Respeta la ventana de tiempo autorizada para iniciar conversaciones (según el tipo de mensaje).
• Evita spam; si muchos usuarios reportan tus mensajes, puede verse afectada tu reputación.

---

7. Ejemplo de flujo: Carrito abandonado automatizado

1. Cliente agrega productos pero no finaliza compra.
2. Tu e-commerce genera un evento carrito_abandonado tras 30–60 minutos.
3. Tu backend envía a la cola un mensaje con:
   • id_cliente
   • número de WhatsApp
   • link al carrito
   • valor estimado del carrito.
4. El worker procesa el evento:
   • Toma la plantilla de carrito.
   • Inserta variables (nombre, link, posible cupón).
   • Llama a WhatzMeAPI vía API REST.
5. Si el cliente responde por WhatsApp:
   • El webhook de WhatzMeAPI notifica a tu sistema.
   • Un bot o agente humano continúa la conversación.

Este mismo patrón lo puedes aplicar a:

• Upselling post-compra (productos relacionados).
• Reactivación de clientes inactivos.
• Encuestas de satisfacción tras la entrega.

---

8. Checklist para lanzar a producción

Antes de ir a producción, verifica que:

• Tienes una cuenta funcional en WhatzMeAPI con número vinculado.
• Guardas la API Key en variables de entorno y no en el código.
• Probaste todos los flujos clave usando la colección de Postman:
  👉 https://documenter.getpostman.com/view/4045446/2s847PJ9PF
• Implementaste logs y monitoreo (tasa de éxito, errores 4xx/5xx).
• Tus plantillas tienen variables bien validadas (sin null ni datos rotos).
• Tu endpoint de webhook es seguro y robusto.
• Cumples las políticas de opt-in y uso de la plataforma de WhatsApp Business.

Conoce WhatzMeAPI (API REST + Chatbot): WhatzMeApi