- Inicio
- API
API de verificación por SMS
Compra números y lee códigos desde tu propio software. La API usa tu saldo, los mismos precios y la misma regla de reembolso de 20 minutos que el sitio web.
La clave de API se crea dentro de tu cuenta. Los números comprados por la API salen del mismo saldo y cuestan lo mismo que en el sitio web.
Datos clave
- Precio más bajo por número
- $0.0018
- Autenticación
- Clave de API
- Formato
- JSON sobre HTTPS
- Límite de solicitudes
- 120 solicitudes por minuto
- Reembolso
- Igual que en el sitio web
REST y JSON
Seis solicitudes cubren saldo, servicios, precios, obtener un número, estado y cancelación.
Una clave de tu cuenta
Crea una clave en la página Clave de API de tu cuenta y envíala en el encabezado Authorization.
Mismos precios que el sitio
Los precios de los números y la regla de reembolso de 20 minutos son los mismos que en la web.
¿Qué solicitudes puedo enviar?
Las rutas van después de la URL base. Cada solicitud necesita tu clave de API.
| Método y ruta | Qué hace |
|---|---|
GET/ | Tu saldo en USD |
GET/ | Todos los servicios con el precio más bajo y la cantidad de países |
GET/ | El precio de un número en cada país para un servicio |
POST/ | Obtiene un número para un servicio y un país; el precio se descuenta de tu saldo |
GET/ | Estado de un número y todos los códigos recibidos hasta ahora |
POST/ | Cancela antes de que llegue un código; el precio vuelve a tu saldo |
¿En qué orden llamo a la API?
- 1
Obtén un número POST /numbers con service y country. Guarda el id y el número.
- 2
Ingresa el número Escribe el número en el servicio que envía el código.
- 3
Consulta el código GET /numbers/{id} cada 5 segundos hasta que la lista codes no esté vacía.
- 4
Termina Usa el código. Si ya no necesitas el número antes de que llegue un código, cancélalo.
¿Cómo obtengo una clave de API?
Inicia sesión y abre Clave de API en tu cuenta. Crea una clave y cópiala enseguida; solo se muestra una vez. Al crear una clave nueva, la anterior deja de funcionar.
Clave de API¿Cuál es la URL base?
Envía cada solicitud a esta dirección con la clave en el encabezado Authorization (Bearer) o en el encabezado X-Api-Key:
https://tomnumber.com/api/v1Authorization: Bearer <API_KEY>Campos de la solicitud
| Campo | Se usa en | Valor |
|---|---|---|
service | POST /numbers, GET /prices | Nombre del servicio según /services, p. ej. telegram |
country | POST /numbers | Código de país de dos letras, p. ej. gb |
Campos de respuesta y estados
| Valor | Significado |
|---|---|
waiting | El número está activo y todavía no llegó ningún código |
received | Llegó al menos un código; pueden llegar más hasta expires_at |
refunded | Sin código en 20 minutos; el precio volvió a tu saldo |
canceled | Cancelaste antes de que llegara un código; el precio volvió a tu saldo |
Ejemplo de respuesta
{ "ok": true, "id": "R8KQ2M7XWD4P", "service": "telegram", "country": "gb", "number": "+44 7700 900412", "price": "0.167", "status": "received", "expires_at": "2026-11-11T09:20:00.000Z", "codes": [ { "code": "483920", "text": "Telegram code: 483920", "received_at": "2026-11-11T09:01:12.000Z" } ]}Códigos de error
unauthorized | Falta la clave de API o es incorrecta |
rate_limited | Más de 120 solicitudes en un minuto |
bad_service | Nombre de servicio desconocido |
bad_country | País no disponible para ese servicio |
low_balance | El saldo es menor que el precio |
unavailable | No hay números disponibles ahora. No se cobró nada |
not_found | No hay ningún número con ese id en tu cuenta |
cannot_cancel | Ya llegó un código o el número está cerrado |
Ejemplos de código
# get a numbercurl -X POST https://tomnumber.com/api/v1/numbers \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"service":"telegram","country":"gb"}' # check for codescurl https://tomnumber.com/api/v1/numbers/R8KQ2M7XWD4P \ -H "Authorization: Bearer $API_KEY"const api = (path, init = {}) => fetch("https://tomnumber.com/api/v1" + path, { ...init, headers: { Authorization: "Bearer " + process.env.API_KEY, "Content-Type": "application/json" }, }).then((r) => r.json()); const n = await api("/numbers", { method: "POST", body: JSON.stringify({ service: "telegram", country: "gb" }) });console.log(n.number); // enter this number in the app let codes = [];while (!codes.length) { await new Promise((r) => setTimeout(r, 5000)); const s = await api("/numbers/" + n.id); if (s.status === "refunded" || s.status === "canceled") break; codes = s.codes;}console.log(codes.map((c) => c.code));import os, time, requests API = "https://tomnumber.com/api/v1"H = {"Authorization": "Bearer " + os.environ["API_KEY"]} n = requests.post(API + "/numbers", json={"service": "telegram", "country": "gb"}, headers=H).json()print(n["number"]) # enter this number in the app while True: time.sleep(5) s = requests.get(API + "/numbers/" + n["id"], headers=H).json() if s["codes"] or s["status"] in ("refunded", "canceled"): breakprint([c["code"] for c in s["codes"]])Preguntas frecuentes sobre la API de verificación por SMS
¿Qué es una API de verificación por SMS?
Una forma de comprar números y leer códigos desde tu propio programa en lugar del sitio web.
¿La API tiene un costo adicional?
No. Los números cuestan lo mismo que en el sitio web y se pagan con el mismo saldo.
¿Cuántas solicitudes puedo enviar?
Hasta 120 solicitudes por minuto por clave. Consultar cada 5 segundos queda muy por debajo de ese límite.
¿También se reembolsan los números de la API?
Sí, con la misma regla: si no llega código en 20 minutos, el precio vuelve a tu saldo.
¿Dónde creo la clave?
En tu cuenta, en Clave de API.