# 📖 Documentación de Integración - API WhatsApp Notificaciones

Bienvenido a la documentación de integración del servicio de notificaciones de WhatsApp. Este servicio permite el envío asíncrono y de alta velocidad de mensajes de WhatsApp desde cualquier aplicación externa (CRM, sistemas de facturación, e-commerce, bots, scripts, etc.).

---

## 🌐 Endpoint Principal

* **URL del Endpoint:** `https://notificaciones.systemsmx.com/api/v1/send-message`
* **Método HTTP:** `POST`
* **Formato de Contenido:** `application/json`

---

## 🔑 Autenticación

Todas las peticiones a la API requieren autenticación mediante un **API Token** generado desde la consola de administración.

Debes enviar el token en cada petición utilizando la cabecera HTTP `Authorization`:

```http
Authorization: Bearer wa_tu_api_token_aqui
```

*(También se admite la cabecera alternativa `X-API-Token: wa_tu_api_token_aqui`).*

---

## 📝 Estructura de la Petición

### Cuerpo del Payload (JSON)

| Campo | Tipo | Requerido | Descripción | Ejemplo |
| --- | --- | --- | --- | --- |
| `targetNumber` | `string` | **Sí** | Número de teléfono de destino con código de país, sin espacios, guiones ni el signo `+`. | `"5215512345678"` |
| `textBody` | `string` | **Sí** | El contenido del mensaje de texto a enviar. | `"Hola, tu pedido #1042 ha sido enviado."` |

#### Ejemplo de JSON:
```json
{
  "targetNumber": "5215512345678",
  "textBody": "Hola! Tu código de verificación es: 49201"
}
```

---

## 🔄 Respuestas de la API

### 1. `HTTP 202 Accepted` (Éxito)
El mensaje fue validado y encolado correctamente en Azure Storage Queue para su despacho inmediato.

```json
{
  "success": true,
  "message": "Mensaje encolado con éxito",
  "messageId": "ca00b96d-06f6-40df-9900-aff2f138087c",
  "insertedOn": "2026-08-03T17:22:44.306Z"
}
```

### 2. `HTTP 401 Unauthorized` (Error de Autenticación)
El token no fue proporcionado, es inválido o ha sido revocado.

```json
{
  "error": "Token de API inválido o revocado"
}
```

### 3. `HTTP 400 Bad Request` (Error en el Payload)
Faltan campos obligatorios en el objeto JSON.

```json
{
  "error": "Campos requeridos faltantes: 'targetNumber' y 'textBody'"
}
```

---

## 💻 Ejemplos de Código

### 1. cURL (Línea de comandos / Bash)

```bash
curl -X POST https://notificaciones.systemsmx.com/api/v1/send-message \
  -H "Authorization: Bearer wa_tu_api_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "targetNumber": "5215512345678",
    "textBody": "Hola! Mensaje de prueba desde la API."
  }'
```

---

### 2. JavaScript / Node.js (`fetch`)

```javascript
async function sendWhatsAppNotification(phoneNumber, messageText, apiToken) {
  const url = 'https://notificaciones.systemsmx.com/api/v1/send-message';
  
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      targetNumber: phoneNumber,
      textBody: messageText
    })
  });

  if (!response.ok) {
    const errorData = await response.json();
    throw new Error(`Error ${response.status}: ${errorData.error}`);
  }

  const result = await response.json();
  console.log('Mensaje encolado:', result.messageId);
  return result;
}

// Ejemplo de uso:
sendWhatsAppNotification('5215512345678', 'Tu cita fue programada.', 'wa_tu_api_token_aqui');
```

---

### 3. Python (`requests`)

```python
import requests

def send_whatsapp(target_number, text_body, api_token):
    url = "https://notificaciones.systemsmx.com/api/v1/send-message"
    headers = {
        "Authorization": f"Bearer {api_token}",
        "Content-Type": "application/json"
    }
    payload = {
        "targetNumber": target_number,
        "textBody": text_body
    }
    
    response = requests.post(url, json=payload, headers=headers)
    
    if response.status_code == 202:
        print("Mensaje enviado con éxito:", response.json())
    else:
        print(f"Error {response.status_code}:", response.json())

# Ejemplo de uso:
send_whatsapp("5215512345678", "Hola desde Python!", "wa_tu_api_token_aqui")
```

---

### 4. PHP (`cURL`)

```php
<?php

function sendWhatsApp($targetNumber, $textBody, $apiToken) {
    $url = "https://notificaciones.systemsmx.com/api/v1/send-message";
    
    $payload = json_encode([
        "targetNumber" => $targetNumber,
        "textBody" => $textBody
    ]);

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer " . $apiToken,
        "Content-Type: application/json"
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    return [
        "statusCode" => $httpCode,
        "response" => json_decode($response, true)
    ];
}

// Ejemplo de uso:
$result = sendWhatsApp("5215512345678", "Mensaje desde PHP", "wa_tu_api_token_aqui");
print_r($result);
?>
```

---

## ⚡ Notas y Buenas Prácticas

1. **Formato de Números (`targetNumber`):** Asegúrate de incluir la clave del país sin símbolos (ejemplo: `521` para celulares en México, `34` para España).
2. **Respuesta Rápida:** La API responde en menos de 100ms porque coloca el trabajo en una cola asíncrona de Azure.
3. **Persistencia:** Si tu servidor de WhatsApp está reiniciándose o reconectándose, la cola retendrá tus mensajes hasta 7 días sin que se pierdan.