API de alquiler de números
Alquila un número por un periodo fijo y lee todos los SMS que recibe, mediante el endpoint compatible handler_api.php.
Cómo funciona
Cada solicitud es un GET a /stubs/handler_api.php con api_key y action. Las acciones de alquiler responden en JSON, tanto en éxito como en error.
Las acciones de alquiler solo aceptan autenticación con clave de API. Los tokens de sesión web reciben WRONG_ACTION.
Los precios son los mismos que en el panel web y se cobran en USD desde tu saldo.
Acciones
| Acción | Parámetros | Qué hace |
|---|---|---|
getRentServicesAndCountries | country, rent_time | Ofertas de alquiler con precio para un país y una duración. services.{code}.cost es el precio, quant es el stock disponible. |
getRentNumber | service, country, rent_time | Alquila un número y cobra el saldo. Devuelve phone.id, phone.number y phone.endDate. |
getRentStatus | id, page, size | SMS recibidos por el número alquilado, del más reciente al más antiguo. page (empieza en 0) y size opcionales. |
setRentStatus | id, status (1 | 2) | status=1 finaliza el alquiler antes de tiempo sin reembolso. status=2 lo cancela; el reembolso total solo se hace si no llegó ningún SMS. |
continueRentNumber | id, rent_time, expectedCharge | Extiende un alquiler activo rent_time horas y cobra el saldo. |
getRentList | - | Tus alquileres activos: id y phone. |
getContinueRentPriceNumber | id, rent_time | Precio de extender un alquiler, sin cobrar. |
Códigos de país
- El alquiler está disponible en 27 países: AT, BE, BR, CZ, DE, EE, ES, FI, FR, GB, GE, GR, HR, ID, IT, LV, MD, MY, NL, PL, PT, RO, SE, SI, SK, UA, US. Para alquilar un número o consultar precios, country es obligatorio; se recomienda el código ISO de dos letras. Duraciones: 24, 72, 168 horas.
- Para leer esta lista desde la API, llama a getRentServicesAndCountries sin country: la respuesta contiene countryList (códigos ISO), hours y currency, sin precios ni stock. Para precios y stock, envía country y rent_time.
- Recomendado: envía el código ISO del país, por ejemplo country=US o country=GB. Funcionan mayúsculas y minúsculas.
- Los ID numéricos de país no son iguales en todos los servicios. Si envías un número, léelo de la respuesta de getCountries con tu propia clave de API; no lo copies de la lista de otro proveedor.
- Las acciones de alquiler solo aceptan el ID numérico de los países disponibles para alquiler, tal como aparece en getCountries. Cualquier otro número devuelve BAD_COUNTRY; si tienes dudas, usa el código ISO.
- Los números 42 (DE), 44 (HR), 45 (SE), 47 (NL), 48 (LV), 49 (AT), 51 (TH), 55 (ES), 58 (SI), 62 (CZ), 72 (BR), 77 (FR), 90 (SK), 97 (PT), 115 (GE), 116 (GR), 128 (BE), 175 (FI), 178 (IT) no se aceptan para alquiler, porque en otros servicios corresponden a otro país. Siempre devuelven BAD_COUNTRY_USE_ISO; no se cobra nada y no se alquila ningún número. Envía el código ISO en su lugar, por ejemplo country=DE. Para estos países, countries en la respuesta de getRentServicesAndCountries está vacío.
- También se acepta nuestro slug de país.
- getRentServicesAndCountries devuelve el ID numérico del país en countries.
Lista de países y sus códigos
curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getCountries"Ofertas de alquiler de un país por código ISO
curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentServicesAndCountries&country=US&rent_time=24"Lista de países disponibles para alquiler
curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentServicesAndCountries"Respuesta
{"countryList":["AT","BE","BR","CZ","DE","EE","ES","FI","FR","GB","GE","GR","HR","ID","IT","LV","MD","MY","NL","PL","PT","RO","SE","SI","SK","UA","US"],"hours":[24,72,168],"currency":840}Ejemplo
Solicitud
curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentNumber&service=wa&country=US&rent_time=24"Respuesta
{
"status": "success",
"phone": {
"id": "cm4x9k2...",
"endDate": "2026-11-02T12:00:00",
"number": "15550000001"
}
}Solicitud
curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentStatus&id=cm4x9k2..."Respuesta
{
"status": "success",
"quantity": "1",
"values": {
"0": {
"phoneFrom": "WhatsApp",
"text": "Your code: 123456",
"service": "wa",
"date": "2026-11-01 12:05:00"
}
}
}Detalles de la respuesta
- El id del alquiler es una cadena (por ejemplo "cm4x9k2..."), no un número. Guárdalo como texto.
- La duración en horas se lee de rent_time; también se acepta el parámetro time.
- Si no se envía duración, se usa la duración disponible más corta (ahora 24 horas). Envía rent_time de forma explícita al alquilar o extender.
- currency es 840 (USD). cost y price son números en USD.
- endDate y las fechas de los SMS están en UTC, sin sufijo de zona horaria.
- El parámetro url se ignora: los alquileres no envían webhooks. Consulta getRentStatus para leer SMS nuevos.
- Los errores se devuelven como {"status":"error","message":"<CODE>"}. Los errores de autenticación y de límite de velocidad mantienen el formato de texto plano (BAD_KEY, RATE_LIMITED).
- Pide una cotización con getContinueRentPriceNumber antes de continueRentNumber. El importe cobrado nunca supera la última cotización que se te mostró (válida 10 minutos, mismo alquiler y rent_time). El expectedCharge opcional (USD, por ejemplo 1.334) solo puede bajar este tope, nunca subirlo. Si el precio supera el tope, o no tienes una cotización válida, el alquiler no se extiende, no se cobra nada y se devuelve una nueva cotización: WRONG_CHARGE con el importe en price. Vuelve a intentarlo con la nueva cotización.
- Un alquiler solo se puede extender cuando termina su ventana de cancelación gratuita (los primeros 20 minutos); antes, continueRentNumber devuelve CONTINUE_TOO_EARLY y no se cobra nada.
Ventana de cancelación
La cancelación se rechaza durante los primeros 2 minutos del alquiler (CANT_CANCEL).
La cancelación gratuita es posible hasta 20 minutos después del inicio del alquiler. Después de esa ventana la cancelación se rechaza, normalmente con CANT_CANCEL (en casos raros TEMPORARILY_UNAVAILABLE); usa status=1 para finalizar.
Un alquiler cancelado se reembolsa por completo solo si no recibió ningún SMS.
Tiempos de espera y reintentos
getRentNumber no es idempotente: no lo reintentes tras un tiempo de espera agotado. Llama primero a getRentList; si encuentras un alquiler que no necesitas, cancélalo entre el minuto 2 y el minuto 20 para un reembolso total (sin SMS recibidos).
Límites
Los alquileres nuevos están limitados por clave de API y día UTC (las extensiones no cuentan): como máximo 50 alquileres por clave. Por encima: RENT_LIMIT.
getRentNumber y continueRentNumber también cuentan para la cuota diaria de compras de la clave.
Estas acciones están disponibles para todas las claves de API de tu cuenta.
Códigos de error
{ "status": "error", "message": "NO_BALANCE" }NO_ | Saldo insuficiente. |
NO_ | No hay número disponible para este servicio, país y duración en este momento. |
BAD_ | Código de servicio ausente o no admitido. |
BAD_ | País ausente, desconocido o no disponible (usa el código ISO). |
BAD_ | ID numérico de país no aceptado para alquiler (en otros servicios corresponde a otro país). Usa el código ISO; no se cobra nada. Los números afectados figuran en la sección Códigos de país. La respuesta también incluye un campo legible description. |
BAD_ | Duración no ofrecida. |
NO_ | Falta el parámetro id. |
INVALID_ | No hay alquiler con este id en tu cuenta. |
INCORECT_ | El status de setRentStatus debe ser 1 o 2. |
CANT_ | No se puede cancelar ahora (durante los primeros 2 minutos o después de la ventana gratuita de hasta 20 minutos). |
ALREADY_ | El alquiler ya ha finalizado. |
ALREADY_ | El alquiler ya fue cancelado. |
STATUS_ | El alquiler está activo pero aún no ha llegado ningún SMS. |
STATUS_ | El alquiler fue cancelado. |
STATUS_ | El alquiler ha finalizado o expirado. |
RENT_ | Se alcanzó el límite diario de alquileres de esta clave de API. |
TEMPORARILY_ | Problema temporal. En getRentNumber y continueRentNumber no se cobró nada o el cobro fue reembolsado. En una cancelación el resultado puede ser desconocido: comprueba el alquiler con getRentStatus antes de reintentar. |
WRONG_ | continueRentNumber: el precio supera tu tope (la última cotización que se te mostró, válida 10 minutos, reducida por expectedCharge) o no tienes una cotización válida. No se extendió y no se cobró nada. La nueva cotización está en price; vuelve a intentarlo con ella. |
CONTINUE_ | continueRentNumber: no se puede extender durante los primeros 20 minutos del alquiler (la ventana de cancelación gratuita). No se cobró nada; inténtalo de nuevo después. getContinueRentPriceNumber sigue funcionando. |
ERROR_ | Error inesperado del servidor. |
API REST
Las mismas operaciones están disponibles para todas las claves de API como endpoints JSON en /api/v1/rentals (envía la clave en la cabecera x-api-key). El límite diario de alquileres por clave es compartido con las acciones anteriores; por encima, la API REST responde 429 con el motivo rent_daily_cap.
curl -X POST "https://smsbulk.net/api/v1/rentals" \
-H "x-api-key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ "serviceCode": "wa", "countryIso": "US", "durationHours": 24 }'Extensiones: primero pide una cotización con GET /api/v1/rentals/{id}/extend-price y luego llama a POST /api/v1/rentals/{id}/extend. El importe cobrado nunca supera la última cotización que se te mostró (válida 10 minutos, mismo alquiler y duración). El expectedCharge opcional (USD como texto, por ejemplo "1.334") solo puede bajar este tope, nunca subirlo. Si el precio supera el tope, o no tienes una cotización válida, el alquiler no se extiende, no se cobra nada y la API responde 409 PRICE_CHANGED con la nueva cotización en currentCharge. Vuelve a intentarlo con la nueva cotización.
Durante los primeros 20 minutos del alquiler (la ventana de cancelación gratuita), POST /api/v1/rentals/{id}/extend responde 409 RENTAL_EXTEND_TOO_EARLY; el cuerpo incluye extendAllowedFrom (hora ISO), el momento a partir del cual se acepta la extensión. No se cobra nada y las cotizaciones siguen disponibles.