Biała lista podatników VAT i migracja API MF (2026)

Biała lista podatników VAT i migracja API Ministerstwa Finansów (2026)

Przewodnik techniczny dla integratorów ERP, FK i zespołów finansowych: jak weryfikować status VAT i rachunek bankowy NRB kontrahenta przed przelewem, czym różni się jednorazowe sprawdzenie od ciągłego monitoringu oraz co oznacza wyłączenie starego hosta wl-api.mf.gov.pl w dniu 1.12.2026 r.

1. Migracja hosta API MF: wl-api.mf.gov.pl -> wykazpodatnikowvat.mf.gov.pl/api

Zgodnie z oficjalnym komunikatem Ministerstwa Finansów / KAS na stronie https://www.gov.pl/web/kas/api-wykazu-podatnikow-vat, w dniu 15.10.2026 r. usługa https://wl-api.mf.gov.pl została przekierowana do nowej witryny https://wykazpodatnikowvat.mf.gov.pl/api wraz ze zmianą certyfikatu bezpieczeństwa. Dotychczasowy adres https://wl-api.mf.gov.pl jest obsługiwany wyłącznie do dnia 1.12.2026 r. RiskWatch komunikuje się bezpośrednio z nowym adresem produkcyjnym https://wykazpodatnikowvat.mf.gov.pl/api.

2. Oficjalne metody i dzienne limity Ministerstwa Finansów

Ministerstwo Finansów publikuje trzy ścieżki dostępu do danych Wykazu podatników VAT oraz dzienny plik płaski, z limitami liczonymi na adres IP i resetowanymi o północy (00:00 czasu polskiego):

Metoda pełna „search” (/api/search/nip/{nip}, /api/search/nips/{nips}) — Do 100 zapytań dziennie, maksymalnie 30 podmiotów w jednym zapytaniu. Zwraca pełny zakres danych z wykazu (status VAT: Czynny, Zwolniony, Niezarejestrowany, dane rejestrowe, listę rachunków rozliczeniowych i flagę rachunków wirtualnych) oraz elektroniczny klucz potwierdzenia (requestId).
Metoda uproszczona „check” (/api/check/nip/{nip}/bank-account/{nrb}) — Do 5000 zapytań o podmioty dziennie. Przyjmuje NIP (lub REGON), 26-cyfrowy numer rachunku oraz datę; zwraca odpowiedź TAK albo NIE (accountAssigned) oraz identyfikator potwierdzenia (requestId).
Usługa API WL2 oraz plik płaski — API WL2 pozwala sprawdzić sam status VAT przy limicie 50 000 zapytań dziennie. Plik płaski (publikowany codziennie o północy pod https://wykazpodatnikowvat.mf.gov.pl/plik-plaski) zawiera jednokierunkowe skróty par NIP–rachunek do masowej weryfikacji rachunków i nie zwraca statusu VAT bez znajomości numeru rachunku.

3. Kiedy użyć jednorazowego sprawdzenia (/v1/checks/*), a kiedy listy obserwowanych (/v1/watchlist)

Jednorazowe sprawdzenie przed przelewem (POST /v1/checks/bank-account lub POST /v1/checks/vat) odpowiada natychmiast w ścieżce płatności, zwraca request_id Ministerstwa Finansów i nie dopisuje kontrahenta do stałego portfela. Ciągły monitoring (POST /v1/watchlist) służy do stałych dostawców: harmonogram sprawdza rejestr cyklicznie, wykrywa wykreślenie z VAT (VAT_REMOVED) albo zmianę zestawu rachunków bankowych (VAT_BANK_ACCOUNTS_CHANGED, przechowując wyłącznie skróty SHA-256 bez surowych numerów NRB) i na planach Starter+ wysyła podpisany webhook.

POST /v1/checks/bank-account (jednorazowa weryfikacja NRB)

curl -X POST https://api.riskwatch.pl/v1/checks/bank-account \
  -H "Authorization: Bearer rw_live_yourkey" \
  -H "Idempotency-Key: check-nrb-001" \
  -H "Content-Type: application/json" \
  -d '{"nip":"<YOUR_VALID_NIP>","account":"<YOUR_26_DIGIT_NRB>","date":"2026-11-06"}'

POST /v1/checks/vat (jednorazowy batch do 30 NIP)

curl -X POST https://api.riskwatch.pl/v1/checks/vat \
  -H "Authorization: Bearer rw_live_yourkey" \
  -H "Idempotency-Key: check-vat-001" \
  -H "Content-Type: application/json" \
  -d '{"nips":["<YOUR_VALID_NIP>"],"date":"2026-11-06"}'

POST /v1/watchlist (ciągły monitoring VAT)

curl -X POST https://api.riskwatch.pl/v1/watchlist \
  -H "Authorization: Bearer rw_live_yourkey" \
  -H "Idempotency-Key: quickstart-001" \
  -H "Content-Type: application/json" \
  -d '{"nips":["<YOUR_VALID_NIP>"],"sources":["VAT"]}'

4. Zakres planów RiskWatch i zasada fail-closed

Plan Free (0 PLN) obejmuje monitoring Białej listy VAT do 25 NIP-ów (wspólna pula 100 odczytów monitoringu/dzień UTC, gdzie 1 odczyt = 1 NIP × 1 źródło) oraz jednorazowe sprawdzenia /v1/checks/* w ramach wspólnej puli 3 000 zapytań API na miesiąc kalendarzowy UTC (przy czym wywołania Białej listy MF /v1/checks/vat i /v1/checks/bank-account korzystają dodatkowo z osobnego, współdzielonego dziennego budżetu MF). Plan Starter (99 PLN/mies.) dodaje monitoring KRS (250 NIP-ów, 2 000 odczytów/dzień UTC łącznie, 60 000 zapytań API/mies. UTC) i 2 webhooki, a Pro (399 PLN/mies.) odblokowuje KRZ (2 000 NIP-ów, 20 000 odczytów/dzień UTC łącznie, 600 000 zapytań API/mies. UTC). Gdy API MF jest niedostępne lub zwraca niepełną odpowiedź, RiskWatch działa w trybie fail-closed: zwraca 502/503 i nigdy nie nadpisuje ostatniego zweryfikowanego stanu fałszywym statusem „czysto”. Prezentowane informacje mają charakter techniczny i nie stanowią porady podatkowej ani prawnej.

Źródła oficjalne i przegląd po 1.12.2026

Źródło pierwotne: Ministerstwo Finansów / Krajowa Administracja Skarbowa — Specyfikacja API Wykazu podatników VAT (https://www.gov.pl/web/kas/api-wykazu-podatnikow-vat, wersja dokumentacji v1.6.2 z 05.11.2026 r., stan zweryfikowany 06.11.2026 r.). Po dacie wyłączenia starego hosta (1.12.2026 r.) sekcja migracyjna zostanie zaktualizowana do stanu docelowego.

Załóż darmowe konto (25 NIP VAT) · Przejdź do szybkiego startu API · Porównaj plany Free, Starter i Pro