manifest / integrations / perfecty-post-rest-push

Perfecty Post REST Push

Espone una API REST per inviare notifiche push Perfecty Push a partire da ID o URL di un post, inclusi custom post type.

by Matteo Morreale · github.com/matteomorreale/perfecty-post-rest-push

★ 0stars

Install

Download source zip No release zip yet

This is the repository archive. It installs, but the folder name will carry the branch suffix and updates will not flow.

Install straight from GitHub with WP-CLI:

wp plugin install https://github.com/matteomorreale/perfecty-post-rest-push/archive/refs/heads/main.zip

No built-in updater. New versions won't appear under Dashboard → Updates. Install new releases yourself, or let Git Updater track the repository.

Readme github.com/matteomorreale/perfecty-post-rest-push ↗

Perfecty Post REST Push è un plugin WordPress che espone una API REST autenticata per inviare una notifica push tramite Perfecty Push Notifications partendo da un ID post oppure dall’URL di un post, inclusi i custom post type pubblici.

Il plugin non modifica Perfecty Push e non ne include il codice. Se Perfecty Push non è installato, non è attivo o non ha caricato le classi necessarie, l’endpoint restituisce un errore REST controllato e nell’amministrazione viene mostrato un avviso, senza generare errori fatali.

Requisiti

Requisito	Valore
WordPress	6.2 o superiore
PHP	7.4 o superiore
Dipendenza	Perfecty Push Notifications 1.6.5 o compatibile
Permessi amministrativi	`manage_options` per configurare il plugin

Installazione

Carica la cartella perfecty-post-rest-push in wp-content/plugins/, poi attiva il plugin dalla schermata Plugin di WordPress. All’attivazione viene generata automaticamente una chiave API. La chiave è visibile e rigenerabile da Impostazioni > Perfecty REST Push.

Endpoint

Metodo	Endpoint	Descrizione
`POST`	`/wp-json/perfecty-post-push/v1/push`	Programma una notifica broadcast Perfecty Push per il post indicato.
`GET`	`/wp-json/perfecty-post-push/v1/status`	Restituisce lo stato del plugin e della dipendenza Perfecty Push.

Autenticazione

La richiesta è autorizzata se l’utente WordPress corrente ha il permesso manage_options, oppure se viene inviata la chiave API configurata. La chiave può essere passata in uno dei due modi seguenti.

X-PPRA-API-Key: LA_TUA_CHIAVE_API

Authorization: Bearer LA_TUA_CHIAVE_API

Corpo richiesta push

Campo	Tipo	Obbligatorio	Descrizione
`id`	integer	No, alternativo a `url`	ID del post o custom post type.
`url`	string	No, alternativo a `id`	URL del post. Deve appartenere allo stesso host del sito.
`title`	string	No	Titolo personalizzato della notifica. Se vuoto, Perfecty Push usa il nome del sito.
`body`	string	No	Testo della notifica. Se vuoto, viene usato il titolo del post.
`image`	string	No	URL immagine personalizzata. Se vuoto, viene usata l’immagine in evidenza o la prima immagine nel contenuto.
`url_to_open`	string	No	URL aperto al clic. Se vuoto, viene usato il permalink del post.
`scheduled_time`	integer/string	No	Timestamp Unix o data compatibile con `DateTime` per programmare l’invio.
`timeoffset`	integer	No	Ritardo in minuti rispetto al momento della chiamata; ignorato se `scheduled_time` è valorizzato.

Esempi

Invio immediato tramite ID post.

curl -X POST 'https://example.com/wp-json/perfecty-post-push/v1/push' \
  -H 'Content-Type: application/json' \
  -H 'X-PPRA-API-Key: LA_TUA_CHIAVE_API' \
  -d '{"id":123}'

Invio tramite URL con titolo e testo personalizzati.

curl -X POST 'https://example.com/wp-json/perfecty-post-push/v1/push' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer LA_TUA_CHIAVE_API' \
  -d '{
    "url":"https://example.com/news/articolo-demo/",
    "title":"Nuovo aggiornamento",
    "body":"Leggi ora il nuovo articolo pubblicato.",
    "timeoffset":10
  }'

Risposta di successo

{
  "success": true,
  "notification_id": 42,
  "scheduled_time": null,
  "post": {
    "id": 123,
    "type": "post",
    "status": "publish",
    "title": "Titolo articolo",
    "permalink": "https://example.com/titolo-articolo/"
  },
  "payload": {
    "title": "Nome sito",
    "body": "Titolo articolo",
    "icon": "https://example.com/wp-content/uploads/icon.png",
    "image": "https://example.com/wp-content/uploads/thumb.jpg",
    "require_interaction": false,
    "extra": {
      "url_to_open": "https://example.com/titolo-articolo/"
    }
  }
}

Gestione errori

Quando Perfecty Push non è disponibile, l’endpoint risponde con codice HTTP 503 e un oggetto dependency che indica quali classi o opzioni risultano mancanti. Se l’autenticazione non è corretta, viene restituito 403; se il post non esiste, viene restituito 404.

Note tecniche

Il plugin richiama direttamente Perfecty_Push_Lib_Payload::build() e Perfecty_Push_Lib_Push_Server::schedule_broadcast_async(), cioè gli stessi componenti usati da Perfecty Push per creare il payload e schedulare un broadcast. La risoluzione degli URL usa prima url_to_postid() e poi un fallback sullo slug limitato ai post type pubblici dello stesso host del sito.