¿Cómo consigo un token?

Crea una cuenta y genera uno en el panel, en el apartado de acceso a la API. Allí se muestra completo y se puede rotar cuando lo necesites.

¿Llamar a la API cuesta algo?

Las peticiones son gratuitas; los números no. Se te cobra por un número cuando `request-number` emite uno, al mismo precio por verificación que un pedido hecho desde el panel.

¿Hay un entorno de pruebas?

No hay un entorno separado. Hay uno solo, y un número pedido es un número real con un cargo real, que es también lo que hace que merezca la pena probar contra esta API.

¿Con qué frecuencia debo consultar el código?

`get-number-details` es una búsqueda indexada sin llamadas externas, así que unos pocos segundos entre consultas es razonable. Para cuando `pin` tenga valor o cuando el pedido pase su caducidad, y libera todo lo que no recibió nada.

¿Pueden avisarme en lugar de consultar?

Sí. Los webhooks se configuran por cuenta desde el panel y se disparan en los eventos de pedido, de modo que una integración de larga duración no tiene que quedarse en un bucle.

API de Verificación SMS para Desarrolladores

Tres llamadas cubren el flujo entero: pedir un número, consultar hasta que llega el código y liberarlo si no llega. Token de portador, JSON de entrada y salida, y todo lo que se puede hacer en el panel está disponible por la misma API.

Desde: $0.01por código
Servicios: 740

Conseguir un número Ver todos los precios

Pagas por verificación. Si cancelas un pedido que no recibió ningún mensaje, el importe vuelve a tu saldo.

El flujo, en llamadas

GET /api/v2/tn101/get-services — el catálogo, con el identificador por el que vas a pedir y su precio actual.
POST /api/v2/tn101/request-number — pide uno. Acepta service_key, y opcionalmente state y prefijos. Responde con el identificador del pedido, el número y cuándo caduca.
GET /api/v2/tn101/get-number-details — consúltalo con order_id. pin es nulo hasta que llega el código y lo contiene después. Es la lectura más barata de la API y la que está pensada para llamarse en bucle.
POST /api/v2/tn101/reject-number — libera un número que no recibió nada. Es también lo que devuelve el importe.

En este camino no se te envía nada de forma proactiva, así que el paso 3 es una consulta repetida. Si prefieres que te avisen en lugar de preguntar, la cuenta también envía webhooks en los eventos de pedido, configurables desde el panel.

Autenticación

Cada petición lleva Authorization: Bearer <token>. Los tokens se generan en el panel, en el apartado de acceso a la API, y se pueden rotar allí en cualquier momento: rotar invalida el token anterior de inmediato, así que cámbialo primero en tu configuración.

Una petición sin token válido recibe 401. Una cuenta suspendida, o con el acceso a la API desactivado, recibe 403. Cuando la API está desactivada para todo el sitio, todos los endpoints responden 503 en lugar de fingir.

El envoltorio de la respuesta

Todos los endpoints responden con los mismos tres campos:

data lleva el contenido, success es el booleano sobre el que ramificar y summery es el mensaje legible. Esa grafía no es una errata de esta página: es el nombre de campo que la API lleva enviando desde siempre, está en todas las integraciones escritas contra ella, y renombrarlo las rompería todas por corregir una letra. Lee summery.

Los fallos de validación responden 422 con data como un objeto de nombres de campo a mensajes de error, de modo que quien llama puede informar de qué argumento estaba mal y no solo de que algo lo estaba.

Probar flujos de verificación

La API es una forma práctica de ejercitar un registro o una recuperación de contraseña contra una ruta real de operador en lugar de contra un simulador: pides un número, rellenas tu propio formulario con él, consultas hasta que llega el código y compruebas qué hace después tu aplicación. Es una prueba más lenta que un doble de prueba y detecta lo que un doble no puede: la normalización, el filtrado por tipo de línea y los retrasos de entrega que tus usuarios van a sufrir de verdad.

Límites

No hay un límite de peticiones por segundo en la API, pero sí dos cuotas sobre los pedidos, y son las mismas que aplica el panel:

Pedidos abiertos. Una cuenta solo puede tener un número limitado de números reservados a la vez. Consulta y libera, en lugar de abrir muchos en paralelo.
Pedidos cancelados y caducados al día. Si superas la cantidad diaria permitida, los pedidos se pausan durante un tiempo, que se alarga si se repite. Cada reserva consume suministro real llegue o no un código, y eso es lo que protege la cuota.

Las dos se describen con más detalle en los números temporales, que es donde se explica cómo transcurre un pedido.

Un ejemplo completo

Pedir, consultar y liberar. Sustituye YOUR_API_TOKEN por un token del panel y cada uno de estos ejemplos funciona tal cual está pegado.

# 1. Pide un número.
curl -X POST https://smsportal.io/api/v2/tn101/request-number \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"service_key": "Google"}'

# 2. Consulta hasta que "pin" deje de ser nulo.
curl "https://smsportal.io/api/v2/tn101/get-number-details?order_id=12345" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# 3. ¿No llegó nada? Libéralo y recupera el importe.
curl -X POST https://smsportal.io/api/v2/tn101/reject-number \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"order_id": 12345}'

Qué devuelve el paso 2 cuando llega el código

Antes de que llegue, la misma llamada devuelve la misma estructura con pin y message a nulo.

{
  "data": {
    "order_id": 12345,
    "number": "12085551234",
    "service": "Google",
    "status": "Reserved",
    "state": "CA",
    "pin": "418902",
    "message": "418902 is your Google verification code.",
    "price": 0.35,
    "till_expiration": "2026-09-03T12:20:00.000Z"
  },
  "success": true,
  "summery": "Success"
}

Endpoints

Diez en total. Todos aceptan el mismo token de portador y responden con el mismo envoltorio.

GET/api/v2/profile
Perfil de la cuenta
GET/api/v2/account-details
Saldo del monedero
GET/api/v2/tn101/get-services
Lista de servicios S1
GET/api/v2/tn101/us-states
Estados de EE. UU.
POST/api/v2/tn101/request-number
Pedir un número
POST/api/v2/tn101/reuse-number
Reutilizar un número
GET/api/v2/tn101/get-number-details
Detalle del pedido
GET/api/v2/tn101/get-reserved-list
Números reservados
GET/api/v2/tn101/get-order-histories
Histórico de pedidos
POST/api/v2/tn101/reject-number
Cancelar y reembolsar

Crea una cuenta para generar un token: la referencia completa y tus claves están en el panel, en el apartado de acceso a la API.

Preguntas frecuentes

¿Cómo consigo un token?: Crea una cuenta y genera uno en el panel, en el apartado de acceso a la API. Allí se muestra completo y se puede rotar cuando lo necesites.
¿Llamar a la API cuesta algo?: Las peticiones son gratuitas; los números no. Se te cobra por un número cuando `request-number` emite uno, al mismo precio por verificación que un pedido hecho desde el panel.
¿Hay un entorno de pruebas?: No hay un entorno separado. Hay uno solo, y un número pedido es un número real con un cargo real, que es también lo que hace que merezca la pena probar contra esta API.
¿Con qué frecuencia debo consultar el código?: `get-number-details` es una búsqueda indexada sin llamadas externas, así que unos pocos segundos entre consultas es razonable. Para cuando `pin` tenga valor o cuando el pedido pase su caducidad, y libera todo lo que no recibió nada.
¿Pueden avisarme en lugar de consultar?: Sí. Los webhooks se configuran por cuenta desde el panel y se disparan en los eventos de pedido, de modo que una integración de larga duración no tiene que quedarse en un bucle.

Páginas relacionadas

¿Todo listo para recibir tu código?

Crear la cuenta lleva un minuto y solo pagas por los números que entregan el mensaje.

Crear una cuenta gratis