# Notifiche d'ordine WhatsApp dal tuo backend

URL: https://wa.genuka.com/it/docs/guides/order-notifications
Language: Italian

> Invia da WhatsApp conferme d'ordine, aggiornamenti di spedizione e di consegna dal tuo backend: modelli di utilità, variabili, idempotenza e stati di consegna.

Per avvisare i clienti di un ordine su WhatsApp, crea un modello di categoria `UTILITY` per ogni
fase (confermato, spedito, consegnato), fallo approvare da Meta, poi chiama `POST /api/v1/messages`
dal tuo backend con le variabili dell'ordine. Il testo libero è consentito solo se il cliente ti ha
scritto nelle ultime 24 ore.

*Ultimo aggiornamento: 8 ottobre 2026*

## Cosa mi serve prima di iniziare?

* Un numero collegato a Genuka WA e il suo `connectionId`: vedi la [guida rapida](https://wa.genuka.com/it/docs/quickstart).
* Una chiave API, usata **solo lato server**: vedi [Autenticazione](https://wa.genuka.com/it/docs/authentication).
* **Un metodo di pagamento sul WhatsApp Business Account, presso Meta.** Genuka è un Meta Tech
  Provider, non un BSP: Meta fattura direttamente l'account, e un cliente registrato tramite un
  Tech Provider deve aggiungere il proprio metodo di pagamento
  ([Meta, Partners](https://developers.facebook.com/documentation/business-messaging/whatsapp/solution-providers/overview)).
  Senza, i modelli vengono approvati ma ogni invio torna indietro con l'errore `131042`: vedi
  [errore 131042](https://wa.genuka.com/it/docs/errors/131042).

## Quali modelli dovrebbe creare un negozio online?

Un modello per ogni momento in cui il cliente aspetta notizie sul suo ordine. Tre bastano per
iniziare:

| Fase              | Modello           | Variabili del corpo    | Pulsante                                  |
| ----------------- | ----------------- | ---------------------- | ----------------------------------------- |
| Ordine confermato | `order_confirmed` | nome, numero, importo  | URL "Vedi il mio ordine"                  |
| Ordine spedito    | `order_shipped`   | nome, numero, corriere | URL "Traccia il mio pacco"                |
| Ordine consegnato | `order_delivered` | nome, numero           | Nessuno: il messaggio invita a rispondere |

Per Meta, un modello di utilità è attivato da un'azione o una richiesta del cliente, è specifico per
quel cliente e non contiene nulla di promozionale. Le conferme d'ordine e gli aggiornamenti di
spedizione sono gli esempi da manuale; un modello che mescola informazioni sull'ordine con
un'offerta, un upsell o una spinta al rinnovo viene ricategorizzato come marketing
([documentazione Meta, categorization](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/template-categorization)).
Tieni le promozioni fuori da questi messaggi.

## Come creo un modello di utilità?

1. ### Invia il modello

   Ogni variabile del corpo richiede un esempio in `example.body_text`, e la variabile di un pulsante
   URL sostituisce solo la **fine** dell'indirizzo, con il suo esempio.

   ```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"] }
         ] }
       ]
     }'
   ```

   Nella dashboard: **Modelli** › **Nuovo modello**, categoria Utilità.

2. ### Attendi l'approvazione

   Il verdetto di Meta arriva come webhook `template_status` (se il tuo endpoint è iscritto a
   `template.status_changed`, o a tutti gli eventi), si può leggere su `GET /api/v1/templates/{id}` e
   si può recuperare con `POST /api/v1/templates/sync` se un webhook è andato perso. Invia solo un
   modello `approved`.

3. ### Imposta una durata di validità se il messaggio diventa obsoleto

   Se un messaggio non può essere consegnato, WhatsApp continua a riprovare per la durata di validità
   del modello: 30 giorni per impostazione predefinita per un modello di utilità, configurabile da 30
   secondi a 12 ore
   ([documentazione Meta, time-to-live](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/time-to-live)).
   Un "il tuo corriere arriva tra 30 minuti" ricevuto il giorno dopo fa più danni che altro: per quel
   tipo di modello, passa `messageSendTtlSeconds` alla creazione.

## Come invio la notifica dal mio backend?

Una chiamata per notifica. `body` riempie `{{1}}`, `{{2}}`, `{{3}}` in ordine (`variables` è un
alias accettato), e `buttons[].text` completa l'URL del pulsante.

**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 };

/** Il corpo della risposta: `data` in caso di successo, altrimenti `error` (più `meta` se Meta ha rifiutato). */
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, // internazionale, con il +: "+237699001122"
      template: {
        name: "order_shipped",
        language: "en", // la lingua esatta del modello, altrimenti l'invio punta a "en_US"
        body: [order.firstName, order.number, order.carrier],
        buttons: [{ type: "url", text: order.number }],
      },
    }),
    signal: AbortSignal.timeout(15_000),
  });

  // Un 5xx della CDN non è JSON: senza questo catch, l'errore di parsing perderebbe `retryable`
  // e la notifica verrebbe archiviata come errore 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 rifiuto permanente (modello, numero) non vale un nuovo tentativo: lo dice meta.retryable.
      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 rifiuto permanente (modello, numero) non vale un nuovo tentativo: lo dice meta.retryable.
        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"],  # internazionale, con il +: "+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 della CDN non è 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, // internazionale, con il +: "+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 rifiuto permanente (modello, numero) non vale un nuovo tentativo: lo dice meta.retryable.
        $retryable = $response->serverError() || $response->json('meta.retryable') === true;
        throw new OrderNotificationFailed($response->json('message') ?? $response->json('error'), $retryable);
    }

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

Chiamala da un job in coda (`ShouldQueue`) invece che dentro la richiesta di checkout: il cliente
non dovrebbe aspettare WhatsApp per vedere la sua pagina di conferma.

**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="Risposta"
{ "data": { "messageId": "wamid.HBg…" } }
```

Un `200` significa che Meta ha accettato il messaggio; segui la consegna via webhook, usando questo
`messageId`. Per inviare lo stesso modello a un intero elenco in una volta, usa invece le
[campagne](https://wa.genuka.com/it/docs/campaigns); ogni tipo di contenuto è descritto in
[Inviare messaggi](https://wa.genuka.com/it/docs/messages).

## Quando posso inviare testo libero invece di un modello?

Quando il cliente ti scrive, si apre una finestra del servizio clienti di 24 ore, e ogni suo nuovo
messaggio la fa ripartire. Finché è aperta puoi rispondere con qualsiasi messaggio; una volta
chiusa, passano solo i modelli approvati
([documentazione Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages)).

Il caso tipico: il cliente risponde all'aggiornamento di spedizione con "Domani non sarò a casa". La
tua risposta può essere testo semplice, citato con `replyTo`:

```json title="POST /api/v1/messages"
{
  "connectionId": "con_1",
  "to": "+237699001122",
  "replyTo": "wamid.HBg…",
  "text": "Ricevuto, il corriere ripasserà giovedì tra le 14 e le 16."
}
```

In fattura, Meta non addebita i messaggi non modello, e anche un modello di utilità consegnato
dentro una finestra aperta è gratuito
([prezzi di Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)).

Fuori dalla finestra, il testo libero fallisce, ma non al momento dell'invio. Nei nostri test su un
numero reale, Meta lo ha accettato con un `messageId` e poi lo ha scartato: di solito segue uno
stato `failed` con l'errore `131047`
([codici di errore di Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes));
a volte non arriva alcuno stato. Quindi non aspettare l'errore: Genuka WA non blocca l'invio, ma ti
avvisa nella risposta, ed è su quell'avviso che devi agire:

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

`outside_service_window` significa che l'ultimo messaggio del cliente risale a più di 24 ore fa:
invia invece un modello. `unverified_service_window` significa solo che non abbiamo in archivio
alcun messaggio in arrivo da quel contatto, il che non prova che la finestra sia chiusa. Segui lo
stato del messaggio e reinvialo come modello solo se arriva `failed` con `131047`, o non arriva
nulla: reinviarlo subito rischia di consegnare due volte la stessa notifica.

## Come evito di inviare due volte la stessa notifica?

L'API non ha una chiave di idempotenza: è il tuo backend a garantire che un ordine riceva ogni
notifica una sola volta. Il modo più semplice è una tabella la cui chiave primaria è la coppia
ordine + fase.

```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,                            -- il wamid restituito da 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. Prenotazione: una seconda chiamata per lo stesso ordine e la stessa fase non fa nulla.
  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. Invia, 3. salva il wamid: è ciò che collega gli stati successivi a questa riga.
    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) {
      // Libera la prenotazione: la prossima esecuzione del job riproverà.
      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 di rete è ambiguo: Meta può aver accettato il messaggio prima che la risposta andasse
persa. Questo codice lo archivia come errore piuttosto che rischiare un duplicato. Se per il tuo
negozio un raro duplicato è meglio di una conferma persa, tratta anche i timeout come ritentabili.

## Come seguo la consegna di ogni notifica?

Gli stati raggiungono il tuo webhook con il tipo `message_status`. `data.id` è il `messageId`
restituito al momento dell'invio, e `data.status` è `sent`, `delivered`, `read` o `failed`. In caso
di errore, `data.errors[0].code` contiene il codice di Meta
([documentazione Meta, statuses](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status)).

```ts title="Nel tuo ricevitore di webhook (firma già verificata)"
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);

  // Gli stati possono arrivare in disordine: uno stato non viene mai declassato,
  // e `failed` è definitivo.
  if (row && row.status !== "failed" && (RANK[status] ?? -1) > RANK[row.status]) {
    await setNotificationStatus(messageId, status, errors?.[0]?.code ?? null);
  }
}
```

Per Meta, `read` significa che il messaggio è stato visualizzato in una chat aperta sul dispositivo
del cliente; non costruire logica di business che lo aspetti. La verifica della firma e la
deduplicazione sono trattate in
[Ricevere risposte e stati via webhook](https://wa.genuka.com/it/docs/guides/receive-messages-webhooks).

## Quali errori incontrerò più spesso?

| Errore                      | Dove leggerlo                        | Significato                                                                           | Cosa fare                                                                                  |
| --------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `400 missing_fields`        | Risposta                             | Manca `connectionId` o `to`                                                           | Completa la richiesta                                                                      |
| `400 recipient_is_sender`   | Risposta                             | `to` è il numero mittente stesso                                                      | Cambia il destinatario                                                                     |
| `402 subscription_past_due` | Risposta                             | La prova o il periodo pagato è scaduto: non si invia nulla finché non viene rinnovato | Rinnova il piano, poi reinvia ciò che `notifyOnce` ha archiviato come `failed`             |
| `402 plan_limit_messages`   | Risposta                             | La quota di messaggi del periodo è esaurita                                           | Aggiungi numeri o cambia piano                                                             |
| `404 connection_not_found`  | Risposta                             | Il `connectionId` non esiste o è fuori dall'ambito della tua chiave                   | Controlla l'id e la chiave                                                                 |
| `409 number_released`       | Risposta                             | Il numero è stato rilasciato dal tuo piano                                            | Ricollegalo tramite l'Embedded Signup                                                      |
| `403 account_deactivated`   | Risposta                             | Il cliente a cui appartiene il numero è sospeso                                       | Ripristina il cliente dalla sua pagina nella dashboard                                     |
| `132001`                    | `meta.code` o stato `failed`         | Modello mancante in quella lingua, o non approvato                                    | Controlla nome, lingua e stato                                                             |
| `132000`                    | `meta.code` o stato `failed`         | Il numero di variabili è diverso da quello del modello                                | Fai corrispondere `body` a `{{1}}`…`{{n}}`                                                 |
| `131026`                    | Stato `failed`                       | Messaggio non consegnabile, ad es. numero senza WhatsApp                              | Ripiega su email o SMS                                                                     |
| `131047`                    | Stato `failed`, a volte mai ricevuto | Testo libero inviato più di 24 h dopo l'ultimo messaggio del cliente                  | Invia un modello; agisci sul `warning` della risposta                                      |
| `130429`                    | `meta.code`                          | Raggiunto il throughput della Cloud API                                               | Riprova con un backoff crescente                                                           |
| `131042`                    | `meta.code` o stato `failed`         | Problema con il metodo di pagamento sull'account Meta                                 | Il cliente sistema la fatturazione lato Meta: vedi [errore 131042](https://wa.genuka.com/it/docs/errors/131042) |

I significati dei codici di Meta vengono dal suo
[elenco dei codici di errore](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes).

## FAQ

### Quanto costa una notifica d'ordine WhatsApp?

Meta addebita i modelli consegnati per categoria e paese del destinatario, fatturati direttamente al
WhatsApp Business Account del commerciante; un modello di utilità consegnato dentro una finestra del
servizio clienti aperta è gratuito
([prezzi di Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)).
Genuka WA non applica ricarichi su queste tariffe: paghi un abbonamento per numero, con una quota di
messaggi: vedi i [piani](https://wa.genuka.com/it#pricing).

### Posso inserire un codice promozionale nella conferma d'ordine?

No. Un'offerta o un upsell dentro un modello di utilità lo fa ricategorizzare come marketing da Meta.
Invia la promozione a parte, in un modello marketing, ai clienti che hanno accettato di riceverle.

### Mi serve il consenso del cliente?

Sì. Meta ti chiede di indicare chiaramente che la persona accetta di ricevere messaggi dalla tua
azienda, e di nominare quell'azienda
([documentazione Meta, opt-in](https://developers.facebook.com/documentation/business-messaging/whatsapp/getting-opt-in)).
Una casella "Ricevi gli aggiornamenti dell'ordine da \[Nome del negozio] su WhatsApp" al checkout,
salvata con l'ordine, soddisfa entrambe le condizioni.

### E se il cliente non ha un account WhatsApp?

Lo stato torna `failed` con il codice `131026`. Non riprovare: invia la stessa informazione via email
o SMS.

### Gestisco più negozi: come scelgo il numero mittente?

Ogni negozio collega il suo numero e ottiene il proprio `connectionId`; è questo che decide da dove
parte il messaggio. Una chiave partner raggiunge tutti i tuoi negozi, una chiave cliente solo uno:
vedi [Autenticazione](https://wa.genuka.com/it/docs/authentication) e, per trovare il numero di un negozio,
[Collegare un numero](https://wa.genuka.com/it/docs/onboarding).

## Fonti

* [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)
