Dokumentacja referencyjna REST API Checkout Guard

Czasami chcesz zablokować klienta bez otwierania panelu administracyjnego WordPress. Być może usługa oceny ryzyka oszustwa oznaczy zamówienie lub narzędzie helpdesk oznaczy kogoś jako nadużywającego. Checkout Guard udostępnia REST API, dzięki czemu Twoje własne skrypty i narzędzia mogą odczytywać i zarządzać Twoimi zablokowanymi wpisami oraz sprawdzać, czy klient zostałby zablokowany.

Wszystkie trasy znajdują się w jednej przestrzeni nazw, cgfw/v1. Ten artykuł wymienia każdą trasę dla zablokowanych wpisów i ustawień, co akceptuje, co zwraca i jakie błędy możesz napotkać. Przestrzeń nazw zawiera również dwie trasy licencyjne, których używa ekran Ustawienia wtyczki. Ten artykuł ich nie obejmuje.

Jest to dokumentacja referencyjna dla programistów. Zakłada się, że czujesz się komfortowo, wykonując żądania HTTP za pomocą narzędzia takiego jak curl. Jeśli chcesz tylko ręcznie dodać lub usunąć zablokowany wpis, przejdź do WooCommerce → Checkout Guard w swoim panelu administracyjnym. W przypadku typowych problemów z blokowaniem, zapoznaj się z przewodnikiem rozwiązywania problemów z Checkout Guard.

Wymagania wstępne

Wymaganie	Szczegóły
Wtyczka	Checkout Guard w wersji 1.0.2 lub nowszej. Trasy /check i /entries/batch oraz dopasowywanie symboli wieloznacznych są częścią wersji 1.0.2.
WordPress	Wersja 5.6 lub nowsza do korzystania z haseł aplikacji. Sam Checkout Guard obsługuje WordPress w wersji 5.2 i nowszych, ale witryny w wersjach od 5.2 do 5.5 nie mogą korzystać z poniższej metody uwierzytelniania.
Rola użytkownika	Użytkownik z uprawnieniem manage_woocommerce, taki jak Administrator lub Kierownik sklepu.
Połączenie	HTTPS. WordPress włącza hasła aplikacji tylko na stronach HTTPS lub na stronach, gdzie WP_ENVIRONMENT_TYPE jest ustawiony na local.

Podstawowy adres URL i format żądania

Każda trasa zaczyna się od podstawowego adresu URL REST Twojej witryny, a następnie przestrzeni nazw:

https://your-store.example.com/wp-json/cgfw/v1

W każdym poniższym przykładzie zastąp your-store.example.com własną domeną.

Jeśli Twoja witryna używa zwykłych permalinków, /wp-json/ nie zadziała. Zamiast tego użyj formularza rest_route:

https://your-store.example.com/?rest_route=/cgfw/v1/entries

Wysyłaj ciała żądań jako JSON i ustaw nagłówek Content-Type: application/json. Odpowiedzi również są w formacie JSON. Jeśli adres URL zwraca kod 404, najpierw sprawdź podstawowy adres REST swojej witryny.

Uwierzytelnianie

Każda trasa wymaga uprawnienia manage_woocommerce, więc tylko Administratorzy i Kierownicy sklepów mogą wywoływać API. W przypadku skryptów i innych automatycznych wywoływaczy użyj hasła aplikacji WordPress. Podpisuje ono każde żądanie jako konkretny użytkownik za pomocą uwierzytelniania HTTP Basic. Nie potrzebujesz ciasteczka ani nonce.

Aby utworzyć hasło aplikacji:

1. Zaloguj się jako Administrator lub Kierownik sklepu i przejdź do Użytkownicy → Profil.
2. Przewiń w dół do sekcji Hasła aplikacji.
3. Wprowadź nazwę, na przykład automatyzacja Checkout Guard, w polu Nazwa nowego hasła aplikacji.
4. Kliknij Dodaj hasło aplikacji.
5. Skopiuj hasło teraz, ponieważ WordPress pokazuje je tylko raz. Wygląda to tak: xxxx xxxx xxxx xxxx xxxx xxxx. Możesz je wysłać ze spacjami lub bez.

Użyj nazwy użytkownika tego użytkownika jako nazwy użytkownika i Hasła Aplikacji jako hasła:

curl https://your-store.example.com/wp-json/cgfw/v1/entries \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx"

API odpowiada na problemy z uwierzytelnianiem na dwa sposoby:

• Brak poświadczeń: otrzymasz 401 Unauthorized.
• Ważne poświadczenia, ale użytkownikowi brakuje manage_woocommerce: otrzymasz 403 Forbidden. Hasło Aplikacji dla konta Klienta lub Edytora zaloguje się poprawnie, ale nadal zostanie odrzucone.

Ekran administracyjny Checkout Guard używa tych samych tras. Uwierzytelnia się za pomocą pliku cookie sesji zalogowanego użytkownika oraz nagłówka X-WP-Nonce. Potrzebujesz tego podejścia tylko wtedy, gdy Twój własny kod działa wewnątrz panelu administracyjnego WordPress.

Przegląd tras

Ścieżki są względne w stosunku do /wp-json/cgfw/v1.

Metoda	Trasa	Cel
POBIERZ	/wpisy	Wyświetl zablokowane wpisy, opcjonalnie filtrowane.
POST	/wpisy	Utwórz wpis. Bezpieczne do powtórzenia.
POST	/wpisy/partia	Utwórz i usuń wiele wpisów w jednym żądaniu.
PUT	/wpisy/{id}	Zaktualizuj wpis.
DELETE	/wpisy/{id}	Usuń wpis.
POST	/sprawdz	Sprawdź, czy klient zostałby zablokowany.
POBIERZ	/ustawienia	Odczytaj ustawienia wtyczki.
POST	/ustawienia	Zaktualizuj ustawienia wtyczki.

Jak działa zablokowany wpis

Każdy zablokowany wpis zawiera te pola:

Pole	Typ	Szczegóły
id	string	Identyfikator UUID, który Checkout Guard przypisuje podczas tworzenia wpisu.
imię	string	Opcjonalne. Obsługuje symbol wieloznaczny *, na przykład jo*.
nazwisko	string	Opcjonalne. Obsługuje symbol wieloznaczny *, na przykład sm*th.
e-mail	string	Opcjonalne. Obsługuje symbol wieloznaczny *, na przykład *@example.com.
adres_ip	string	Opcjonalne. Pojedynczy adres IPv4 lub IPv6, lub symbol wieloznaczny IPv4, na przykład 192.168.1.*.
notatki	string	Opcjonalne. Obcięte do 140 bajtów, co oznacza 140 znaków dla zwykłego tekstu łacińskiego i mniej dla innych skryptów.
created_by_user_id	integer	Użytkownik, który utworzył wpis.
źródło	string	api, gdy wpis został utworzony za pomocą hasła aplikacji, w przeciwnym razie admin.

Musisz wysłać co najmniej jedno z pól first_name, last_name, email lub ip_address. Nazwa blokuje tylko wtedy, gdy wpis zawiera zarówno imię, jak i nazwisko.

Wpis blokuje klienta, gdy spełniony jest jeden z poniższych warunków:

• Zarówno imię, jak i nazwisko pasują do imienia i nazwiska klienta.
• Jego adres e-mail pasuje do adresu e-mail klienta.
• Jego adres IP pasuje do adresu IP klienta podczas finalizacji zakupu.

Dopasowanie nazwy i adresu e-mail ignoruje wielkość liter. Dopasowanie adresu IP jest dokładne.

Checkout Guard odczytuje adres IP klienta tak, jak robi to WooCommerce, więc podąża za popularnymi nagłówkami proxy.

Reguły z symbolami wieloznacznymi

Wartości nazwy i adresu e-mail mogą używać * do dopasowania zera lub większej liczby znaków. Dopasowanie jest zakotwiczone do całej wartości, więc john* pasuje do johnny, ale nie do ajohn. Każdy inny znak, w tym ., pasuje dosłownie.

Adresy IP akceptują symbole wieloznaczne tylko w formie IPv4. Użyj dokładnie czterech segmentów, gdzie każdy segment jest albo samymi cyframi, albo dokładnie *, i co najmniej jeden segment jest cyfrą.

Każdy segment cyfrowy musi wynosić od 0 do 255 bez zer wiodących, więc 192.168.01.* i 256.1.1.* są odrzucane z kodem 400.

Wartość	Wynik
192.168.1.*, 192.168.*.1, 192.*.*.1	Zaakceptowano
*.*.*.*	Odrzucono z kodem 400. Brak segmentu cyfrowego.
19*.168.1.1	Odrzucono z kodem 400. Mieszany segment.
1.2.3.*.5	Odrzucono z kodem 400. Pięć segmentów.
2001:db8::*	Odrzucono z kodem 400. Symbole wieloznaczne IPv6 nie są obsługiwane.

Kilka dodatkowych ograniczeń dotyczy każdego pola:

• Brak pustych symboli wieloznacznych. Wartość, która pasuje do wszystkiego, taka jak *, **, *@* lub *.*, jest odrzucana z kodem 400. *@example.com jest w porządku, ponieważ pozostał tekst dosłowny.
• Maksymalnie 5 symboli wieloznacznych. Wartość z 6 lub więcej znakami * jest odrzucana z kodem 400.
• Tworzenie wsadowe pomija złe wartości. W żądaniu wsadowym odrzucony element nie jest zapisywany. Jest on liczony w całkowitej liczbie skipped, a samo żądanie nadal zwraca 200.
• Wyszukiwania pozostają dosłowne. Podczas filtrowania GET /entries lub wysyłania ponownego utworzenia, * jest traktowany jako zwykły znak. Reguła symbolu wieloznacznego i dosłowna wartość z tymi samymi znakami są zawsze osobnymi wpisami.

Punkty końcowe

Lista wpisów

GET /entries zwraca tablicę wpisów. Dodaj dowolne z parametrów zapytania email, first_name, last_name lub ip_address, aby filtrować listę. Filtry nazwy i adresu e-mail są dokładnymi dopasowaniami, niezależnymi od wielkości liter. Filtr ip_address jest dokładnym dopasowaniem. Kilka filtrów łączy się za pomocą AND. Nieprawidłowy email lub ip_address zwraca 400.

Każdy wpis na liście zawiera również created_by_display_name i created_by_edit_url, gdy użytkownik tworzący nadal istnieje.

curl https://your-store.example.com/wp-json/cgfw/v1/entries \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx"

# Look up one email
curl "https://your-store.example.com/wp-json/cgfw/v1/[email protected]" \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx"

Odpowiedź:

[
  {
    "id": "11112222-3333-4444-5555-666677778888",
    "first_name": "",
    "last_name": "",
    "email": "[email protected]",
    "ip_address": "",
    "notes": "chargeback fraud",
    "created_by_user_id": 2,
    "source": "api",
    "created_by_display_name": "Shop Manager",
    "created_by_edit_url": "https://your-store.example.com/wp-admin/user-edit.php?user_id=2"
  }
]

Utwórz wpis

POST /entries tworzy wpis i zwraca go. Powtórzenie tego samego żądania nie tworzy duplikatu. Jeśli wpis z tym samym email już istnieje, Checkout Guard aktualizuje go o wszelkie niepuste pola, które wyślesz, i zwraca go. Gdy nie wysyłasz adresu e-mail, dopasowanie następuje na podstawie tego samego imienia i nazwiska. Gdy nie wysyłasz żadnego z nich, dopasowanie następuje na podstawie tego samego ip_address.

curl -X POST https://your-store.example.com/wp-json/cgfw/v1/entries \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","notes":"chargeback fraud"}'

Odpowiedź:

{
  "id": "11112222-3333-4444-5555-666677778888",
  "first_name": "",
  "last_name": "",
  "email": "[email protected]",
  "ip_address": "",
  "notes": "chargeback fraud",
  "created_by_user_id": 2,
  "source": "api"
}

Aby zablokować tylko według adresu IP, wyślij {"ip_address":"203.0.113.42","notes":"repeat spammer"}. Niepusty ip_address, który nie jest prawidłowy, zwraca 400.

Twórz i usuwaj masowo

POST /entries/batch pozwala zsynchronizować całą listę w jednym żądaniu. Wyślij tablicę create, tablicę delete identyfikatorów wpisów lub obie. Checkout Guard najpierw przetwarza tworzenie, każde z nich przez tę samą ścieżkę bezpieczną przed powtórzeniami, co pojedyncze tworzenie. Następnie przetwarza usuwanie. Co najmniej jedna z tych dwóch tablic musi zawierać coś, w przeciwnym razie otrzymasz 400.

curl -X POST https://your-store.example.com/wp-json/cgfw/v1/entries/batch \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "create": [
      { "email": "[email protected]", "notes": "ring leader" },
      { "first_name": "Jane", "last_name": "Doe" }
    ],
    "delete": [ "99998888-7777-6666-5555-444433332222" ]
  }'

Odpowiedź:

{
  "created": [
    {
      "id": "aaaa1111-2222-3333-4444-555566667777",
      "first_name": "",
      "last_name": "",
      "email": "[email protected]",
      "ip_address": "",
      "notes": "ring leader",
      "created_by_user_id": 2,
      "source": "api"
    }
  ],
  "deleted": [ "99998888-7777-6666-5555-444433332222" ],
  "not_found": [],
  "skipped": 0
}

Pole odpowiedzi	Znaczenie
utworzone	Wpisy, które zostały utworzone lub zaktualizowane.
usunięte	Identyfikatory, które zostały usunięte.
nie znaleziono	Usuń identyfikatory, które nie pasowały do żadnego wpisu.
pominięte	Ile elementów tworzenia zostało zignorowanych. Element jest pomijany, gdy nie ma nazwy, adresu e-mail ani adresu IP, lub gdy ma nieprawidłowy adres IP lub symbol wieloznaczny.

Zaktualizuj lub usuń jeden wpis

PUT /entries/{id} zmienia wpis. Wyślij tylko pola, które chcesz zmienić. Odpowiedź to pełny zaktualizowany wpis. Nie możesz wyczyścić każdego identyfikującego pola. Wpis musi zachować co najmniej jedno z pól nazwy, adresu e-mail lub adresu IP, w przeciwnym razie otrzymasz 400.

DELETE /entries/{id} usuwa wpis i zwraca { "success": true }. Jeśli identyfikator nie pasuje do wpisu, obie trasy zwracają 404.

curl -X PUT https://your-store.example.com/wp-json/cgfw/v1/entries/11112222-3333-4444-5555-666677778888 \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{"notes":"confirmed fraud"}'

curl -X DELETE https://your-store.example.com/wp-json/cgfw/v1/entries/11112222-3333-4444-5555-666677778888 \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx"

Sprawdź klienta

POST /check informuje, czy klient zostałby zablokowany przy kasie. Uruchamia tę samą logikę dopasowywania, co rzeczywiste kasy, więc odpowiedź odpowiada temu, co otrzymałoby prawdziwe zamówienie. Wyślij co najmniej jeden z email, first_name, last_name lub ip_address, w przeciwnym razie otrzymasz 400.

Ta trasa jest rygorystyczna w kwestii symboli wieloznacznych. Wartości, które wysyłasz, to dane rzeczywistego klienta, a nie wzorzec. * w jakimkolwiek polu zwraca 400.

curl -X POST https://your-store.example.com/wp-json/cgfw/v1/check \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

Odpowiedź:

{
  "blocked": true,
  "matched_entry": {
    "id": "11112222-3333-4444-5555-666677778888",
    "first_name": "",
    "last_name": "",
    "email": "[email protected]",
    "ip_address": "",
    "notes": "chargeback fraud",
    "created_by_user_id": 2,
    "source": "api"
  }
}

Gdy żaden wpis nie pasuje, blocked ma wartość false, a matched_entry ma wartość null.

Odczytaj i zaktualizuj ustawienia

GET /settings zwraca ustawienia wtyczki. Jedynym ustawieniem jest checkout_denial_message, czyli wiadomość, którą zablokowany klient widzi przy kasie. POST /settings zmienia ją i zwraca zapisane ustawienia. Wiadomość nie może być pusta, w przeciwnym razie otrzymasz 400.

curl https://your-store.example.com/wp-json/cgfw/v1/settings \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx"

curl -X POST https://your-store.example.com/wp-json/cgfw/v1/settings \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{"checkout_denial_message":"Sorry, you cannot place an order right now."}'

Odpowiedź:

{ "checkout_denial_message": "Sorry, you cannot place an order right now." }

Odpowiedzi błędów

Błędy używają standardowego formatu WordPress, z code, message i statusem HTTP.

Status	Kod	Kiedy to się zdarza
400	nieprawidłowe_pole	Tworzenie lub aktualizacja nie ma nazwy, adresu e-mail ani adresu IP.
400	nieprawidłowe_sprawdzenie	Żądanie /check nie zawiera email, first_name, last_name ani ip_address.
400	nieprawidłowa_partia	Żądanie wsadowe ma puste tablice create i delete.
400	nieprawidłowy_adres_ip	Adres IP lub symbol wieloznaczny adresu IP nie jest prawidłowy.
400	nieprawidłowa_wartość_wieloznaczna	Wartość symbolu wieloznacznego jest pustym symbolem wieloznacznym lub zawiera więcej niż 5 znaków *.
400	nieprawidłowe_ustawienia	Komunikat ustawień jest pusty.
400	rest_nieprawidłowy_parametr	Parametr zapytania lub /check nie jest prawidłowy, na przykład nieprawidłowy adres e-mail lub * w polu /check.
401	rest_zabronione	Żądanie nie zawiera poświadczeń.
403	rest_zabronione	Użytkownik nie ma uprawnień manage_woocommerce.
404	nie_znaleziono_wpisu	Żaden wpis nie odpowiada identyfikatorowi w adresie URL.

404 bez kodu oznacza, że bazowy adres URL REST Twojej witryny jest inny niż ten, którego użyłeś.

Prywatność

Zablokowane wpisy to dane osobowe. Jeśli przechowujesz adresy e-mail klientów, ich imiona lub adresy IP, jesteś odpowiedzialny za ich obsługę zgodnie z obowiązkami dotyczącymi prywatności, takimi jak RODO.

Rozwiązywanie problemów

Często zadawane pytania

Potrzebujesz pomocy?

Checkout Guard to licencjonowana wtyczka. Jeśli nadal masz problemy, otwórz zgłoszenie pomocy technicznej i dołącz trasę, wysłane zapytanie oraz otrzymaną odpowiedź. Pomoże to naszemu zespołowi bezpośrednio sprawdzić Twoją konfigurację.