# Documentación de la API de SMS Nitro

Todo lo necesario para comprar un número temporal, leer el código de verificación y cerrar el pedido desde tu propio código. JSON sobre HTTPS, una clave de API, los mismos precios y la misma regla de cobro que el panel.

## ¿Cómo funciona la API de SMS Nitro?

Envías POST /v1/orders con la app y el país y recibes un número de teléfono. Luego consultas GET /v1/orders/{id} cada 3 a 5 segundos hasta que el SMS aparece en messages y llamas a finish. Si el SMS no llega, cancelas y el importe reservado vuelve a tu saldo: solo pagas los códigos que llegan.

## Inicio rápido en cuatro llamadas

1. **Genera la clave** Haz la primera recarga, abre Panel > API y genera tu clave. Envíala en la cabecera X-Api-Key.
2. **Compra un número** POST /v1/orders con product y country. El precio queda reservado en tu saldo.
3. **Lee el código** Consulta GET /v1/orders/{id} cada 3 a 5 segundos hasta que messages traiga el SMS.
4. **Cierra el pedido** POST finish si el código funcionó, o cancel si no llegó nada, para recuperar el importe.

## La API de un vistazo

| Elemento | Valor |
|---|---|
| URL base | https://smsnitro.com/api/v1 |
| Formato | JSON sobre HTTPS, UTF-8. Precios como cadena decimal (USD), fechas en ISO 8601 (UTC) |
| Autenticación | Cabecera X-Api-Key, o Authorization: Bearer |
| Cobro | Precio reservado al comprar, cobrado solo cuando llega el SMS, devuelto si no llega |
| Vigencia del número | Hasta 20 minutos por activación |
| Límites | 500 compras por minuto, 30 solicitudes de reenvío por minuto |
| Especificación | OpenAPI 3.1 en /developers/openapi.json |

## Tu primera petición

Comprueba que la clave funciona leyendo el saldo. Una respuesta 200 con balance y frozen significa que ya puedes comprar números. Frozen es el importe reservado por los pedidos que todavía esperan un SMS.

**Petición**

```bash
curl https://smsnitro.com/api/v1/balance \
  -H "X-Api-Key: $SMSNITRO_API_KEY"
```

**Respuesta**

```json
{
  "balance": "12.50",
  "frozen": "0.45",
  "currency": "USD"
}
```

## FAQ

**¿Hay un entorno de pruebas?** No. Las llamadas usan el catálogo real, pero no se cobra nada sin SMS, así que probar el flujo completo solo cuesta los códigos que recibes de verdad.

**¿Los precios de la API son distintos a los del panel?** No. La API usa el mismo catálogo, los mismos precios y el mismo saldo que la web, sin recargo.

**¿Dónde está la especificación OpenAPI?** El documento OpenAPI 3.1 de los endpoints públicos está en https://smsnitro.com/developers/openapi.json. Impórtalo en Postman, Insomnia o un generador de código.

**¿Cómo consigo una clave de API?** Crea la cuenta, haz la primera recarga y genera la clave en Panel > API. Cada cuenta tiene una clave activa.

## Artículos

- [Autenticación](https://smsnitro.com/es/desarrolladores/autenticacion): Cómo autenticarte en la API de SMS Nitro: dónde generar la clave, las cabeceras X-Api-Key y Bearer, cómo cambiarla y por qué nunca debe estar en el front-end.
- [Referencia de endpoints](https://smsnitro.com/es/desarrolladores/endpoints): Todos los endpoints de la API REST v1 de SMS Nitro: saldo, servicios, países, pedidos, finish, cancel, resend y ban, con parámetros, curl y respuestas JSON.
- [Ciclo del pedido y cobro](https://smsnitro.com/es/desarrolladores/ciclo-del-pedido): Qué significa cada estado de pedido en SMS Nitro, cuándo se cobra o se devuelve el saldo, cuánto dura el número y cuándo puedes terminar, cancelar o pedir otro SMS.
- [Errores y límites de uso](https://smsnitro.com/es/desarrolladores/errores): Los códigos HTTP que devuelve la API de SMS Nitro (400, 401, 402, 404, 409, 429, 502), qué significa cada uno, los límites de uso y una estrategia de reintentos.
- [Verificación por SMS en Python](https://smsnitro.com/es/desarrolladores/python): Recibe códigos de verificación por SMS en Python con la API de SMS Nitro y requests: compra el número, espera el código, termina o cancela. Script completo.
- [Verificación por SMS en Node.js](https://smsnitro.com/es/desarrolladores/nodejs): Recibe códigos de verificación por SMS en Node.js 18+ con fetch y la API de SMS Nitro: compra el número, espera el código, termina o cancela. Con tipos TypeScript.
- [Verificación por SMS en PHP](https://smsnitro.com/es/desarrolladores/php): Recibe códigos de verificación por SMS en PHP 8 con cURL y la API de SMS Nitro: compra el número, espera el código, termina o cancela. Script completo para copiar.

Fuente: https://smsnitro.com/es/desarrolladores