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

0forks

Install

No release zip yet. The repository archive installs, but the folder name will carry the branch suffix and updates will not flow:

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

Readme

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.

Read the full README on GitHub →