API weryfikacji wieku dla stron internetowych i aplikacji
Sprawdź, czy odwiedzający spełnia próg wiekowy, bez przechowywania w aplikacji dokumentów tożsamości ani dat urodzenia.
Sprawdzenie, czy odwiedzający spełnia próg wiekowy
Jedna sesja obejmuje obie części: odwiedzający dowodzi kontroli nad swoim numerem telefonu przez WhatsApp, raz odpowiada na pytanie o wiek, a aplikacja otrzymuje wynik: spełniony lub niespełniony, względem ustawionego progu.
Jak działa weryfikacja wieku
Krok pierwszy: weryfikacja telefonu. Wywołujesz POST /start-verification z flow=age i wyświetlasz zwrócony deep link WhatsApp jako kod QR na komputerze lub przycisk na urządzeniu mobilnym. Odwiedzający wysyła jedną gotową wiadomość z własnego konta WhatsApp, więc kontrola nad numerem jest udowodniona samym aktem wysłania, a nie kodem, który został na ten numer wysłany.
Krok drugi: ustawienie progu. To samo wywołanie przyjmuje opcjonalny min_age. Jeśli go pominiesz, obowiązuje próg skonfigurowany na koncie, czyli 18, o ile nie został zmieniony. min_age jest akceptowany tylko przy flow=age i musi być dodatnią liczbą całkowitą, w przeciwnym razie zwracany jest błąd 400.
Krok trzeci: dokończenie kontroli wieku. Gdy tylko część dotycząca telefonu zostanie udowodniona, odpowiedź zawiera blok age ze statusem pending i adresem age_verification_url. Ten sam jednorazowy link jest wysyłany odwiedzającemu przez WhatsApp i można go użyć, by przeprowadzić go dalej w przeglądarce, w której już jest. Odpowiada on u dostawcy weryfikacji wieku, a następnie trafia z powrotem na callback_url z dołączonymi token oraz age=verified, denied lub failed.
Krok czwarty: odebranie wyniku. Drugi webhook, age_verification_result, uruchamia się, gdy dostawca odpowie, a GET /check-verification-status zwraca to samo. Blok age zawiera status, verified, required (czyli faktycznie sprawdzony próg), verified_at oraz provider.
Warto znać jedną pułapkę, zanim powstanie pętla odpytywania. Własny status sesji osiąga verified, gdy tylko numer telefonu zostanie udowodniony, podczas gdy age.status wciąż ma wartość pending. Sygnałem dla kroku weryfikacji wieku jest blok age, nigdy status sesji.
Weryfikacja telefonu i weryfikacja wieku
Te dwa kroki odpowiadają na dwa różne pytania, a przepływ celowo je rozdziela. Wysłanie wiadomości WhatsApp dowodzi, że odwiedzający kontroluje dany numer. Nie mówi absolutnie nic o jego wieku: numer telefonu nie jest dowodem wieku i żadna część tego przepływu go tak nie traktuje.
Krok z telefonem daje miejsce, w którym można umieścić odpowiedź. Sam wynik dotyczący wieku to nieprzypisany fakt: ktoś, gdzieś, przekroczył próg. Powiązany z numerem, którego odwiedzający właśnie wyraźnie użył, staje się czymś, co można rozpoznać przy kolejnej wizycie.
Dzięki temu powracający odwiedzający jest tani w obsłudze. Pozytywny wynik jest przechowywany przy numerze telefonu przez rok, więc osoba, która już przekroczyła ten sam próg, ponownie udowadnia numer i przenosi wcześniejszą odpowiedź, zamiast wracać do dostawcy. Zakończenie wiadomości WhatsApp tekstem #reset omija pamięć podręczną, gdy potrzebna jest świeża odpowiedź.
Weryfikacja wieku bez budowania bazy tożsamości
Pytanie zadawane przez bramkę wiekową ma odpowiedź logiczną. Większość danych zwykle zbieranych, by na nie odpowiedzieć, taka nie jest, i to czyni archiwum dokumentów tak złym układem: przechowuje się paszporty i prawa jazdy, aby zapisać jedno „tak”.
To, czego potrzebuje aplikacja, jest niewielkie. Wynik: verified, denied, failed lub wciąż pending. Sprawdzony próg. Kiedy udzielono odpowiedzi i który dostawca jej udzielił. Identyfikator sesji i zweryfikowany numer telefonu, które wiążą odpowiedź z odwiedzającym po drugiej stronie. To cały blok age plus to, co przepływ telefoniczny już zwraca.
Aplikacja nie potrzebuje daty urodzenia ani dokumentu tożsamości, a API nie zwraca żadnego z nich, więc nie ma pola, które można by przypadkowo zapisać w logach. Pozytywna odpowiedź jest przechowywana przy numerze telefonu jako odpowiedź, próg i data. Poświadczenia dostawcy znajdują się w sekretach po stronie serwera, a to, co dostawca musiał obejrzeć, by podjąć decyzję, nie jest przekazywane dalej.
Nic z tego nie jest oświadczeniem o własnych obowiązkach. To, co trzeba sprawdzić, jak długo trzeba móc wykazać, że sprawdzono, i co jest dopuszczalną metodą, to pytania do radcy prawnego i regulatora, a nie do dostawcy API.
Weryfikacja wieku a weryfikacja tożsamości
Weryfikacja wieku odpowiada na jedno pytanie: czy ten odwiedzający spełnia ustawiony próg wiekowy? Weryfikacja tożsamości odpowiada na inne: kim jest ta osoba? Oba rozwiązania są często sprzedawane razem i przenoszą bardzo różne ilości danych.
flow=age należy do pierwszego rodzaju. Nie zwraca imienia i nazwiska, daty urodzenia ani niczego z dokumentu. To nie jest KYC, a pozytywny wynik nie jest oświadczeniem o tożsamości, na którym można się opierać gdzie indziej. Jeśli obowiązkiem jest wiedzieć, kim jest klient, to nie jest narzędzie do tej części zadania.
Dziedziczy ono też założenie leżące u podstaw każdej kontroli opartej na telefonie: że numer należy do osoby, która z niego korzysta. Udowodnienie kontroli przez wysłanie wiadomości to pewniejszy grunt niż odebranie SMS-a, ale nastolatek mający dostęp do telefonu osoby dorosłej to scenariusz, którego żadna zdalna kontrola nie zamyka w pełni. Artykuł o kontrolach wieku, które nie stają się bazą dokumentów tożsamości, wskazany poniżej, omawia architekturę, cztery stany i ograniczenia bardziej szczegółowo.
Integracja weryfikacji wieku z aplikacją
To te same dwa wywołania REST, których używa każda integracja Phone-Verif, ze zmienionym jednym parametrem. Uwierzytelnienie odbywa się kluczem API w nagłówku x-api-key, sesję otwiera się z flow=age, a blok age odczytuje się z endpointu statusu lub z webhooka.
- Odwiedzający
- Weryfikacja telefonu przez WhatsApp
- Kontrola wieku u dostawcy
- Wynik weryfikacji wieku
- Aplikacja
Te dwa kroki odpowiadają na dwa różne pytania i pozostają rozdzielone na każdym etapie. Wysłanie wiadomości WhatsApp dowodzi, że odwiedzający kontroluje dany numer, a nie jest to nigdy traktowane jako dowód jego wieku. Wynik dotyczący wieku powstaje dopiero w kroku weryfikacji wieku.
curl -X POST "https://api.phone-verif.com/start-verification?flow=age&min_age=18" \
-H "x-api-key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"session_id": "checkout-4821", "callback_url": "https://your-app.example/age-checked"}'Otwórz sesję z flow=age. Jeśli pominiesz min_age, obowiązuje próg skonfigurowany na koncie, czyli 18, o ile nie został zmieniony.
{
"status": "verified",
"age": { "status": "pending", "verified": false, "required": 18 },
"age_verification_url": "https://t.phone-verif.com/av/AbCd1234"
}Sesja osiąga stan verified, gdy tylko numer telefonu zostanie udowodniony, podczas gdy krok weryfikacji wieku jest wciąż otwarty. Odpowiedź o wieku należy czytać z age.status, a nie ze statusu sesji, a odwiedzającego skierować na age_verification_url, aby dokończył kontrolę w przeglądarce, w której już jest.
{
"event": "age_verification_result",
"session_id": "checkout-4821",
"validation_token": "...",
"age": {
"status": "verified",
"verified": true,
"required": 18,
"verified_at": "2026-09-01T22:00:00.000Z",
"provider": "ageverif"
}
}Gdy dostawca odpowie, drugi webhook przekazuje wynik, a endpoint statusu zwraca ten sam blok.
flow=age wymaga skonfigurowanego na koncie dostawcy weryfikacji wieku. Przy żądaniu bez niego API odpowiada kodem 503 i kodem age_not_configured, dzięki czemu błąd konfiguracji da się odróżnić od awarii.
Najczęstsze pytania o weryfikację wieku
- Czy mogę zweryfikować, że użytkownicy mają ponad 18 lat?
- Tak. Należy otworzyć sesję z flow=age i pominąć min_age: przepływ sprawdza wtedy próg skonfigurowany na koncie, czyli 18, o ile nie został zmieniony w ustawieniach.
- Czy mogę użyć innego minimalnego wieku?
- Tak. Wystarczy przekazać min_age w wywołaniu startowym z wymaganym progiem. Musi to być dodatnia liczba całkowita, jest akceptowany tylko przy flow=age, a każda inna wartość jest odrzucana z błędem 400. Każda sesja zachowuje próg, względem którego została otwarta, a ten próg wraca jako required w bloku age, więc późniejszy czytelnik wie, co faktycznie ustalono.
- Czy muszę przechowywać datę urodzenia użytkownika?
- Nie, a nawet nie byłoby to możliwe: API jej nie zwraca. Zwracane jest to, czy próg został spełniony, jaki był próg, kiedy udzielono odpowiedzi i który dostawca jej udzielił.
- Czy muszę przechowywać dokumenty tożsamości?
- Nie. Dostawca może potrzebować wglądu w dokument, aby sformułować odpowiedź, ale aplikacja otrzymuje wyłącznie odpowiedź. API nie zwraca niczego z dokumentu, więc nie ma czego przechowywać.
- Czy weryfikacja wieku potwierdza czyjąś tożsamość?
- Nie. flow=age odpowiada na pytanie, czy osoba posiadająca udowodniony numer telefonu spełnia próg. To nie jest weryfikacja tożsamości ani KYC: bez imienia i nazwiska, daty urodzenia i dokumentu.
- Co się dzieje, gdy weryfikacja wieku się nie powiedzie?
- denied i failed to różne wyniki, których nie należy łączyć w jeden. denied to decyzja dostawcy, a ponowne uruchomienie nie zmieni odpowiedzi. failed oznacza, że z dostawcą nie udało się połączyć, więc nic nie rozstrzygnięto i ponowna próba jest uzasadniona. Odmowa ani błąd dostawcy nie są rozliczane, a zakończona kontrola wieku jest rozliczana jako druga jednostka obok weryfikacji telefonu.
- Czy mogę połączyć weryfikację telefonu z weryfikacją wieku?
- Dokładnie to robi flow=age. Jedna sesja dowodzi numeru telefonu przez WhatsApp, a następnie uruchamia krok weryfikacji wieku, a oba wyniki trafiają do tej samej sesji. Nie trzeba uruchamiać dwóch integracji ani uzgadniać dwóch identyfikatorów.
- Czy mogę wymusić nową kontrolę dla powracającego odwiedzającego?
- Tak. Pozytywny wynik jest wykorzystywany ponownie przez rok dla tego samego numeru telefonu i tego samego progu. Zakończenie wiadomości weryfikacyjnej WhatsApp tekstem #reset omija zapisaną odpowiedź i kieruje odwiedzającego przez pełną kontrolę.
Related
Zastosowania weryfikacji wieku
Treści dla dorosłych
Tam, gdzie samodzielne zaznaczenie pola nie jest już traktowane jako kontrola. Wynik weryfikacji wieku decyduje o dostępie, zanim cokolwiek zostanie udostępnione, a odwiedzający nie musi przesyłać dokumentu.
Hazard online
Konta bukmacherskie i kasynowe, które muszą wykluczać niepełnoletnich graczy. Kontrola pasuje przy rejestracji oraz ponownie przed wrażliwym działaniem, jeśli wymagają tego własne zasady.
Alkohol i towary z ograniczeniem wiekowym
Napoje, tytoń, e-papierosy, noże, rozpuszczalniki i fajerwerki. Kontrola jest umieszczona przed finalizacją zamówienia, na poziomie zamówienia, a nie sesji przeglądania.
Gry
Tytuły z klasyfikacją wiekową, funkcje czatu i płatne mechaniki ograniczone poniżej określonego wieku. Próg jest parametrem żądania, więc różne funkcje mogą wymagać różnych progów.
Marketplace
Oferty ograniczone prawem lub własną polityką. Kupujących i sprzedających można objąć różnymi progami, otwierając sesję z innym min_age.
Platformy społecznościowe i społeczności
Zasady minimalnego wieku dla kont, wiadomości bezpośrednich lub funkcji na żywo. Odpowiedź jest powiązana ze zweryfikowanym numerem telefonu, więc przetrwa koniec sesji.
Build your weryfikacja wieku flow today
Start integrating in minutes with clear documentation, SDKs, and global message delivery.