# Plan de integración EnvíaTuSMS API v2

Entrega este plan a tu asistente de programación junto con la arquitectura de tu proyecto. Implementa solo lo necesario en el lenguaje y framework existentes; no envíes credenciales ni datos de clientes al asistente.

## Contrato

- Base URL: `https://www.enviatusms.com/api/v2` (HTTPS obligatorio).
- En cada solicitud: `Authorization: Bearer <API_KEY>`. No incluyas `api_key` en URL, cuerpo ni logs. Obtén la clave en las opciones de la cuenta y consérvala en un gestor de secretos o variable de entorno. La misma clave se puede rotar y restringir por IP.
- GET usa parámetros en la ruta. POST/PUT usa JSON con `Content-Type: application/json`. Consulta la documentación de `/desarrolladores` para los campos y formatos completos.
- GET `/balance`: devuelve `status`, `sms` (por operadora) y `balance` (USD).
- POST `/sms-multi`: JSON `{"numeros":["04241234567"],"texto":"Hola"}`. `texto` también puede ser una lista del mismo tamaño que `numeros`; `permitir_duplicados` es opcional. Devuelve `status` y `campaign_id` en caso de éxito.
- POST `/sms-costo`: mismo JSON que `/sms-multi`; cotiza sin enviar.
- GET `/campaign/{submission_id}`: estado/detalles de una campaña del usuario.
- POST `/acortar-url`: JSON `{"link":"https://example.com"}`; PUT `/modificar-url-acortado`: JSON `{"id":"XYZ","link":"https://example.com/nuevo"}`. Estos endpoints responden con `success` y, ante error, `error`.
- Las respuestas de v2 mantienen la forma de v1: comprueba tanto el estado HTTP como `status == "ok"` o `success == true` según el endpoint. Algunas validaciones de v1 devuelven un error JSON con HTTP 200.

## Pasos

1. Identifica el cliente HTTP, la gestión de configuración y los tests ya presentes en el proyecto. No añadas un SDK ni dupliques clientes sin necesidad.
2. Configura base URL y clave como secretos de servidor. Exige que falte ninguna clave antes de realizar solicitudes; jamás la expongas al navegador ni la imprimas.
3. Implementa una función de solicitud reutilizable que adjunte la cabecera Bearer y JSON, aplique TLS verificado y timeout, analice JSON y propague errores HTTP y errores de negocio sin convertirlos en éxitos.
4. Crea métodos tipados para los endpoints que necesites. Valida números, longitud de texto y correspondencia entre listas antes de enviar. No reintentes automáticamente POST de envío SMS: podrías generar duplicados.
5. Prueba con claves inválidas y ausentes, IP no permitida, JSON inválido, errores de red y respuesta de negocio fallida. Comprueba que ninguna petición envíe la clave en query/body ni en logs. Prueba balance y cotización antes de un envío real autorizado.

Ejemplo mínimo:

```sh
curl -H "Authorization: Bearer MI_API_KEY" https://www.enviatusms.com/api/v2/balance
```