← Blog
12 października 2026 Marta Zielińska 8 min

Hurtowe sprawdzanie domen przez API: jak zbudować proces dla portfela

Hurtowa kontrola domen ma sens, gdy wynik prowadzi do decyzji. Poznaj projekt API dla dostępności, DNS, WHOIS, wyceny i bezpieczeństwa bez chaosu danych.

APIhurtowe zapytaniadomenyautomatyzacjaDNS

Hurtowe sprawdzanie domen pojawia się zwykle przy audycie portfela, migracji, zakupie nazw, monitoringu marki albo porządkowaniu aktywów po przejęciu. Pokusa jest prosta: wysłać tysiące zapytań i zapisać tabelę wyników. Taki proces szybko staje się jednak trudny do interpretacji. Dostępność domeny, dane rejestrowe, DNS, reputacja i wycena opisują różne rzeczy. Bez modelu decyzji duża tabela nie odpowie, które nazwy kupić, wycofać, monitorować albo przekazać do analizy prawnej.

Projekt zacznij od wyniku, który ma podjąć człowiek lub system. Czy szukasz wolnych nazw, domen do odnowienia, nieznanych rekordów, podobnych marek, czy kandydatów do dalszej wyceny? Każdy cel wymaga innych pól, kosztu i tolerancji błędu. Endpoint, który zwraca status domeny, nie jest automatycznie dobrym endpointem do oceny reputacji. Rozdzielenie zadań ogranicza koszty i sprawia, że wynik można uczciwie opisać.

Znormalizuj wejście przed pierwszym zapytaniem

Lista wejściowa powinna zostać oczyszczona z protokołu, ścieżki, prefiksu www i przypadkowych spacji. Zapisz nazwę kanoniczną oraz formę Unicode i ASCII dla IDN. Usuń duplikaty, ale zachowaj informację o źródłach, które wskazały tę samą nazwę. Od razu odrzuć niepoprawne domeny, adresy URL i ciągi przekraczające ograniczenia. Walidacja przed wysłaniem zmniejsza liczbę błędów, obniża koszt i ułatwia rozliczenie wyników.

  • canonicalDomain: nazwa użyta do zapytania po normalizacji.
  • inputSources: listy lub systemy, z których pochodzi nazwa.
  • requestedChecks: zakres kontroli dla konkretnej partii.
  • correlationId: identyfikator pozwalający odtworzyć całą operację.

Dobierz zakres do decyzji

Dla selekcji nazw do zakupu zacznij od statusu rejestracji i danych RDAP, a dopiero dla krótkiej listy dodaj historię, DNS i wycenę. Dla portfela własnego zacznij od terminów, DNS, certyfikatów i reputacji. Dla ochrony marki wygeneruj warianty, ale oznacz je jako kandydatów, nie potwierdzone zagrożenia. Dla audytu poczty dodaj SPF, DKIM, DMARC i MX. Składanie jednego „superraportu” dla każdej domeny może zwiększać opóźnienie i koszt bez proporcjonalnej wartości.

Zaprojektuj stany odpowiedzi

W hurtowym procesie sukces i brak danych nie mogą zostać zlane w jedną wartość null. Rozróżnij checked, present, absent, unknown, not-supported, invalid, rate-limited, failed i cached. Jeżeli usługa rejestracyjna odpowiada 403 lub timeoutem, nie oznaczaj domeny jako wolnej. Jeżeli DNS nie odpowiada, nie oznaczaj hosta jako usuniętego. Klient biznesowy musi widzieć, które decyzje są pewne, a które wymagają ponowienia lub ręcznej kontroli.

Zapisuj także metodę, czas, źródło, kod klasy odpowiedzi, confidence i ewentualny refund. Dwa wyniki „unknown” mogą mieć różne przyczyny: chwilową niedostępność albo brak obsługi danej końcówki. Takie metadane są potrzebne do monitorowania jakości i do uczciwego komunikatu dla użytkownika, który nie powinien otrzymać pozornie precyzyjnej odpowiedzi.

Obsłuż limity i ponowienia

Nie zwiększaj równoległości tylko dlatego, że lista jest długa. Ustal limit partii, kolejkę, budżet na hosta i strategię backoff dla 429 oraz błędów infrastruktury. Ponów tylko wtedy, gdy błąd jest przejściowy. Nie ponawiaj bez końca odpowiedzi walidacyjnej ani autorytatywnego braku. Zaprojektuj idempotencję, aby wznowienie partii po przerwaniu nie tworzyło podwójnych wyników i nie naliczało ponownie kosztu za już potwierdzoną obserwację.

Zabezpiecz dane i audyt integracji

Klucz API przechowuj poza kodem, ogranicz jego zakres i nie zapisuj go w logach. W odpowiedziach filtruj dane, których nie potrzebuje operator. Przechowuj numer partii, wersję klienta, datę i parametry, aby można było odtworzyć, dlaczego wynik wyglądał tak, a nie inaczej. Jeśli dane rejestrowe są zredagowane, pokaż ten stan zamiast sugerować, że brak oznacza brak abonenta. Taka przejrzystość jest ważna zwłaszcza w procesach zakupowych i prawnych.

RDAP i WHOIS w procesie portfelowym

ICANN wskazuje RDAP jako definitywne źródło danych rejestracyjnych gTLD od 28 stycznia 2025 roku. RDAP zwraca strukturalne odpowiedzi, ale zakres publicznych danych zależy od polityki i rejestru. Dla domen .pl korzystaj z informacji właściwych dla rejestru NASK. Nie porównuj mechanicznie tekstowego WHOIS i JSON RDAP, jeśli pola, statusy lub polityka ujawniania danych mają inną semantykę. Normalizacja powinna zachować oryginalne źródło i różnice.

Dodaj cache i świeżość do wyniku

Nie każdy wynik wymaga zapytania przy każdym uruchomieniu. Ustal TTL zależnie od decyzji. Status dostępności może wymagać świeżości tuż przed rejestracją, a dane opisowe portfela można odświeżać rzadziej. Zapisuj cacheHit, checkedAt i expiresAt. Nie pokazuj danych jako aktualnych, gdy pochodzą z przeterminowanej obserwacji. Przy zmianie źródła lub kontraktu API oznacz wersję, aby później nie mieszać wyników uzyskanych różnymi metodami.

Wynik musi prowadzić do kolejki decyzji

Zamiast jednej tabeli „OK” przygotuj widoki: do rejestracji, do ręcznego audytu, do monitoringu, do odrzucenia i nieznane. Dodaj powód, który operator rozumie. „DMARC missing” jest lepsze niż „score 42”, jeśli zespół ma naprawić pocztę. „RDAP unavailable” jest lepsze niż „available”, gdy trzeba ponowić sprawdzenie. Wynik API powinien być wystarczająco szczegółowy dla automatyzacji i wystarczająco czytelny dla osoby, która podejmuje decyzję.

  1. Przyjmij listę i zwróć raport walidacji wejścia.
  2. Uruchom najtańsze i najbardziej rozstrzygające kontrole.
  3. Rozszerz zakres tylko dla wyników, które przejdą pierwszy próg.
  4. Zapisz dowody, metadane, stany nieznane i błędy do ponowienia.
  5. Eksportuj kolejkę decyzji, nie tylko surową odpowiedź dostawcy.

Testuj prawdziwe przypadki graniczne

Testy partii powinny obejmować domenę poprawną, IDN, duplikat, nazwę z błędem, wolną nazwę, nazwę zajętą, odpowiedź 429, timeout, błąd parsowania, cache hit i częściowo nieudaną partię. Dodaj stabilny przypadek obecny oraz bezpiecznie wygenerowany przypadek nieobecny. Sprawdź, czy błąd zapisu wyników nie blokuje bezpiecznego rozliczenia i czy ponowienie nie tworzy duplikatów. Waliduj też kontrakt odpowiedzi, bo zmiana nazwy pola może zepsuć raport bez błędu HTTP.

Wdrożenie zacznij od małej partii i porównaj wyniki z ręcznymi kontrolami. Zmierz czas, odsetek nieznanych stanów, liczbę ponowień, cache hit i różnice względem oczekiwań. Dopiero potem podnieś rozmiar partii. Dzięki temu problemy z limitem, normalizacją i interpretacją wyjdą na jaw zanim proces zacznie sterować zakupem domen, blokadą kampanii lub zmianą poczty w całej organizacji.

Dobre API hurtowe nie ukrywa niepewności. Zamienia ją w jawny stan, który można ponowić, wyjaśnić albo świadomie zaakceptować.

Praktyka integracji domenowych

Przykład partii dla audytu portfela

Załóżmy, że firma ma 4 tysiące domen po przejęciu konkurenta. Pierwsza partia nie powinna uruchamiać wszystkich drogich kontroli. Najpierw normalizujesz nazwy, sprawdzasz duplikaty i statusy rejestracyjne, następnie wybierasz domeny aktywne, wygasające, podobne do marki i związane z pocztą. Dla tej krótszej listy uruchamiasz DNS, SSL, reputację i profil. Wynik dzielisz na: zachować, odnowić, zabezpieczyć, wyjaśnić i wycofać. Każdy etap ma własny koszt, limit oraz test jakości.

Jeśli 8 procent nazw zwróci unknown, nie wpisuj ich do grupy „brak danych” bez przyczyny. Sprawdź, ile to timeouty, ile końcówki bez obsługi, ile odpowiedzi 429, a ile błędów wejścia. Powtórz tylko stany przejściowe i zachowaj pierwszą odpowiedź. Taki podział pomaga ocenić, czy problem jest w źródle, kolejce, parserze czy liście domen. Zespół może wtedy poprawić proces zamiast ręcznie sprawdzać tysiące rekordów.

Zaprojektuj kontrakt dla użytkownika

Dokumentacja partii powinna opisywać maksymalny rozmiar, sposób podawania nazw, koszt jednostkowy, czas oczekiwania, format postępu i możliwe stany. Opisz, co oznacza brak, niedostępność oraz cache. Jeśli endpoint zwraca częściowe wyniki, klient musi wiedzieć, czy może bezpiecznie użyć ukończonych elementów. Nie ukrywaj limitów za ogólnym komunikatem o błędzie. Przejrzysty kontrakt pozwala zespołowi zbudować retry, kolejkę i alerty bez zgadywania.

  • batchId i status przetwarzania całej partii
  • liczba przyjętych, odrzuconych, ukończonych i ponawianych elementów
  • wynik per domena z metodą, timestampem i confidence
  • błędy możliwe do naprawy oraz błędy wymagające zmiany wejścia
  • informacja o cache i czasie ważności danych

W testach obciążeniowych nie używaj przypadkowo prawdziwej listy klientów. Przygotuj bezpieczne przypadki obejmujące poprawne domeny, IDN, błędne formaty, domeny zajęte i nieaktywne oraz odpowiedzi syntetyczne dla limitów. Sprawdź, czy przerwanie klienta pozwala wznowić partię, czy wynik jest idempotentny i czy po błędzie zapisu nie zostaje niejasny status. Logi powinny zawierać identyfikator partii oraz domenę zanonimizowaną tam, gdzie pełna nazwa nie jest potrzebna.

Rozdziel dane surowe od decyzji

Przechowuj surową odpowiedź i osobny, stabilny model używany przez raporty. Dzięki temu możesz poprawić parser bez utraty dowodu, a zmiana schematu nie niszczy historii. Model decyzyjny powinien mieć jasne pola, takie jak status, confidence, source, checkedAt i caveats. Nie nadpisuj starego wyniku bez zachowania wersji. Przy porównaniu partii zobaczysz wtedy, czy domena się zmieniła, czy tylko zmienił się sposób interpretacji odpowiedzi.

Ustal, które pola są obowiązkowe dla każdej kontroli, a które pojawiają się tylko w określonych endpointach. Jeśli brak pola jest prawidłowy, oznacz go jako not-supported albo not-requested, nie jako błąd. Jeżeli dostawca zwróci dane częściowe, zachowaj częściowy status i wyjaśnienie. Taka dyscyplina pozwala klientom budować reguły bez ryzyka, że pusty string zostanie uznany za potwierdzony brak.

  • Surowy payload pozostaje dowodem, z ograniczonym dostępem.
  • Model normalizowany ma stabilne enumy i jawne unknown.
  • Reguła decyzji wskazuje, które pola są wystarczające.
  • Wersja parsera i źródła pozwala porównać wyniki w czasie.

Przed zwiększeniem partii zdefiniuj SLO procesu: maksymalny czas, dopuszczalny odsetek unknown, czas ponowienia i sposób zgłoszenia błędu. Mierz te wartości osobno dla typów kontroli, bo RDAP, DNS, SSL i reputacja mają różne opóźnienia. Jeśli wynik spada poniżej progu, zatrzymaj automatyczne decyzje i skieruj partię do kontroli. Właściciel powinien widzieć, czy problem dotyczy listy wejściowej, źródła, limitu czy zapisu, zanim zacznie zmieniać konfigurację.

Przed wdrożeniem ustal też, kto może zatrzymać partię. Jeśli odsetek unknown rośnie, źródło zwraca nieznane statusy albo zapis wyników jest opóźniony, automatyczna decyzja o rejestracji lub wycofaniu powinna zostać wstrzymana. Zespół musi widzieć powód, zakres i bezpieczny sposób wznowienia. Taka bramka chroni przed sytuacją, w której chwilowa awaria źródła zostaje zamieniona w tysiące błędnych decyzji w portfelu.

Po każdej większej partii porównaj kilka wyników z ręcznym sprawdzeniem. Jeśli różnice są systematyczne, zatrzymaj dalsze zwiększanie skali i popraw normalizację lub mapowanie statusów. Kontrola próbki nie zastępuje testów, ale pozwala szybko wykryć błąd, który mógłby powielić się w całym portfelu. Zapisz próg akceptacji i osobę, która zatwierdza przejście do następnego etapu.

Hurtowe sprawdzanie domen jest wartościowe wtedy, gdy łączy znormalizowane wejście, właściwy zakres, bezpieczną kolejkę i decyzję po stronie odbiorcy. RDAP, DNS, poczta, SSL i reputacja dostarczają różnych sygnałów, więc zachowaj ich pochodzenie i nie twórz pozornej pewności. Projektuj dla błędów, limitów i wznowień od początku. Wtedy portfel domen staje się obserwowalny, a automatyzacja naprawdę oszczędza czas zespołu.

Najwazniejsze wnioski

  • Najpierw zdefiniuj decyzję biznesową, a dopiero potem wybierz endpoint i pola wyniku.
  • Hurtowy proces musi rozróżniać sukces, brak, błąd, limit, cache i stan nieznany.
  • Idempotencja, walidacja wejścia i ponowienia są ważniejsze niż maksymalna równoległość.
  • Wyniki powinny zachować źródło, czas, confidence i wersję procesu.

Powiazane artykuly