# API de SMS para Verificación

La **API de SMS Falcon** permite que tu código compre un número, lea el código de verificación y cancele o cierre el pedido con **REST y JSON**, sin nada más. Usa los mismos precios, el mismo saldo y los mismos **reembolsos automáticos** que el sitio, con una **entrega del 90% al 98% en todos los servicios**.

- **REST + JSON** una clave de API por cuenta
- **desde US$0.01** los mismos precios del sitio
- **Reembolso automático** si no llega el código

## Empieza a integrar en cuatro pasos

1. **Crea tu cuenta y recarga saldo.** Con tarjeta o cripto, desde US$5.
2. **Genera tu clave de API.** Tras tu primera recarga confirmada, abre la sección API en tu panel y crea la clave. Guárdala en secreto.
3. **Envíala en cada solicitud.** Pon la clave en el encabezado **X-Api-Key** (o en Authorization: Bearer). La URL base es https://smsfalcon.com/api/v1.
4. **Compra un número y consulta el código.** Crea un pedido y vuelve a leerlo hasta que el SMS aparezca en sus mensajes.

## Endpoints de la API

Todas las rutas son relativas a **https://smsfalcon.com/api/v1**.

| Método y ruta | Qué hace |
|---|---|
| GET /balance | Tu saldo en dólares y el importe reservado en pedidos abiertos |
| GET /services | Todas las apps para las que puedes comprar un número, con su precio inicial |
| GET /services/{product}/countries | Los países y precios de una app |
| POST /orders | Compra un número: envía product y, si quieres, country |
| GET /orders | Tus pedidos recientes |
| GET /orders/{id} | Un pedido, con los mensajes SMS que recibió |
| POST /orders/{id}/resend | Pide otro SMS en el mismo número activo, sin costo extra |
| POST /orders/{id}/finish | Cierra un pedido cuando ya usaste el código |
| POST /orders/{id}/cancel | Cancela antes de que llegue un código; el importe reservado vuelve a tu saldo |
| POST /orders/{id}/ban | Devuelve un número que la app rechazó; se reembolsa si no llegó ningún código |

## Ejemplo de solicitud y respuesta

Compra de un número de WhatsApp del Reino Unido y lectura del código. Los valores de los campos son de ejemplo.

| Paso | Lo que envías o recibes |
|---|---|
| Solicitud | POST https://smsfalcon.com/api/v1/orders con el encabezado X-Api-Key y el cuerpo {"product": "whatsapp", "country": "gb"} |
| Respuesta | 201 con el pedido: id, phone, product, country, price, status, expires y una lista messages vacía |
| Consulta | GET https://smsfalcon.com/api/v1/orders/{id} cada pocos segundos |
| Llega el código | messages trae sender, text, code y received_at; después llama a finish |
| No llega el código | Cuando el número vence, el precio reservado vuelve solo a tu saldo |

## Códigos de estado que vas a ver

| Código | Significado | Qué hacer |
|---|---|---|
| 201 | Pedido creado | Consulta el pedido hasta ver sus mensajes |
| 401 | Falta la clave de API o no es válida | Revisa el encabezado X-Api-Key |
| 402 | Saldo insuficiente | Recarga y vuelve a intentar |
| 404 | App o pedido desconocido | Revisa el nombre de product en /services |
| 409 | No hay número para esa app y ese país en este momento | Prueba con otro país |
| 429 | Demasiadas solicitudes (más de 500 compras por minuto) | Baja el ritmo y reintenta |

## Cómo se cobra por la API

- **Reservado y cobrado al recibir.** Al comprar, el precio queda reservado en tu saldo. Solo se cobra cuando llega un SMS.
- **Reembolsos automáticos.** Si el número vence sin código, o cancelas antes de que llegue, el importe reservado vuelve.
- **Otro SMS sin costo.** Mientras el número siga activo, /resend pide un código nuevo en él.
- **Los mismos precios del sitio.** Desde US$0.01; WhatsApp desde US$0.32.

## Lo que conviene saber antes de integrar

- Una clave de API por cuenta. Puedes revocarla y crear otra desde tu panel.
- El código se lee consultando el pedido. No hay notificaciones push hacia tu servidor.
- Hasta 500 compras por minuto por cuenta.
- Los números reciben solo SMS, no llamadas.
- Usa la API para tus propias apps, QA y pruebas, dentro de los [términos](https://smsfalcon.com/es/terminos).

## La API de SMS Falcon en una tabla

| | |
|---|---|
| URL base | https://smsfalcon.com/api/v1 |
| Autenticación | Encabezado X-Api-Key, una clave por cuenta |
| Cobertura | 265 apps en 156+ países |
| Entrega | 90% al 98% en todos los servicios |
| Si el código no llega | Reembolso automático a tu saldo |
| Pago | Tarjeta o cripto desde US$5 |

## Páginas relacionadas

- [Cómo funciona una activación](https://smsfalcon.com/es/activacion-sms) (reservada, cobrada o reembolsada)
- [Precios en CSV o JSON](https://smsfalcon.com/es/datos) (para tus propias herramientas)
- [Conserva un número más tiempo](https://smsfalcon.com/es/alquiler-de-numero) (alquileres)

## Preguntas frecuentes sobre la API de SMS

### ¿Qué es la API de SMS Falcon?

Una API REST que permite que tu código compre números virtuales y lea los códigos de verificación por SMS que reciben, con los mismos precios y reembolsos que el sitio.

### ¿Cómo consigo una clave de API?

Recarga tu cuenta una vez y crea la clave en la sección API de tu panel.

### ¿Cuánto cuesta usar la API?

No hay tarifa por la API. Pagas el mismo precio por número que en el sitio, desde US$0.01.

### ¿Cómo obtengo el código?

Lee el pedido con GET /orders/{id} hasta que su lista messages tenga el SMS. El código está en el campo code.

### ¿Qué pasa si no llega ningún código?

El precio reservado vuelve solo a tu saldo cuando el número vence. Si cancelas antes de que llegue un código, también vuelve.

### ¿Puedo pedir otro código en el mismo número?

Sí, con POST /orders/{id}/resend mientras el número siga activo, sin costo extra.

### ¿Hay un límite de solicitudes?

Sí: hasta 500 compras por minuto por cuenta. Si recibes un 429, baja el ritmo.

### ¿Puedo elegir el país?

Sí. Envía el país como código ISO, por ejemplo gb, o no lo envíes para usar el predeterminado.

### ¿Los números pueden recibir llamadas?

No. Solo reciben mensajes de texto.

### ¿Para qué puedo usar la API?

Para tus propias apps, QA y pruebas, dentro de nuestros términos. No sirve para saltarse los controles ni las reglas de ninguna app.

### ¿Cómo veo la lista de apps y precios desde la API?

GET /services devuelve cada app con su precio inicial, y GET /services/{product}/countries muestra los países y precios de una app.

Fuente: https://smsfalcon.com/es/api-de-sms · Actualizado el 2026-11-05