Jak rozszerzyć rejestr SaveTo Wishlist za pomocą haków i interfejsu REST API

Tworzysz niestandardową integrację z listami prezentów lub zmieniasz sposób działania list na Twoim sklepie? SaveTo Wishlist Registry dodaje haki PHP i trasy REST API, które pozwalają zrobić obie rzeczy bez edycji plików wtyczki. Ten artykuł zawiera listę tras, kto może ich używać, co zwracają trasy publiczne oraz haki, których możesz użyć, wraz z działającymi przykładami.

Aby uzyskać dokumentację deweloperską podstawowej wtyczki, zobacz Jak rozszerzyć SaveTo Wishlist za pomocą haków i REST API.

Zanim zaczniesz

• SaveTo Wishlist Registry (w WordPressie widoczny jako SaveTo Wishlist Gift Registry Addon) wymaga aktywnego WooCommerce i SaveTo Wishlist Lite. Jest dostępny w planach Plus i Business i posiada własny klucz licencyjny, oddzielny od SaveTo Wishlist Pro.
• Każda nazwa haka zaczyna się od stwreg_. Dodaj swój kod do małej wtyczki lub do pliku functions.php motywu potomnego.
• Haki i trasy opisane w tym artykule są dostępne w SaveTo Wishlist Registry w wersji 1.0.0.
• Dane rejestru znajdują się w niestandardowych tabelach, które używają prefiksu tabel WordPressa: wp_stw_registries, wp_stw_registry_items, wp_stw_registry_purchases i wp_stw_registry_contributions. Używaj poniższych haków i tras zamiast bezpośredniego zapisu do tych tabel.

Jak działa REST API

Wszystkie trasy używają przestrzeni nazw saveto-wishlist-registry/v1. Na stronie https://example.com pełny adres bazowy to https://example.com/wp-json/saveto-wishlist-registry/v1/.

Trasy wymagające zalogowanego użytkownika używają standardowej autentykacji REST WordPressa. W sesji przeglądarki wyślij nagłówek X-WP-Nonce z nonce wp_rest. W przypadku wywołań serwer-serwer użyj hasła aplikacji WordPress. Trasy publiczne nie wymagają logowania.

Kolumna „Kto może jej użyć” w tabelach tras używa następujących terminów:

• Każdy: logowanie nie jest wymagane.
• Zalogowany użytkownik: dowolne konto zalogowanego użytkownika.
• Właściciel rejestru: zalogowany użytkownik, który jest właścicielem rejestru w trasie, lub dowolny użytkownik z uprawnieniem manage_woocommerce (domyślnie menedżerowie sklepów i administratorzy).
• Właściciel zakupu: zalogowany użytkownik, który jest właścicielem rejestru, do którego należy zakup, lub dowolny użytkownik z uprawnieniem manage_woocommerce.
• Właściciel lub menedżer sklepu (registry_id): właściciel rejestru podanego w parametrze zapytania registry_id lub użytkownik z uprawnieniem manage_woocommerce. Jeśli registry_id brakuje, przechodzą tylko użytkownicy z tym uprawnieniem.
• Menedżer sklepu: użytkownik z uprawnieniem manage_woocommerce.

Błędy wracają jako standardowe błędy WordPress REST z code, komunikatem i statusem HTTP. Żądania z ograniczonym limitem zwracają status 429 z kodem rate_limited.

Trasy REST API

Trasy publiczne

Metoda	Trasa	Kto może ją wywołać	Co robi
GET	/registry/search	Każdy	Wyszukuje opublikowane rejestry. Parametry zapytania: name (minimum 2 znaki), event_type, page, per_page (maksymalnie 20, domyślnie 20). Ograniczone do 30 żądań na 5 minut dla każdego adresu IP.
GET	/registry/{url_code}	Każdy	Zwraca jeden rejestr według jego publicznego kodu. Kod ma od 4 do 16 liter lub cyfr. Zwraca 404 dla usuniętego rejestru. Zarchiwizowane rejestry są nadal zwracane.
GET	/registry/{url_code}/items	Każdy	Zwraca pozycje w rejestrze. Zwraca 404 dla usuniętego rejestru.
POST	/contributions	Każdy	Rejestruje oczekującą wpłatę pieniędzy. Pola ciała: registry_id, amount, registry_item_id (opcjonalnie), contributor_name, contributor_email, message. Rejestr musi być opublikowany i mieć włączone zbieranie funduszy. Zwraca nowy id i status pending.

Trasa POST /contributions jedynie rejestruje wiersz ze statusem pending. Nie przyjmuje płatności. Integracja płatności musi sama zaktualizować status.

Trasy właściciela rejestru

Metoda	Trasa	Kto może ją wywołać	Co robi
POST	/registry/convert	Zalogowany użytkownik	Konwertuje listę życzeń na rejestr dla bieżącego użytkownika. Wymaga aktywnej licencji, w przeciwnym razie zwraca 403 z kodem license_inactive. Pola ciała: collection_id, event_type, event_date, registrant_name, co_registrant_name, message, location, cover_image_attachment_id, allow_fund_pooling.
POST	/registry/cover-image	Zalogowany użytkownik	Przesyła obrazek okładki jako plik multipart w polu file. JPEG, PNG lub WebP, do 5 MB. Zwraca attachment_id i url.
GET	/my-registries	Zalogowany użytkownik	Wyświetla tylko rejestry należące do bieżącego użytkownika, w tym menedżerów sklepu, z liczbą pozycji, liczbą podziękowań i ogólnym blokiem stats.
PUT	/registry/{id}	Właściciel rejestru	Aktualizuje szczegóły rejestru. Wyślij ciało JSON z polami do zmiany.
USUŃ	/registry/{id}	Właściciel rejestru	Usuwa rejestr. Zwraca {"deleted":true}.
POST	/rejestr/{id}/elementy	Właściciel rejestru	Dodaje produkt do rejestru. Pola ciała: product_id (wymagane), variation_id, quantity (domyślnie 1), priority (domyślnie medium; dozwolone wartości to low, medium i high).
ZMIEN	/rejestr/{id}/elementy/zmiana-kolejnosci	Właściciel rejestru	Zapisuje nową kolejność elementów. Pole ciała: item_ids (wymagana tablica identyfikatorów elementów). Każdy identyfikator musi należeć do rejestru.
ZMIEN	/rejestr/{id}/elementy/{item_id}	Właściciel rejestru	Zmienia żądaną ilość jednego elementu. Pole ciała: quantity. Ilość nie może spaść poniżej liczby już zakupionych. Zwraca 409, jeśli rejestr jest zarchiwizowany.
USUŃ	/rejestr/{id}/elementy/{item_id}	Właściciel rejestru	Usuwa jeden element. Zwraca 409, jeśli rejestr jest zarchiwizowany.
GET	/rejestr/{id}/produkty/wyszukiwanie	Właściciel rejestru	Wyszukuje produkty do dodania. Parametry zapytania: q, per_page. Ograniczone do 60 żądań na 5 minut dla każdego użytkownika.
GET	/rejestr/{id}/produkty/{product_id}/wariacje	Właściciel rejestru	Wyświetla wariacje produktu. Ograniczone do 60 żądań na 5 minut dla każdego użytkownika.

Trasy zakupu i wkładu

Metoda	Trasa	Kto może ją wywołać	Co robi
GET	/zakupy	Właściciel lub kierownik sklepu (registry_id)	Wyświetla zakupy dla rejestru. Parametry zapytania: registry_id, thank_you_sent (all, true lub false), page, per_page, orderby, order. Każdy wiersz zawiera imię i adres e-mail kupującego, więc tylko właściciele i kierownicy sklepów mogą go odczytać.
POST	/zakupy/{id}/notatka	Właściciel zakupu	Zapisuje notatkę właściciela przy zakupie. Pole ciała: note.
POST	/zakupy/{id}/podziekowanie	Właściciel zakupu	Oznacza jeden zakup jako podziękowany lub nie. Pole ciała: sent.
POST	/zakupy/zbiorowe-podziekowanie	Właściciel zakupu	Oznacza kilka zakupów naraz. Pola ciała: ids i sent. Dla właściciela wszystkie identyfikatory muszą należeć do rejestrów, które posiada.
GET	/contributions	Właściciel lub kierownik sklepu (registry_id)	Wyświetla wkłady dla rejestru w parametrze zapytania registry_id, najnowsze najpierw. Wiersze zawierają adres e-mail darczyńcy.

Trasy administratora rejestru

Wszystkie trasy administracyjne wymagają kierownika sklepu.

Metoda	Trasa	Co robi
GET	/admin/rejestry	Wyświetla rejestry. Parametry zapytania: status, event_type, search, orderby, order, page, per_page, include_deleted.
GET	/admin/registries/{id}	Zwraca jeden rejestr z jego pozycjami i maksymalnie 100 zakupami.
PUT	/admin/registries/{id}	Aktualizuje rejestr jako administrator.
USUŃ	/admin/registries/{id}	Usuwa rejestr jako administrator.
POST	/admin/registries/{id}/close	Archiwizuje rejestr. Publiczna strona pozostaje online z banerem archiwalnym.
POST	/admin/registries/{id}/restore	Przywraca rejestr.
POST	/admin/registries/bulk	Wykonuje jedną akcję na wielu rejestrach. Pola ciała: action (archive, unarchive lub delete) i ids. Zwraca wynik dla każdego ID plus liczbę succeeded i failed.
POST	/admin/registries/convert	Konwertuje listę życzeń w rejestr dla właściciela listy życzeń. Wymagane pole ciała: collection_id. Inne pola pasują do /registry/convert.
GET	/admin/registries/by-collections	Znajduje rejestr dla każdego ID listy życzeń w parametrze zapytania ids (rozdzielanym przecinkami). Zwraca registry_id, url_code, status i public_url dla każdego dopasowania. Usunięte rejestry są pomijane.

Co udostępniają publiczne trasy

Publiczne trasy mogą być wywoływane przez każdego, więc sprawdź, co zwracają, zanim zaczniesz na nich budować.

GET /registry/{url_code} zwraca rekord rejestru i dane strony docelowej połączone w jedną odpowiedź. Zawiera:

• Pola rejestru: 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 i updated_at.
• Pola wyświetlania: title, event_type_label, event_date_iso, event_date_formatted, registrant_names, cover_image_url, cover_image_alt, is_archived, is_owner i public_url.
• Lista items. Każdy element zawiera tytuł produktu, adres URL produktu, obraz, sformatowaną cenę, quantity i purchased_quantity.

Gdy dzwoniący jest właścicielem rejestru lub menedżerem sklepu, odpowiedź zawiera również listę event_types.

GET /registry/{url_code}/items zwraca każdy element z jego ID, blokiem product (ID, ID wariacji, nazwa, SKU, adres URL miniaturki, sformatowana cena i czy produkt nadal istnieje), quantity_wanted, quantity_purchased, quantity_remaining, is_fully_claimed, is_archived i priority.

GET /registry/search zwraca tylko opublikowane listy. Każdy wynik zawiera id, url_code, event_type, event_date, registrant_name, co_registrant_name, cover_image_id, public_url i event_date_formatted. Odpowiedź zawiera również total, page i per_page.

Żadna z publicznych tras nie zwraca nazw kupujących, adresów e-mail kupujących, pozycji zakupu, identyfikatorów zamówień ani pozycji wpłat. Są one dostępne tylko przez trasy właściciela i administratora. Użyj poniższego filtra stwreg_registry_data, aby dodać lub usunąć pola z odpowiedzi GET /registry/{url_code}. Przetestuj stronę swojej listy po usunięciu pola.

Haki

Poniższe haki są najbardziej przydatne do rozszerzania wtyczki. Liczba argumentów jest dokładna. Dodając hak z więcej niż jednym argumentem, przekaż liczbę argumentów jako czwarty parametr add_filter() lub add_action().

Filtry danych listy i strony docelowej

Filtr	Argumenty	Co zmienia
stwreg_registry_data	$data (tablica), $row (obiekt)	Pełna odpowiedź GET /registry/{url_code}. $row to surowy wiersz listy.
stwreg_registry_items_data	$response (tablica), $row (obiekt)	Odpowiedź GET /registry/{url_code}/items. Tablica zawiera data, total, currentPage i is_archived.
stwreg_registry_landing_data	$payload (tablica), $row (obiekt)	Dane używane do budowania strony docelowej i odpowiedzi REST, przed jej wyrenderowaniem.
stwreg_search_results	$results (tablica), $args (tablica)	Wynik wyszukiwania listy przed zwróceniem. Tablica zawiera data, total, page i per_page.
stwreg_landing_html	$html (ciąg znaków), $payload (tablica)	Ostateczny kod HTML całej strony docelowej listy.
stwreg_landing_item_card	$html (ciąg znaków), $item (tablica), $payload (tablica)	Kod HTML pojedynczej karty przedmiotu na stronie docelowej.

Zawsze zwracaj ten sam typ, który otrzymujesz. Wtyczka rzutuje wartość zwracaną na tablicę lub ciąg znaków.

Ten przykład dodaje niestandardowe pole do publicznej odpowiedzi listy:

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

    return $data;
}, 10, 2 );

Ten przykład dodaje linię tekstu pod stroną docelową:

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

Strona docelowa jest również budowana z mniejszych filtrów sekcji, po jednym dla każdej części strony. Ich nazwy zaczynają się od stwreg_landing_section_ i przyjmują $html oraz $payload. Przykłady to stwreg_landing_section_header, stwreg_landing_section_message i stwreg_landing_section_footer. Aby zmienić wygląd strony bez kodu, zobacz Ustawienia wyglądu strony docelowej listy.

Filtry limitu żądań

Poniższe trasy ograniczają, jak często jeden użytkownik lub jeden adres IP może je wywoływać. Każdy limit ma dwa filtry. Jeden określa liczbę żądań. Drugi określa okno w sekundach. Każdy filtr przyjmuje jeden argument i musi zwracać liczbę całkowitą.

Filtr limitu	Filtr okna	Domyślnie	Trasa	Zliczane na
stwreg_add_item_rate_limit	stwreg_add_item_rate_window	30 żądań w 5 minut	POST /registry/{id}/items	Użytkownik
stwreg_cover_image_rate_limit	stwreg_cover_image_rate_window	30 żądań w 5 minut	POST /registry/cover-image	Użytkownik
stwreg_convert_rate_limit	stwreg_convert_rate_window	5 żądań w 5 minut	POST /registry/convert	Użytkownik
stwreg_contribute_rate_limit	stwreg_contribute_rate_window	10 żądań w 5 minut	POST /contributions	Adres IP i rejestr

Limit wyszukiwania (30 żądań na 5 minut dla każdego adresu IP) oraz limity wyszukiwania produktów i wariantów (60 żądań na 5 minut dla każdego użytkownika) nie mają filtra. Limit kwoty składki ma własny filtr, stwreg_contribution_max_amount (float, domyślnie 100000).

Ten przykład zwiększa limit dodawania elementów do 60 żądań w ciągu 10 minut:

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

Domyślnie wtyczka używa REMOTE_ADDR do znalezienia adresu IP odwiedzającego dla limitów opartych na adresie IP. Jeśli Twoja witryna znajduje się za serwerem proxy lub CDN, REMOTE_ADDR to adres serwera proxy, więc wszyscy odwiedzający dzielą jeden limit. Użyj filtra stwreg_trusted_ip_headers, aby wymienić zmienne serwera, które przechowują rzeczywisty adres IP. Wymieniaj tylko nagłówki ustawione przez Twój serwer proxy, ponieważ odwiedzający mogą fałszować inne.

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

    return $headers;
} );

Akcje zakupu

Akcja	Argumenty	Kiedy działa
stwreg_after_save_purchase	$purchase_id (int), $payload (array)	Po utworzeniu lub zaktualizowaniu wiersza zakupu. Działa dla nowych wierszy i aktualizacji istniejącego wiersza zamówienia.
stwreg_after_void_purchase	$purchase_id (int), $purchase (object), $previous_status (string), $refunded_quantity (int)	Gdy zakup przejdzie w stan unieważniony, na przykład po zwrocie.
stwreg_after_record_purchases_from_order	$order_id (int), $order (WC_Order)	Po tym, jak wtyczka przetworzy opłacone zamówienie zawierające pozycje z listy życzeń. Działa nawet jeśli niektóre pozycje nie mogły zostać dopasowane.
stwreg_overpurchase_recorded	$registry_item_id (int), $purchased_total (int), $requested_quantity (int)	Po tym, jak łączna liczba zarejestrowanych zakupów dla pozycji jest wyższa niż ilość, o którą prosił właściciel.

Tablica $payload akcji stwreg_after_save_purchase zawiera następujące klucze: registry_id, registry_item_id, order_id, line_item_id, quantity, buyer_name, buyer_email i status. Status to recorded, voided lub refunded. Wtyczka zapisuje zakupy z zamówień i zapisuje je ponownie, gdy ta sama pozycja zamówienia jest przetwarzana ponownie. Napisz swój program obsługi tak, aby można go było bezpiecznie uruchomić dwukrotnie dla tego samego zakupu.

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

Pozycja z listy życzeń może mieć więcej zarejestrowanych zakupów niż prosił właściciel, na przykład gdy dwóch kupujących jednocześnie dokonuje zakupu. Wtyczka dopuszcza to z założenia. Kiedy to się zdarza, uruchamia stwreg_overpurchase_recorded po zapisaniu nowego łącznego wyniku. Akcja może uruchamiać się ponownie za każdym razem, gdy wtyczka przelicza pozycję, która nadal przekracza swoją ilość, więc nie zakładaj, że uruchamia się tylko raz.

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

Filtry i akcje e-mail

Wtyczka wysyła trzy e-maile: e-mail o zakupie dla właściciela (typ owner_new_purchase), e-mail o zwrocie dla właściciela (typ owner_order_refund) i e-mail o nowej liście życzeń dla administratora (typ admin_new_registry). Aby zmienić ich treść, zobacz Jak skonfigurować powiadomienia e-mail o listach życzeń.

Hook	Typ	Argumenty	Co robi
stwreg_email_send_async	Filtr	$async (bool), $payload (array)	Domyślnie true. Gdy jest prawdziwe, wtyczka umieszcza e-mail w kolejce za pomocą WP-Cron. Gdy jest fałszywe, wysyła e-mail w tym samym żądaniu.
stwreg_email_{type}_subject	Filtr	$subject (string), $context (array), $payload (array)	Zmienia temat. Zastąp {type} typem e-maila, na przykład stwreg_email_owner_new_purchase_subject.
stwreg_email_{type}_body	Filtr	$body (string), $context (array), $payload (array)	Zmienia wyrenderowane ciało przed dodaniem układu e-maila.
stwreg_after_email_dispatched	Akcja	$type (string), $payload (array), $success (bool)	Uruchamia się po próbie wysłania e-maila przez wtyczkę. $success jest fałszywe, gdy e-mail został pominięty lub nie powiódł się.

Użyj trybu synchronicznego, gdy WP-Cron jest wyłączony na Twojej stronie lub gdy chcesz przetestować e-mail w jednym żądaniu:

add_filter( 'stwreg_email_send_async', '__return_false' );

Jeśli WP-Cron jest wyłączony i pozostawisz domyślne ustawienia, e-maile w kolejce będą czekać na uruchomienie rzeczywistego zadania cron.

Ten przykład zmienia temat e-maila z zakupem dla właściciela:

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

Dla e-maili właściciela, $context zawiera recipient, owner_display_name, registry (obiekt wiersza), purchase (obiekt wiersza), item (obiekt wiersza), subject, owner_dashboard i public_url.

Filtry uprawnień REST

Każda trasa uruchamia sprawdzanie uprawnień, a każde sprawdzenie ma filtr. Użyj tych filtrów, aby ograniczyć dostęp. Nie mogą one poszerzyć dostępu. Jeśli wtyczka odrzuci żądanie, filtr nie może go zezwolić. Jeśli wtyczka zezwoli na żądanie, filtr nadal może zwrócić WP_Error, aby je odrzucić.

Filtr	Używane przez	Argumenty
stwreg_api_public_permissions_check	Trasy publiczne (/registry/search, /registry/{url_code}, /registry/{url_code}/items, POST /contributions)	$decision (bool lub WP_Error), $request (WP_REST_Request)
stwreg_api_logged_in_permissions_check	Trasy dla każdego zalogowanego użytkownika	$decision, $request
stwreg_api_owner_permissions_check	Trasy właściciela rejestru	$decision, $request
stwreg_api_admin_permissions_check	Trasy administratora rejestru	$decision, $request

Ten przykład sprawia, że wyszukiwanie rejestru jest dostępne tylko dla zalogowanych użytkowników:

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

Trasy /purchases/{id}/note, /purchases/{id}/thank-you i /purchases/bulk-thank-you używają własnych kontroli własności i nie uruchamiają tych filtrów. GET /purchases i GET /contributions przepuszczają właściciela rejestru bez filtra. Dla wszystkich innych uruchamiają kontrolę administratora, więc stwreg_api_admin_permissions_check ma do nich zastosowanie.

Inne akcje

Akcja	Argumenty	Kiedy działa
stwreg_before_convert_wishlist_to_registry	$collection_id (int), $args (array)	Przed konwersją listy życzeń. Zobacz Jak przekonwertować listę życzeń na rejestr prezentów.
stwreg_after_convert_wishlist_to_registry	$registry_id (int), $collection_id (int), $args (array)	Po konwersji listy życzeń.
stwreg_after_add_registry_item	$registry_id (int), $row (object)	Po dodaniu elementu do rejestru.
stwreg_after_save_contribution	$contribution_id (int), $registry_id (int)	Po zapisaniu wiersza wkładu.

Często zadawane pytania

Czy mogę zmienić prefiks adresu URL strony rejestru?
Tak. Filtr stwreg_url_prefix przyjmuje prefiks jako ciąg znaków, a stwreg_registry_public_url przyjmuje pełny adres URL (ciąg znaków) i publiczny kod (ciąg znaków).

Gdzie znaleźć eksport danych o prywatności i usuwanie danych rejestru?
Zobacz Jak wyeksportować i usunąć dane rejestru na potrzeby żądań dotyczących prywatności.

Co dalej?

• Jak przeglądać zakupione prezenty i wysyłać podziękowania
• Jak skonfigurować stronę wyszukiwania listy prezentów
• Jak ustawić powiadomienia e-mail o rejestrze prezentów

Potrzebujesz pomocy?

Jeśli masz pytanie lub napotkasz jakiekolwiek problemy, jesteśmy tutaj, aby pomóc.

• Użytkownicy premium: Otwórz zgłoszenie wsparcia
• Użytkownicy darmowi: Odwiedź nasze forum społeczności