Hoe breid je SaveTo Wishlist Registry uit met hooks en de REST API

Een aangepaste integratie met geschenkenregisters bouwen, of het gedrag van registers op uw winkel aanpassen? SaveTo Wishlist Registry voegt PHP-hooks en REST API-routes toe waarmee u beide kunt doen zonder pluginbestanden te bewerken. Dit artikel bevat de routes, wie ze kan aanroepen, wat de openbare routes retourneren en de hooks die u kunt gebruiken, met werkende voorbeelden.

Voor de ontwikkelaarsreferentie van de basisplugin, zie Hoe SaveTo Wishlist uit te breiden met hooks en de REST API.

Voordat u begint

• SaveTo Wishlist Registry (vermeld in WordPress als SaveTo Wishlist Gift Registry Addon) vereist dat WooCommerce en SaveTo Wishlist Lite actief zijn. Het wordt geleverd met de Plus- en Business-abonnementen en heeft een eigen licentiesleutel, gescheiden van SaveTo Wishlist Pro.
• Elke hooknaam begint met stwreg_. Voeg uw code toe aan een kleine plugin of aan het functions.php-bestand van een child theme.
• De hooks en routes in dit artikel bestaan in SaveTo Wishlist Registry 1.0.0.
• Registergegevens bevinden zich in aangepaste tabellen die uw WordPress-tabelprefix gebruiken: wp_stw_registries, wp_stw_registry_items, wp_stw_registry_purchases en wp_stw_registry_contributions. Gebruik de onderstaande hooks en routes in plaats van rechtstreeks naar deze tabellen te schrijven.

Hoe de REST API werkt

Alle routes gebruiken de naamruimte saveto-wishlist-registry/v1. Op een site op https://example.com is de volledige basis-URL https://example.com/wp-json/saveto-wishlist-registry/v1/.

Routes die een ingelogde gebruiker nodig hebben, gebruiken standaard WordPress REST-authenticatie. Stuur in een browsersessie de X-WP-Nonce-header mee met een wp_rest nonce. Gebruik voor server-naar-server-aanroepen een WordPress-appwachtwoord. Openbare routes hebben geen login nodig.

De kolom "Wie kan het aanroepen" in de routetabellen gebruikt deze termen:

• Iedereen: geen login nodig.
• Ingeplugde gebruiker: elk ingelogd account.
• Eigenaar register: de ingelogde gebruiker die eigenaar is van het register in de route, of elke gebruiker met de manage_woocommerce-mogelijkheid (standaard winkelmanagers en beheerders).
• Eigenaar aankoop: de ingelogde gebruiker die eigenaar is van het register waartoe de aankoop behoort, of elke gebruiker met de manage_woocommerce-mogelijkheid.
• Eigenaar of winkelmanager (registry_id): de eigenaar van het register dat wordt gegeven in de queryparameter registry_id, of een gebruiker met de manage_woocommerce-mogelijkheid. Als registry_id ontbreekt, slagen alleen gebruikers met die mogelijkheid.
• Winkelmanager: een gebruiker met de manage_woocommerce-mogelijkheid.

Fouten komen terug als standaard WordPress REST-fouten met een code, een bericht en een HTTP-status. Verzoeken met snelheidslimieten retourneren status 429 met de code rate_limited.

REST API-routes

Openbare routes

Methode	Route	Wie kan het aanroepen	Wat het doet
GET	/registry/search	Iedereen	Doorzoekt gepubliceerde registers. Query parameters: name (minimaal 2 tekens), event_type, page, per_page (maximaal 20, standaard 20). Beperkt tot 30 verzoeken per 5 minuten voor elk IP-adres.
GET	/registry/{url_code}	Iedereen	Retourneert één register op basis van zijn openbare code. De code bestaat uit 4 tot 16 letters of cijfers. Retourneert 404 voor een verwijderd register. Gearchiveerde registers worden nog steeds geretourneerd.
GET	/registry/{url_code}/items	Iedereen	Retourneert de items in een register. Retourneert 404 voor een verwijderd register.
POST	/contributions	Iedereen	Registreert een openstaande geldelijke bijdrage. Bodyvelden: registry_id, amount, registry_item_id (optioneel), contributor_name, contributor_email, message. Het register moet gepubliceerd zijn en fondsenwerving ingeschakeld hebben. Retourneert de nieuwe id en de status pending.

De route POST /contributions registreert alleen een rij met de status pending. Het neemt geen betaling in ontvangst. Een betalingsintegratie moet de status zelf bijwerken.

Routes voor register-eigenaar

Methode	Route	Wie kan het aanroepen	Wat het doet
POST	/registry/convert	Ingelogde gebruiker	Converteert een verlanglijst naar een register voor de huidige gebruiker. Vereist een actieve licentie, anders retourneert het 403 met de code license_inactive. Bodyvelden: collection_id, event_type, event_date, registrant_name, co_registrant_name, message, location, cover_image_attachment_id, allow_fund_pooling.
POST	/registry/cover-image	Ingelogde gebruiker	Uploadt een omslagafbeelding als een multipart-bestand in het veld file. JPEG, PNG of WebP, tot 5 MB. Retourneert attachment_id en url.
GET	/my-registries	Ingelogde gebruiker	Lijst alleen de registers op die eigendom zijn van de huidige gebruiker, inclusief winkelmanagers, met itemaantallen, bedankjesaantallen en een algemeen stats-blok.
PUT	/registry/{id}	Register-eigenaar	Werkt registerdetails bij. Stuur een JSON-body met de te wijzigen velden.
DELETE	/registry/{id}	Register-eigenaar	Verwijdert het register. Retourneert {"deleted":true}.
POST	/registry/{id}/items	Register-eigenaar	Voegt een product toe aan het register. Bodyvelden: product_id (verplicht), variation_id, quantity (standaard 1), priority (standaard medium; toegestane waarden zijn low, medium en high).
PATCH	/registry/{id}/items/reorder	Register-eigenaar	Slaat een nieuwe itemvolgorde op. Bodyveld: item_ids (verplicht array van item-ID's). Elke ID moet tot het register behoren.
PATCH	/registry/{id}/items/{item_id}	Register-eigenaar	Wijzigt de gevraagde hoeveelheid van één artikel. Body veld: quantity. De hoeveelheid kan niet lager zijn dan het reeds gekochte aantal. Geeft 409 terug als het register is gearchiveerd.
DELETE	/registry/{id}/items/{item_id}	Register-eigenaar	Verwijdert één artikel. Geeft 409 terug als het register is gearchiveerd.
GET	/registry/{id}/products/search	Register-eigenaar	Zoekt producten om toe te voegen. Query parameters: q, per_page. Beperkt tot 60 verzoeken per 5 minuten voor elke gebruiker.
GET	/registry/{id}/products/{product_id}/variations	Register-eigenaar	Toont de variaties van een product. Beperkt tot 60 verzoeken per 5 minuten voor elke gebruiker.

Aankoop- en bijdrageroutes

Methode	Route	Wie kan het aanroepen	Wat het doet
GET	/purchases	Eigenaar of winkelmanager (registry_id)	Toont aankopen voor een register. Query parameters: registry_id, thank_you_sent (all, true of false), page, per_page, orderby, order. Elke rij bevat de naam en e-mail van de koper, dus alleen eigenaren en winkelmanagers kunnen deze lezen.
POST	/purchases/{id}/note	Aankoopeigenaar	Slaat de notitie van de eigenaar op een aankoop op. Body veld: note.
POST	/purchases/{id}/thank-you	Aankoopeigenaar	Markeert één aankoop als bedankt of niet. Body veld: sent.
POST	/purchases/bulk-thank-you	Aankoopeigenaar	Markeert meerdere aankopen tegelijk. Body velden: ids en sent. Voor een eigenaar moeten alle ID's toebehoren aan registers die zij bezitten.
GET	/contributions	Eigenaar of winkelmanager (registry_id)	Toont de bijdragen voor het register in de query parameter registry_id, nieuwste eerst. Rijen bevatten de e-mail van de bijdrager.

Registerbeheerder routes

Alle beheerdersroutes vereisen een winkelmanager.

Methode	Route	Wat het doet
GET	/admin/registries	Toont registers. Query parameters: status, event_type, search, orderby, order, page, per_page, include_deleted.
GET	/admin/registries/{id}	Geeft één register terug met zijn artikelen en maximaal 100 aankopen.
PUT	/admin/registries/{id}	Werkt een register bij als beheerder.
DELETE	/admin/registries/{id}	Verwijdert een register als beheerder.
POST	/admin/registries/{id}/close	Archiveert een register. De openbare pagina blijft online met een gearchiveerde banner.
POST	/admin/registries/{id}/restore	Herstelt een register.
POST	/admin/registries/bulk	Voert één actie uit op veel registers. Bodyvelden: action (archive, unarchive of delete) en ids. Geeft een resultaat voor elke ID plus succeeded en failed tellingen terug.
POST	/admin/registries/convert	Converteert een verlanglijst naar een register voor de eigenaar van de verlanglijst. Vereist bodyveld: collection_id. Andere velden komen overeen met /registry/convert.
GET	/admin/registries/by-collections	Vindt het register voor elke verlanglijst-ID in de ids queryparameter (komma-gescheiden). Geeft registry_id, url_code, status en public_url terug voor elke overeenkomst. Verwijderde registers worden weggelaten.

Wat de publieke routes blootstellen

Publieke routes kunnen door iedereen worden aangeroepen, dus controleer wat ze retourneren voordat je erop bouwt.

GET /registry/{url_code} retourneert het registerrecord en de landingspagina-gegevens samengevoegd in één antwoord. Het bevat:

• Registervelden: 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 en updated_at.
• Weergavevelden: title, event_type_label, event_date_iso, event_date_formatted, registrant_names, cover_image_url, cover_image_alt, is_archived, is_owner en public_url.
• Een items lijst. Elk item heeft de producttitel, product-URL, afbeelding, geformatteerde prijs, quantity en purchased_quantity.

Wanneer de aanroeper eigenaar is van het register of een winkelmanager is, bevat het antwoord ook een event_types lijst.

GET /registry/{url_code}/items retourneert elk item met zijn ID, een product blok (ID, variatie-ID, naam, SKU, miniatuur-URL, geformatteerde prijs en of het product nog bestaat), quantity_wanted, quantity_purchased, quantity_remaining, is_fully_claimed, is_archived en priority.

GET /registry/search retourneert alleen gepubliceerde registers. Elk resultaat heeft id, url_code, event_type, event_date, registrant_name, co_registrant_name, cover_image_id, public_url en event_date_formatted. Het antwoord heeft ook total, page en per_page.

Geen van de openbare routes retourneert kopersnamen, e-mailadressen van kopers, aankoopregels, bestel-ID's of bijdragerregels. Deze zijn alleen beschikbaar via de eigenaar- en beheerdersroutes. Gebruik het stwreg_registry_data filter hieronder om velden toe te voegen aan of te verwijderen uit de GET /registry/{url_code} respons. Test uw registratiepagina nadat u een veld hebt verwijderd.

Hooks

De onderstaande hooks zijn het meest nuttig voor het uitbreiden van de plugin. Het aantal argumenten is exact. Wanneer u een hook met meer dan één argument toevoegt, geeft u het aantal argumenten door als de vierde parameter van add_filter() of add_action().

Filters voor registratiegegevens en de landingspagina

Filter	Argumenten	Wat het verandert
stwreg_registry_data	$data (array), $row (object)	De volledige respons van GET /registry/{url_code}. $row is de ruwe registratieregel.
stwreg_registry_items_data	$response (array), $row (object)	De respons van GET /registry/{url_code}/items. De array bevat data, total, currentPage en is_archived.
stwreg_registry_landing_data	$payload (array), $row (object)	De gegevens die worden gebruikt om de landingspagina en de REST-respons op te bouwen, voordat deze worden gerenderd.
stwreg_search_results	$results (array), $args (array)	Het zoekresultaat van de registratie voordat het wordt geretourneerd. De array bevat data, total, page en per_page.
stwreg_landing_html	$html (string), $payload (array)	De uiteindelijke HTML van de gehele registratie landingspagina.
stwreg_landing_item_card	$html (string), $item (array), $payload (array)	De HTML van één itemkaart op de landingspagina.

Retourneer altijd hetzelfde type dat u ontvangt. De plugin converteert de retourwaarde naar een array of een string.

Dit voorbeeld voegt een aangepast veld toe aan de openbare registratie respons:

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

    return $data;
}, 10, 2 );

Dit voorbeeld voegt een tekstregel toe onder de landingspagina:

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 );

De landingspagina wordt ook opgebouwd uit kleinere sectiefilters, één voor elk deel van de pagina. Hun namen beginnen met stwreg_landing_section_ en ze nemen $html en $payload. Voorbeelden zijn stwreg_landing_section_header, stwreg_landing_section_message en stwreg_landing_section_footer. Om het uiterlijk van de pagina zonder code aan te passen, zie Instellingen voor het uiterlijk van de registratie landingspagina.

Rate limit filters

De onderstaande routes beperken hoe vaak een gebruiker of een IP-adres ze kan aanroepen. Elke limiet heeft twee filters. Eén stelt het aantal verzoeken in. De andere stelt het venster in seconden in. Elke filter neemt één argument en moet een geheel getal retourneren.

Limiet filter	Venster filter	Standaard	Route	Geteld per
stwreg_add_item_rate_limit	stwreg_add_item_rate_window	30 verzoeken in 5 minuten	POST /registry/{id}/items	Gebruiker
stwreg_cover_image_rate_limit	stwreg_cover_image_rate_window	30 verzoeken in 5 minuten	POST /registry/cover-image	Gebruiker
stwreg_convert_rate_limit	stwreg_convert_rate_window	5 verzoeken in 5 minuten	POST /registry/convert	Gebruiker
stwreg_contribute_rate_limit	stwreg_contribute_rate_window	10 verzoeken in 5 minuten	POST /contributions	IP-adres en registratie

De zoeklimiet (30 verzoeken per 5 minuten voor elk IP-adres) en de productzoek- en variatielimieten (60 verzoeken per 5 minuten voor elke gebruiker) hebben geen filter. De limiet voor het bijdragebedrag heeft zijn eigen filter, stwreg_contribution_max_amount (float, standaard 100000).

Dit voorbeeld verhoogt de limiet voor het toevoegen van items naar 60 verzoeken in 10 minuten:

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;
} );

Standaard gebruikt de plugin REMOTE_ADDR om het IP-adres van de bezoeker te vinden voor de op IP-adres gebaseerde limieten. Als uw site achter een proxy of CDN staat, is REMOTE_ADDR het proxyadres, dus alle bezoekers delen één limiet. Gebruik de stwreg_trusted_ip_headers filter om de servervariabelen op te sommen die het echte IP-adres bevatten. Vermeld alleen headers die uw proxy instelt, omdat bezoekers de andere kunnen vervalsen.

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

    return $headers;
} );

Aankoopacties

Actie	Argumenten	Wanneer het wordt uitgevoerd
stwreg_after_save_purchase	$purchase_id (int), $payload (array)	Nadat een aankooprij is aangemaakt of bijgewerkt. Het wordt uitgevoerd voor nieuwe rijen en voor updates van een bestaande bestellijn.
stwreg_after_void_purchase	$purchase_id (int), $purchase (object), $previous_status (string), $refunded_quantity (int)	Wanneer een aankoop naar de geannuleerde status gaat, bijvoorbeeld na een terugbetaling.
stwreg_after_record_purchases_from_order	$order_id (int), $order (WC_Order)	Nadat de plugin een betaalde bestelling met registratie-items heeft verwerkt. Het wordt uitgevoerd, zelfs als sommige items niet konden worden gematcht.
stwreg_overpurchase_recorded	$registry_item_id (int), $purchased_total (int), $requested_quantity (int)	Nadat het totaal van geregistreerde aankopen voor een item hoger is dan de gevraagde hoeveelheid door de eigenaar.

De $payload array van stwreg_after_save_purchase heeft deze sleutels: registry_id, registry_item_id, order_id, line_item_id, quantity, buyer_name, buyer_email en status. De status is recorded, voided of refunded. De plugin slaat aankopen uit bestellingen op, en slaat ze opnieuw op wanneer dezelfde bestellijn opnieuw wordt verwerkt. Schrijf je handler zodat deze veilig twee keer kan worden uitgevoerd voor dezelfde aankoop.

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 );

Een registratie-item kan meer geregistreerde aankopen hebben dan de eigenaar heeft gevraagd, bijvoorbeeld wanneer twee kopers tegelijkertijd afrekenen. De plugin staat dit toe. Wanneer dit gebeurt, voert het stwreg_overpurchase_recorded uit nadat het nieuwe totaal is opgeslagen. De actie kan elke keer opnieuw worden uitgevoerd wanneer de plugin een item opnieuw berekent dat nog steeds boven de hoeveelheid is, dus ga er niet van uit dat het slechts één keer wordt uitgevoerd.

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 );

E-mail filters en acties

De plugin verzendt drie e-mails: de eigenaar aankoop e-mail (type owner_new_purchase), de eigenaar restitutie e-mail (type owner_order_refund), en de admin nieuwe registratie e-mail (type admin_new_registry). Om te wijzigen wat ze zeggen, zie Hoe e-mailmeldingen voor cadeauregistratie in te stellen.

Hook	Type	Argumenten	Wat het doet
stwreg_email_send_async	Filter	$async (bool), $payload (array)	Standaard true. Wanneer true, plaatst de plugin de e-mail in de wachtrij met WP-Cron. Wanneer false, verzendt het de e-mail in dezelfde aanvraag.
stwreg_email_{type}_subject	Filter	$subject (string), $context (array), $payload (array)	Wijzigt het onderwerp. Vervang {type} met een e-mailtype, bijvoorbeeld stwreg_email_owner_new_purchase_subject.
stwreg_email_{type}_body	Filter	$body (string), $context (array), $payload (array)	Wijzigt de gerenderde body voordat de e-mail lay-out wordt toegevoegd.
stwreg_after_email_dispatched	Actie	$type (string), $payload (array), $success (bool)	Wordt uitgevoerd nadat de plugin heeft geprobeerd een e-mail te verzenden. $success is false wanneer de e-mail is overgeslagen of is mislukt.

Gebruik de synchrone modus wanneer WP-Cron is uitgeschakeld op uw site of wanneer u een e-mail wilt testen in één enkele aanvraag:

add_filter( 'stwreg_email_send_async', '__return_false' );

Als WP-Cron is uitgeschakeld en u de standaardinstelling laat staan, wachten wachtende e-mails totdat een echte cron-taak wordt uitgevoerd.

Dit voorbeeld wijzigt het onderwerp van de aankoop e-mail voor de eigenaar:

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

Voor de e-mails naar de eigenaar bevat $context recipient, owner_display_name, registry (rij object), purchase (rij object), item (rij object), subject, owner_dashboard en public_url.

REST permissie filters

Elke route voert een permissiecontrole uit en elke controle heeft een filter. Gebruik deze filters om de toegang strikter te maken. Ze kunnen de toegang niet breder maken. Als de plugin een verzoek weigert, kan het filter dit niet toestaan. Als de plugin een verzoek toestaat, kan het filter nog steeds een WP_Error retourneren om het te weigeren.

Filter	Gebruikt door	Argumenten
stwreg_api_public_permissions_check	Openbare routes (/registry/search, /registry/{url_code}, /registry/{url_code}/items, POST /contributions)	$decision (bool of WP_Error), $request (WP_REST_Request)
stwreg_api_logged_in_permissions_check	Routes voor elke ingelogde gebruiker	$decision, $request
stwreg_api_owner_permissions_check	Routes voor register-eigenaar	$decision, $request
stwreg_api_admin_permissions_check	Registerbeheerder routes	$decision, $request

Dit voorbeeld maakt de registry-zoekfunctie alleen beschikbaar voor ingelogde gebruikers:

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 );

De routes /purchases/{id}/note, /purchases/{id}/thank-you en /purchases/bulk-thank-you gebruiken hun eigen eigenaarschapscontroles en voeren deze filters niet uit. GET /purchases en GET /contributions laten de registry-eigenaar door zonder filter. Voor alle anderen voeren ze de admin-controle uit, dus stwreg_api_admin_permissions_check is op hen van toepassing.

Andere acties

Actie	Argumenten	Wanneer het wordt uitgevoerd
stwreg_before_convert_wishlist_to_registry	$collection_id (int), $args (array)	Voordat een verlanglijst wordt geconverteerd. Zie Hoe een verlanglijst om te zetten in een cadeauregister.
stwreg_after_convert_wishlist_to_registry	$registry_id (int), $collection_id (int), $args (array)	Nadat een verlanglijst is geconverteerd.
stwreg_after_add_registry_item	$registry_id (int), $row (object)	Nadat een item aan een register is toegevoegd.
stwreg_after_save_contribution	$contribution_id (int), $registry_id (int)	Nadat een bijdragerij is opgeslagen.

Veelgestelde vragen

Kan ik het URL-voorvoegsel van de registerpagina wijzigen?
Ja. Het filter stwreg_url_prefix neemt het voorvoegsel als een string, en stwreg_registry_public_url neemt de volledige URL (string) en de openbare code (string).

Waar vind ik privacy-export en -verwijdering voor registergegevens?
Zie Hoe registergegevens te exporteren en te verwijderen voor privacyverzoeken.

Wat nu?

• Hoe cadeau-aankopen te bekijken en dankbetuigingen te verzenden
• Hoe stel je een pagina in om een cadeaulijst te zoeken
• Hoe stel je e-mailmeldingen voor cadeaulijsten in

Hulp nodig?

Als u een vraag heeft of tegen problemen aanloopt, staan we klaar om u te helpen.

• Premium gebruikers: Open een supportticket
• Gratis gebruikers: Bezoek ons communityforum