# Plan de integración EnvíaTuSMS API v1 (compatibilidad)

Entrega este plan a tu asistente de programación junto con el contexto de tu proyecto. No pegues la API Key real ni información de clientes en el prompt. Para integraciones nuevas, prefiere v2: transmite la clave en una cabecera en lugar de la URL.

## Contrato

- Base URL: `https://www.enviatusms.com/api/v1`. La antigua URL `https://www.enviatusms.com/api` sigue funcionando con las mismas operaciones y respuestas.
- Añade `api_key=<API_KEY>` como parámetro de la URL en cada solicitud. Conserva la clave en un gestor de secretos o variable de entorno, codifica el parámetro y evita registrar URLs completas. Usa HTTPS. La clave puede regenerarse o restringirse por IP desde las opciones de la cuenta.
- GET `/balance`: `status`, `sms` (por operadora), `balance` (USD).
- POST `/sms-multi`: JSON `{"numeros":["04241234567"],"texto":"Hola"}`. `texto` admite una lista con un mensaje por número; `permitir_duplicados` es opcional.
- POST `/sms-costo`: mismo JSON, solo cotiza el costo.
- GET `/campaign/{submission_id}`: consulta campaña propia.
- POST `/acortar-url`: JSON `{"link":"https://example.com"}`.
- PUT `/modificar-url-acortado`: JSON `{"id":"XYZ","link":"https://example.com/nuevo"}`.
- POST/PUT requiere `Content-Type: application/json` cuando se envía JSON. Para detalles de campos y respuestas, consulta `/desarrolladores`. Los errores de negocio pueden responder con HTTP 200: comprueba `status == "ok"` o `success == true` (enlaces) además del código HTTP.

## Pasos

1. Examina el cliente HTTP y las convenciones del proyecto. Introduce una configuración para base URL y API Key sin fijarlas en código.
2. Implementa un cliente que codifique `api_key` como query param, verifique TLS, aplique timeout y analice la respuesta JSON. Oculta la URL completa de logs y trazas para que no se filtre la clave.
3. Implementa los métodos necesarios, valida los datos antes de enviar y propaga explícitamente errores HTTP y de negocio. No reintentes automáticamente el envío de SMS.
4. Añade pruebas de petición con clave válida/inválida, errores de red y negocio, y de ausencia de claves en logs. Verifica balance y cotización antes de enviar mensajes reales.
5. Si migras a v2, cambia la base URL a `/api/v2`, elimina el parámetro de URL e incorpora `Authorization: Bearer <API_KEY>` en todas las peticiones; las respuestas no cambian.

```sh
curl "https://www.enviatusms.com/api/v1/balance?api_key=MI_API_KEY"
```