개발자 API 빠른 시작
직접 만든 소프트웨어에서 번호를 구매하고 코드를 읽어 오세요. 키 만들기, 가격 확인, 번호 구매, SMS 대기, 완료까지 단계별로 안내합니다.
SmsGrab 개발자 API 기능은 앱과 같은 번호를 JSON 기반 REST API 방식으로 내 소프트웨어에 제공합니다. 별도의 개발자 가격이 적용되는 유료 기능이며, 일반 SmsGrab 잔액에서 결제되고 같은 자동 환불로 보호됩니다.
사용할 수 있는 사람
- 주소가 확인된 이메일 계정. 게스트 계정은 키를 만들 수 없습니다.
- 이용이 제한되지 않은 계정.
1. API 키 만들기
웹사이트의 계정 > 개발자 또는 앱의 설정 > 개발자 API 화면을 열고 키를 만듭니다. 보안을 위해 비밀번호로, 2단계 인증이 켜져 있다면 인증 코드로도 확인합니다. 읽기만 하는 도구에는 read 범위를, 번호를 구매하려면 read 및 purchase 범위를 고르세요.
키는 sgk_ 형태로 시작하며 한 번만 표시됩니다. 서버의 비밀 저장소에 보관하세요. API 키와 보안 문서를 참고하세요.
2. 인증
기본 URL 주소는 https://smsgrab.com/api/dev/v1 형태입니다. 키는 Bearer 토큰으로 보내거나 X-Api-Key 헤더에 넣어 보냅니다.
GET /api/dev/v1/balance HTTP/1.1
Host: smsgrab.com
Authorization: Bearer sgk_your_key_here키는 서버에 두어야 합니다. 웹사이트, 브라우저 확장 프로그램, 다른 사람에게 배포하는 앱에는 절대 넣지 마세요.
3. 잔액과 가격 확인
export SMSGRAB_KEY="sgk_your_key_here"
curl -s https://smsgrab.com/api/dev/v1/balance \
-H "Authorization: Bearer $SMSGRAB_KEY"curl -s "https://smsgrab.com/api/dev/v1/prices?service=whatsapp&country=indonesia" \
-H "Authorization: Bearer $SMSGRAB_KEY"금액은 항상 USD의 최소 단위로 표시되므로 18 값은 0.18 USD 금액을 뜻합니다. price_minor 값은 내 개발자 가격이고 retail_price_minor 값은 앱 가격입니다.
{ "currency": "USD", "markup_percent": 80,
"items": [ { "service_id": "whatsapp", "country_id": "indonesia", "price_minor": 18,
"retail_price_minor": 25, "available_numbers": 30412 } ] }4. 번호 구매
curl -s -X POST https://smsgrab.com/api/dev/v1/activations \
-H "Authorization: Bearer $SMSGRAB_KEY" \
-H "Idempotency-Key: order-7f3c2a" \
-H "Content-Type: application/json" \
-d '{"service":"whatsapp","country":"indonesia","max_price_minor":20}'service및country항목에는whatsapp,indonesia같은 SmsGrab ID 값을 씁니다. 국가에는ID같은 ISO 코드도 쓸 수 있습니다.max_price_minor값이 나를 보호합니다. 가격이 오르면 아무것도 차감되지 않고409 PRICE_CHANGED응답을 받습니다.Idempotency-Key헤더 덕분에 재시도가 안전합니다. 같은 키로 요청을 반복하면 두 번 구매되지 않고 첫 결과가 반환됩니다.
응답은 활성화 정보가 담긴 201 Created 응답입니다.
{ "id": "5c1d0c2e-8a41-4f7e-9d7a-2f1d9f1b8c11", "compat_id": 100000123, "status": "WAITING_SMS",
"service_id": "whatsapp", "country_id": "indonesia", "phone_number": "+6281234567890",
"price_minor": 18, "currency": "USD",
"created_at": "2026-09-27T10:05:00.000Z", "expires_at": "2026-09-27T10:25:00.000Z",
"refunded": false, "refund_minor": 0, "sms": [] }5. SMS 기다리기
짧은 간격으로 계속 묻는 대신, 변화가 있을 때까지 최대 30초 동안 요청을 붙잡아 두도록 하세요.
curl -s "https://smsgrab.com/api/dev/v1/activations/100000123?wait=25" \
-H "Authorization: Bearer $SMSGRAB_KEY"메시지가 도착하면 status 값이 CODE_RECEIVED 상태로 바뀌고, sms 항목에 지금까지의 모든 메시지가 담깁니다.
{ "status": "CODE_RECEIVED",
"sms": [ { "code": "482913", "text": "Your WhatsApp code is 482-913", "sender": "WhatsApp",
"received_at": "2026-09-27T10:06:12.004Z" } ] }폴링보다 푸시가 좋다면 웹훅을 설정하세요.
6. 완료 또는 취소
curl -s -X POST https://smsgrab.com/api/dev/v1/activations/100000123/finish \
-H "Authorization: Bearer $SMSGRAB_KEY"
curl -s -X POST https://smsgrab.com/api/dev/v1/activations/100000123/cancel \
-H "Authorization: Bearer $SMSGRAB_KEY"- finish 호출은 코드를 사용한 뒤에 합니다. 코드가 도착한 뒤에만 받아들여집니다.
- cancel 호출은 첫 코드를 기다리는 동안 합니다. 전액이 환불됩니다.
- 아무것도 하지 않으면 코드가 없는 번호는 20분 후 만료되고 자동으로 환불됩니다.
상태 값
| 상태 | 의미 |
|---|---|
WAITING_SMS |
구매됨, 첫 메시지 대기 중 |
CODE_RECEIVED |
메시지가 한 통 이상 도착함 |
COMPLETED |
내가 완료했거나, 코드 수신 후 시간이 끝남 |
CANCELLED |
코드 전에 취소됨, 환불 완료 |
EXPIRED |
20분 안에 코드 없음, 환불 완료 |
오류
모든 오류는 같은 형식입니다. code 값과 reason 값에 따라 처리하고, 아직 모르는 사유는 무시하세요.
{ "code": "NO_NUMBERS_AVAILABLE", "message": "No numbers available for this service and country", "reason": "OUT_OF_STOCK" }자주 나오는 경우는 402 INSUFFICIENT_BALANCE, 409 NO_NUMBERS_AVAILABLE, 409 PRICE_CHANGED, ACTIVATION_LIMIT_REACHED 사유의 422 응답(계정당 동시에 대기할 수 있는 번호는 최대 100개), Retry-After 헤더가 붙은 429 RATE_LIMITED 응답입니다.
전체 레퍼런스는 개발자 문서에 있습니다.
이 문서가 도움이 되었나요?
감사합니다! 도움이 되었다니 기쁩니다.