Chọn ngôn ngữ

Bắt đầu nhanh với API cho nhà phát triển

Mua số và đọc mã từ phần mềm của bạn. Tạo khóa, xem giá, mua số, chờ SMS và hoàn tất, từng bước một.

Trên trang này
  1. Ai có thể dùng
  2. 1. Tạo khóa API
  3. 2. Xác thực
  4. 3. Kiểm tra số dư và giá
  5. 4. Mua số
  6. 5. Chờ SMS
  7. 6. Hoàn tất hoặc hủy
  8. Giá trị trạng thái
  9. Lỗi

API cho nhà phát triển của SmsGrab cung cấp cho phần mềm của bạn đúng những số như trên ứng dụng, qua một REST API dùng JSON. Bạn trả cùng mức giá như trong ứng dụng, trừ mức giảm sỉ của bạn, từ số dư SmsGrab thông thường và được hưởng cùng cơ chế hoàn tiền tự động.

Ai có thể dùng

  • Tài khoản email có địa chỉ đã xác nhận. Tài khoản khách không thể tạo khóa.
  • Tài khoản không bị hạn chế.

1. Tạo khóa API

Mở Tài khoản > Nhà phát triển trên website, hoặc Cài đặt > API cho nhà phát triển trên ứng dụng, rồi tạo khóa. Để bảo mật, bạn xác nhận bằng mật khẩu, và bằng mã xác minh 2 bước nếu đang bật. Chọn phạm vi read cho công cụ chỉ đọc, hoặc read và purchase để mua số.

Khóa bắt đầu bằng sgk_ và chỉ hiển thị một lần. Hãy lưu trong kho bí mật của máy chủ. Xem Khóa API và bảo mật.

2. Xác thực

URL gốc là https://smsgrab.com/api/dev/v1. Gửi khóa dưới dạng bearer token, hoặc trong header X-Api-Key:

HTTP
GET /api/dev/v1/balance HTTP/1.1
Host: smsgrab.com
Authorization: Bearer sgk_your_key_here

Khóa phải nằm trên máy chủ. Đừng bao giờ đặt khóa trong website, tiện ích trình duyệt hoặc ứng dụng bạn phát cho người khác.

3. Kiểm tra số dư và giá

Bash
export SMSGRAB_KEY="sgk_your_key_here"

curl -s https://smsgrab.com/api/dev/v1/balance \
  -H "Authorization: Bearer $SMSGRAB_KEY"
Bash
curl -s "https://smsgrab.com/api/dev/v1/prices?service=whatsapp&country=indonesia" \
  -H "Authorization: Bearer $SMSGRAB_KEY"

Số tiền luôn tính bằng đơn vị nhỏ nhất của USD, nên 24 nghĩa là 0,24 USD. price_minor là giá của bạn đã gồm mức giảm sỉ và retail_price_minor là giá niêm yết trên ứng dụng.

JSON
{ "currency": "USD", "discount_percent": 5,
  "items": [ { "service_id": "whatsapp", "country_id": "indonesia", "price_minor": 24,
               "retail_price_minor": 25, "available_numbers": 30412 } ] }

4. Mua số

Bash
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":24}'
  • service và country nhận mã định danh của chúng tôi, như whatsapp và indonesia. Quốc gia cũng nhận mã ISO như ID.
  • max_price_minor bảo vệ bạn: nếu giá đã tăng, không có gì bị trừ và bạn nhận 409 PRICE_CHANGED.
  • Idempotency-Key giúp thử lại an toàn. Gửi lại yêu cầu với cùng khóa sẽ trả về kết quả đầu tiên thay vì mua hai lần.

Phản hồi là 201 Created kèm lượt kích hoạt:

JSON
{ "id": "5c1d0c2e-8a41-4f7e-9d7a-2f1d9f1b8c11", "compat_id": 100000123, "status": "WAITING_SMS",
  "service_id": "whatsapp", "country_id": "indonesia", "phone_number": "+6281234567890",
  "price_minor": 24, "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. Chờ SMS

Thay vì hỏi liên tục trong vòng lặp dày, hãy để API giữ yêu cầu tối đa 30 giây cho đến khi có thay đổi:

Bash
curl -s "https://smsgrab.com/api/dev/v1/activations/100000123?wait=25" \
  -H "Authorization: Bearer $SMSGRAB_KEY"

Khi tin nhắn đến, status chuyển thành CODE_RECEIVED và sms chứa mọi tin nhắn tính đến lúc đó:

JSON
{ "status": "CODE_RECEIVED",
  "sms": [ { "code": "482913", "text": "Your WhatsApp code is 482-913", "sender": "WhatsApp",
             "received_at": "2026-09-27T10:06:12.004Z" } ] }

Thích nhận đẩy hơn là hỏi liên tục? Hãy thiết lập webhook.

6. Hoàn tất hoặc hủy

Bash
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 sau khi đã dùng mã. Chỉ được chấp nhận sau khi mã đã đến.
  • cancel khi vẫn đang chờ mã đầu tiên. Toàn bộ số tiền được hoàn.
  • Nếu bạn không làm gì, số không có mã sẽ hết hạn vào thời điểm expires_at và được hoàn tiền tự động. Thời gian dùng tùy theo dịch vụ và quốc gia, vì vậy hãy luôn đọc expires_at thay vì giả định một khoảng thời gian cố định.

Giá trị trạng thái

Trạng thái Ý nghĩa
WAITING_SMS Đã mua, đang chờ tin nhắn đầu tiên
CODE_RECEIVED Đã có ít nhất một tin nhắn
COMPLETED Bạn đã hoàn tất, hoặc hết giờ sau khi có mã
CANCELLED Hủy trước khi có mã, đã hoàn tiền
EXPIRED Không có mã trước expires_at, đã hoàn tiền

Lỗi

Mọi lỗi đều có cùng cấu trúc. Hãy xử lý theo code và reason, và bỏ qua các lý do bạn chưa biết:

JSON
{ "code": "NO_NUMBERS_AVAILABLE", "message": "No numbers available for this service and country", "reason": "OUT_OF_STOCK" }

Các trường hợp thường gặp là 402 INSUFFICIENT_BALANCE, 409 NO_NUMBERS_AVAILABLE, 409 PRICE_CHANGED, 422 kèm ACTIVATION_LIMIT_REACHED (mỗi tài khoản có tối đa 100 số cùng chờ) và 429 RATE_LIMITED kèm header Retry-After.

Tài liệu tham chiếu đầy đủ có trong tài liệu cho nhà phát triển.

Bài viết này có hữu ích không?

Vẫn cần trợ giúp?

Nhắn cho chúng tôi. Chúng tôi trả lời mọi tin nhắn, thường trong vài giờ.

Hoặc gửi email tới support@smsgrab.com