REST 호출과 웹훅으로 바하마 +1 242 OTP 수집하기

바하마 OTP API 연동에는 어떤 요청이 필요한가요?

바하마 OTP API 연동은 https://otproute.com/api/v1을 대상으로 하는 짧은 호출 체인이며, 개발자 콘솔에서 생성한 접두사 or_live_의 Bearer 키로 인증합니다. 바하마의 국가 id는 bs이고, whatsapp이나 telegram 같은 서비스 id는 카탈로그에서 가져옵니다.

1. GET /api/v1/services와 GET /api/v1/countries로 카탈로그를 불러오고, 표시 이름으로 매칭하지 말고 id를 설정에 보관합니다.
2. 주문하기 전에 GET /api/v1/prices?country=bs&service=<id>를 요청합니다. 응답에는 현재 가격이 들어 있고, 가용성이 하루 동안 변하므로 지금 이 순간 경로가 열려 있는지도 알려 줍니다.
3. {"service": "<id>", "country": "bs"} 본문으로 POST /api/v1/activations를 호출해 활성화를 만듭니다. 활성화 id와 +1 242 번호를 받습니다.
4. 그 번호를 테스트 대상 제품의 가입 또는 로그인 단계에 입력합니다.
5. 웹훅으로 코드를 기다리거나 GET /api/v1/activations/{id}를 폴링합니다. 실행을 깔끔하게 포기하려면 POST /api/v1/activations/{id}/cancel을 호출합니다.

계정은 키를 최대 10개 보유하고 분당 300건의 요청을 보낼 수 있으므로, 스테이징, CI, 동료의 노트북에 각각 별도의 키를 주고 따로 폐기할 수 있습니다. 이 SMS 인증 API의 파라미터와 응답은 API 문서에 나와 있습니다.

+1 242 코드를 위한 서명된 웹훅은 어떻게 검증하나요?

수동으로 한 번 확인할 때는 폴링으로 충분합니다. 여러 스위트가 나란히 돌기 시작하면 푸시 전달이 더 깔끔합니다. 개발자 콘솔에 엔드포인트를 최대 5개 등록하고 activation.sms_received, activation.expired, activation.cancelled를 구독하세요.

모든 전송에는 X-OTPRoute-Signature: t=<unix>,v1=<hex>가 붙습니다. 서명 대상 문자열을 <t>.<raw body>로 구성하고, 엔드포인트 시크릿으로 HMAC-SHA256을 계산한 뒤 결과를 v1과 상수 시간 함수로 비교하세요. 도착한 그대로의 바이트로 작업해야 합니다. 파싱한 JSON을 다시 직렬화하면 공백이 바뀌어 다이제스트가 더 이상 일치하지 않습니다. 캡처된 요청이 재생되지 않도록 몇 분보다 오래된 타임스탬프는 거부하세요.

재전송된 요청이 테스트를 두 번 통과 처리하지 않도록 핸들러를 활성화 id를 키로 멱등적으로 만드세요. 시계 오차와 시크릿 교체는 HMAC로 OTP 웹훅 보호하기 글에서 다룹니다.

바하마 경로에는 어떤 서비스가 있고, 직원이 직접 주문할 수 있나요?

바하마 경로에는 현재 900개가 넘는 서비스가 나열되어 있습니다. 인기 서비스로는 WhatsApp, Telegram, Google (Gmail & YouTube), Facebook, Instagram, TikTok, X (Twitter), ChatGPT (OpenAI), Microsoft & Outlook, Amazon, Discord, LinkedIn, Uber, Airbnb, Signal이 있습니다. 이 목록은 스냅샷으로 보세요. 중요한 것은 주문 시점의 API 응답입니다.

키를 만지지 않는 동료는 브라우저에서 같은 결과를 얻습니다. 로그인해서 OTP Gateway를 열고, 바하마와 서비스를 선택하고, 표시된 가격을 읽고 주문하세요. 바하마 인증용 번호가 카운트다운과 함께 나타나며, 코드가 도착하면 같은 화면에 표시됩니다.

20분의 시간 창 안에서는 어떤 일이 일어나고, 아무것도 오지 않으면 어떻게 되나요?

모든 활성화는 20분 동안 열려 있습니다. 그 시간 안에 SMS가 도착하면 표시된 가격을 내고, 시간 창이 빈 채로 닫히거나 먼저 취소하면 전체 금액이 자동으로 지갑에 돌아갑니다.

바하마 코드가 나타나지 않을 때는 이렇게 하세요.

• 일부 발신자는 메시지를 큐에 쌓아 두므로, 테스트를 실패로 판단하기 전에 시간 창이 끝날 때까지 기다리세요.
• 재고와 발신자 동작이 하루 동안 변하므로 나중에 다시 시도하거나 다른 서비스 경로로 시도하세요.
• 서비스가 가상 번호를 허용하는지 먼저 확인하세요. 거부하는 서비스도 있으며, 환불이 존재하는 이유가 바로 이것입니다.
• 짧은 루프로 재주문하지 마세요. 불안정한 테스트 하나가 요청 예산을 소진하지 않도록 시도 사이에 간격을 두세요.

더 많은 문제 해결 패턴은 실패한 OTP 전송 줄이기에 정리되어 있습니다.

+1 242 번호는 어떻게 저장하고 정규화해야 하나요?

바하마는 북미 번호 계획(NANP)의 일부이므로 미국, 캐나다와 국가 코드 1을 공유합니다. 전체 번호는 1, 지역 번호 242, 일곱 자리 가입자 번호로 이루어지며, E.164로는 +1242 뒤에 일곱 자리가 붙어 모두 열한 자리가 됩니다. 주민들은 현지 일곱 자리만 말하는 경우가 많고, 번호 계획 내 다른 지역의 발신자는 242 앞에 1을 누릅니다.

이로부터 코드에 두 가지 결과가 따릅니다. +1만으로 국가를 추론하는 검증기는 바하마 사용자를 미국인으로 분류하므로, 지역 번호를 확인하거나 NANP 영토를 아는 번호 라이브러리를 사용하세요. 그리고 조회와 중복 제거가 일관되도록 모든 번호를 E.164로 저장하고 서식은 표시할 때만 적용하세요. 바하마 회선의 인증 문자는 보통 공용어인 영어로 오므로, 현지화 점검은 번역된 문구보다 번호 형식과 국가 라벨에 집중하면 됩니다.

제품 팀이 바하마를 대상으로 가입을 테스트하는 이유는 무엇인가요?

관광, 호스피탈리티, 금융 서비스가 바하마 경제의 큰 부분을 차지하므로, 카리브해 고객을 둔 예약 플랫폼, 차량 호출 및 배달 앱, 결제 제품, 은행은 모두 +1 242 사용자를 위한 동작하는 경로가 필요합니다. 테스트용 +1 242 번호가 있으면 QA 엔지니어는 양식이 번호를 받아들이는지, 국가 선택기가 바하마를 미국에 합치지 않고 바하마로 표시하는지, SMS 동의 문구가 올바르게 렌더링되는지 확인할 수 있습니다. 좋은 OTP 라우팅은 또한 본토 번호를 기본값으로 쓰지 않고 테스트 케이스마다 올바른 국가를 선택하는 것을 뜻합니다. QA 테스트 플레이북에서 이를 자동화 스위트에 연결하는 방법을 볼 수 있습니다. 모든 점검은 조직이 소유한 계정에 대해서만 하고 각 서비스의 약관을 지키세요. OTP Route의 이용 정책(Acceptable Use Policy)은 모든 주문에 적용됩니다.

바하마의 장기 번호가 가능한가요? 사용량은 어떻게 청구되나요?

바하마에는 셀프 서비스 방식의 장기 번호가 없습니다. Dedicated Number는 미국과 캐나다 전용 제품으로 월 $1.95부터이며 수신·발신 SMS, 브라우저 통화, 웹훅 전달을 지원합니다. 팀에 지속적인 바하마 회선이 필요하다면 [email protected]으로 이메일을 보내세요. 가능 여부는 현지 규정에 달려 있고 약속할 수 없습니다.

사용량은 월 요금도 선택할 요금제도 없는 하나의 선불 USD 지갑에서 차감됩니다. 카드 또는 USDT/USDC로 충전하며, 충전마다 PDF 인보이스가 받은편지함에 도착합니다. 연동 작업에는 개발 계정을 샌드박스로 전환해 달라고 요청하세요. 시뮬레이션된 번호와 코드를 반환하므로 지갑 자금을 쓰지 않고 전체 흐름을 실행해 볼 수 있습니다. 청구 방식은 요금 페이지에서 볼 수 있습니다.

자주 묻는 질문

현지 SIM 없이 우리 앱의 바하마 가입 흐름을 테스트할 수 있나요?

네. 테스트 중인 서비스용 +1 242 번호를 OTP Gateway에서 주문해 흐름에 입력하고, 대시보드나 웹훅에서 코드를 확인하세요. 코드당 $0.20부터이며, SMS가 도착했을 때만 비용을 냅니다.

API에서 바하마의 국가 id는 무엇인가요?

bs입니다. GET /api/v1/prices와 POST /api/v1/activations의 본문에 전달하세요.

내 전화번호 라이브러리가 +1 242를 미국 번호로 취급하나요?

국가 코드만으로 국가를 추측하는 경우에만 그렇습니다. 바하마 번호가 올바르게 표시되도록 지역 번호를 확인하거나 NANP 영토 데이터를 갖춘 라이브러리를 사용하세요.

코드가 오지 않으면 요금이 청구되나요?

아니요. 20분 안에 아무것도 도착하지 않거나 취소하면 전체 금액이 자동으로 지갑에 돌아갑니다.

앞으로의 로그인을 위해 바하마 인증용 번호를 유지할 수 있나요?

셀프 서비스 제품으로는 불가능합니다. 장기 Dedicated Number는 미국과 캐나다에만 있습니다. 바하마 회선은 [email protected]으로 이메일을 보내면 현지 규정이 허용하는 범위를 안내해 드립니다.

테스트 스위트는 몇 건의 요청을 보낼 수 있나요?

계정당 분당 최대 300건이며, 최대 10개의 API 키에 나눌 수 있습니다. 몇 초마다 폴링하거나 웹훅으로 전환하면 이 한도 안에서 충분히 여유 있게 운영할 수 있습니다.

스테이블코인으로 지갑을 충전할 수 있나요?

네. 지갑은 카드와 USDT/USDC를 받으며, 충전마다 PDF 인보이스가 이메일로 발송됩니다.

서비스 이름은 각 소유자의 상표입니다. OTP Route는 해당 소유자와 제휴 관계가 없습니다. 번호는 합법적으로 사용하고, 각 서비스의 약관과 당사의 허용 가능한 사용 정책을 준수하세요.