Trzy kanały dostępu do wykazu
Ministerstwo Finansów udostępnia dane wykazu na trzy sposoby, każdy z innym przeznaczeniem i innymi limitami.
| Kanał | Co zwraca | Limit | Do czego się nadaje |
|---|---|---|---|
| API, metoda search | pełne dane podmiotu, status, rachunki, daty, identyfikator wyszukiwania | 100 zapytań dziennie z jednego IP, do 30 podmiotów w zapytaniu | audyt kontrahenta z dowodem sprawdzenia |
| API, metoda check | „TAK” lub „NIE” dla pary NIP (albo REGON) i rachunek na dany dzień, plus identyfikator | 5000 podmiotów dziennie z jednego IP | sprawdzanie rachunków przed paczką przelewów |
| plik płaski | skróty kryptograficzne par „data + NIP + rachunek”, bez nazw i statusów | bez limitu zapytań, plik pobierany raz dziennie | integracje w ERP i bankowości korporacyjnej |
| usługa SOAP „Sprawdź status VAT” | tylko status: C czynny, Z zwolniony, N niezarejestrowany, I niepoprawny NIP | do 10 żądań na sekundę, dodatkowe ograniczenia IP | szybki test statusu bez danych podmiotu |
Jak liczą się limity
Limit metody search dotyczy liczby zapytań, nie liczby podmiotów. Jedno zapytanie może zawierać do 30 NIP-ów, więc realnie da się sprawdzić do 3000 podmiotów dziennie z jednego adresu IP, pod warunkiem, że pakujesz numery w pełne paczki. Sto zapytań po jednym NIP-ie wyczerpuje limit przy stu podmiotach.
Limit metody check liczy się w podmiotach: 5000 par dziennie. Po przekroczeniu któregokolwiek limitu MF blokuje dostęp do końca dnia. Blokada obejmuje obie metody API i wyszukiwarkę na stronie podatki.gov.pl, bo liczona jest per adres IP. W biurze, gdzie wszyscy wychodzą do internetu przez jeden router, jedna osoba może zablokować cały zespół.
Plik płaski: co daje, a czego nie
Plik publikowany jest codziennie po północy w dni robocze, jako archiwum o rozmiarze około 200 MB. W środku jest JSON z nagłówkiem, listą skrótów dla podatników czynnych, listą skrótów dla zwolnionych i maskami rachunków wirtualnych. Skrót to wielokrotnie iterowany SHA-512 z ciągu „data wygenerowania + NIP + numer rachunku”; dla podmiotu bez rachunku liczony jest z samej daty i NIP-u.
Oznacza to, że z pliku nie odczytasz nazw, adresów ani rachunków. Możesz jedynie potwierdzić, że posiadana para NIP i rachunek była w wykazie na dany dzień. Brak skrótu nie jest równoznaczny ze statusem „nieaktywny”: wynik zależy od daty pliku, od tego, czy podałeś rachunek, i od bloku, w którym szukasz. To narzędzie dla systemów, które sprawdzają tysiące przelewów dziennie, nie dla pojedynczego księgowego.
Pięć zasad, które chronią przed blokadą
- Deduplikuj. Lista dostawców z ERP ma zwykle po kilka wpisów dla tego samego NIP-u. Sprawdzaj każdy numer raz.
- Pakuj po 30. Metoda search przyjmuje do 30 numerów w jednym zapytaniu. Paczki po 30 dają dziesięć razy więcej sprawdzeń niż pojedyncze zapytania.
- Cache na 24 godziny. Wykaz zmienia się raz dziennie, więc ponowne pytanie o ten sam NIP tego samego dnia to zmarnowane zapytanie. Zapisz wynik z datą.
- Sprawdzaj na właściwy dzień. API pozwala podać datę. Sprawdzenie „na dziś” wykonaj w dniu przelewu, a nie tydzień wcześniej i tydzień później.
- Rozłóż duże listy w czasie. Trzy tysiące podmiotów mieści się w limicie, ale dziesięć tysięcy trzeba podzielić na dni albo skorzystać z pliku płaskiego.
Jak robi to Nipscan
Nipscan stosuje te zasady automatycznie: usuwa duplikaty, odrzuca numery z błędną sumą kontrolną, dzieli listę na paczki po 30 i odpytuje produkcyjne API search, żeby każdy wynik miał identyfikator wyszukiwania. Statusy z usługi SOAP trzymane są w cache przez 24 godziny, a kolejka zapytań ma ograniczoną współbieżność, więc narzędzie nie generuje lawiny żądań. Nie stosujemy rotacji adresów IP ani innych sposobów obchodzenia limitów. Dlatego jedno sprawdzenie w Nipscan ma limit 30 numerów bez logowania i 100 po założeniu konta.
Co zrobić, gdy blokada już nastąpiła
Nic nie przyspieszy odblokowania: dostęp wraca o północy. Do tego czasu możesz sprawdzić pojedynczy podmiot z innego łącza, na przykład z telefonu w sieci komórkowej, albo skorzystać z narzędzia, które odpytuje wykaz z własnej infrastruktury. Zanotuj, ile zapytań wykonaliście przed blokadą, i przy następnej dużej liście zaplanuj paczki.