# Clave de API

La clave de API conecta tus scripts, bots o sistemas con SMS Nitro para comprar números y leer códigos sin pasar por el panel. Tiene el mismo poder de compra que tu cuenta, así que trátala como una contraseña.

## ¿Dónde encuentro la clave de API de SMS Nitro?

En la sección API del panel. Se habilita después de tu primera recarga confirmada: ahí generas la clave, que se muestra una sola vez, así que cópiala y guárdala en un lugar seguro. Cada cuenta tiene una clave activa; generar otra revoca la anterior al instante. Sirve para la API REST y para el endpoint compatible con SMS-Activate.

## Generar tu clave

1. **Haz tu primera recarga** El acceso a la API se desbloquea con el primer depósito confirmado, desde US$ 5.
2. **Abre la sección API del panel** Ahí ves si tienes una clave activa, su prefijo, la fecha de creación y el último uso.
3. **Genera la clave y cópiala** La clave completa aparece una sola vez. Guárdala en un gestor de contraseñas o en una variable de entorno de tu servidor.

## Dónde se usa la clave

- API REST: base https://smsnitro.com/api/v1, con la clave en el encabezado X-Api-Key o como Authorization: Bearer. Respuestas en JSON.
- Endpoint compatible con SMS-Activate: https://smsnitro.com/api/stubs/handler_api.php, con la clave en el parámetro api_key. Sirve para bots y programas que ya hablan ese protocolo.
- Las compras por API siguen las mismas reglas que el panel: el precio se retiene, solo se cobra si llega el código y, sin SMS, el importe vuelve a tu saldo.

## Respuestas que vas a ver en el endpoint compatible

- NO_KEY o BAD_KEY: falta la clave, está mal escrita o fue revocada al generar una nueva.
- NO_BALANCE: no tienes saldo suficiente para esa compra. Recarga y vuelve a intentar.
- NO_NUMBERS: esa llamada no devolvió número para la app y el país pedidos. Repite la llamada o prueba otro país; no se cobra nada.
- WRONG_COUNTRY o BAD_SERVICE: el país o la app no se ofrecen en ese servidor.
- STATUS_WAIT_CODE y STATUS_OK: todavía esperando el SMS, o SMS entregado con el código.
- BAD_STATUS: la acción no se permite en el estado actual, por ejemplo cancelar después de recibir el código.

## Límites de uso

Hay límites de peticiones por clave para proteger el servicio, entre ellos un máximo de 500 compras por minuto. Consultar el estado de un pedido cada pocos segundos es normal; consultar el catálogo en bucle no lo es. En algunos números la cancelación solo está disponible unos minutos después de la compra, y la API responde con un error claro si lo intentas antes.

## Buenas prácticas con tu clave

- No la compartas ni la publiques en repositorios, capturas de pantalla o chats. Quien tenga la clave puede gastar tu saldo.
- Guárdala en variables de entorno o en un gestor de secretos, nunca dentro del código de una app que se instala en celulares o navegadores.
- Rótala si sospechas una filtración o si alguien que la conocía deja tu equipo: genera una nueva en el panel y la anterior deja de funcionar en ese momento.
- Revisa la fecha de último uso en el panel. Si ves actividad que no reconoces, genera una clave nueva y abre un ticket.
- Cambiar la contraseña de la cuenta no cambia la clave de API: son independientes.

## FAQ

**¿Por qué no puedo generar una clave de API?** Porque el acceso a la API se habilita después del primer depósito confirmado. Recarga saldo y la opción para generar la clave aparecerá en la sección API del panel.

**Perdí mi clave de API, ¿pueden enviármela?** No. Solo guardamos una versión cifrada y la clave completa se muestra una vez. Genera una nueva en el panel: la anterior queda revocada al instante y debes actualizarla en tus sistemas.

**¿La API es compatible con SMS-Activate?** Sí. El endpoint handler_api.php habla el mismo protocolo, así que muchos bots y programas funcionan cambiando solo la URL y la clave. Para integraciones nuevas, la API REST en JSON es más cómoda.

**¿Puedo tener varias claves de API?** No. Cada cuenta tiene una clave activa. Generar una nueva revoca la anterior, lo que facilita rotarla sin dejar claves viejas funcionando.

Source: https://smsnitro.com/es/ayuda/clave-api