# Referencia de endpoints

Diez endpoints cubren todo el flujo: consultar el saldo, ver apps y países, comprar un número, leer el SMS y cerrar el pedido.

## ¿Qué endpoints tiene la API de SMS Nitro?

GET /v1/balance, GET /v1/services, GET /v1/services/{product}/countries, POST /v1/orders, GET /v1/orders, GET /v1/orders/{id} y POST /v1/orders/{id}/finish, /cancel, /resend y /ban. Todos están en https://smsnitro.com/api y requieren la cabecera X-Api-Key.

## Todos los endpoints

| Endpoint | Qué hace |
|---|---|
| GET /v1/balance | Saldo disponible e importe reservado por pedidos abiertos (USD) |
| GET /v1/services | Apps disponibles con su precio inicial. Opcionales: country, server (1 o 2), search |
| GET /v1/services/{product}/countries | Países de una app con precio, tasa de éxito y prefijo. Opcional: server |
| POST /v1/orders | Compra un número. Cuerpo: product (obligatorio), country, operator, server |
| GET /v1/orders | Tus pedidos, del más reciente al más antiguo. Opcionales: limit (1 a 100, por defecto 50), offset |
| GET /v1/orders/{id} | Un pedido sincronizado en tiempo real: aquí aparece el SMS |
| POST /v1/orders/{id}/finish | Cierra la activación después de usar el código |
| POST /v1/orders/{id}/cancel | Cancela antes de cualquier SMS y devuelve el importe reservado |
| POST /v1/orders/{id}/resend | Pide otro SMS en el mismo número, tras el primer código |
| POST /v1/orders/{id}/ban | Devuelve un número que la app dice que ya está en uso |

## Ver apps y países

Usa los endpoints de catálogo para elegir qué comprar. El valor de product (por ejemplo telegram) es el identificador que envías al comprar. En la lista de países, rate3 y rate24 son las tasas recientes de entrega en porcentaje, y offers muestra el precio de cada servidor.

**Apps disponibles en un país**

```bash
curl "https://smsnitro.com/api/v1/services?country=usa" \
  -H "X-Api-Key: $SMSNITRO_API_KEY"
```

**Respuesta**

```json
[
  { "product": "telegram", "price": "0.30", "count": 850,
    "rate": null, "countries": [], "countries_count": 120 }
]
```

**Países de una app**

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

**Respuesta**

```json
[
  {
    "country": "usa", "name": "United States", "iso": "us", "dial_code": "+1",
    "price": "0.45", "count": 1200, "rate3": 95.0, "rate24": null, "server": 1,
    "offers": [
      { "server": 1, "price": "0.45", "count": 1200, "rate3": 95.0 },
      { "server": 2, "price": "0.52", "count": 300, "rate3": 88.0 }
    ]
  }
]
```

## Comprar un número

Envía product y country. El país acepta el identificador del catálogo (usa, england), el código ISO (gb) o el nombre en inglés, y por defecto es usa. Omite server para que la API elija el mejor. La respuesta es el pedido con estado PENDING y el número que debes introducir en la app.

| Campo | Descripción |
|---|---|
| product | Obligatorio. Identificador de la app en GET /v1/services |
| country | Opcional. Identificador del catálogo, ISO 3166-1 alfa-2 o nombre en inglés. Por defecto: usa |
| operator | Opcional. Operador, por defecto any |
| server | Opcional. 1 o 2. Sin él: automático |

**Petición**

```bash
curl -X POST https://smsnitro.com/api/v1/orders \
  -H "X-Api-Key: $SMSNITRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product": "telegram", "country": "usa"}'
```

**Respuesta (201 Created)**

```json
{
  "id": 123456,
  "provider_order_id": "987654321",
  "country": "usa",
  "operator": "any",
  "product": "telegram",
  "phone": "+12025550123",
  "status": "PENDING",
  "price": "0.45",
  "created_at": "2026-10-24T12:00:00Z",
  "expires": "2026-10-24T12:20:00Z",
  "messages": [],
  "awaiting_resend": false,
  "server": 1
}
```

## Leer el SMS

Consulta el pedido cada 3 a 5 segundos. Cuando llega el SMS, el estado pasa a RECEIVED y messages incluye el remitente, el texto completo y el código extraído. Usa code si viene relleno; si viene vacío, lee text.

**Petición**

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

**Respuesta tras el SMS**

```json
{
  "id": 123456,
  "phone": "+12025550123",
  "status": "RECEIVED",
  "price": "0.45",
  "expires": "2026-10-24T12:20:00Z",
  "messages": [
    {
      "sender": "Telegram",
      "text": "Telegram code: 48291",
      "code": "48291",
      "received_at": "2026-10-24T12:01:10Z"
    }
  ],
  "awaiting_resend": false,
  "server": 1
}
```

## Terminar, cancelar, reenviar o devolver

Cada acción devuelve el pedido actualizado. Las reglas de cuándo se permite cada una están en la página del ciclo del pedido.

**Acciones del pedido**

```bash
# Done: the code worked
curl -X POST https://smsnitro.com/api/v1/orders/123456/finish -H "X-Api-Key: $SMSNITRO_API_KEY"

# No SMS: cancel and get the frozen amount back
curl -X POST https://smsnitro.com/api/v1/orders/123456/cancel -H "X-Api-Key: $SMSNITRO_API_KEY"

# Another SMS on the same number (after the first code, no extra cost)
curl -X POST https://smsnitro.com/api/v1/orders/123456/resend -H "X-Api-Key: $SMSNITRO_API_KEY"

# The app says the number is already used: return it
curl -X POST https://smsnitro.com/api/v1/orders/123456/ban -H "X-Api-Key: $SMSNITRO_API_KEY"
```

## Listar tus pedidos

**Petición**

```bash
curl "https://smsnitro.com/api/v1/orders?limit=20&offset=0" \
  -H "X-Api-Key: $SMSNITRO_API_KEY"
```

## FAQ

**¿Hay un webhook cuando llega el SMS?** No. Consulta GET /v1/orders/{id} cada 3 a 5 segundos; el SMS aparece en cuanto llega.

**¿Qué es el campo server?** Los números vienen de dos servidores de suministro. El servidor 1 es el principal y el 2 el alternativo. Sin el campo, la API elige; indícalo para comparar precios o reintentar en el otro.

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