Vous créez une intégration personnalisée avec des registres cadeaux, ou vous modifiez le comportement des registres sur votre boutique ? SaveTo Wishlist Registry ajoute des hooks PHP et des routes d'API REST qui vous permettent de faire les deux sans modifier les fichiers du plugin. Cet article répertorie les routes, qui peut les appeler, ce que les routes publiques retournent, et les hooks que vous pouvez utiliser, avec des exemples fonctionnels.
Pour la référence développeur du plugin de base, consultez Comment étendre SaveTo Wishlist avec des hooks et l'API REST.
Avant de commencer
- SaveTo Wishlist Registry (répertorié dans WordPress sous le nom SaveTo Wishlist Gift Registry Addon) nécessite que WooCommerce et SaveTo Wishlist Lite soient actifs. Il est inclus dans les plans Plus et Business et possède sa propre clé de licence, distincte de SaveTo Wishlist Pro.
- Chaque nom de hook commence par
stwreg_. Ajoutez votre code à un petit plugin ou au fichierfunctions.phpd'un thème enfant. - Les hooks et les routes de cet article existent dans SaveTo Wishlist Registry 1.0.0.
- Les données du registre résident dans des tables personnalisées qui utilisent le préfixe de votre table WordPress :
wp_stw_registries,wp_stw_registry_items,wp_stw_registry_purchasesetwp_stw_registry_contributions. Utilisez les hooks et les routes ci-dessous au lieu d'écrire directement dans ces tables.
Comment fonctionne l'API REST
Toutes les routes utilisent l'espace de noms saveto-wishlist-registry/v1. Sur un site à l'adresse https://example.com, l'URL de base complète est https://example.com/wp-json/saveto-wishlist-registry/v1/.
Les routes qui nécessitent un utilisateur connecté utilisent l'authentification REST standard de WordPress. Dans une session de navigateur, envoyez l'en-tête X-WP-Nonce avec un nonce wp_rest. Pour les appels serveur à serveur, utilisez un mot de passe d'application WordPress. Les routes publiques ne nécessitent aucune connexion.
La colonne « Qui peut l'appeler » dans les tableaux de routes utilise ces termes :
- N'importe qui : aucune connexion requise.
- Utilisateur connecté : tout compte connecté.
- Propriétaire du registre : l'utilisateur connecté qui possède le registre dans la route, ou tout utilisateur ayant la capacité
manage_woocommerce(gestionnaires de boutique et administrateurs par défaut). - Propriétaire de l'achat : l'utilisateur connecté qui possède le registre auquel l'achat appartient, ou tout utilisateur ayant la capacité
manage_woocommerce. - Propriétaire ou gestionnaire de boutique (registry_id) : le propriétaire du registre donné dans le paramètre de requête
registry_id, ou un utilisateur ayant la capacitémanage_woocommerce. Siregistry_idest manquant, seuls les utilisateurs ayant cette capacité réussissent. - Gestionnaire de boutique : un utilisateur ayant la capacité
manage_woocommerce.
Les erreurs reviennent sous forme d'erreurs REST WordPress standard avec un code, un message et un statut HTTP. Les requêtes limitées en bande passante retournent le statut 429 avec le code rate_limited.
Routes de l'API REST
Routes publiques
| Méthode | Route | Qui peut l'appeler | Ce qu'il fait |
|---|---|---|---|
| GET | /registry/search | N'importe qui | Recherche les listes publiées. Paramètres de requête : name (au moins 2 caractères), event_type, page, per_page (maximum 20, par défaut 20). Limité à 30 requêtes par 5 minutes pour chaque adresse IP. |
| GET | /registry/{url_code} | N'importe qui | Retourne une liste par son code public. Le code est composé de 4 à 16 lettres ou chiffres. Retourne 404 pour une liste supprimée. Les listes archivées sont toujours retournées. |
| GET | /registry/{url_code}/items | N'importe qui | Retourne les articles d'une liste. Retourne 404 pour une liste supprimée. |
| POST | /contributions | N'importe qui | Enregistre une contribution monétaire en attente. Champs du corps : registry_id, amount, registry_item_id (facultatif), contributor_name, contributor_email, message. La liste doit être publiée et avoir la collecte de fonds activée. Retourne le nouvel id et le statut pending. |
La route POST /contributions enregistre uniquement une ligne avec le statut pending. Elle n'accepte pas de paiement. Une intégration de paiement doit mettre à jour le statut elle-même.
Routes du propriétaire de la liste
| Méthode | Route | Qui peut l'appeler | Ce qu'il fait |
|---|---|---|---|
| POST | /registry/convert | Utilisateur connecté | Convertit une liste de souhaits en une liste pour l'utilisateur actuel. Nécessite une licence active, sinon retourne 403 avec le code license_inactive. Champs du corps : collection_id, event_type, event_date, registrant_name, co_registrant_name, message, location, cover_image_attachment_id, allow_fund_pooling. |
| POST | /registry/cover-image | Utilisateur connecté | Télécharge une image de couverture sous forme de fichier multipart dans le champ file. JPEG, PNG ou WebP, jusqu'à 5 Mo. Retourne attachment_id et url. |
| GET | /my-registries | Utilisateur connecté | Liste uniquement les listes appartenant à l'utilisateur actuel, y compris les gestionnaires de boutique, avec le nombre d'articles, le nombre de remerciements et un bloc stats global. |
| PUT | /registry/{id} | Propriétaire de la liste | Met à jour les détails de la liste. Envoyez un corps JSON avec les champs à modifier. |
| SUPPRIMER | /registry/{id} | Propriétaire de la liste | Supprime le registre. Renvoie {"deleted":true}. |
| POST | /registre/{id}/items | Propriétaire de la liste | Ajoute un produit au registre. Champs du corps : product_id (requis), variation_id, quantity (défaut 1), priority (défaut medium ; valeurs autorisées : low, medium et high). |
| PATCH | /registre/{id}/items/reorder | Propriétaire de la liste | Enregistre un nouvel ordre d'articles. Champ du corps : item_ids (tableau d'ID d'articles requis). Chaque ID doit appartenir au registre. |
| PATCH | /registre/{id}/items/{item_id} | Propriétaire de la liste | Modifie la quantité demandée d'un article. Champ du corps : quantity. La quantité ne peut pas être inférieure au nombre déjà acheté. Renvoie 409 si le registre est archivé. |
| SUPPRIMER | /registre/{id}/items/{item_id} | Propriétaire de la liste | Supprime un article. Renvoie 409 si le registre est archivé. |
| GET | /registre/{id}/products/search | Propriétaire de la liste | Recherche des produits à ajouter. Paramètres de requête : q, per_page. Limité à 60 requêtes par 5 minutes pour chaque utilisateur. |
| GET | /registre/{id}/products/{product_id}/variations | Propriétaire de la liste | Liste les variations d'un produit. Limité à 60 requêtes par 5 minutes pour chaque utilisateur. |
Routes d'achat et de contribution
| Méthode | Route | Qui peut l'appeler | Ce qu'il fait |
|---|---|---|---|
| GET | /purchases | Propriétaire ou responsable de boutique (registry_id) | Liste les achats pour un registre. Paramètres de requête : registry_id, thank_you_sent (all, true ou false), page, per_page, orderby, order. Chaque ligne contient le nom et l'e-mail de l'acheteur, donc seuls les propriétaires et les responsables de boutique peuvent la lire. |
| POST | /purchases/{id}/note | Propriétaire de l'achat | Enregistre la note du propriétaire sur un achat. Champ du corps : note. |
| POST | /purchases/{id}/thank-you | Propriétaire de l'achat | Marque un achat comme remercié ou non. Champ du corps : sent. |
| POST | /purchases/bulk-thank-you | Propriétaire de l'achat | Marque plusieurs achats à la fois. Champs du corps : ids et sent. Pour un propriétaire, tous les ID doivent appartenir à des registres qu'il possède. |
| GET | /contributions | Propriétaire ou responsable de boutique (registry_id) | Liste les contributions pour le registre dans le paramètre de requête registry_id, les plus récentes en premier. Les lignes incluent l'e-mail du contributeur. |
Routes d'administration du registre
Toutes les routes d'administration nécessitent un responsable de boutique.
| Méthode | Route | Ce qu'il fait |
|---|---|---|
| GET | /admin/registries | Liste les registres. Paramètres de requête : status, event_type, search, orderby, order, page, per_page, include_deleted. |
| GET | /admin/registries/{id} | Retourne un registre avec ses articles et jusqu'à 100 achats. |
| PUT | /admin/registries/{id} | Met à jour un registre en tant qu'administrateur. |
| SUPPRIMER | /admin/registries/{id} | Supprime un registre en tant qu'administrateur. |
| POST | /admin/registries/{id}/close | Archive un registre. La page publique reste en ligne avec une bannière d'archivage. |
| POST | /admin/registries/{id}/restore | Restaure un registre. |
| POST | /admin/registries/bulk | Exécute une action sur plusieurs registres. Champs du corps : action (archive, unarchive ou delete) et ids. Retourne un résultat pour chaque ID plus les décomptes succeeded et failed. |
| POST | /admin/registries/convert | Convertit une liste de souhaits en un registre pour le propriétaire de la liste de souhaits. Champ du corps requis : collection_id. Les autres champs correspondent à /registry/convert. |
| GET | /admin/registries/by-collections | Recherche le registre pour chaque ID de liste de souhaits dans le paramètre de requête ids (séparé par des virgules). Retourne registry_id, url_code, status et public_url pour chaque correspondance. Les registres supprimés sont exclus. |
Ce que les routes publiques exposent
Les routes publiques peuvent être appelées par n'importe qui, vérifiez donc ce qu'elles retournent avant de vous y baser.
GET /registry/{url_code} retourne l'enregistrement du registre et les données de la page de destination fusionnés en une seule réponse. Elle inclut :
- Champs du registre :
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_atetupdated_at. - Champs d'affichage :
title,event_type_label,event_date_iso,event_date_formatted,registrant_names,cover_image_url,cover_image_alt,is_archived,is_owneretpublic_url. - Une liste
items. Chaque article contient le titre du produit, l'URL du produit, l'image, le prix formaté, laquantityet lapurchased_quantity.
Lorsque l'appelant possède le registre ou est un responsable de boutique, la réponse contient également une liste event_types.
GET /registry/{url_code}/items retourne chaque article avec son ID, un bloc product (ID, ID de variation, nom, SKU, URL de la miniature, prix formaté et si le produit existe toujours), quantity_wanted, quantity_purchased, quantity_remaining, is_fully_claimed, is_archived et priority.
GET /registry/search ne retourne que les listes publiées. Chaque résultat a id, url_code, event_type, event_date, registrant_name, co_registrant_name, cover_image_id, public_url et event_date_formatted. La réponse a aussi total, page et per_page.
Aucune des routes publiques ne retourne les noms des acheteurs, les e-mails des acheteurs, les lignes d'achat, les ID de commande ou les lignes de contribution. Ceux-ci ne sont disponibles que via les routes propriétaire et administrateur. Utilisez le filtre stwreg_registry_data ci-dessous pour ajouter ou supprimer des champs de la réponse GET /registry/{url_code}. Testez votre page de liste après avoir supprimé un champ.
Hooks
Les hooks ci-dessous sont les plus utiles pour étendre le plugin. Le nombre d'arguments est exact. Lorsque vous ajoutez un hook avec plus d'un argument, passez le nombre d'arguments comme quatrième paramètre de add_filter() ou add_action().
Filtres pour les données de liste et la page de destination
| Filtre | Arguments | Ce qu'il change |
|---|---|---|
stwreg_registry_data | $data (tableau), $row (objet) | La réponse complète de GET /registry/{url_code}. $row est la ligne brute de la liste. |
stwreg_registry_items_data | $response (tableau), $row (objet) | La réponse de GET /registry/{url_code}/items. Le tableau a data, total, currentPage et is_archived. |
stwreg_registry_landing_data | $payload (tableau), $row (objet) | Les données utilisées pour construire la page de destination et la réponse REST, avant qu'elles ne soient rendues. |
stwreg_search_results | $results (tableau), $args (tableau) | Le résultat de recherche de la liste avant qu'il ne soit retourné. Le tableau a data, total, page et per_page. |
stwreg_landing_html | $html (chaîne), $payload (tableau) | Le HTML final de toute la page de destination de la liste. |
stwreg_landing_item_card | $html (chaîne), $item (tableau), $payload (tableau) | Le HTML d'une carte d'article sur la page de destination. |
Retournez toujours le même type que celui que vous recevez. Le plugin convertit la valeur de retour en tableau ou en chaîne.
Cet exemple ajoute un champ personnalisé à la réponse publique de la liste :
add_filter( 'stwreg_registry_data', function ( array $data, $row ) {
$data['shipping_note'] = 'Gifts ship within 3 business days.';
return $data;
}, 10, 2 );Cet exemple ajoute une ligne de texte sous la page de destination :
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 page de destination est également construite à partir de filtres de sections plus petits, un pour chaque partie de la page. Leurs noms commencent par stwreg_landing_section_ et ils prennent $html et $payload. Les exemples sont stwreg_landing_section_header, stwreg_landing_section_message et stwreg_landing_section_footer. Pour modifier l'apparence de la page sans code, consultez Paramètres d'apparence de la page de destination de la liste.
Filtres de limitation de débit
Les routes ci-dessous limitent la fréquence à laquelle un utilisateur ou une adresse IP peut les appeler. Chaque limite possède deux filtres. L'un définit le nombre de requêtes. L'autre définit la fenêtre en secondes. Chaque filtre prend un argument et doit retourner un entier.
| Filtre de limite | Filtre de fenêtre | Par défaut | Route | Compté par |
|---|---|---|---|---|
stwreg_add_item_rate_limit | stwreg_add_item_rate_window | 30 requêtes en 5 minutes | POST /registry/{id}/items | Utilisateur |
stwreg_cover_image_rate_limit | stwreg_cover_image_rate_window | 30 requêtes en 5 minutes | POST /registry/cover-image | Utilisateur |
stwreg_convert_rate_limit | stwreg_convert_rate_window | 5 requêtes en 5 minutes | POST /registry/convert | Utilisateur |
stwreg_contribute_rate_limit | stwreg_contribute_rate_window | 10 requêtes en 5 minutes | POST /contributions | Adresse IP et registre |
La limite de recherche (30 requêtes en 5 minutes pour chaque adresse IP) et les limites de recherche de produits et de variations (60 requêtes en 5 minutes pour chaque utilisateur) n'ont pas de filtre. La limite du montant de contribution a son propre filtre, stwreg_contribution_max_amount (float, par défaut 100000).
Cet exemple augmente la limite d'ajout d'éléments à 60 requêtes en 10 minutes :
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;
} );Par défaut, le plugin utilise REMOTE_ADDR pour trouver l'adresse IP du visiteur pour les limites basées sur l'IP. Si votre site est derrière un proxy ou un CDN, REMOTE_ADDR est l'adresse du proxy, donc tous les visiteurs partagent une seule limite. Utilisez le filtre stwreg_trusted_ip_headers pour lister les variables serveur qui contiennent la véritable adresse IP. Ne listez que les en-têtes que votre proxy définit, car les visiteurs peuvent falsifier les autres.
add_filter( 'stwreg_trusted_ip_headers', function ( array $headers ) {
$headers[] = 'HTTP_CF_CONNECTING_IP';
return $headers;
} );Actions d'achat
| Action | Arguments | Quand cela s'exécute |
|---|---|---|
stwreg_after_save_purchase | $purchase_id (int), $payload (array) | Après la création ou la mise à jour d'une ligne d'achat. Elle s'exécute pour les nouvelles lignes et pour les mises à jour d'une ligne de commande existante. |
stwreg_after_void_purchase | $purchase_id (int), $purchase (object), $previous_status (string), $refunded_quantity (int) | Lorsqu'un achat passe à l'état annulé, par exemple après un remboursement. |
stwreg_after_record_purchases_from_order | $order_id (int), $order (WC_Order) | Après que le plugin a traité une commande payée contenant des articles de liste. Il s'exécute même si certains articles n'ont pas pu être mis en correspondance. |
stwreg_overpurchase_recorded | $registry_item_id (int), $purchased_total (int), $requested_quantity (int) | Après que le total des achats enregistrés pour un article est supérieur à la quantité demandée par le propriétaire. |
Le tableau $payload de stwreg_after_save_purchase contient les clés suivantes : registry_id, registry_item_id, order_id, line_item_id, quantity, buyer_name, buyer_email et status. Le statut est recorded, voided ou refunded. Le plugin enregistre les achats des commandes, et il les enregistre à nouveau lorsque la même ligne de commande est traitée à nouveau. Écrivez votre gestionnaire de manière à ce qu'il puisse être exécuté deux fois pour le même achat.
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 article de liste peut se retrouver avec plus d'achats enregistrés que ce que le propriétaire a demandé, par exemple lorsque deux acheteurs finalisent leur achat en même temps. Le plugin le permet par conception. Lorsque cela se produit, il exécute stwreg_overpurchase_recorded après avoir enregistré le nouveau total. L'action peut s'exécuter à nouveau chaque fois que le plugin recalcule un article qui dépasse toujours sa quantité, alors ne supposez pas qu'elle ne s'exécute qu'une seule fois.
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 );Filtres et actions d'e-mail
Le plugin envoie trois e-mails : l'e-mail d'achat du propriétaire (type owner_new_purchase), l'e-mail de remboursement du propriétaire (type owner_order_refund) et l'e-mail de nouvelle liste d'administration (type admin_new_registry). Pour modifier leur contenu, consultez Comment configurer les notifications par e-mail de liste de cadeaux.
| Hook | Type | Arguments | Ce qu'il fait |
|---|---|---|---|
stwreg_email_send_async | Filtre | $async (bool), $payload (array) | Par défaut true. Lorsque vrai, le plugin met l'e-mail en file d'attente avec WP-Cron. Lorsque faux, il envoie l'e-mail dans la même requête. |
stwreg_email_{type}_subject | Filtre | $subject (string), $context (array), $payload (array) | Modifie le sujet. Remplacez {type} par un type d'e-mail, par exemple stwreg_email_owner_new_purchase_subject. |
stwreg_email_{type}_body | Filtre | $body (string), $context (array), $payload (array) | Modifie le corps rendu avant l'ajout de la mise en page de l'e-mail. |
stwreg_after_email_dispatched | Action | $type (string), $payload (array), $success (bool) | S'exécute après que le plugin a tenté d'envoyer un e-mail. $success est faux lorsque l'e-mail a été ignoré ou a échoué. |
Utilisez le mode synchrone lorsque WP-Cron est désactivé sur votre site ou lorsque vous souhaitez tester un e-mail dans une seule requête :
add_filter( 'stwreg_email_send_async', '__return_false' );Si WP-Cron est désactivé et que vous laissez la valeur par défaut, les e-mails mis en file d'attente attendent qu'un vrai cron job s'exécute.
Cet exemple modifie l'objet de l'e-mail d'achat du propriétaire :
add_filter( 'stwreg_email_owner_new_purchase_subject', function ( $subject, $context, $payload ) {
return 'Good news: ' . $subject;
}, 10, 3 );Pour les e-mails du propriétaire, $context inclut recipient, owner_display_name, registry (objet ligne), purchase (objet ligne), item (objet ligne), subject, owner_dashboard et public_url.
Filtres de permission REST
Chaque route exécute une vérification de permission, et chaque vérification a un filtre. Utilisez ces filtres pour rendre l'accès plus strict. Ils ne peuvent pas élargir l'accès. Si le plugin refuse une requête, le filtre ne peut pas l'autoriser. Si le plugin autorise une requête, le filtre peut toujours renvoyer une WP_Error pour la refuser.
| Filtre | Utilisé par | Arguments |
|---|---|---|
stwreg_api_public_permissions_check | Routes publiques (/registry/search, /registry/{url_code}, /registry/{url_code}/items, POST /contributions) | $decision (bool ou WP_Error), $request (WP_REST_Request) |
stwreg_api_logged_in_permissions_check | Routes pour tout utilisateur connecté | $decision, $request |
stwreg_api_owner_permissions_check | Routes du propriétaire de la liste | $decision, $request |
stwreg_api_admin_permissions_check | Routes d'administration du registre | $decision, $request |
Cet exemple rend la recherche de liste disponible uniquement aux utilisateurs connectés :
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 );Les routes /purchases/{id}/note, /purchases/{id}/thank-you et /purchases/bulk-thank-you utilisent leurs propres vérifications de propriété et n'exécutent pas ces filtres. GET /purchases et GET /contributions laissent passer le propriétaire de la liste sans filtre. Pour tous les autres, ils exécutent la vérification administrateur, donc stwreg_api_admin_permissions_check s'applique à eux.
Autres actions
| Action | Arguments | Quand cela s'exécute |
|---|---|---|
stwreg_before_convert_wishlist_to_registry | $collection_id (int), $args (array) | Avant qu'une liste de souhaits ne soit convertie. Voir Comment convertir une liste de souhaits en liste de cadeaux. |
stwreg_after_convert_wishlist_to_registry | $registry_id (int), $collection_id (int), $args (array) | Après la conversion d'une liste de souhaits. |
stwreg_after_add_registry_item | $registry_id (int), $row (object) | Après qu'un article a été ajouté à une liste. |
stwreg_after_save_contribution | $contribution_id (int), $registry_id (int) | Après qu'une ligne de contribution a été enregistrée. |
Questions fréquemment posées
Puis-je changer le préfixe de l'URL de la page de la liste ?
Oui. Le filtre stwreg_url_prefix prend le préfixe sous forme de chaîne, et stwreg_registry_public_url prend l'URL complète (chaîne) et le code public (chaîne).
Où trouver l'exportation et la suppression de la confidentialité pour les données du registre ?
Voir Comment exporter et supprimer les données du registre pour les demandes de confidentialité.
Et ensuite ?
- Comment visualiser les achats de cadeaux et envoyer des notes de remerciement
- Comment configurer une page de recherche de registre « Trouver un registre »
- Comment configurer les notifications par e-mail de registre de cadeaux
Besoin d'aide ?
Si vous avez une question ou rencontrez un problème, nous sommes là pour vous aider.
- Utilisateurs premium : Ouvrir un ticket de support
- Utilisateurs gratuits : Visitez notre forum communautaire
