¿Estás creando una integración personalizada con registros de regalos o cambiando el comportamiento de los registros en tu tienda? SaveTo Wishlist Registry añade hooks de PHP y rutas de la API REST que te permiten hacer ambas cosas sin editar los archivos del plugin. Este artículo enumera las rutas, quién puede llamarlas, qué devuelven las rutas públicas y los hooks que puedes usar, con ejemplos funcionales.
Para la referencia del desarrollador del plugin base, consulta Cómo extender SaveTo Wishlist con hooks y la API REST.
Antes de empezar
- SaveTo Wishlist Registry (listado en WordPress como SaveTo Wishlist Gift Registry Addon) necesita que WooCommerce y SaveTo Wishlist Lite estén activos. Viene con los planes Plus y Business y tiene su propia clave de licencia, separada de SaveTo Wishlist Pro.
- Todos los nombres de hooks comienzan con
stwreg_. Añade tu código a un pequeño plugin o al archivofunctions.phpde un tema hijo. - Los hooks y rutas de este artículo existen en SaveTo Wishlist Registry 1.0.0.
- Los datos del registro residen en tablas personalizadas que utilizan el prefijo de tu tabla de WordPress:
wp_stw_registries,wp_stw_registry_items,wp_stw_registry_purchasesywp_stw_registry_contributions. Utiliza los hooks y rutas a continuación en lugar de escribir directamente en estas tablas.
Cómo funciona la API REST
Todas las rutas utilizan el espacio de nombres saveto-wishlist-registry/v1. En un sitio en https://example.com, la URL base completa es https://example.com/wp-json/saveto-wishlist-registry/v1/.
Las rutas que requieren un usuario conectado utilizan la autenticación REST estándar de WordPress. En una sesión de navegador, envía la cabecera X-WP-Nonce con un nonce wp_rest. Para llamadas de servidor a servidor, utiliza una contraseña de aplicación de WordPress. Las rutas públicas no requieren inicio de sesión.
La columna "Quién puede llamarla" en las tablas de rutas utiliza estos términos:
- Cualquiera: no se necesita inicio de sesión.
- Usuario conectado: cualquier cuenta conectada.
- Propietario del registro: el usuario conectado que posee el registro en la ruta, o cualquier usuario con la capacidad
manage_woocommerce(gerentes de tienda y administradores por defecto). - Propietario de la compra: el usuario conectado que posee el registro al que pertenece la compra, o cualquier usuario con la capacidad
manage_woocommerce. - Propietario o gerente de tienda (registry_id): el propietario del registro dado en el parámetro de consulta
registry_id, o un usuario con la capacidadmanage_woocommerce. Si faltaregistry_id, solo pasan los usuarios con esa capacidad. - Gerente de tienda: un usuario con la capacidad
manage_woocommerce.
Los errores se devuelven como errores estándar de WordPress REST con un código, un mensaje y un estado HTTP. Las solicitudes con límite de tasa devuelven el estado 429 con el código rate_limited.
Rutas de la API REST
Rutas públicas
| Método | Ruta | Quién puede llamarla | Lo que hace |
|---|---|---|---|
| GET | /registry/search | Cualquiera | Busca registros publicados. Parámetros de consulta: name (mínimo 2 caracteres), event_type, page, per_page (máximo 20, por defecto 20). Limitado a 30 solicitudes por cada 5 minutos por dirección IP. |
| GET | /registry/{url_code} | Cualquiera | Devuelve un registro por su código público. El código tiene entre 4 y 16 letras o números. Devuelve 404 para un registro eliminado. Los registros archivados todavía se devuelven. |
| GET | /registry/{url_code}/items | Cualquiera | Devuelve los artículos de un registro. Devuelve 404 para un registro eliminado. |
| POST | /contributions | Cualquiera | Registra una contribución de dinero pendiente. Campos del cuerpo: registry_id, amount, registry_item_id (opcional), contributor_name, contributor_email, message. El registro debe estar publicado y tener activada la recaudación de fondos. Devuelve el nuevo id y el estado pending. |
La ruta POST /contributions solo registra una fila con el estado pending. No realiza un pago. Una integración de pago debe actualizar el estado por sí misma.
Rutas del propietario del registro
| Método | Ruta | Quién puede llamarla | Lo que hace |
|---|---|---|---|
| POST | /registry/convert | Usuario conectado | Convierte una lista de deseos en un registro para el usuario actual. Necesita una licencia activa, de lo contrario devuelve 403 con el código license_inactive. Campos del cuerpo: collection_id, event_type, event_date, registrant_name, co_registrant_name, message, location, cover_image_attachment_id, allow_fund_pooling. |
| POST | /registry/cover-image | Usuario conectado | Sube una imagen de portada como un archivo multipart en el campo file. JPEG, PNG o WebP, hasta 5 MB. Devuelve attachment_id y url. |
| GET | /my-registries | Usuario conectado | Lista solo los registros propiedad del usuario actual, incluidos los administradores de la tienda, con recuentos de artículos, recuentos de agradecimiento y un bloque general de stats. |
| PUT | /registry/{id} | Propietario del registro | Actualiza los detalles del registro. Envía un cuerpo JSON con los campos a cambiar. |
| ELIMINAR | /registry/{id} | Propietario del registro | Elimina el registro. Devuelve {"deleted":true}. |
| POST | /registro/{id}/items | Propietario del registro | Añade un producto al registro. Campos del cuerpo: product_id (obligatorio), variation_id, quantity (por defecto 1), priority (por defecto medium; valores permitidos: low, medium y high). |
| PATCH | /registro/{id}/items/reorder | Propietario del registro | Guarda un nuevo orden de artículos. Campo del cuerpo: item_ids (matriz de IDs de artículos obligatoria). Cada ID debe pertenecer al registro. |
| PATCH | /registro/{id}/items/{item_id} | Propietario del registro | Cambia la cantidad solicitada de un artículo. Campo del cuerpo: quantity. La cantidad no puede ser inferior al número ya comprado. Devuelve 409 si el registro está archivado. |
| ELIMINAR | /registro/{id}/items/{item_id} | Propietario del registro | Elimina un artículo. Devuelve 409 si el registro está archivado. |
| GET | /registro/{id}/products/search | Propietario del registro | Busca productos para añadir. Parámetros de consulta: q, per_page. Limitado a 60 solicitudes cada 5 minutos por usuario. |
| GET | /registro/{id}/products/{product_id}/variations | Propietario del registro | Lista las variaciones de un producto. Limitado a 60 solicitudes cada 5 minutos por usuario. |
Rutas de compra y contribución
| Método | Ruta | Quién puede llamarla | Lo que hace |
|---|---|---|---|
| GET | /purchases | Propietario o gerente de la tienda (registry_id) | Lista las compras de un registro. Parámetros de consulta: registry_id, thank_you_sent (all, true o false), page, per_page, orderby, order. Cada fila tiene el nombre y correo electrónico del comprador, por lo que solo los propietarios y gerentes de la tienda pueden leerla. |
| POST | /purchases/{id}/note | Propietario de la compra | Guarda la nota del propietario en una compra. Campo del cuerpo: note. |
| POST | /purchases/{id}/thank-you | Propietario de la compra | Marca una compra como agradecida o no. Campo del cuerpo: sent. |
| POST | /purchases/bulk-thank-you | Propietario de la compra | Marca varias compras a la vez. Campos del cuerpo: ids y sent. Para un propietario, todos los IDs deben pertenecer a registros que posea. |
| GET | /contributions | Propietario o gerente de la tienda (registry_id) | Lista las contribuciones para el registro en el parámetro de consulta registry_id, las más recientes primero. Las filas incluyen el correo electrónico del contribuyente. |
Rutas de administración de registros
Todas las rutas de administración requieren un gerente de tienda.
| Método | Ruta | Lo que hace |
|---|---|---|
| GET | /admin/registries | Lista los registros. Parámetros de consulta: status, event_type, search, orderby, order, page, per_page, include_deleted. |
| GET | /admin/registries/{id} | Devuelve un registro con sus artículos y hasta 100 compras. |
| PUT | /admin/registries/{id} | Actualiza un registro como administrador. |
| ELIMINAR | /admin/registries/{id} | Elimina un registro como administrador. |
| POST | /admin/registries/{id}/close | Archiva un registro. La página pública permanece en línea con un banner de archivado. |
| POST | /admin/registries/{id}/restore | Restaura un registro. |
| POST | /admin/registries/bulk | Ejecuta una acción sobre muchos registros. Campos del cuerpo: action (archive, unarchive o delete) e ids. Devuelve un resultado para cada ID más los recuentos succeeded y failed. |
| POST | /admin/registries/convert | Convierte una lista de deseos en un registro para el propietario de la lista de deseos. Campo del cuerpo requerido: collection_id. Otros campos coinciden con /registry/convert. |
| GET | /admin/registries/by-collections | Busca el registro para cada ID de lista de deseos en el parámetro de consulta ids (separado por comas). Devuelve registry_id, url_code, status y public_url para cada coincidencia. Los registros eliminados se omiten. |
Lo que exponen las rutas públicas
Las rutas públicas pueden ser llamadas por cualquiera, así que comprueba lo que devuelven antes de basarte en ellas.
GET /registry/{url_code} devuelve el registro y los datos de la página de destino fusionados en una sola respuesta. Incluye:
- Campos 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_atyupdated_at. - Campos de visualización:
title,event_type_label,event_date_iso,event_date_formatted,registrant_names,cover_image_url,cover_image_alt,is_archived,is_ownerypublic_url. - Una lista de
items. Cada artículo tiene el título del producto, la URL del producto, la imagen, el precio formateado, laquantityy lapurchased_quantity.
Cuando el llamante es el propietario del registro o un gerente de la tienda, la respuesta también tiene una lista de event_types.
GET /registry/{url_code}/items devuelve cada artículo con su ID, un bloque product (ID, ID de variación, nombre, SKU, URL de miniatura, precio formateado y si el producto todavía existe), quantity_wanted, quantity_purchased, quantity_remaining, is_fully_claimed, is_archived y priority.
GET /registry/search devuelve solo los registros publicados. Cada resultado tiene id, url_code, event_type, event_date, registrant_name, co_registrant_name, cover_image_id, public_url y event_date_formatted. La respuesta también tiene total, page y per_page.
Ninguna de las rutas públicas devuelve nombres de compradores, correos electrónicos de compradores, filas de compra, IDs de pedido o filas de contribución. Estos solo están disponibles a través de las rutas de propietario y administrador. Utilice el filtro stwreg_registry_data a continuación para agregar o eliminar campos de la respuesta GET /registry/{url_code}. Pruebe su página de registro después de eliminar un campo.
Hooks
Los ganchos a continuación son los más útiles para extender el plugin. El número de argumentos es exacto. Cuando agregue un gancho con más de un argumento, pase el número de argumentos como el cuarto parámetro de add_filter() o add_action().
Filtros para datos del registro y la página de destino
| Filtro | Argumentos | Lo que cambia |
|---|---|---|
stwreg_registry_data | $data (array), $row (object) | La respuesta completa de GET /registry/{url_code}. $row es la fila del registro sin procesar. |
stwreg_registry_items_data | $response (array), $row (object) | La respuesta de GET /registry/{url_code}/items. El array tiene data, total, currentPage y is_archived. |
stwreg_registry_landing_data | $payload (array), $row (object) | Los datos utilizados para construir la página de destino y la respuesta REST, antes de que se renderice. |
stwreg_search_results | $results (array), $args (array) | El resultado de la búsqueda del registro antes de ser devuelto. El array tiene data, total, page y per_page. |
stwreg_landing_html | $html (string), $payload (array) | El HTML completo de toda la página de destino del registro. |
stwreg_landing_item_card | $html (string), $item (array), $payload (array) | El HTML de una tarjeta de artículo en la página de destino. |
Devuelve siempre el mismo tipo que recibes. El plugin convierte el valor de retorno a un array o a una cadena.
Este ejemplo agrega un campo personalizado a la respuesta pública del registro:
add_filter( 'stwreg_registry_data', function ( array $data, $row ) {
$data['shipping_note'] = 'Gifts ship within 3 business days.';
return $data;
}, 10, 2 );Este ejemplo agrega una línea de texto debajo de la página de destino:
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 página de destino también se construye a partir de filtros de secciones más pequeñas, uno para cada parte de la página. Sus nombres comienzan con stwreg_landing_section_ y toman $html y $payload. Los ejemplos son stwreg_landing_section_header, stwreg_landing_section_message y stwreg_landing_section_footer. Para cambiar la apariencia de la página sin código, consulte Configuración de apariencia de la página de destino del registro.
Filtros de límite de tasa
Las rutas siguientes limitan la frecuencia con la que un usuario o una dirección IP pueden llamarlas. Cada límite tiene dos filtros. Uno establece el número de solicitudes. El otro establece la ventana en segundos. Cada filtro toma un argumento y debe devolver un entero.
| Filtro de límite | Filtro de ventana | Por defecto | Ruta | Contado por |
|---|---|---|---|---|
stwreg_add_item_rate_limit | stwreg_add_item_rate_window | 30 solicitudes en 5 minutos | POST /registry/{id}/items | Usuario |
stwreg_cover_image_rate_limit | stwreg_cover_image_rate_window | 30 solicitudes en 5 minutos | POST /registry/cover-image | Usuario |
stwreg_convert_rate_limit | stwreg_convert_rate_window | 5 solicitudes en 5 minutos | POST /registry/convert | Usuario |
stwreg_contribute_rate_limit | stwreg_contribute_rate_window | 10 solicitudes en 5 minutos | POST /contributions | Dirección IP y registro |
El límite de búsqueda (30 solicitudes en 5 minutos para cada dirección IP) y los límites de búsqueda de productos y variaciones (60 solicitudes en 5 minutos para cada usuario) no tienen filtro. El límite de cantidad de contribución tiene su propio filtro, stwreg_contribution_max_amount (flotante, por defecto 100000).
Este ejemplo aumenta el límite de añadir artículos a 60 solicitudes en 10 minutos:
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;
} );Por defecto, el plugin utiliza REMOTE_ADDR para encontrar la dirección IP del visitante para los límites basados en IP. Si tu sitio está detrás de un proxy o CDN, REMOTE_ADDR es la dirección del proxy, por lo que todos los visitantes comparten un solo límite. Utiliza el filtro stwreg_trusted_ip_headers para listar las variables del servidor que contienen la dirección IP real. Solo lista las cabeceras que tu proxy establece, ya que los visitantes pueden falsificar las otras.
add_filter( 'stwreg_trusted_ip_headers', function ( array $headers ) {
$headers[] = 'HTTP_CF_CONNECTING_IP';
return $headers;
} );Acciones de compra
| Acción | Argumentos | Cuándo se ejecuta |
|---|---|---|
stwreg_after_save_purchase | $purchase_id (int), $payload (array) | Después de que se crea o actualiza una fila de compra. Se ejecuta para filas nuevas y para actualizaciones de una línea de pedido existente. |
stwreg_after_void_purchase | $purchase_id (int), $purchase (objeto), $previous_status (string), $refunded_quantity (int) | Cuando una compra pasa al estado anulado, por ejemplo después de un reembolso. |
stwreg_after_record_purchases_from_order | $order_id (int), $order (WC_Order) | Después de que el plugin procesa un pedido pagado que contiene artículos de registro. Se ejecuta incluso si algunos artículos no se pudieron emparejar. |
stwreg_overpurchase_recorded | $registry_item_id (int), $purchased_total (int), $requested_quantity (int) | Después de que el total de compras registradas para un artículo sea superior a la cantidad solicitada por el propietario. |
El array $payload de stwreg_after_save_purchase tiene estas claves: registry_id, registry_item_id, order_id, line_item_id, quantity, buyer_name, buyer_email y status. El estado es recorded, voided o refunded. El plugin guarda las compras de los pedidos y las vuelve a guardar cuando se procesa la misma línea de pedido de nuevo. Escriba su manejador para que sea seguro ejecutarlo dos veces para la misma compra.
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 artículo de registro puede terminar con más compras registradas de las que el propietario solicitó, por ejemplo, cuando dos compradores completan la compra al mismo tiempo. El plugin permite esto por diseño. Cuando sucede, ejecuta stwreg_overpurchase_recorded después de guardar el total nuevo. La acción puede ejecutarse de nuevo cada vez que el plugin recalcula un artículo que todavía está por encima de su cantidad, así que no asuma que se ejecuta solo una vez.
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 );Filtros y acciones de correo electrónico
El plugin envía tres correos electrónicos: el correo de compra del propietario (tipo owner_new_purchase), el correo de reembolso del propietario (tipo owner_order_refund) y el correo de registro nuevo del administrador (tipo admin_new_registry). Para cambiar lo que dicen, consulte Cómo configurar las notificaciones por correo electrónico del registro de regalos.
| Hook | Tipo | Argumentos | Lo que hace |
|---|---|---|---|
stwreg_email_send_async | Filtro | $async (bool), $payload (array) | Por defecto true. Cuando es verdadero, el plugin pone en cola el correo electrónico con WP-Cron. Cuando es falso, envía el correo electrónico en la misma solicitud. |
stwreg_email_{type}_subject | Filtro | $subject (string), $context (array), $payload (array) | Cambia el asunto. Reemplace {type} con un tipo de correo electrónico, por ejemplo stwreg_email_owner_new_purchase_subject. |
stwreg_email_{type}_body | Filtro | $body (string), $context (array), $payload (array) | Cambia el cuerpo renderizado antes de que se añada el diseño del correo electrónico. |
stwreg_after_email_dispatched | Acción | $type (string), $payload (array), $success (bool) | Se ejecuta después de que el plugin intente enviar un correo electrónico. $success es falso cuando el correo electrónico se omitió o falló. |
Utilice el modo síncrono cuando WP-Cron esté desactivado en su sitio o cuando desee probar un correo electrónico en una sola solicitud:
add_filter( 'stwreg_email_send_async', '__return_false' );Si WP-Cron está desactivado y deja el valor predeterminado, los correos electrónicos en cola esperan hasta que se ejecute un trabajo cron real.
Este ejemplo cambia el asunto del correo electrónico de compra del propietario:
add_filter( 'stwreg_email_owner_new_purchase_subject', function ( $subject, $context, $payload ) {
return 'Good news: ' . $subject;
}, 10, 3 );Para los correos electrónicos del propietario, $context incluye recipient, owner_display_name, registry (objeto de fila), purchase (objeto de fila), item (objeto de fila), subject, owner_dashboard y public_url.
Filtros de permisos REST
Cada ruta ejecuta una comprobación de permisos, y cada comprobación tiene un filtro. Usa estos filtros para hacer el acceso más estricto. No pueden hacer el acceso más amplio. Si el plugin deniega una solicitud, el filtro no puede permitirla. Si el plugin permite una solicitud, el filtro aún puede devolver un WP_Error para denegarla.
| Filtro | Usado por | Argumentos |
|---|---|---|
stwreg_api_public_permissions_check | Rutas públicas (/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 | Rutas para cualquier usuario conectado | $decision, $request |
stwreg_api_owner_permissions_check | Rutas del propietario del registro | $decision, $request |
stwreg_api_admin_permissions_check | Rutas de administración de registros | $decision, $request |
Este ejemplo hace que la búsqueda de registros esté disponible solo para usuarios conectados:
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 );Las rutas /purchases/{id}/note, /purchases/{id}/thank-you y /purchases/bulk-thank-you usan sus propias comprobaciones de propiedad y no ejecutan estos filtros. GET /purchases y GET /contributions permiten al propietario del registro sin filtro. Para todos los demás, ejecutan la comprobación de administrador, por lo que stwreg_api_admin_permissions_check se aplica a ellos.
Otras acciones
| Acción | Argumentos | Cuándo se ejecuta |
|---|---|---|
stwreg_before_convert_wishlist_to_registry | $collection_id (int), $args (array) | Antes de que se convierta una lista de deseos. Ver Cómo convertir una lista de deseos en un registro de regalos. |
stwreg_after_convert_wishlist_to_registry | $registry_id (int), $collection_id (int), $args (array) | Después de que se convierte una lista de deseos. |
stwreg_after_add_registry_item | $registry_id (int), $row (object) | Después de que se añade un artículo a un registro. |
stwreg_after_save_contribution | $contribution_id (int), $registry_id (int) | Después de que se guarda una fila de contribución. |
Preguntas frecuentes
¿Puedo cambiar el prefijo de la URL de la página de registro?
Sí. El filtro stwreg_url_prefix toma el prefijo como una cadena, y stwreg_registry_public_url toma la URL completa (cadena) y el código público (cadena).
¿Dónde encuentro la exportación y el borrado de privacidad para los datos del registro?
Ver Cómo exportar y borrar datos del registro para solicitudes de privacidad.
¿Qué sigue?
- Cómo ver las compras de regalos y enviar notas de agradecimiento
- Cómo configurar una página de búsqueda de "Encuentra un registro"
- Cómo configurar notificaciones por correo electrónico del registro de regalos
¿Necesitas ayuda?
Si tienes alguna pregunta o encuentras algún problema, estamos aquí para ayudarte.
- Usuarios premium: Abrir un ticket de soporte
- Usuarios gratuitos: Visita nuestro foro comunitario
