API de alquiler de números

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.

Las acciones de alquiler están disponibles para todas las claves de API, con un límite diario por clave (consulta Límites).

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ónParámetrosQué hace
getRentServicesAndCountriescountry, rent_timeOfertas de alquiler con precio para un país y una duración. services.{code}.cost es el precio, quant es el stock disponible.
getRentNumberservice, country, rent_timeAlquila un número y cobra el saldo. Devuelve phone.id, phone.number y phone.endDate.
getRentStatusid, page, sizeSMS recibidos por el número alquilado, del más reciente al más antiguo. page (empieza en 0) y size opcionales.
setRentStatusid, 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.
continueRentNumberid, rent_time, expectedChargeExtiende un alquiler activo rent_time horas y cobra el saldo.
getRentList-Tus alquileres activos: id y phone.
getContinueRentPriceNumberid, rent_timePrecio 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_BALANCESaldo insuficiente.
NO_NUMBERSNo hay número disponible para este servicio, país y duración en este momento.
BAD_SERVICECódigo de servicio ausente o no admitido.
BAD_COUNTRYPaís ausente, desconocido o no disponible (usa el código ISO).
BAD_COUNTRY_USE_ISOID 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_TIMEDuración no ofrecida.
NO_ID_RENTFalta el parámetro id.
INVALID_PHONENo hay alquiler con este id en tu cuenta.
INCORECT_STATUSEl status de setRentStatus debe ser 1 o 2.
CANT_CANCELNo se puede cancelar ahora (durante los primeros 2 minutos o después de la ventana gratuita de hasta 20 minutos).
ALREADY_FINISHEl alquiler ya ha finalizado.
ALREADY_CANCELEl alquiler ya fue cancelado.
STATUS_WAIT_CODEEl alquiler está activo pero aún no ha llegado ningún SMS.
STATUS_CANCELEl alquiler fue cancelado.
STATUS_FINISHEl alquiler ha finalizado o expirado.
RENT_LIMITSe alcanzó el límite diario de alquileres de esta clave de API.
TEMPORARILY_UNAVAILABLEProblema 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_CHARGEcontinueRentNumber: 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_TOO_EARLYcontinueRentNumber: 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_SQLError 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.