De Palma Labs, distributore per l'Italia della piattaforma AYROMEX, Meta Tech Provider

Riferimento API

Base URL: https://api.depalmalabs.it. Autenticazione con Authorization: Bearer <chiave>. Scarica la specifica completa in OpenAPI 3.1 o la collection Postman.

post/v1/messages

Invia un messaggio

Testo (solo entro 24 ore dall'ultimo messaggio del destinatario), template approvato o media (link https). Header opzionale `Idempotency-Key`: la stessa chiave con lo stesso corpo restituisce il messaggio già creato (200, header `Idempotent-Replayed: true`). Risposta 202: esito presso Meta non confermato (timeout): non riprovare alla cieca, lo stato arriverà via webhook.

  • Idempotency-Key (header)

Esempio: template

{
  "customer_id": "cus_xxxxxxxx",
  "to": "+393331234567",
  "type": "template",
  "template": {
    "name": "promemoria_appuntamento",
    "language": "it",
    "variables": [
      "Maria",
      "domani alle 10:00"
    ]
  }
}

Esempio: testo

{
  "customer_id": "cus_xxxxxxxx",
  "to": "+393331234567",
  "type": "text",
  "text": {
    "body": "Grazie, a domani!"
  }
}

Esempio: documento

{
  "customer_id": "cus_xxxxxxxx",
  "to": "+393331234567",
  "type": "document",
  "media": {
    "link": "https://esempio.it/fattura-123.pdf",
    "filename": "Fattura 123.pdf",
    "caption": "La tua fattura"
  }
}
RispostaSignificato
200Replay idempotente
201Messaggio accettato
202Esito non confermato da Meta
401Chiave mancante o non valida
402Pagamento Meta mancante sul WABA del cliente
403Cliente sospeso, marketing in pausa o account sospeso
404Cliente non trovato
409Cliente non attivo / Idempotency-Key riusata
422Dati non validi o rifiutati da Meta (codice in error.details.meta_code)
429Limite di velocità o limite giornaliero
503Invii temporaneamente sospesi dalla piattaforma

get/v1/messages/{id}

Stato di un messaggio

  • id (path, obbligatorio): Id della piattaforma (msg_…) o wamid di Meta
RispostaSignificato
200Messaggio
404Non trovato

get/v1/customers

Elenco clienti

RispostaSignificato
200Elenco

post/v1/customers

Crea un cliente

Esempio: cliente

{
  "name": "Centro Estetico Luna",
  "external_ref": "CLI-042"
}
RispostaSignificato
201Creato
422Dati non validi

get/v1/customers/{id}

Dettaglio cliente

  • id (path, obbligatorio): Id cliente (cus_…)
RispostaSignificato
200Cliente
404Non trovato

post/v1/customers/{id}/onboarding-link

Link di onboarding per il cliente finale

Solo chiavi live e account approvato. Il link vale 14 giorni e sostituisce il precedente.

  • id (path, obbligatorio): Id cliente (cus_…)
RispostaSignificato
201Link
402Riepiloghi scaduti da oltre 15 giorni
403Chiave sandbox o account non approvato

get/v1/customers/{id}/templates

Template del cliente

  • id (path, obbligatorio): Id cliente (cus_…)
RispostaSignificato
200Elenco

post/v1/customers/{id}/templates

Crea un template

Inviato a Meta per l'approvazione. Regole: corpo senza variabile all'inizio o alla fine, variabili numerate da {{1}}, esempi in example.body_text. Con chiave sandbox il template è solo locale e risulta subito APPROVED.

  • id (path, obbligatorio): Id cliente (cus_…)

Esempio: promemoria

{
  "name": "promemoria_appuntamento",
  "language": "it",
  "category": "UTILITY",
  "components": [
    {
      "type": "BODY",
      "text": "Ciao {{1}}, ti ricordiamo l'appuntamento di {{2}}. A presto!",
      "example": {
        "body_text": [
          [
            "Maria",
            "domani alle 10:00"
          ]
        ]
      }
    }
  ]
}
RispostaSignificato
201Creato
409Nome e lingua già usati
422Template non valido

delete/v1/customers/{id}/templates

Cancella un template per nome

  • id (path, obbligatorio): Id cliente (cus_…)
  • name (query, obbligatorio)
  • language (query)
RispostaSignificato
200Cancellato
404Non trovato

post/v1/customers/{id}/uploads

Carica l'immagine di esempio di un template

Serve per i template con intestazione IMAGE: Meta vuole l'immagine di esempio caricata, indicata con `components[].example.header_handle: ["<header_handle>"]`. Corpo `multipart/form-data` con il campo `file`, oppure JSON `{ "link": "https://..." }` (scarichiamo noi il file: solo https pubblico, massimo 10 secondi, fino a 3 redirect). Solo JPEG o PNG (controllato sul contenuto, non solo sul content-type), massimo 5 MB; in multipart il limite pratico è circa 4 MB per il tetto di dimensione delle richieste dell'hosting: per file più grandi usa `link`. Con chiave sandbox nessuna chiamata a Meta: `header_handle` è finto (`sandbox:…`) e deterministico, valido solo per i template sandbox.

  • id (path, obbligatorio): Id cliente (cus_…)

Esempio: link

{
  "link": "https://tuo-gestionale.it/immagini/promo-estate.jpg"
}
RispostaSignificato
201Caricata
401Chiave mancante o non valida
403Cliente bloccato
404Cliente non trovato
409Cliente non ancora collegato a WhatsApp (solo chiave live)
413File oltre 5 MB (error.code file_too_large)
422File mancante, vuoto, non JPEG/PNG o diverso dal tipo dichiarato; link non valido o non scaricabile (download_failed); errore Meta (codice in error.details.meta_code)
429Limite di velocità
502Meta non raggiungibile

put/v1/customers/{id}/webhook

Imposta il webhook del cliente

URL https pubblico (porte 443 o 8443). `url: null` disattiva. Il secret di firma è restituito alla prima configurazione o con `rotate_secret: true`.

  • id (path, obbligatorio): Id cliente (cus_…)

Esempio: url

{
  "url": "https://tuo-gestionale.it/whatsapp/webhook"
}
RispostaSignificato
200Configurato
422URL non valido

get/v1/usage

Consumi del mese

Solo messaggi che Meta segna come a pagamento. Fee De Palma Labs più stima del costo Meta (pagato direttamente dal cliente finale).

  • month (query): YYYY-MM (default mese corrente, fuso Europe/Rome)
RispostaSignificato
200Consumi
422Mese non valido