API ed esempi di integrazione – Push E2EE / Willy Push

Riassunto

Push normali: registrazione device (token FCM), invio singolo o bulk (send, send_bulk), lista dispositivi (list), statistiche (stats), disiscrizione (unregister), rimozione per token_hash (delete_device).
Push cifrate (E2EE): il client genera coppia di chiavi, invia la chiave pubblica in registrazione (campo public_key in business). Invio tramite send_encrypted.php: il server cifra il payload con la chiave pubblica di ogni device e invia solo enc + ephem; il service worker decifra e mostra la notifica. Lista device con chiave: list_encrypted.php. Rimozione: delete_encrypted_device.php.
Autenticazione: le API di invio, lista cifrata, delete e campagne richiedono gli header X-Willy-App-Id e X-Willy-App-Key. Il server ricava il dominio dall'appId nel proprio database e valida l'header Origin del browser. Solo get-firebase-config è senza autenticazione; firebase_check richiede WILLY_ADMIN_TOKEN. List: paginazione limit (max 200), offset. Vedi api-push/SECURITY.md per rate limit e audit.
Firebase: ogni token è legato al progetto Firebase usato in registrazione. Il client invia firebase_project_id in registrazione; l'invio usa le credenziali del progetto corretto (file in config/firebase-accounts/ o file singolo).
Statistiche: stats.php restituisce total_registrations, total_active_devices, total_inactive_devices, total_push_sent, total_push_failed, total_invalidated_tokens, last_cleanup_at, updated_at. Valgono sia per invii normali sia per invii cifrati.

Base URL e autenticazione

Sostituisci BASE con l'URL della tua installazione (es. https://TUO_SITO.it/api-push). Per le API protette invia gli header:

X-Willy-App-Id: IL_TUO_APP_ID + X-Willy-App-Key: LA_TUA_APP_KEY — autenticazione tramite appId + appKey negli header HTTP

Dominio gestito lato server: il client non invia mai un parametro domain. Il server ricava il dominio dall’appId nel proprio database e valida l’header Origin del browser. Nessun dato di dominio viene inviato dal client.

Content-Type per POST: Content-Type: application/json.

Nota: Il server ricava il dominio dall'app_id. Non inviare mai un dominio dal client.

Sicurezza e tenant: il server ricava il dominio dall'appId nel proprio database. L'header Origin del browser viene validato automaticamente. Ogni richiesta deve includere gli header X-Willy-App-Id e X-Willy-App-Key; il server associa l'appId al dominio corretto senza che il client invii alcun parametro di dominio. Per dettagli su rate limit e audit vedi api-push/SECURITY.md.

Elenco API

Tutte le API in api/ richiedono gli header X-Willy-App-Id e X-Willy-App-Key. Il server ricava il dominio dall'appId. Content-Type per POST: application/json.

Metodo	Endpoint	Auth	Descrizione
GET	`get-firebase-config.php`	No	Config Firebase Web (apiKey, projectId, vapidKey, …) per il client.
GET	`api/firebase_check.php`	Admin	Verifica service account (richiede X-API-TOKEN = WILLY_ADMIN_TOKEN).
POST	`api/register.php`	Sì	Registra/aggiorna device: push_token obbligatorio; app_id e app_key negli header. Opz. platform, device_type, business: public_key, firebase_project_id.
POST	`api/unregister.php`	Sì	Disiscrivi device (push_token, reason?).
POST	`api/heartbeat.php`	Sì	Aggiorna last_seen_at (push_token). Debounce 5 min.
GET	`api/list.php?app_id=...&limit=100&offset=0&platform=...&device_type=...&role=...`	Sì	Lista device attivi (token_hash, no token completo). limit max 200, paginazione con offset.
GET	`api/list_encrypted.php?app_id=...`	Sì	Lista device con public_key (per push cifrate).
GET	`api/stats.php?app_id=...`	Sì	Statistiche dominio (total_push_sent, total_push_failed, total_active_devices, …).
POST	`api/send.php`	Sì	Invio singolo: title, body, url?, target? (token o filtri), data?, icon?, image?, tag?.
POST	`api/send_bulk.php`	Sì	Invio multiplo: title, body, url?, target?, limit? (max server-side 2000).
POST	`api/send_encrypted.php`	Sì	Invio cifrato: title, body, url?, icon?, badge?, image?, tag?, target?, limit?; oppure encrypted_messages[] (E2EE puro).
POST	`api/delete_device.php`	Sì	Rimuovi device (token_hash).
POST	`api/delete_encrypted_device.php`	Sì	Rimuovi device dalla lista push cifrate (token_hash).
GET	`api/campaign_list.php?app_id=...`	Sì	Lista campagne.
POST	`api/campaign_create.php`	Sì	Crea campagna.
POST	`api/campaign_send.php`	Sì	Invia campagna.
GET	`api/campaign_stats.php?app_id=...&campaign_id=...`	Sì	Statistiche campagna.
POST	`api/cleanup_invalid.php`	Sì	Pulizia log e statistiche.

File da mettere nel sito (integrazione push)

Script embed (una riga): <script src="/api-push/embed.js" data-api-base="/api-push"></script> – carica Firebase e espone WillyPush.askPermission(), WillyPush.onForegroundMessage(callback).
Service Worker (push normali): il client deve registrare uno SW che usa la config Firebase (es. api-push/firebase-messaging-sw.php o file statico che legge firebase-messaging-sw.php).
Push cifrate: servono sw-cifrato.php (o SW che gestisce data.enc, data.ephem, data.e2ee), crypto-client.js (WillyPushCrypto per generare chiavi e decifrare), e una pagina che chiama register con public_key e firebase_project_id in business.
Config lato server: api-push/config/firebase_web_config.json (per get-firebase-config e SW), api-push/config/firebase_service_account.json o file in api-push/config/firebase-accounts/*.json per l'invio.

Esempi di chiamate

1. Config Firebase (GET)

cURL

curl -s "BASE/get-firebase-config.php"

JavaScript (fetch)

const config = await fetch(BASE + '/get-firebase-config.php').then(r => r.json());
if (config.error) throw new Error(config.error);
// config.apiKey, config.projectId, config.vapidKey, ...

PHP

$config = json_decode(file_get_contents('https://TUO_SITO.it/api-push/get-firebase-config.php'), true);
if (!empty($config['error'])) throw new Exception($config['error']);

Python

import requests
r = requests.get(BASE + '/get-firebase-config.php')
config = r.json()
if 'error' in config:
    raise ValueError(config['error'])

2. Registrazione device (POST) – push normale

cURL

curl -X POST "BASE/api/register.php" \
  -H "Content-Type: application/json" \
  -H "X-Willy-App-Id: IL_TUO_APP_ID" -H "X-Willy-App-Key: LA_TUA_APP_KEY" \
  -d '{"push_token":"FCM_TOKEN_QUI","platform":"web","device_type":"web_browser","firebase_project_id":"tuo-project-id"}'

JavaScript (fetch)

await fetch(BASE + '/api/register.php', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Willy-App-Id': appId, 'X-Willy-App-Key': appKey },
  body: JSON.stringify({
    push_token: fcmToken,
    platform: 'web',
    device_type: 'web_browser',
    firebase_project_id: firebase.app().options?.projectId || ''
  })
});

PHP

$payload = [
  'push_token' => $fcmToken,
  'platform' => 'web',
  'device_type' => 'web_browser',
  'firebase_project_id' => $projectId
];
$ch = curl_init($base . '/api/register.php');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode($payload),
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'X-Willy-App-Id: ' . $appId, 'X-Willy-App-Key: ' . $appKey],
  CURLOPT_RETURNTRANSFER => true
]);
$res = curl_exec($ch);

Python

import requests
r = requests.post(BASE + '/api/register.php', json={
    'push_token': fcm_token,
    'platform': 'web',
    'device_type': 'web_browser',
    'firebase_project_id': project_id
}, headers={'X-Willy-App-Id': app_id, 'X-Willy-App-Key': app_key})
data = r.json()

3. Registrazione device con chiave pubblica (E2EE)

cURL

curl -X POST "BASE/api/register.php" \
  -H "Content-Type: application/json" \
  -H "X-Willy-App-Id: IL_TUO_APP_ID" -H "X-Willy-App-Key: LA_TUA_APP_KEY" \
  -d '{"push_token":"FCM_TOKEN","platform":"web","device_type":"web_browser","public_key":"BASE64URL_CHIAVE_PUBBLICA","firebase_project_id":"project-id"}'

JavaScript (fetch)

await fetch(BASE + '/api/register.php', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Willy-App-Id': appId, 'X-Willy-App-Key': appKey },
  body: JSON.stringify({
    push_token: token,
    platform: 'web',
    device_type: 'web_browser',
    user_agent: navigator.userAgent,
    public_key: publicKeyBase64,
    firebase_project_id: window.firebase?.app()?.options?.projectId || ''
  })
});

4. Lista device (GET) – limit e offset per paginazione

cURL

curl -s -H "X-Willy-App-Id: IL_TUO_APP_ID" -H "X-Willy-App-Key: LA_TUA_APP_KEY" "BASE/api/list.php?app_id=IL_TUO_APP_ID&limit=100&offset=0"
curl -s -H "X-Willy-App-Id: IL_TUO_APP_ID" -H "X-Willy-App-Key: LA_TUA_APP_KEY" "BASE/api/list.php?app_id=IL_TUO_APP_ID&platform=web&device_type=web_browser"

JavaScript

const res = await fetch(BASE + '/api/list.php?app_id=' + encodeURIComponent(appId) + '&limit=100&offset=0', {
  headers: { 'X-Willy-App-Id': appId, 'X-Willy-App-Key': appKey }
});
const data = await res.json();
console.log(data.data.devices, data.data.count, data.data.total);

5. Lista device cifrati (GET) – richiede X-Willy-App-Id / X-Willy-App-Key

cURL

curl -s -H "X-Willy-App-Id: IL_TUO_APP_ID" -H "X-Willy-App-Key: LA_TUA_APP_KEY" "BASE/api/list_encrypted.php?app_id=IL_TUO_APP_ID"

PHP

$ch = curl_init($base . '/api/list_encrypted.php?app_id=' . urlencode($appId));
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => ['X-Willy-App-Id: ' . $appId, 'X-Willy-App-Key: ' . $appKey],
  CURLOPT_RETURNTRANSFER => true
]);
$json = json_decode(curl_exec($ch), true);

6. Statistiche (GET)

cURL

curl -s -H "X-Willy-App-Id: IL_TUO_APP_ID" -H "X-Willy-App-Key: LA_TUA_APP_KEY" "BASE/api/stats.php?app_id=IL_TUO_APP_ID"

Risposta esempio

{
  "success": true,
  "data": {
    "domain": "tuodominio.it",
    "stats": {
      "total_registrations": 10,
      "total_active_devices": 8,
      "total_inactive_devices": 2,
      "total_push_sent": 150,
      "total_push_failed": 3,
      "total_invalidated_tokens": 1,
      "last_cleanup_at": "2025-03-14 12:00:00",
      "updated_at": "2025-03-14 12:00:00"
    }
  }
}

Nota: il campo domain nella risposta è ricavato dal server in base all'appId — non è un dato inviato dal client.

JavaScript

const res = await fetch(BASE + '/api/stats.php?app_id=' + encodeURIComponent(appId), {
  headers: { 'X-Willy-App-Id': appId, 'X-Willy-App-Key': appKey }
});
const data = await res.json();
const stats = data.data.stats;
console.log('Inviati:', stats.total_push_sent, 'Falliti:', stats.total_push_failed);

Python

r = requests.get(BASE + '/api/stats.php', params={'app_id': app_id}, headers={'X-Willy-App-Id': app_id, 'X-Willy-App-Key': app_key})
stats = r.json()['data']['stats']
print('Inviati:', stats['total_push_sent'])

7. Invio singolo (POST) – richiede X-Willy-App-Id / X-Willy-App-Key

cURL

curl -X POST "BASE/api/send.php" \
  -H "Content-Type: application/json" \
  -H "X-Willy-App-Id: IL_TUO_APP_ID" -H "X-Willy-App-Key: LA_TUA_APP_KEY" \
  -d '{"title":"Titolo","body":"Corpo messaggio","url":"/pagina"}'

JavaScript

await fetch(BASE + '/api/send.php', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Willy-App-Id': appId,
    'X-Willy-App-Key': appKey
  },
  body: JSON.stringify({
    title: 'Titolo',
    body: 'Corpo',
    url: '/pagina',
    target: {}
  })
});

PHP

$body = [
  'title' => 'Titolo',
  'body' => 'Corpo',
  'url' => '/pagina',
  'target' => []
];
$ch = curl_init($base . '/api/send.php');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode($body),
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'X-Willy-App-Id: ' . $appId, 'X-Willy-App-Key: ' . $appKey],
  CURLOPT_RETURNTRANSFER => true
]);
$res = curl_exec($ch);

Python

requests.post(BASE + '/api/send.php', json={
    'title': 'Titolo', 'body': 'Corpo', 'url': '/pagina', 'target': {}
}, headers={'X-Willy-App-Id': app_id, 'X-Willy-App-Key': app_key})

8. Invio bulk (POST)

cURL

curl -X POST "BASE/api/send_bulk.php" \
  -H "Content-Type: application/json" \
  -H "X-Willy-App-Id: IL_TUO_APP_ID" -H "X-Willy-App-Key: LA_TUA_APP_KEY" \
  -d '{"title":"Bulk","body":"Messaggio","target":{},"limit":5000}'

PHP

$body = [
  'title' => 'Bulk',
  'body' => 'Messaggio',
  'target' => [],
  'limit' => 5000
];
$ch = curl_init($base . '/api/send_bulk.php');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode($body),
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'X-Willy-App-Id: ' . $appId, 'X-Willy-App-Key: ' . $appKey],
  CURLOPT_RETURNTRANSFER => true
]);
$res = curl_exec($ch);

9. Invio cifrato E2EE (POST)

cURL

curl -X POST "BASE/api/send_encrypted.php" \
  -H "Content-Type: application/json" \
  -H "X-Willy-App-Id: IL_TUO_APP_ID" -H "X-Willy-App-Key: LA_TUA_APP_KEY" \
  -d '{"title":"Cifrato","body":"Solo questo device può decifrare.","url":"/","icon":"/logobase.png","target":{},"limit":5000}'

JavaScript

const res = await fetch(BASE + '/api/send_encrypted.php', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Willy-App-Id': appId,
    'X-Willy-App-Key': appKey
  },
  body: JSON.stringify({
    title: 'Cifrato',
    body: 'Solo questo device può decifrare.',
    url: '/',
    icon: '/logobase.png',
    target: {},
    limit: 5000
  })
});
const data = await res.json();
// data.data.sent, data.data.failed, data.data.invalidated, data.data.total

PHP

$body = [
  'title' => 'Cifrato',
  'body' => 'Solo questo device può decifrare.',
  'url' => '/',
  'icon' => '/logobase.png',
  'target' => [],
  'limit' => 5000
];
$ch = curl_init($base . '/api/send_encrypted.php');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode($body),
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'X-Willy-App-Id: ' . $appId, 'X-Willy-App-Key: ' . $appKey],
  CURLOPT_RETURNTRANSFER => true
]);
$res = curl_exec($ch);

Python

r = requests.post(BASE + '/api/send_encrypted.php', json={
    'title': 'Cifrato',
    'body': 'Solo questo device può decifrare.',
    'url': '/', 'icon': '/logobase.png', 'target': {}, 'limit': 5000
}, headers={'X-Willy-App-Id': app_id, 'X-Willy-App-Key': app_key})
print(r.json()['data']['sent'], r.json()['data']['failed'])

10. Rimuovi device (POST) – token_hash da list o list_encrypted

cURL (normale)

curl -X POST "BASE/api/delete_device.php" \
  -H "Content-Type: application/json" \
  -H "X-Willy-App-Id: IL_TUO_APP_ID" -H "X-Willy-App-Key: LA_TUA_APP_KEY" \
  -d '{"token_hash":"abc123def456"}'

cURL (cifrato)

curl -X POST "BASE/api/delete_encrypted_device.php" \
  -H "Content-Type: application/json" \
  -H "X-Willy-App-Id: IL_TUO_APP_ID" -H "X-Willy-App-Key: LA_TUA_APP_KEY" \
  -d '{"token_hash":"abc123def456"}'

11. Disiscrivi (unregister) – con push_token

cURL

curl -X POST "BASE/api/unregister.php" \
  -H "Content-Type: application/json" \
  -H "X-Willy-App-Id: IL_TUO_APP_ID" -H "X-Willy-App-Key: LA_TUA_APP_KEY" \
  -d '{"push_token":"FCM_TOKEN","reason":"user"}'

12. Heartbeat

cURL

curl -X POST "BASE/api/heartbeat.php" \
  -H "Content-Type: application/json" \
  -H "X-Willy-App-Id: IL_TUO_APP_ID" -H "X-Willy-App-Key: LA_TUA_APP_KEY" \
  -d '{"push_token":"FCM_TOKEN"}'

13. Verifica Firebase (GET) – solo admin

cURL

curl -s -H "X-API-TOKEN: WILLY_ADMIN_TOKEN" "BASE/api/firebase_check.php"

Risposta standard

Tutte le API JSON restituiscono un oggetto con success (true/false), message, data (opzionale), request_id. In caso di errore: success: false, error_code, message.