Walidacja NIP i automatyczne pobieranie danych firmy z API GUS (BIR1) w kasie WooCommerce. Autouzupełnienie adresu, weryfikacja aktywności VAT (Biała Lista MF), cache transient 24h.
Wtyczka dodaje pole NIP do sekcji billing w kasie WooCommerce. Klient klika przycisk Sprawdź — JS wysyła żądanie AJAX, które po stronie PHP weryfikuje sumę kontrolną NIP, odpytuje API GUS BIR1 (SOAP) o dane podmiotu, opcjonalnie sprawdza status VAT w Białej Liście MF, a następnie zwraca dane do formularza. Wyniki API są cachowane w WordPress transients (GUS: 24h, MF: 6h).
phpinfo() lub php -m | grep soapphp-soap.
bstudio-nip-gus do /wp-content/plugins/.| Opcja | Opis |
|---|---|
| Klucz API GUS | Klucz do API GUS BIR1. Jeśli puste — używany klucz demo (środowisko testowe). |
| Środowisko | testowe = klucz demo, ograniczone dane. produkcyjne = pełny dostęp, wymagany własny klucz. |
| NIP wymagany | Wymusza podanie NIP przed złożeniem zamówienia. |
| Autouzupełnianie | Po weryfikacji NIP automatycznie wypełnia pola: Firma, Adres, Miasto, Kod pocztowy. |
| Pozycja pola NIP | Gdzie w formularzu billing ma pojawić się pole NIP. |
| Weryfikacja VAT (MF) | Po kliknięciu „Sprawdź" dodatkowo weryfikuje status VAT w Białej Liście MF. |
| Pokaż NIP gdy pole | Klucz pola z Flexible Checkout (np. checkbox). Jeśli puste — NIP zawsze widoczny. |
| = wartość | Wartość pola warunkowego wyzwalająca widoczność NIP (zazwyczaj 1). |
Pole billing_nip jest dodawane do sekcji billing. Klucz przechowywany w metadanych zamówienia jako _billing_nip (surowy) i _billing_nip_formatted (format XXX-XX-XX-XXX).
1234567890, 123-456-78-90, 123-45-67-890, spacje.Komunikacja SOAP z serwisem GUS BIR1 v1.1. Klasa BNG_GUS_API obsługuje logowanie sesją SID, cookie sid, wyszukiwanie podmiotu po NIP i wylogowanie.
Nazwa)Ulica, NrNieruchomosci, NrLokalu)Miejscowosc)KodPocztowy)bng_gus_{md5(nip+env)}. Zmiana środowiska (test/prod) generuje nowy klucz cache.
REST API Ministerstwa Finansów: https://wl-api.mf.gov.pl/api/search/nip/{nip}?date={YYYY-MM-DD}. Weryfikacja sprawdza pole result.subject.statusVat — wartość Czynny oznacza aktywnego podatnika VAT.
bng_mf_{nip}_{data}. Zmiana daty powoduje nowe zapytanie (wymagana aktualność danych dziennych).
Jeśli masz wtyczkę BStudio Flexible Checkout i dodałeś pole np. Chcę fakturę VAT (checkbox, klucz np. billing_invoice), wpisz ten klucz w ustawieniu Pokaż NIP gdy pole, a wartość ustaw na 1.
Pole NIP będzie ukryte domyślnie i pojawi się dopiero po zaznaczeniu checkboxa. Logika działa po stronie JS (real-time show/hide) bez przeładowania strony.
| Meta key | Zawartość |
|---|---|
_billing_nip | NIP — tylko cyfry (10 znaków) |
_billing_nip_formatted | NIP w formacie XXX-XX-XX-XXX |
_bng_gus_name | Nazwa firmy z GUS (jeśli zweryfikowano) |
_bng_gus_street | Ulica i numer z GUS |
_bng_gus_city | Miejscowość z GUS |
_bng_gus_postcode | Kod pocztowy z GUS |
NIP wyświetlany jest w panelu admina pod danymi adresowymi zamówienia (hook woocommerce_admin_order_data_after_billing_address).
Tak — w trybie testowym używany jest klucz demo GUS (abcde12345abcde12345). Dane testowe są ograniczone i nie zawierają pełnych danych produkcyjnych. Do pracy produkcyjnej wymagany jest własny klucz z systemu GUS.
Wtyczka zwraca błąd z komunikatem. Klient może mimo to złożyć zamówienie — weryfikacja GUS jest opcjonalna (walidacja obowiązkowa to tylko suma kontrolna NIP).
Tak — hook woocommerce_checkout_process weryfikuje sumę kontrolną. Zapytanie do GUS nie jest wykonywane przy składaniu zamówienia (tylko przy kliknięciu „Sprawdź" przez klienta).
Plik uninstall.php usuwa opcję bng_settings oraz wszystkie transients z prefiksami bng_gus_ i bng_mf_. Metadane zamówień (_billing_nip itd.) pozostają — są częścią historii zamówień.
| Parametr | Wartość |
|---|---|
| PHP SOAP | Wymagane — class_exists('SoapClient') sprawdzane przy init |
| GUS WSDL (test) | UslugaBIRzewnPubl-ver11-test.wsdl |
| GUS WSDL (prod) | UslugaBIRzewnPubl-ver11-prod.wsdl |
| Cache GUS | _transient_bng_gus_{hash} — 24h |
| Cache MF | _transient_bng_mf_{nip}_{date} — 6h |
| AJAX action | bng_verify_nip (auth + nopriv) |
| Order meta | _billing_nip, _billing_nip_formatted, _bng_gus_* |
| Settings option | bng_settings w wp_options |
| JS global | bngData (via wp_localize_script) |
| HPOS | Kompatybilny — FeaturesUtil::declare_compatibility |
Masz pytanie, napotkałeś problem albo chcesz rozwinąć to rozwiązanie pod swój sklep? Pomożemy.
Problemy z instalacją, konfiguracją lub działaniem wtyczki — opisz zgłoszenie, a wrócimy z rozwiązaniem.
Wyślij e-mail na shop@biegun.studio. W temacie podaj nazwę wtyczki i krótki opis. Dołącz wersje WordPressa, WooCommerce i PHP oraz kroki odtworzenia problemu.
Potrzebujesz dodatkowej funkcji albo integracji? Realizujemy rozszerzenia i wdrożenia na zamówienie — napisz na shop@biegun.studio.
Pełna oferta wtyczek: biegun.studio/sklep