Skip to content
Inżynieria
8 min czytania29 września 2025

Technicznie od środka: budowa nowoczesnego systemu weryfikacji telefonu

Kompleksowe spojrzenie na architekturę, technologie i decyzje inżynieryjne stojące za naszą platformą weryfikacji telefonu. Infrastruktura backendu, projekt API, kwestie bezpieczeństwa i weryfikacja w czasie rzeczywistym.

Diagram architektury technicznej przedstawiający komponenty systemu weryfikacji telefonu

Przegląd systemu

Nasz system weryfikacji telefonu opiera się na nowoczesnej, skalowalnej architekturze łączącej możliwości Supabase w usługach backendowych, Vonage w infrastrukturze telekomunikacyjnej oraz frontend oparty na React z funkcjami czasu rzeczywistego. System obsługuje tysiące żądań weryfikacji z czasem odpowiedzi poniżej sekundy i dostępnością 99,9%.

Stos frontendowy

  • React 18 - interfejs oparty na komponentach z funkcjami współbieżnymi
  • TypeScript - programowanie z kontrolą typów
  • Vite - szybki development i zoptymalizowane buildy
  • Tailwind CSS - stylowanie oparte na klasach użytkowych z własnym systemem projektowym
  • Framer Motion - płynne animacje i przejścia
  • React Query - zarządzanie stanem serwera i buforowanie

Stos backendowy

  • Supabase - baza PostgreSQL z subskrypcjami w czasie rzeczywistym
  • Supabase Edge Functions - bezserwerowe środowisko Deno dla endpointów API
  • Supabase Row Level Security - kontrola dostępu na poziomie bazy danych
  • Vonage API - infrastruktura telekomunikacyjna
  • Vonage Cloud Runtime - hostowane, skalowalne usługi backendowe o wysokiej wydajności
  • Stripe - obsługa płatności i zarządzanie subskrypcjami
Diagram przepływu integracji Reverse OTP

Architektura Reverse OTP

Główną innowacją naszego systemu jest przepływ „Reverse OTP”, który eliminuje konieczność ręcznego wpisywania kodów weryfikacyjnych. Zamiast tego użytkownicy skanują kod QR telefonem i wysyłają wiadomość WhatsApp, aby ukończyć weryfikację.

Kroki przepływu weryfikacji

  1. Inicjalizacja sesji: klient żąda sesji weryfikacyjnej przez POST /start-verification
  2. Powstaje w ten sposób unikalny token walidacyjny powiązany z identyfikatorem sesji; oba są przechowywane w bazie redis.
  3. Integracja z WhatsApp: generowany jest bezpośredni deep link WhatsApp zawierający wstępnie wypełnioną wiadomość z tokenem. Link można przedstawić jako kod QR, który kieruje do WhatsApp z wstępnie wypełnioną wiadomością do naszego bota
  4. Wyodrębnienie numeru telefonu: backend hostowany w Vonage odbiera webhook z WhatsApp i wyodrębnia numer telefonu z wiadomości WhatsApp
  5. Walidacja: system waliduje format numeru telefonu i łączy go z pierwotną sesją dzięki tokenowi weryfikacyjnemu. Frontend może stale sprawdzać status weryfikacji
Diagram przepływu integracji Reverse OTP

Projekt schematu bazy danych

Supabase zapewnia niezawodną bazę PostgreSQL z funkcjami czasu rzeczywistego, co czyni ją idealnym wyborem dla naszego systemu weryfikacji. Stanowi trzon portalu oraz magazyn danych użytkowników, kluczy API i ich limitów. Służy też do logowania i analityki. Nasz schemat PostgreSQL jest zaprojektowany z myślą o skalowalności, bezpieczeństwie i wydajności. Stosujemy polityki Row Level Security, aby użytkownicy mieli dostęp wyłącznie do własnych danych, a role serwisowe obsługują operacje systemowe.

Funkcje bezpieczeństwa

  • Row Level Security: użytkownicy mają dostęp wyłącznie do własnych sesji weryfikacyjnych
  • Walidacja klucza API: wszystkie żądania są sprawdzane względem klucza API
  • Wygasanie sesji: automatyczne czyszczenie wygasłych sesji weryfikacyjnych
  • Limitowanie żądań: wbudowana ochrona przed nadużyciami i spamem
  • Logowanie audytowe: kompleksowe rejestrowanie wszystkich prób weryfikacji

Architektura bezpieczeństwa

Bezpieczeństwo jest w systemie weryfikacji telefonu sprawą nadrzędną. Stosujemy wiele warstw ochrony, aby zapobiegać oszustwom, nadużyciom i nieautoryzowanemu dostępowi. Używamy krótkotrwałych tokenów walidacyjnych oraz krótkoterminowego przechowywania pełnego zeskanowanego numeru telefonu bez możliwości jego listowania. Nie przechowujemy żadnych numerów telefonów w postaci jawnej, a do analityki i debugowania używamy wersji z zamaskowanymi cyframi.

Wydajność i skalowalność

Nasz system jest zaprojektowany do obsługi dużej liczby żądań weryfikacji przy minimalnych opóźnieniach. Osiągamy to dzięki przemyślanym wyborom architektonicznym i strategiom optymalizacji.

Wskaźniki wydajności

< 200ms
Czas odpowiedzi API
99.9%
SLA dostępności
do 500 rps
i skalowalne

Uwagi dotyczące skalowania

Wraz ze wzrostem liczby weryfikacji nasza architektura skaluje się horyzontalnie dzięki:

  • • Automatycznemu skalowaniu Edge Functions
  • • Kolejkowemu przetwarzaniu webhooków
  • • Równoważeniu obciążenia między regionami
  • • Automatycznemu skalowaniu instancji Vonage

Integracja i projekt API

Nasze API REST jest zaprojektowane z myślą o prostocie i niezawodności. Programiści mogą zintegrować weryfikację telefonu ze swoimi aplikacjami za pomocą zaledwie kilku wywołań API.

Endpointy API

POST
/start-verification

Inicjalizacja nowej sesji weryfikacyjnej

GET
/check-verification-status/{session_id}

Sprawdzanie statusu weryfikacji w czasie rzeczywistym

Zarządzanie sesjami i tokenami

Nasz system weryfikacji wykorzystuje rozbudowane zarządzanie sesjami i tokenami, aby zapewnić bezpieczeństwo, śledzić postęp i zapobiegać nadużyciom. Każde żądanie weryfikacji tworzy unikalną sesję z wieloma punktami śledzenia na całej ścieżce użytkownika.

Cykl życia sesji

1. Utworzenie sesji

Gdy inicjowane jest żądanie weryfikacji, system generuje:

  • • Identyfikator sesji: unikalny UUID do śledzenia próby weryfikacji
  • • Token walidacyjny: kryptograficznie bezpieczny token osadzony w kodzie QR
  • • Czas wygaśnięcia: 15-minutowe okno na ukończenie

2. Walidacja tokena

Token walidacyjny pełni wiele funkcji: uwierzytelnia wiadomość WhatsApp, zapobiega atakom typu replay i łączy numer telefonu z właściwą sesją. Tokeny są jednorazowego użytku i wygasają automatycznie.

Stany statusu weryfikacji

System weryfikacji śledzi szczegółowe informacje o statusie na całej ścieżce użytkownika, zapewniając informację zwrotną w czasie rzeczywistym i umożliwiając precyzyjną analitykę zachowań użytkowników oraz konwersji.

Przebieg statusów

pending

Stan początkowy po utworzeniu sesji weryfikacyjnej. Kod QR został wygenerowany, ale jeszcze nie zeskanowany.

qr_code_scanned

Użytkownik zeskanował kod QR swoim urządzeniem. Nastąpiło wejście na adres śledzący.

whatsapp_previewed

WhatsApp został otwarty, a wiadomość wyświetlona w podglądzie, ale jeszcze nie wysłana.

opened

Rozmowa w WhatsApp została w pełni otwarta, wiadomość jest gotowa do wysłania.

verified / sms_validated

Numer telefonu został pomyślnie wyodrębniony i zwalidowany. Weryfikacja zakończona.

expired / failed

Sesja wygasła (limit 15 min) lub zakończyła się niepowodzeniem z powodu nieprawidłowego tokena/numeru telefonu.

Śledzenie podglądu WhatsApp i kodu QR

Zaawansowane mechanizmy śledzenia monitorują interakcje użytkownika na każdym etapie weryfikacji, dostarczając szczegółowej analityki zachowań i pomagając optymalizować konwersję.

Wykrywanie skanowania kodu QR

Generowanie adresu śledzącego

Każdy kod QR zawiera unikalny adres śledzący, który rejestruje zdarzenie skanowania przed przekierowaniem do WhatsApp:

https://t.phone-verif.com/t/{validation_token}?sid={session_id}

Śledzenie stanu WhatsApp

Wykrywanie podglądu

WhatsApp wywołuje nasz adres śledzący podczas generowania podglądów linków, co pozwala wykryć, że wiadomość jest właśnie tworzona, ale jeszcze nie wysłana.

  • • Analiza User-Agent: odróżnianie botów podglądu WhatsApp od prawdziwych użytkowników
  • • Analiza czasowa: rozróżnianie podglądu od faktycznego dostępu
  • • Geolokalizacja IP: weryfikacja spójności geograficznej

Analityka lejka konwersji

100%
Kod QR wygenerowany
~90%
Kod QR zeskanowany
~89%
WhatsApp otwarty
~85%
Wiadomość wysłana

Typowa konwersja od wygenerowania kodu QR do udanej weryfikacji

Plan rozwoju

Stale ulepszamy platformę, dodając nowe funkcje i optymalizacje.

Zacznij już teraz

Gotowi, by zintegrować weryfikację telefonu ze swoją aplikacją? Nasze API jest zaprojektowane dla programistów, z obszerną dokumentacją i pakietami SDK dla popularnych języków programowania.

🚀 Plan bezpłatny: 100 weryfikacji miesięcznie
📚 Pełna dokumentacja API
🛠️ SDK dla JS, Python, PHP, Go