Qatar OTP API: webhooki, polling i numery testowe +974

Jak wygląda sekwencja wywołań Qatar OTP API?

Wszystko znajduje się pod https://otproute.com/api/v1, a uwierzytelnianie odbywa się kluczem Bearer zaczynającym się od or_live_. Możesz mieć do 10 kluczy, więc daj CI, stagingowi i skryptowi operacyjnemu osobne klucze i unieważniaj jeden bez ruszania pozostałych. Pełna aktywacja numeru +974 to najwyżej cztery wywołania:

1. GET /api/v1/prices?country=qa&service=<id> zwraca aktualną cenę i informuje, że trasa jest teraz otwarta dla danej usługi.
2. POST /api/v1/activations z {"service": "<id>", "country": "qa"} rezerwuje katarski numer i zwraca identyfikator aktywacji.
3. GET /api/v1/activations/{id} to wywołanie pollingowe: pokazuje, na jakim etapie jest zamówienie z Kataru, i zawiera kod po dostarczeniu.
4. POST /api/v1/activations/{id}/cancel kończy zamówienie wcześniej i zwraca kwotę do portfela.

Obraz uzupełniają dwa pomocnicze wywołania: GET /api/v1/services mapuje nazwy na identyfikatory usług, a GET /api/v1/balance pozwala potokowi zatrzymać się, zanim skończą mu się środki. Utrzymuj ruch poniżej 300 żądań na minutę na konto. Przegląd dla deweloperów zbiera strony referencyjne.

Jak handler webhooka powinien traktować zdarzenia aktywacji z Kataru?

Polling działa, ale webhook pozwala Twojemu runnerowi testów zareagować w chwili, gdy coś się wydarzy. Zarejestruj do pięciu endpointów i zasubskrybuj activation.sms_received, activation.expired i activation.cancelled; pierwsze niesie kod, a pozostałe dwa informują runnera, że może przestać czekać.

Każde żądanie zawiera X-OTPRoute-Signature w postaci t=<unix>,v1=<hex>. Odtwórz podpisywany ciąg jako znacznik czasu, kropkę i surowe ciało żądania, oblicz HMAC-SHA256 z sekretem endpointu i porównaj w stałym czasie. Odrzucaj wszystko z nieaktualnym znacznikiem czasu. Ponieważ ponowienia mogą dostarczyć to samo zdarzenie więcej niż raz, zapisuj identyfikator aktywacji i ignoruj powtórzenia. Implementację referencyjną znajdziesz w artykule o przechwytywaniu OTP przez webhook.

Które usługi mogą skierować kod na numer +974?

Katar to jedna z szerszych tras, z ponad 1600 usług w najnowszym zestawieniu. Popularne pozycje to WhatsApp, Google (Gmail & YouTube), Microsoft & Outlook, Telegram, Instagram, Facebook, LinkedIn, Snapchat, TikTok, Uber, Airbnb, ChatGPT (OpenAI), Claude i Discord.

Zasoby zmieniają się w ciągu dnia, więc traktuj zestawienie jako orientację, a odpowiedź API jako prawdę. Kilka usług odrzuca numery wirtualne; wtedy zamówienie po prostu wygasa, a pieniądze wracają. Każda z powyższych nazw jest znakiem towarowym swojego właściciela i nie sugerujemy żadnych powiązań.

Normalizacja katarskich numerów w fixture'ach testowych

Katarskie numery mają osiem cyfr po +974 i nie mają prefiksu krajowego, więc przy zamianie numeru lokalnego na międzynarodowy nie ma czego odrzucać. Trzymaj fixture'y w E.164 (+974 plus osiem cyfr) i czyść dane wpisywane przez użytkowników z 00974, spacjami lub zbędnym początkowym zerem przeniesionym z nawyków z innego kraju.

Językiem urzędowym jest arabski, a angielski jest szeroko używany w biznesie i przez populację z dużym udziałem ekspatriantów. Wiadomości weryfikacyjne przychodzą więc w języku, który wybierze usługa nadawcza dla konta, często po angielsku lub arabsku. Sprawdź, czy Twoja logika ekstrakcji znajduje kod w obu pismach i czy arabski interfejs zachowuje używalność pola wpisywania OTP w układzie od prawej do lewej.

Zespoły testują trasę katarską, gdy wchodzą na rynek Zatoki Perskiej (GCC), lokalizują aplikację konsumencką dla arabskojęzycznych użytkowników, prowadzą operacje hotelarskie lub logistyczne w Dosze albo weryfikują regionalne konto firmowe bez podawania prywatnego numeru pracownika. Poradnik testów CI pokazuje, jak wpiąć te kontrole w automatyczne przebiegi.

Test dla Kataru z panelu zamiast kodu

Nie każda weryfikacja wymaga skryptu. W panelu otwórz OTP Gateway, wybierz Katar i usługę, sprawdź wyświetlaną cenę i potwierdź. Skopiuj numer +974 do aplikacji, zażądaj SMS-a, a kod pojawi się przy zamówieniu. 20-minutowe okno liczy się od momentu złożenia zamówienia, a płacisz tylko wtedy, gdy kod dotrze.

Kody, które nie przychodzą: lista debugowania

• Czy czekałeś wystarczająco długo? Pozwól aktywacji działać przez pełne okno, zanim uznasz ją za nieudaną.
• Czy numery wirtualne są akceptowane? Niektóre usługi je blokują, a powtarzane próby tego nie zmienią.
• Czy polityka ponowień jest rozsądna? Zwiększ odstępy i spróbuj później albo przełącz się na inną trasę dla tej samej usługi. Ponowne zamawianie w ciasnej pętli marnuje limit zapytań i rzadko pomaga.
• Czy handler działa poprawnie? Jeśli weryfikacja podpisu zawodzi lub endpoint zwraca błąd, odpytaj GET /api/v1/activations/{id}, aby sprawdzić, czy kod został dostarczony, gdy webhook go nie odebrał.

Aktywacja, która kończy się bez SMS-a, przez wygaśnięcie lub anulowanie, jest zwracana w całości.

Czy istnieje długoterminowa linia katarska i jak rozliczane jest użycie?

Dla Kataru nie ma samoobsługowego numeru długoterminowego. Dedykowane numery wirtualne (własna linia z przychodzącymi i wychodzącymi SMS-ami, przekazywaniem webhookiem i dzwonieniem z przeglądarki) są oferowane tylko w Stanach Zjednoczonych i Kanadzie, od $1.95/month. W sprawie potrzeby związanej konkretnie z Katarem napisz na [email protected]; to, co jest możliwe, wyznaczają lokalne przepisy.

Użycie dla Kataru czerpie z jednego przedpłaconego portfela w USD, a nic nie jest rozliczane miesięcznie. Doładuj kartą lub USDT/USDC, odbieraj fakturę PDF za każde doładowanie i poproś o tryb sandbox dla konta deweloperskiego, jeśli chcesz przetestować integrację na symulowanych numerach. Używaj numerów +974 wyłącznie do własnych produktów i legalnych kont firmowych, przestrzegaj regulaminów poszczególnych usług i stosuj się do Polityki Dopuszczalnego Użytkowania OTP Route.

Najczęstsze pytania

Jak odebrać kody SMS OTP z Kataru w teście automatycznym?

Utwórz aktywację z krajem qa, wpisz zwrócony numer w testowanej aplikacji i poczekaj na webhook activation.sms_received. OTP Route obsługuje też polling aktywacji, jeśli Twój runner testów nie może przyjmować żądań przychodzących.

Czy mogę użyć numeru +974 do testów bez katarskiej karty SIM?

Tak. OTP Gateway udostępnia katarski numer weryfikacyjny na jeden kod, więc możesz testować rejestrację lub logowanie bez lokalnej karty SIM i urządzenia.

Jak sprawdzić ceny dla Kataru przed zamówieniem?

Wywołaj GET /api/v1/prices?country=qa&service=<id> albo zajrzyj do panelu. Stawki zaczynają się od $0.20 za kod i zależą od usługi.

Czy płacę za nieudane aktywacje z Kataru?

Nie. Rozliczasz się tylko wtedy, gdy kod dotrze; aktywacje, które wygasły lub zostały anulowane, są automatycznie zwracane do portfela.

Dlaczego testować na numerze katarskim, a nie z sąsiedniego kraju?

Wybierz kraj odpowiadający rzeczywistemu rynkowi konta. Jeśli Twój produkt startuje w Katarze, numer +974 sprawdza dokładnie tę obsługę kodu kraju, język i routing OTP, które zobaczą Twoi klienci, jak wyjaśnia artykuł o routingu krajowym dla OTP.

Czy konto deweloperskie może działać bez środków w portfelu?

Tak. Na prośbę konto deweloperskie można przełączyć w tryb sandbox, który zwraca symulowane numery i kody do testów end-to-end.

Czy mogę zachować katarski numer do powtarzanych logowań?

Nie w modelu samoobsługowym, ponieważ linie dedykowane są ograniczone do USA i Kanady. Napisz na [email protected], jeśli chcesz zapytać o długoterminową linię katarską.

Nazwy usług są znakami towarowymi ich właścicieli. OTP Route nie jest z nimi powiązany. Korzystaj z numerów zgodnie z prawem oraz przestrzegaj regulaminów poszczególnych usług i naszej Polityki akceptowalnego użytkowania.