Inicio rápido de la API para desarrolladores

La API para desarrolladores de SmsGrab da a tu software los mismos números que la app, a través de una API REST en JSON. Es un producto de pago con sus propios precios para desarrolladores, se paga con tu saldo habitual de SmsGrab y tiene los mismos reembolsos automáticos.

Quién puede usarla

• Una cuenta con correo y la dirección confirmada. Las cuentas de invitado no pueden crear claves.
• Una cuenta sin restricciones.

1. Crea una clave de API

Abre Cuenta > Desarrolladores en la web, o Ajustes > API para desarrolladores en la app, y crea una clave. Por seguridad, confirmas con tu contraseña y, si la tienes activada, con tu código de verificación en dos pasos. Elige el ámbito read para herramientas de solo lectura, o read y purchase para comprar números.

La clave empieza por sgk_ y se muestra una sola vez. Guárdala en el almacén de secretos de tu servidor. Consulta Claves de API y seguridad.

2. Autentícate

La URL base es https://smsgrab.com/api/dev/v1. Envía la clave como token Bearer o en la cabecera X-Api-Key:

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

Las claves van en servidores. Nunca las pongas en una web, una extensión de navegador o una app que distribuyas a otras personas.

3. Consulta tu saldo y los precios

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"

Los importes siempre van en unidades menores de USD: 18 significa 0,18 USD. price_minor es tu precio de desarrollador y retail_price_minor el precio de la app.

{ "currency": "USD", "markup_percent": 80,
  "items": [ { "service_id": "whatsapp", "country_id": "indonesia", "price_minor": 18,
               "retail_price_minor": 25, "available_numbers": 30412 } ] }

4. Compra un número

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 y country usan nuestros identificadores, como whatsapp e indonesia. En los países también valen los códigos ISO, como ID.
• max_price_minor te protege: si el precio ha subido, no se cobra nada y recibes 409 PRICE_CHANGED.
• Idempotency-Key hace seguros los reintentos. Repetir la petición con la misma clave devuelve el primer resultado en lugar de comprar dos veces.

La respuesta es 201 Created con la activación:

{ "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. Espera el SMS

En lugar de consultar en bucle, deja que la API retenga la petición hasta que algo cambie, durante un máximo de 30 segundos:

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

Cuando llega un mensaje, status pasa a CODE_RECEIVED y sms contiene todos los mensajes recibidos:

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

¿Prefieres recibir avisos en lugar de consultar? Configura webhooks.

6. Termina o cancela

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 cuando hayas usado el código. Solo se acepta después de que llegue un código.
• cancel mientras aún esperas el primer código. Se reembolsa el precio completo.
• Si no haces nada, un número sin código caduca a los 20 minutos y se reembolsa automáticamente.

Valores de estado

Errores

Todos los errores tienen la misma forma. Actúa según code y reason, e ignora los motivos que todavía no conozcas:

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

Los casos habituales son 402 INSUFFICIENT_BALANCE, 409 NO_NUMBERS_AVAILABLE, 409 PRICE_CHANGED, 422 con ACTIVATION_LIMIT_REACHED (como máximo 100 números pueden esperar a la vez por cuenta) y 429 RATE_LIMITED con una cabecera Retry-After.

La referencia completa está en la documentación para desarrolladores.