¿Necesitas un número de teléfono para recibir un código de verificación por SMS y quieres hacerlo desde código en lugar de navegar por una web? Este tutorial muestra cómo usar la API REST de 2FASMS para consultar tu saldo, listar los servicios disponibles, comprar un número virtual y leer el código SMS.

Todas las peticiones usan curl, así que puedes seguirlo desde cualquier terminal. Al final hay una colección de Postman lista para usar.

Requisitos previos

  • Una cuenta de 2FASMS
  • Tu clave de API, que aparece en los ajustes de tu cuenta

Guarda la clave en una variable de entorno para no pegarla en los comandos ni subirla por error a un repositorio:

export API_KEY="YOUR_API_KEY"

La URL base de todas las peticiones es https://api.2fasms.com. Los endpoints autenticados esperan tu clave en la cabecera Authorization como token Bearer.

Paso 1: Consultar tu saldo 

curl -H "Authorization: Bearer $API_KEY" \ "https://api.2fasms.com/order/api/get_balance"

Respuesta:

{ "balance": 25.50, "user_id": 123 }

Si falta la clave obtienes un 400, y si la clave no es válida, un 401.

Paso 2: Listar los servicios disponibles

Este endpoint no requiere autenticación. Añade el slug de un país para ver los servicios de ese país:

curl "https://api.2fasms.com/order/api/services?country=france"

Respuesta (abreviada):

{ "country": "france", "services": [ { "name": "whatsapp", "providers": ["provider_5", "provider_7", "provider_9"], "min_price": 15.20, "max_price": 33.50 } ], "total": 89, "from_cache": true }

El campo name es el slug del servicio que usarás en el siguiente paso. Para ver la lista de países y sus slugs, llama a GET /order/api/countries.

Paso 3: Comprar un número

Envía un POST con los slugs del país y del servicio:

curl -X POST \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"country":"france","service":"whatsapp"}' \ "https://api.2fasms.com/order/api/get_number"

Respuesta:

{ "orderId": 12345, "number": "+33123456789", "status": "ok" }

Guarda el orderId: lo necesitas para leer el SMS. Usa el number en la aplicación o web donde quieres recibir el código.

Posibles errores: 400 por parámetros inválidos, 406 por saldo insuficiente y 500 si el servicio o el país no están disponibles.

Paso 4: Leer el código SMS

Cuando hayas solicitado el código en el servicio de destino, consulta el pedido:

curl -X POST \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"orderId":12345}' \ "https://api.2fasms.com/order/api/check_order"

Cuando llega el SMS, la respuesta contiene el código:

{ "status": "success", "data": [{ "orderId": 12345, "sms": "123456" }] }

Este pequeño bucle de shell consulta cada 5 segundos durante 2 minutos como máximo:

for i in $(seq 1 24); do curl -s -X POST \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"orderId":12345}' \ "https://api.2fasms.com/order/api/check_order" echo sleep 5 done

Obtienes un 404 si el pedido no existe y un 400 si falta orderId.

Webhook en lugar de consultar cada pocos segundos

Puedes registrar un endpoint HTTPS y 2FASMS enviará con POST cada SMS recibido:

curl -X POST \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://your-app.com/sms-hook"}' \ "https://api.2fasms.com/user/webhook"

El contenido incluye el ID del pedido, el servicio, el país, el texto completo del SMS, el code extraído, el número y la hora de recepción. Las entregas fallidas (respuestas que no son 2xx) se reintentan hasta 3 veces. Envía una url vacía para desactivar el webhook.

Paso 5: Finalizar el pedido

Cuando termines, cierra el pedido:

curl -X POST \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"orderId":12345}' \ "https://api.2fasms.com/order/api/finish_order" 
{ "message": "order has been finished" }

Un 406 significa que el pedido ya estaba cancelado o caducado, o que el SMS sigue pendiente.

Pruébalo en Postman

He reunido las cuatro peticiones principales (saldo, servicios, compra de número y lectura del SMS) en una colección pública de Postman. La clave es una variable {{api_key}}: solo tienes que poner la tuya.

https://documenter.getpostman.com/view/59423970/2sBYHXRJZs

Para terminar

Este es el flujo completo: saldo, servicios, número, código. A partir de aquí puedes integrarlo en tu suite de pruebas, en la automatización de registros de tu entorno de staging o en cualquier flujo que necesite un número temporal.

Puedes crear una cuenta y obtener tu clave de API aquí: https://2fasms.com/?ref=dev-tuto

Divulgación: trabajo en el equipo de 2FASMS.