# Notificaciones de pedidos por WhatsApp desde tu backend

URL: https://wa.genuka.com/es/docs/guides/order-notifications
Language: Spanish

> Envía confirmaciones de pedido, avisos de envío y de entrega por WhatsApp desde tu backend: plantillas de utilidad, variables, idempotencia y estados de entrega.

Para notificar a tus clientes sobre un pedido por WhatsApp, crea una plantilla de categoría `UTILITY` por etapa
(confirmado, enviado, entregado), consigue que Meta la apruebe y luego llama a `POST /api/v1/messages` desde
tu backend con las variables del pedido. El texto libre solo se permite si el cliente te escribió
en las últimas 24 horas.

*Última actualización: 8 de octubre de 2026*

## ¿Qué necesito antes de empezar?

* Un número conectado a Genuka WA y su `connectionId` — consulta el [inicio rápido](https://wa.genuka.com/es/docs/quickstart).
* Una clave API, usada **solo del lado del servidor** — consulta [Autenticación](https://wa.genuka.com/es/docs/authentication).
* **Un método de pago en la cuenta de WhatsApp Business, en Meta.** Genuka es un Tech Provider de Meta,
  no un BSP: Meta factura directamente a la cuenta, y un cliente incorporado por un Tech Provider debe agregar
  su propio método de pago
  ([Meta, Partners](https://developers.facebook.com/documentation/business-messaging/whatsapp/solution-providers/overview)).
  Sin él, las plantillas se aprueban, pero cada envío vuelve con el error `131042` — consulta
  [error 131042](https://wa.genuka.com/es/docs/errors/131042).

## ¿Qué plantillas debe crear una tienda en línea?

Una plantilla por cada momento en que el cliente espera noticias de su pedido. Tres bastan
para empezar:

| Etapa             | Plantilla         | Variables del cuerpo          | Botón                                  |
| ----------------- | ----------------- | ----------------------------- | -------------------------------------- |
| Pedido confirmado | `order_confirmed` | nombre, número, monto         | URL "Ver mi pedido"                    |
| Pedido enviado    | `order_shipped`   | nombre, número, transportista | URL "Seguir mi paquete"                |
| Pedido entregado  | `order_delivered` | nombre, número                | Ninguno: el mensaje invita a responder |

Para Meta, una plantilla de utilidad se activa por una acción o una solicitud del cliente, es específica de ese
cliente y no contiene nada promocional. Las confirmaciones de pedido y los avisos de envío son los
ejemplos de manual; una plantilla que mezcla información del pedido con una oferta, una venta adicional o un incentivo
de renovación se recategoriza como marketing
([documentación de Meta, categorización](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/template-categorization)).
Mantén las promociones fuera de estos mensajes.

## ¿Cómo creo una plantilla de utilidad?

1. ### Envía la plantilla

   Cada variable del cuerpo necesita un ejemplo en `example.body_text`, y la variable de un botón URL solo
   reemplaza el **final** de la dirección, con su propio ejemplo.

   ```bash title="POST /api/v1/templates"
   curl -X POST https://wa.genuka.com/api/v1/templates \
     -H "Authorization: Bearer $GENUKA_WA_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "connectionId": "con_1",
       "name": "order_shipped",
       "language": "en",
       "category": "UTILITY",
       "components": [
         { "type": "BODY",
           "text": "Hi {{1}}, your order {{2}} is on its way with {{3}}. Track it with the button below.",
           "example": { "body_text": [["Awa", "ORD-1042", "DHL"]] } },
         { "type": "BUTTONS", "buttons": [
           { "type": "URL", "text": "Track my parcel",
             "url": "https://shop.example.com/track/{{1}}",
             "example": ["https://shop.example.com/track/ORD-1042"] }
         ] }
       ]
     }'
   ```

   En el panel: **Plantillas** › **Nueva plantilla**, categoría Utilidad.

2. ### Espera la aprobación

   El veredicto de Meta llega como un webhook `template_status` (si tu endpoint está suscrito a
   `template.status_changed`, o a todos los eventos), se puede leer en `GET /api/v1/templates/{id}` y
   se puede recuperar con `POST /api/v1/templates/sync` si se perdió un webhook. Envía solo una
   plantilla `approved`.

3. ### Define un tiempo de vida si el mensaje pierde vigencia

   Si un mensaje no se puede entregar, WhatsApp sigue reintentando durante el tiempo de vida de la plantilla: 30 días
   por defecto para una plantilla de utilidad, configurable de 30 segundos a 12 horas
   ([documentación de Meta, time-to-live](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/time-to-live)).
   Un "tu repartidor llega en 30 minutos" recibido al día siguiente hace más daño que bien: para ese
   tipo de plantilla, pasa `messageSendTtlSeconds` al crearla.

## ¿Cómo envío la notificación desde mi backend?

Una llamada por notificación. `body` rellena `{{1}}`, `{{2}}`, `{{3}}` en orden (`variables` es un
alias aceptado), y `buttons[].text` completa la URL del botón.

**Node.js**

```ts title="send-order-shipped.ts"
const API = "https://wa.genuka.com/api/v1";

type Order = { number: string; firstName: string; phone: string; carrier: string };

/** El cuerpo de la respuesta: `data` si tiene éxito; si no, `error` (más `meta` si Meta lo rechazó). */
type ApiResult = {
  data?: { messageId: string };
  error?: string;
  message?: string;
  meta?: { retryable?: boolean; code?: number };
};

export async function sendOrderShipped(order: Order): Promise<string> {
  const response = await fetch(`${API}/messages`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.GENUKA_WA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      connectionId: process.env.GENUKA_WA_CONNECTION_ID,
      to: order.phone, // internacional, con el +: "+237699001122"
      template: {
        name: "order_shipped",
        language: "en", // el idioma exacto de la plantilla; si no, el envío apunta a "en_US"
        body: [order.firstName, order.number, order.carrier],
        buttons: [{ type: "url", text: order.number }],
      },
    }),
    signal: AbortSignal.timeout(15_000),
  });

  // Un 5xx de la CDN no es JSON: sin este catch, el error de parseo perdería `retryable`
  // y la notificación se archivaría como un fallo permanente.
  const result = (await response.json().catch(() => ({}))) as ApiResult;
  if (!response.ok || !result.data) {
    throw Object.assign(new Error(result.message ?? result.error), {
      status: response.status,
      // Un rechazo permanente (plantilla, número) no vale la pena reintentarlo: meta.retryable lo indica.
      retryable: response.status >= 500 || result.meta?.retryable === true,
    });
  }
  return result.data.messageId;
}
```

**Python**

```python title="send_order_shipped.py"
import os

import requests

API = "https://wa.genuka.com/api/v1"


class NotificationError(Exception):
    def __init__(self, status, body):
        super().__init__(body.get("message") or body.get("error"))
        # Un rechazo permanente (plantilla, número) no vale la pena reintentarlo: meta.retryable lo indica.
        self.retryable = status >= 500 or body.get("meta", {}).get("retryable") is True


def send_order_shipped(order):
    response = requests.post(
        f"{API}/messages",
        headers={
            "Authorization": f"Bearer {os.environ['GENUKA_WA_API_KEY']}",
            "User-Agent": "shop/1.0 (+https://shop.example.com)",
        },
        json={
            "connectionId": os.environ["GENUKA_WA_CONNECTION_ID"],
            "to": order["phone"],  # internacional, con el +: "+237699001122"
            "template": {
                "name": "order_shipped",
                "language": "en",
                "body": [order["first_name"], order["number"], order["carrier"]],
                "buttons": [{"type": "url", "text": order["number"]}],
            },
        },
        timeout=15,
    )
    try:
        body = response.json()
    except ValueError:  # un 5xx de la CDN no es JSON
        body = {}
    if not response.ok:
        raise NotificationError(response.status_code, body)
    return body["data"]["messageId"]
```

**PHP (Laravel)**

```php title="app/Notifications/SendOrderShipped.php"
<?php

use Illuminate\Support\Facades\Http;

function sendOrderShipped(Order $order): string
{
    $response = Http::withToken(config('services.genuka_wa.key'))
        ->timeout(15)
        ->post('https://wa.genuka.com/api/v1/messages', [
            'connectionId' => config('services.genuka_wa.connection_id'),
            'to' => $order->phone, // internacional, con el +: "+237699001122"
            'template' => [
                'name' => 'order_shipped',
                'language' => 'en',
                'body' => [$order->first_name, $order->number, $order->carrier],
                'buttons' => [['type' => 'url', 'text' => $order->number]],
            ],
        ]);

    if ($response->failed()) {
        // Un rechazo permanente (plantilla, número) no vale la pena reintentarlo: meta.retryable lo indica.
        $retryable = $response->serverError() || $response->json('meta.retryable') === true;
        throw new OrderNotificationFailed($response->json('message') ?? $response->json('error'), $retryable);
    }

    return $response->json('data.messageId');
}
```

Llámala desde un job en cola (`ShouldQueue`) en lugar de hacerlo dentro de la solicitud del checkout: el cliente
no debería esperar a WhatsApp para ver su página de confirmación.

**curl**

```bash title="POST /api/v1/messages"
curl -X POST https://wa.genuka.com/api/v1/messages \
  -H "Authorization: Bearer $GENUKA_WA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "con_1",
    "to": "+237699001122",
    "template": {
      "name": "order_shipped",
      "language": "en",
      "body": ["Awa", "ORD-1042", "DHL"],
      "buttons": [{ "type": "url", "text": "ORD-1042" }]
    }
  }'
```

```json title="Respuesta"
{ "data": { "messageId": "wamid.HBg…" } }
```

Un `200` significa que Meta aceptó el mensaje; sigue la entrega por webhook usando este `messageId`. Para
enviar la misma plantilla a toda una lista de una vez, usa mejor las [campañas](https://wa.genuka.com/es/docs/campaigns); cada
tipo de contenido se describe en [Enviar mensajes](https://wa.genuka.com/es/docs/messages).

## ¿Cuándo puedo enviar texto libre en lugar de una plantilla?

Cuando el cliente te escribe, se abre una ventana de atención al cliente de 24 horas, y cada nuevo mensaje
suyo la reinicia. Mientras está abierta puedes responder con cualquier mensaje; una vez cerrada, solo pasan las
plantillas aprobadas
([documentación de Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages)).

El caso típico: el cliente responde al aviso de envío con "Mañana no estaré en casa". Tu
respuesta puede ser texto simple, citando el mensaje con `replyTo`:

```json title="POST /api/v1/messages"
{
  "connectionId": "con_1",
  "to": "+237699001122",
  "replyTo": "wamid.HBg…",
  "text": "Anotado, el repartidor volverá el jueves entre las 2 y las 4 p. m."
}
```

En la factura, Meta no cobra los mensajes que no son plantillas, y una plantilla de utilidad entregada
dentro de una ventana abierta también es gratuita
([precios de Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)).

Fuera de la ventana, el texto libre falla, pero no en el momento del envío. En nuestras pruebas con un número real,
Meta lo aceptó con un `messageId` y luego lo descartó: por lo general sigue un estado `failed` con el error
`131047`
([códigos de error de Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes));
a veces no llega ningún estado. Así que no esperes el fallo: Genuka WA no bloquea el
envío, pero te advierte en la respuesta, y es esa advertencia la que debes tener en cuenta:

```json title="200 OK — con una advertencia"
{
  "data": {
    "messageId": "wamid.HBg…",
    "warning": { "code": "outside_service_window", "message": "…" }
  }
}
```

`outside_service_window` significa que el último mensaje del cliente tiene más de 24 horas: envía una
plantilla en su lugar. `unverified_service_window` solo significa que no tenemos registrado ningún mensaje entrante de ese
contacto, lo que no demuestra que la ventana esté cerrada. Vigila el estado del mensaje y
reenvíalo como plantilla solo si llega `failed` con `131047`, o si no llega nada: reenviar de inmediato
puede hacer que la misma notificación se entregue dos veces.

## ¿Cómo evito enviar la misma notificación dos veces?

La API no tiene clave de idempotencia: es tu backend el que garantiza que un pedido reciba cada
notificación una sola vez. La forma más sencilla es una tabla cuya clave primaria es el par pedido + etapa.

```sql title="schema.sql"
create table order_notifications (
  order_id    text        not null,
  event       text        not null,                  -- confirmed | shipped | delivered
  status      text        not null default 'pending',
  message_id  text unique,                            -- el wamid devuelto por Genuka WA
  error_code  integer,
  created_at  timestamptz not null default now(),
  primary key (order_id, event)
);
```

```ts title="notify-once.ts"
import { Pool } from "pg";

const db = new Pool();

export async function notifyOnce(orderId: string, event: string, send: () => Promise<string>) {
  // 1. Reservar: una segunda llamada para el mismo pedido y la misma etapa no hace nada.
  const claimed = await db.query(
    "insert into order_notifications (order_id, event) values ($1, $2) on conflict do nothing",
    [orderId, event],
  );
  if (claimed.rowCount === 0) return;

  try {
    // 2. Enviar, 3. guardar el wamid: es lo que vincula los estados posteriores con esta fila.
    const messageId = await send();
    await db.query(
      "update order_notifications set status = 'sent', message_id = $3 where order_id = $1 and event = $2",
      [orderId, event, messageId],
    );
  } catch (error) {
    if ((error as { retryable?: boolean }).retryable === true) {
      // Liberar la reserva: la próxima ejecución del job lo intentará de nuevo.
      await db.query("delete from order_notifications where order_id = $1 and event = $2", [orderId, event]);
    } else {
      await db.query(
        "update order_notifications set status = 'failed' where order_id = $1 and event = $2",
        [orderId, event],
      );
    }
    throw error;
  }
}

// await notifyOnce(order.id, "shipped", () => sendOrderShipped(order));
```

Un timeout de red es ambiguo: Meta pudo haber aceptado el mensaje antes de que se perdiera la respuesta.
Este código lo archiva como fallo en lugar de arriesgarse a un duplicado. Si, para tu tienda, un duplicado ocasional
es preferible a una confirmación perdida, trata también los timeouts como reintentables.

## ¿Cómo sigo la entrega de cada notificación?

Los estados llegan a tu webhook con el tipo `message_status`. `data.id` es el `messageId` devuelto en el
momento del envío, y `data.status` es `sent`, `delivered`, `read` o `failed`. En caso de fallo,
`data.errors[0].code` contiene el código de Meta
([documentación de Meta, statuses](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status)).

```ts title="En tu receptor de webhooks (firma ya verificada)"
const RANK: Record<string, number> = { pending: 0, sent: 1, delivered: 2, read: 3, failed: 4 };

if (event.type === "message_status") {
  const { id: messageId, status, errors } = event.data;
  const row = await findNotificationByMessageId(messageId);

  // Los estados pueden llegar desordenados: un estado nunca retrocede,
  // y `failed` es definitivo.
  if (row && row.status !== "failed" && (RANK[status] ?? -1) > RANK[row.status]) {
    await setNotificationStatus(messageId, status, errors?.[0]?.code ?? null);
  }
}
```

Para Meta, `read` significa que el mensaje se mostró en un chat abierto en el dispositivo del cliente; no
construyas lógica de negocio que dependa de él. La verificación de la firma y la eliminación de duplicados se explican en
[Recibir respuestas y estados por webhook](https://wa.genuka.com/es/docs/guides/receive-messages-webhooks).

## ¿Con qué errores me encontraré con más frecuencia?

| Error                       | Dónde leerlo                            | Significado                                                                     | Qué hacer                                                                                            |
| --------------------------- | --------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `400 missing_fields`        | Respuesta                               | Falta `connectionId` o `to`                                                     | Completa la solicitud                                                                                |
| `400 recipient_is_sender`   | Respuesta                               | `to` es el propio número emisor                                                 | Cambia el destinatario                                                                               |
| `402 subscription_past_due` | Respuesta                               | La prueba o el período pagado ha vencido: no se envía nada hasta que se renueve | Renueva el plan y luego reenvía lo que `notifyOnce` archivó como `failed`                            |
| `402 plan_limit_messages`   | Respuesta                               | La asignación de mensajes del período se agotó                                  | Agrega números o cambia de plan                                                                      |
| `404 connection_not_found`  | Respuesta                               | El `connectionId` no existe o está fuera del alcance de tu clave                | Verifica el id y la clave                                                                            |
| `409 number_released`       | Respuesta                               | El número se liberó de tu plan                                                  | Vuelve a conectarlo mediante el Embedded Signup                                                      |
| `403 account_deactivated`   | Respuesta                               | El cliente propietario del número está suspendido                               | Restablece el cliente desde su página en el panel                                                    |
| `132001`                    | `meta.code` o estado `failed`           | La plantilla no existe en ese idioma o no está aprobada                         | Verifica el nombre, el idioma y el estado                                                            |
| `132000`                    | `meta.code` o estado `failed`           | El número de variables difiere del de la plantilla                              | Ajusta `body` a `{{1}}`…`{{n}}`                                                                      |
| `131026`                    | Estado `failed`                         | Mensaje imposible de entregar, p. ej. número sin WhatsApp                       | Recurre al correo electrónico o al SMS                                                               |
| `131047`                    | Estado `failed`, a veces nunca recibido | Texto libre enviado más de 24 h después del último mensaje del cliente          | Envía una plantilla; ten en cuenta el `warning` de la respuesta                                      |
| `130429`                    | `meta.code`                             | Se alcanzó el rendimiento máximo de la Cloud API                                | Reintenta con un tiempo de espera creciente                                                          |
| `131042`                    | `meta.code` o estado `failed`           | Problema con el método de pago en la cuenta de Meta                             | El cliente corrige la facturación del lado de Meta — consulta [error 131042](https://wa.genuka.com/es/docs/errors/131042) |

Los significados de los códigos de Meta provienen de su
[lista de códigos de error](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes).

## Preguntas frecuentes

### ¿Cuánto cuesta una notificación de pedido por WhatsApp?

Meta cobra las plantillas entregadas según la categoría y el país del destinatario, y las factura directamente a la
cuenta de WhatsApp Business del comerciante; una plantilla de utilidad entregada dentro de una ventana de atención al cliente abierta
es gratuita
([precios de Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)).
Genuka WA no aplica ningún margen sobre esas tarifas: pagas una suscripción por número, con una asignación de
mensajes — consulta los [planes](https://wa.genuka.com/es#pricing).

### ¿Puedo incluir un código promocional en la confirmación del pedido?

No. Una oferta o una venta adicional dentro de una plantilla de utilidad hace que Meta la recategorice como marketing.
Envía la promoción por separado, en una plantilla de marketing, a los clientes que aceptaron recibirlas.

### ¿Necesito el consentimiento del cliente?

Sí. Meta te pide indicar claramente que la persona acepta recibir mensajes de tu
negocio, y nombrar ese negocio
([documentación de Meta, opt-in](https://developers.facebook.com/documentation/business-messaging/whatsapp/getting-opt-in)).
Una casilla "Recibir las novedades de mi pedido de \[Nombre de la tienda] por WhatsApp" en el checkout, guardada con el pedido,
cumple ambas condiciones.

### ¿Y si el cliente no tiene cuenta de WhatsApp?

El estado vuelve como `failed` con el código `131026`. No lo reintentes: envía la misma información por
correo electrónico o SMS.

### Tengo varias tiendas: ¿cómo elijo el número emisor?

Cada tienda conecta su número y obtiene su propio `connectionId`; eso es lo que decide desde dónde sale el
mensaje. Una clave de socio alcanza todas tus tiendas, una clave de cliente solo una — consulta
[Autenticación](https://wa.genuka.com/es/docs/authentication) y, para encontrar el número de una tienda,
[Conectar un número](https://wa.genuka.com/es/docs/onboarding).

## Fuentes

* [Meta — Template categorization](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/template-categorization)
* [Meta — Time-to-live](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/time-to-live)
* [Meta — Send messages (customer service window)](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages)
* [Meta — Pricing](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)
* [Meta — Status messages webhook](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status)
* [Meta — Error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)
* [Meta — Getting opt-in](https://developers.facebook.com/documentation/business-messaging/whatsapp/getting-opt-in)
* [Meta — Partners (Tech Providers and Solution Partners)](https://developers.facebook.com/documentation/business-messaging/whatsapp/solution-providers/overview)
