Dokumentacja

Jedno zapytanie, jedna odpowiedź

API sprawdza adresy email i numery telefonu. Zwraca werdykt w trzech stopniach, a przy literówce podpowiada poprawną wersję. Odpowiedź przychodzi w milisekundach, bo wynik trzymamy w cache przez 30 dni.

Uwierzytelnianie

Każde zapytanie wymaga klucza w nagłówku X-API-Key. Klucz wygenerujesz w panelu. Trzymaj go na serwerze — nigdy w kodzie strony, który widzi przeglądarka.

X-API-Key: vk_TWOJ_KLUCZ

Adres API: http://localhost:8000 (środowisko lokalne). Po wdrożeniu na serwer podmieniasz tylko ten adres.

Sprawdzenie adresu email

POST/verify/email

Treść zapytania:

{ "email": "anna.kowalska@gmail.com" }

Odpowiedź dla poprawnego adresu:

{
  "valid": true,
  "status": "valid",
  "reason": null,
  "suggestion": null,
  "checks": {
    "syntax": true,
    "mx": true,
    "smtp": "skipped",
    "disposable": false,
    "role": false
  }
}

Odpowiedź dla literówki — zwróć uwagę na suggestion:

{
  "valid": false,
  "status": "risky",
  "reason": "domain_typo",
  "suggestion": "jan@gmail.com",
  "checks": { "syntax": true, "mx": false, "smtp": "skipped",
              "disposable": false, "role": false }
}

Pola odpowiedzi

valid: true tylko dla statusu valid. Do prostej decyzji: wpuścić czy nie.
status: valid, risky albo invalid — opis niżej.
reason: kod powodu, gdy coś jest nie tak. Lista poniżej.
suggestion: poprawiony adres przy literówce w domenie. Inaczej null.
checks: co po kolei sprawdziliśmy: składnia, rekord MX, SMTP, adres jednorazowy, adres funkcyjny.

Powody (pole reason)

bad_syntax: adres nie jest poprawnym adresem email
domain_typo: literówka w domenie — poprawiony adres jest w polu suggestion
disposable: adres jednorazowy, tymczasowa skrzynka
no_mx: domena nie odbiera poczty
dns_error: domena nie odpowiada
role_account: adres funkcyjny: biuro@, kontakt@, sklep@
catch_all: domena przyjmuje każdy adres, nie da się potwierdzić skrzynki
mailbox_not_found: serwer odpowiedział, że skrzynki nie ma

Sprawdzenie numeru telefonu

POST/verify/phone

Treść zapytania:

{ "phone": "+48 601 234 567" }

Odpowiedź:

{
  "valid": true,
  "status": "valid",
  "normalized": "+48601234567",
  "type": "mobile",
  "operator": "Plus",
  "operator_source": "libphonenumber",
  "reason": null
}

normalized: numer w formacie międzynarodowym — ten zapisz w bazie.
type: mobile, fixed_line, voip, premium_rate i podobne.
operator: operator z tablic numeracyjnych UKE.
operator_source: skąd wiemy o operatorze: uke albo libphonenumber.

Powody (pole reason)

bad_format: numeru nie da się odczytać
not_polish: numer spoza Polski
unassigned_prefix: prefiks nieprzydzielony operatorowi (tablice UKE)
unusual_number_type: numer nietypowy: premium, usługowy, satelitarny

Sprawdzamy poprawność i przydział numeru, nie to, czy telefon jest w tej chwili włączony. Sprawdzenie w sieci operatora (HLR) będzie osobną, płatną opcją.

Trzy statusy i co z nimi zrobić

valid

Wszystko się zgadza. Przyjmij kontakt.

risky

Da się dostarczyć, ale coś budzi wątpliwość: literówka, adres funkcyjny, domena przyjmująca wszystko. Nie odrzucaj — zapytaj klienta albo oznacz w CRM.

invalid

Kontakt nie istnieje lub jest błędny. Zatrzymaj formularz i poproś o poprawkę.

Przykłady

curl -X POST http://localhost:8000/verify/email \
  -H "X-API-Key: TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  -d '{"email":"anna.kowalska@gmail.com"}'

Kody błędów

Błąd zwracamy jako { "detail": "opis po polsku" }.

401Brak nagłówka X-API-Key albo klucz nie istnieje.

403Klucz wyłączony albo wyczerpany limit miesięczny.

422Błędne dane wejściowe (np. brak pola email w treści zapytania).

429Za dużo zapytań na sekundę. Nagłówek Retry-After mówi, ile odczekać.

Zasada na produkcji: gdy walidacja odpowie błędem, przepuść klienta dalej. Lepiej przyjąć jeden podejrzany adres niż stracić zamówienie.

Limity i rozliczenie

Wspólna pula: Email i telefon liczą się do tego samego limitu miesięcznego.
Cache 30 dni: Powtórne sprawdzenie tej samej wartości jest natychmiastowe, ale nadal liczy się do limitu.
Tempo: 10 zapytań na sekundę na klucz. Powyżej dostajesz 429 z nagłówkiem Retry-After.
Po limicie: Wchodzi pula prepaid, jeśli ją masz. Bez niej zapytania dostają 403.
Plik CSV: Całą bazę sprawdzisz w panelu bez pisania kodu — do 20 000 rekordów na paczkę.

Podgląd interaktywny

Pełna specyfikacja OpenAPI, z możliwością wysłania zapytania prosto z przeglądarki: http://localhost:8000/docs. Działa, gdy API jest uruchomione.