Come estendere il Registro di SaveTo Wishlist con hook e la REST API

Stai creando un'integrazione personalizzata con registri regali o modificando il comportamento dei registri sul tuo negozio? SaveTo Wishlist Registry aggiunge hook PHP e route REST API che ti permettono di fare entrambe le cose senza modificare i file del plugin. Questo articolo elenca le route, chi può chiamarle, cosa restituiscono le route pubbliche e gli hook che puoi utilizzare, con esempi funzionanti.

Per il riferimento per sviluppatori del plugin di base, vedi Come estendere SaveTo Wishlist con hook e la REST API.

Prima di iniziare

• SaveTo Wishlist Registry (elencato in WordPress come SaveTo Wishlist Gift Registry Addon) richiede che WooCommerce e SaveTo Wishlist Lite siano attivi. Viene fornito con i piani Plus e Business e ha una propria chiave di licenza, separata da SaveTo Wishlist Pro.
• Ogni nome di hook inizia con stwreg_. Aggiungi il tuo codice a un piccolo plugin o al file functions.php di un tema child.
• Gli hook e le route in questo articolo esistono in SaveTo Wishlist Registry 1.0.0.
• I dati del registro si trovano in tabelle personalizzate che utilizzano il prefisso delle tabelle di WordPress: wp_stw_registries, wp_stw_registry_items, wp_stw_registry_purchases e wp_stw_registry_contributions. Utilizza gli hook e le route sottostanti invece di scrivere direttamente in queste tabelle.

Come funziona la REST API

Tutte le route utilizzano lo spazio dei nomi saveto-wishlist-registry/v1. Su un sito all'indirizzo https://example.com, l'URL di base completo è https://example.com/wp-json/saveto-wishlist-registry/v1/.

Le route che richiedono un utente connesso utilizzano l'autenticazione REST standard di WordPress. In una sessione del browser, invia l'header X-WP-Nonce con un nonce wp_rest. Per le chiamate server-to-server, utilizza una password applicazione di WordPress. Le route pubbliche non richiedono login.

La colonna "Chi può chiamarla" nelle tabelle delle route utilizza questi termini:

• Chiunque: non è necessario il login.
• Utente connesso: qualsiasi account connesso.
• Proprietario del registro: l'utente connesso che possiede il registro nella route, o qualsiasi utente con la capacità manage_woocommerce (gestori del negozio e amministratori per impostazione predefinita).
• Proprietario dell'acquisto: l'utente connesso che possiede il registro a cui appartiene l'acquisto, o qualsiasi utente con la capacità manage_woocommerce.
• Proprietario o gestore del negozio (registry_id): il proprietario del registro fornito nel parametro di query registry_id, o un utente con la capacità manage_woocommerce. Se registry_id è mancante, solo gli utenti con tale capacità passano.
• Gestore del negozio: un utente con la capacità manage_woocommerce.

Gli errori vengono restituiti come errori REST standard di WordPress con un code, un messaggio e uno stato HTTP. Le richieste con limitazione di frequenza restituiscono lo stato 429 con il codice rate_limited.

Percorsi API REST

Percorsi pubblici

Metodo	Percorso	Chi può chiamarlo	Cosa fa
GET	/registry/search	Chiunque	Cerca registri pubblicati. Parametri di query: name (almeno 2 caratteri), event_type, page, per_page (massimo 20, predefinito 20). Limitato a 30 richieste ogni 5 minuti per indirizzo IP.
GET	/registry/{url_code}	Chiunque	Restituisce un registro tramite il suo codice pubblico. Il codice è composto da 4 a 16 lettere o numeri. Restituisce 404 per un registro eliminato. I registri archiviati vengono comunque restituiti.
GET	/registry/{url_code}/items	Chiunque	Restituisce gli articoli in un registro. Restituisce 404 per un registro eliminato.
POST	/contributions	Chiunque	Registra un contributo in denaro in sospeso. Campi del corpo: registry_id, amount, registry_item_id (opzionale), contributor_name, contributor_email, message. Il registro deve essere pubblicato e avere l'aggregazione di fondi attivata. Restituisce il nuovo id e lo stato pending.

Il percorso POST /contributions registra solo una riga con lo stato pending. Non effettua un pagamento. Un'integrazione di pagamento deve aggiornare autonomamente lo stato.

Percorsi del proprietario del registro

Metodo	Percorso	Chi può chiamarlo	Cosa fa
POST	/registry/convert	Utente connesso	Converte una lista dei desideri in un registro per l'utente corrente. Richiede una licenza attiva, altrimenti restituisce 403 con il codice license_inactive. Campi del corpo: collection_id, event_type, event_date, registrant_name, co_registrant_name, message, location, cover_image_attachment_id, allow_fund_pooling.
POST	/registry/cover-image	Utente connesso	Carica un'immagine di copertina come file multipart nel campo file. JPEG, PNG o WebP, fino a 5 MB. Restituisce attachment_id e url.
GET	/my-registries	Utente connesso	Elenca solo i registri di proprietà dell'utente corrente, inclusi i gestori del negozio, con conteggi degli articoli, conteggi dei ringraziamenti e un blocco complessivo di stats.
PUT	/registry/{id}	Proprietario del registro	Aggiorna i dettagli del registro. Invia un corpo JSON con i campi da modificare.
ELIMINA	/registry/{id}	Proprietario del registro	Elimina il registro. Restituisce {"deleted":true}.
POST	/registry/{id}/items	Proprietario del registro	Aggiunge un prodotto al registro. Campi del corpo: product_id (richiesto), variation_id, quantity (predefinito 1), priority (predefinito medium; valori consentiti: low, medium e high).
PATCH	/registry/{id}/items/reorder	Proprietario del registro	Salva un nuovo ordine degli articoli. Campo del corpo: item_ids (array di ID articolo richiesto). Ogni ID deve appartenere al registro.
PATCH	/registry/{id}/items/{item_id}	Proprietario del registro	Modifica la quantità richiesta di un articolo. Campo del corpo: quantity. La quantità non può scendere al di sotto del numero già acquistato. Restituisce 409 se il registro è archiviato.
ELIMINA	/registry/{id}/items/{item_id}	Proprietario del registro	Rimuove un articolo. Restituisce 409 se il registro è archiviato.
GET	/registry/{id}/products/search	Proprietario del registro	Cerca prodotti da aggiungere. Parametri di query: q, per_page. Limitato a 60 richieste ogni 5 minuti per utente.
GET	/registry/{id}/products/{product_id}/variations	Proprietario del registro	Elenca le varianti di un prodotto. Limitato a 60 richieste ogni 5 minuti per utente.

Percorsi di acquisto e contributo

Metodo	Percorso	Chi può chiamarlo	Cosa fa
GET	/purchases	Proprietario o gestore del negozio (registry_id)	Elenca gli acquisti per un registro. Parametri di query: registry_id, thank_you_sent (all, true o false), page, per_page, orderby, order. Ogni riga contiene il nome e l'email dell'acquirente, quindi solo i proprietari e i gestori del negozio possono leggerla.
POST	/purchases/{id}/note	Proprietario dell'acquisto	Salva la nota del proprietario su un acquisto. Campo del corpo: note.
POST	/purchases/{id}/thank-you	Proprietario dell'acquisto	Segna un acquisto come ringraziato o meno. Campo del corpo: sent.
POST	/purchases/bulk-thank-you	Proprietario dell'acquisto	Segna diversi acquisti contemporaneamente. Campi del corpo: ids e sent. Per un proprietario, tutti gli ID devono appartenere a registri di sua proprietà.
GET	/contributions	Proprietario o gestore del negozio (registry_id)	Elenca i contributi per il registro nel parametro di query registry_id, dal più recente al meno recente. Le righe includono l'email del contributore.

Percorsi di amministrazione del registro

Tutti i percorsi di amministrazione richiedono un gestore del negozio.

Metodo	Percorso	Cosa fa
GET	/admin/registries	Elenca i registri. Parametri di query: status, event_type, search, orderby, order, page, per_page, include_deleted.
GET	/admin/registries/{id}	Restituisce un registro con i suoi articoli e fino a 100 acquisti.
PUT	/admin/registries/{id}	Aggiorna un registro come amministratore.
ELIMINA	/admin/registries/{id}	Elimina un registro come amministratore.
POST	/admin/registries/{id}/close	Archivia un registro. La pagina pubblica rimane online con un banner di archivio.
POST	/admin/registries/{id}/restore	Ripristina un registro.
POST	/admin/registries/bulk	Esegue un'azione su molti registri. Campi del corpo: action (archive, unarchive o delete) e ids. Restituisce un risultato per ogni ID più i conteggi di succeeded e failed.
POST	/admin/registries/convert	Converte una wishlist in un registro per il proprietario della wishlist. Campo del corpo richiesto: collection_id. Altri campi corrispondono a /registry/convert.
GET	/admin/registries/by-collections	Trova il registro per ogni ID di wishlist nel parametro di query ids (separato da virgole). Restituisce registry_id, url_code, status e public_url per ogni corrispondenza. I registri eliminati vengono omessi.

Cosa espongono i percorsi pubblici

I percorsi pubblici possono essere chiamati da chiunque, quindi controlla cosa restituiscono prima di costruirci sopra.

GET /registry/{url_code} restituisce il record del registro e i dati della pagina di destinazione uniti in un'unica risposta. Include:

• Campi del registro: id, collection_id, owner_user_id, url_code, event_type, event_date, registrant_name, co_registrant_name, message, location, cover_image_id, allow_fund_pooling, status, previous_url_code, created_at e updated_at.
• Campi di visualizzazione: title, event_type_label, event_date_iso, event_date_formatted, registrant_names, cover_image_url, cover_image_alt, is_archived, is_owner e public_url.
• Un elenco items. Ogni articolo ha il titolo del prodotto, l'URL del prodotto, l'immagine, il prezzo formattato, la quantity e la purchased_quantity.

Quando il chiamante possiede il registro o è un gestore del negozio, la risposta contiene anche un elenco event_types.

GET /registry/{url_code}/items restituisce ogni articolo con il suo ID, un blocco product (ID, ID variazione, nome, SKU, URL miniatura, prezzo formattato e se il prodotto esiste ancora), quantity_wanted, quantity_purchased, quantity_remaining, is_fully_claimed, is_archived e priority.

GET /registry/search restituisce solo registri pubblicati. Ogni risultato ha id, url_code, event_type, event_date, registrant_name, co_registrant_name, cover_image_id, public_url e event_date_formatted. La risposta ha anche total, page e per_page.

Nessuno dei percorsi pubblici restituisce nomi di acquirenti, email di acquirenti, righe di acquisto, ID ordine o righe di contributo. Questi sono disponibili solo tramite i percorsi proprietario e amministratore. Usa il filtro stwreg_registry_data qui sotto per aggiungere o rimuovere campi dalla risposta di GET /registry/{url_code}. Testa la tua pagina del registro dopo aver rimosso un campo.

Hook

Gli hook qui sotto sono i più utili per estendere il plugin. Il numero di argomenti è esatto. Quando aggiungi un hook con più di un argomento, passa il numero di argomenti come quarto parametro di add_filter() o add_action().

Filtri per i dati del registro e la pagina di destinazione

Filtro	Argomenti	Cosa cambia
stwreg_registry_data	$data (array), $row (oggetto)	La risposta completa di GET /registry/{url_code}. $row è la riga grezza del registro.
stwreg_registry_items_data	$response (array), $row (oggetto)	La risposta di GET /registry/{url_code}/items. L'array ha data, total, currentPage e is_archived.
stwreg_registry_landing_data	$payload (array), $row (oggetto)	I dati utilizzati per costruire la pagina di destinazione e la risposta REST, prima che venga renderizzata.
stwreg_search_results	$results (array), $args (array)	Il risultato della ricerca del registro prima che venga restituito. L'array ha data, total, page e per_page.
stwreg_landing_html	$html (stringa), $payload (array)	L'HTML finale dell'intera pagina di destinazione del registro.
stwreg_landing_item_card	$html (stringa), $item (array), $payload (array)	L'HTML di una singola scheda articolo nella pagina di destinazione.

Restituisci sempre lo stesso tipo di quello che ricevi. Il plugin converte il valore restituito in un array o una stringa.

Questo esempio aggiunge un campo personalizzato alla risposta pubblica del registro:

add_filter( 'stwreg_registry_data', function ( array $data, $row ) {
    $data['shipping_note'] = 'Gifts ship within 3 business days.';

    return $data;
}, 10, 2 );

Questo esempio aggiunge una riga di testo sotto la pagina di destinazione:

add_filter( 'stwreg_landing_html', function ( $html, $payload ) {
    if ( ! empty( $payload['is_archived'] ) ) {
        return $html;
    }

    return $html . '<p>' . esc_html__( 'Need help choosing a gift? Contact us.', 'your-text-domain' ) . '</p>';
}, 10, 2 );

La pagina di destinazione è costruita anche da filtri di sezioni più piccole, uno per ogni parte della pagina. I loro nomi iniziano con stwreg_landing_section_ e prendono $html e $payload. Esempi sono stwreg_landing_section_header, stwreg_landing_section_message e stwreg_landing_section_footer. Per modificare l'aspetto della pagina senza codice, consulta Impostazioni dell'aspetto della pagina di destinazione del registro.

Filtri per il limite di frequenza

I percorsi seguenti limitano la frequenza con cui un singolo utente o un singolo indirizzo IP può chiamarli. Ogni limite ha due filtri. Uno imposta il numero di richieste. L'altro imposta la finestra in secondi. Ogni filtro accetta un argomento e deve restituire un intero.

Filtro limite	Filtro finestra	Predefinito	Percorso	Contato per
stwreg_add_item_rate_limit	stwreg_add_item_rate_window	30 richieste in 5 minuti	POST /registry/{id}/items	Utente
stwreg_cover_image_rate_limit	stwreg_cover_image_rate_window	30 richieste in 5 minuti	POST /registry/cover-image	Utente
stwreg_convert_rate_limit	stwreg_convert_rate_window	5 richieste in 5 minuti	POST /registry/convert	Utente
stwreg_contribute_rate_limit	stwreg_contribute_rate_window	10 richieste in 5 minuti	POST /contributions	Indirizzo IP e registro

Il limite di ricerca (30 richieste al minuto per ogni indirizzo IP) e i limiti di ricerca e variazione del prodotto (60 richieste al minuto per ogni utente) non hanno filtri. Il limite dell'importo del contributo ha un proprio filtro, stwreg_contribution_max_amount (float, predefinito 100000).

Questo esempio aumenta il limite di aggiunta articoli a 60 richieste in 10 minuti:

add_filter( 'stwreg_add_item_rate_limit', function ( $limit ) {
    return 60;
} );

add_filter( 'stwreg_add_item_rate_window', function ( $window ) {
    return 10 * MINUTE_IN_SECONDS;
} );

Per impostazione predefinita, il plugin utilizza REMOTE_ADDR per trovare l'indirizzo IP del visitatore per i limiti basati sull'IP. Se il tuo sito è dietro un proxy o una CDN, REMOTE_ADDR è l'indirizzo del proxy, quindi tutti i visitatori condividono un unico limite. Utilizza il filtro stwreg_trusted_ip_headers per elencare le variabili del server che contengono l'indirizzo IP reale. Elenca solo gli header che il tuo proxy imposta, poiché i visitatori possono falsificare gli altri.

add_filter( 'stwreg_trusted_ip_headers', function ( array $headers ) {
    $headers[] = 'HTTP_CF_CONNECTING_IP';

    return $headers;
} );

Azioni di acquisto

Azione	Argomenti	Quando si attiva
stwreg_after_save_purchase	$purchase_id (int), $payload (array)	Dopo che una riga di acquisto è stata creata o aggiornata. Viene eseguito per le nuove righe e per gli aggiornamenti di una riga d'ordine esistente.
stwreg_after_void_purchase	$purchase_id (int), $purchase (object), $previous_status (string), $refunded_quantity (int)	Quando un acquisto passa allo stato annullato, ad esempio dopo un rimborso.
stwreg_after_record_purchases_from_order	$order_id (int), $order (WC_Order)	Dopo che il plugin elabora un ordine pagato che contiene articoli della lista dei desideri. Viene eseguito anche se alcuni articoli non sono stati trovati.
stwreg_overpurchase_recorded	$registry_item_id (int), $purchased_total (int), $requested_quantity (int)	Dopo che il totale degli acquisti registrati per un articolo è superiore alla quantità richiesta dal proprietario.

L'array $payload di stwreg_after_save_purchase ha queste chiavi: registry_id, registry_item_id, order_id, line_item_id, quantity, buyer_name, buyer_email e status. Lo stato è recorded, voided o refunded. Il plugin salva gli acquisti dagli ordini e li salva di nuovo quando la stessa riga dell'ordine viene elaborata di nuovo. Scrivi il tuo gestore in modo che sia sicuro eseguirlo due volte per lo stesso acquisto.

add_action( 'stwreg_after_save_purchase', function ( $purchase_id, $payload ) {
    if ( 'recorded' !== $payload['status'] ) {
        return;
    }

    error_log( sprintf(
        'Registry %d: item %d bought (purchase %d).',
        $payload['registry_id'],
        $payload['registry_item_id'],
        $purchase_id
    ) );
}, 10, 2 );

Un articolo della lista dei desideri può finire con più acquisti registrati rispetto a quelli richiesti dal proprietario, ad esempio quando due acquirenti completano l'acquisto contemporaneamente. Il plugin lo consente per progettazione. Quando ciò accade, esegue stwreg_overpurchase_recorded dopo aver salvato il nuovo totale. L'azione può essere eseguita di nuovo ogni volta che il plugin ricalcola un articolo che è ancora al di sopra della sua quantità, quindi non presumere che venga eseguita una sola volta.

add_action( 'stwreg_overpurchase_recorded', function ( $registry_item_id, $purchased_total, $requested_quantity ) {
    error_log( sprintf(
        'Registry item %d: %d bought, %d requested.',
        $registry_item_id,
        $purchased_total,
        $requested_quantity
    ) );
}, 10, 3 );

Filtri e azioni email

Il plugin invia tre email: l'email di acquisto del proprietario (tipo owner_new_purchase), l'email di rimborso del proprietario (tipo owner_order_refund) e l'email di nuova lista dei desideri dell'amministratore (tipo admin_new_registry). Per modificare il contenuto, vedi Come configurare le notifiche email della lista dei desideri.

Hook	Tipo	Argomenti	Cosa fa
stwreg_email_send_async	Filtro	$async (bool), $payload (array)	Predefinito true. Quando è vero, il plugin accoda l'email con WP-Cron. Quando è falso, invia l'email nella stessa richiesta.
stwreg_email_{type}_subject	Filtro	$subject (string), $context (array), $payload (array)	Modifica l'oggetto. Sostituisci {type} con un tipo di email, ad esempio stwreg_email_owner_new_purchase_subject.
stwreg_email_{type}_body	Filtro	$body (string), $context (array), $payload (array)	Modifica il corpo renderizzato prima che venga aggiunto il layout dell'email.
stwreg_after_email_dispatched	Azione	$type (string), $payload (array), $success (bool)	Eseguito dopo che il plugin tenta di inviare un'email. $success è falso quando l'email è stata saltata o non è riuscita.

Utilizza la modalità sincrona quando WP-Cron è disattivato sul tuo sito o quando vuoi testare un'email in una singola richiesta:

add_filter( 'stwreg_email_send_async', '__return_false' );

Se WP-Cron è disattivato e si lascia l'impostazione predefinita, le email in coda attendono l'esecuzione di un vero job cron.

Questo esempio modifica l'oggetto dell'email di acquisto per il proprietario:

add_filter( 'stwreg_email_owner_new_purchase_subject', function ( $subject, $context, $payload ) {
    return 'Good news: ' . $subject;
}, 10, 3 );

Per le email del proprietario, $context include recipient, owner_display_name, registry (oggetto riga), purchase (oggetto riga), item (oggetto riga), subject, owner_dashboard e public_url.

Filtri per i permessi REST

Ogni route esegue un controllo dei permessi e ogni controllo ha un filtro. Usa questi filtri per rendere l'accesso più restrittivo. Non possono rendere l'accesso più ampio. Se il plugin nega una richiesta, il filtro non può consentirla. Se il plugin consente una richiesta, il filtro può comunque restituire un WP_Error per negarla.

Filtro	Utilizzato da	Argomenti
stwreg_api_public_permissions_check	Route pubbliche (/registry/search, /registry/{url_code}, /registry/{url_code}/items, POST /contributions)	$decision (bool o WP_Error), $request (WP_REST_Request)
stwreg_api_logged_in_permissions_check	Route per qualsiasi utente connesso	$decision, $request
stwreg_api_owner_permissions_check	Percorsi del proprietario del registro	$decision, $request
stwreg_api_admin_permissions_check	Percorsi di amministrazione del registro	$decision, $request

Questo esempio rende la ricerca del registro disponibile solo agli utenti connessi:

add_filter( 'stwreg_api_public_permissions_check', function ( $decision, $request ) {
    $search_route = '/saveto-wishlist-registry/v1/registry/search';

    if ( $search_route === $request->get_route() && ! is_user_logged_in() ) {
        return new WP_Error(
            'rest_forbidden',
            'Log in to search registries.',
            array( 'status' => 401 )
        );
    }

    return $decision;
}, 10, 2 );

Le route /purchases/{id}/note, /purchases/{id}/thank-you e /purchases/bulk-thank-you utilizzano i propri controlli di proprietà e non eseguono questi filtri. GET /purchases e GET /contributions consentono al proprietario del registro di passare senza filtro. Per tutti gli altri, eseguono il controllo amministrativo, quindi stwreg_api_admin_permissions_check si applica a loro.

Altre azioni

Azione	Argomenti	Quando si attiva
stwreg_before_convert_wishlist_to_registry	$collection_id (int), $args (array)	Prima che una wishlist venga convertita. Vedi Come convertire una wishlist in un registro regali.
stwreg_after_convert_wishlist_to_registry	$registry_id (int), $collection_id (int), $args (array)	Dopo che una wishlist è stata convertita.
stwreg_after_add_registry_item	$registry_id (int), $row (object)	Dopo che un articolo è stato aggiunto a un registro.
stwreg_after_save_contribution	$contribution_id (int), $registry_id (int)	Dopo che una riga di contributo è stata salvata.

Domande frequenti

Posso cambiare il prefisso dell'URL della pagina del registro?
Sì. Il filtro stwreg_url_prefix accetta il prefisso come stringa e stwreg_registry_public_url accetta l'URL completo (stringa) e il codice pubblico (stringa).

Dove trovo l'esportazione e la cancellazione della privacy per i dati del registro?
Vedi Come esportare e cancellare i dati del registro per le richieste di privacy.

Qual è il prossimo passo?

• Come visualizzare gli acquisti di regali e inviare note di ringraziamento
• Come impostare una pagina di ricerca per "Trova un registro"
• Come impostare le notifiche email per il registro dei regali

Serve aiuto?

Se hai una domanda o riscontri problemi, siamo qui per aiutarti.

• Utenti Premium: Apri un ticket di supporto
• Utenti Gratuiti: Visita il nostro forum della community