# Plan de Documentación Técnica

---

## 1. Objetivo de la documentación

Producir una **guía técnica de referencia completa** sobre **Evolution API** —plataforma de integración con WhatsApp— que detalle **todas las capacidades disponibles a junio de 2026**. El documento servirá como la base de conocimiento única para un desarrollador que desea construir un **cliente WhatsApp Lite personal** explotando al máximo la API: envío/recepción de mensajes multimedia, gestión de contactos, acceso a historiales, visualización de estados, y manejo del ciclo de vida completo de una conversación.

---

## 2. Audiencia y nivel técnico

| Perfil | Descripción |
|---|---|
| **Primario** | Desarrolladores full-stack / backend con experiencia intermedia en APIs RESTful, autenticación por token, y WebSockets. |
| **Secundario** | DevOps / Ingenieros de plataforma que despliegan y mantienen la instancia Evolution API. |

**Prerrequisitos esperados del lector:**
- Conocimiento funcional de HTTP, REST, JSON.
- Familiaridad con APIs de mensajería (WhatsApp Business API, Meta Graph API, o similares).
- Manejo básico de WebSockets para eventos en tiempo real.
- Nociones de OAuth2 / JWT / API Keys.
- Lectura de especificaciones OpenAPI/Swagger.

---

## 3. Alcance y versiones

| Dimensión | Definición |
|---|---|
| **Versión documentada** | Evolution API v2.x (rama estable a junio 2026). Se asume la versión más reciente del `main` release channel. |
| **Proveedor de WhatsApp** | Se documentan los dos backends principales soportados por Evolution API: **WhatsApp Web multidispositivo (Baileys-based)** y **WhatsApp Cloud API (Meta Graph API)**. Se indicarán diferencias donde aplique. |
| **Cubierto** | Envío/recepción de texto, multimedia, stickers, documentos, ubicación, contactos, mensajes efímeros, reacciones, estados/stories, gestión de chats/grupos, webhooks de eventos, lectura/entrega, perfiles de contacto, catálogos, flows, etc. |
| **Fuera de alcance** | Personalización del motor interno de Evolution API, administración multi-tenant avanzada, facturación, deployment en Kubernetes (solo se menciona lo esencial), integraciones con CRMs de terceros. |

---

## 4. Estructura del documento

| # | Sección | Propósito |
|---|---|---|
| 1 | **Introducción a Evolution API** | Contexto, qué es, arquitectura de alto nivel (Mermaid), diferencia entre backend Baileys y Cloud API. |
| 2 | **Instalación y despliegue rápido** | Requisitos mínimos, Docker, variables de entorno esenciales, verificación de salud. |
| 3 | **Autenticación y gestión de instancias** | Crear instancia, conectar QR, API Key, JWT, refresco de sesión, logout, desconexión. |
| 4 | **Gestión de mensajes — Envío** | Enviar texto, multimedia (imagen, video, audio, documento), stickers, ubicación, contactos, botones, listas, templates, catálogos, flows, encuestas. Referencia de endpoints con ejemplos cURL/JS. |
| 5 | **Gestión de mensajes — Recepción** | Webhooks de mensajes entrantes, polling, WebSocket events, formato de payload, deserialización por tipo. |
| 6 | **Historial de conversaciones (chats)** | Cargar lista de chats, historial por chat con paginación, mensajes de un contacto específico, filtros por fecha/tipo. |
| 7 | **Estados de mensaje (sent/delivered/read/played)** | Cómo se representan, webhooks asociados, consulta de estado individual, diferencias entre backends. |
| 8 | **Contactos** | Obtener todos los contactos, buscar, sincronizar, modificar, bloquear/desbloquear, obtener foto de perfil, última conexión y presencia. |
| 9 | **Estados / Stories de WhatsApp** | Obtener estados de contactos, publicar estado (imagen/video/texto), eliminar estado propio, webhook de nuevos estados. Limitaciones del backend Cloud API. |
| 10 | **Grupos y comunidades** | Crear, modificar, abandonar, añadir/quitar participantes, cambiar ícono, mención de todos, comunidades (anuncios). |
| 11 | **Webhooks y eventos en tiempo real** | Configuración de webhooks, tipos de eventos, reintentos, firma/verificación, eventos de presencia/estado/conexión. |
| 12 | **Multimedia: carga, descarga y límites** | Subir archivos para envío, descargar multimedia recibida, tipos MIME soportados, límites de tamaño, stickers animados (WebP), notas de voz (ogg/opus). |
| 13 | **Limitaciones, cuotas y buenas prácticas** | Rate limiting, número máximo de instancias, concurrencia, mensajes por segundo, políticas de Meta, recomendaciones anti-ban. |
| 14 | **Apéndice: Comparativa Baileys vs Cloud API** | Tabla de funcionalidades: qué endpoint funciona en cada backend, qué está bloqueado o restringido. |
| 15 | **Apéndice: Referencia rápida de endpoints** | Tabla resumen HTTP method + path + descripción breve. |

---

## 5. Aspectos técnicos a investigar

Se requiere **búsqueda activa en internet + verificación** de los siguientes puntos:

| Tema | Fuente probable | Duda específica |
|---|---|---|
| Endpoints de historial por chat | Evolution API docs / GitHub | ¿Existe `GET /chat/messages/{jid}`? ¿Soporta paginación? ¿Hasta cuántos mensajes? |
| Estados/Stories | Evolution API docs | ¿Endpoints exactos para obtener y publicar estados? ¿Formato de payload? ¿Disponible en Cloud API o solo Baileys? |
| Stickers | Evolution API + librería Baileys | ¿Se envían como `sticker` type o como `image` con conversión? ¿Se requiere pre-convertir a WebP? |
| Estado de mensajes individual | Evolution API webhooks | ¿Eventos `MESSAGES_UPDATE`, `MESSAGES_UPSERT`? ¿Formato JSON del estado? |
| Contactos — sincronización completa | Evolution API docs | ¿Endpoint `GET /contacts`? ¿Campos que retorna (pushname, verifiedName, isBusiness, etc.)? |
| Límites de subida multimedia | Evolution API docs + Meta docs | ¿Tamaños permitidos? ¿Formato multipart/form-data o base64? |
| WebSocket vs Webhook | Evolution API docs | ¿Evolution API ofrece WebSocket nativo para recibir mensajes? ¿O solo webhooks HTTP? |
| Encriptación y seguridad de sesiones | Evolution API GitHub | ¿Dónde se almacenan credenciales y claves de sesión? |
| Versionado a junio 2026 | Roadmap / GitHub Releases | ¿Qué versión exacta está activa? ¿Endpoints deprecated recientemente? |
| Flows y catálogos (WhatsApp Business) | Meta Graph API docs | ¿Disponibles solo en Cloud API? ¿Formato del payload? |

---

## 6. Convenciones

| Elemento | Convención |
|---|---|
| **Idioma** | Español (neutro, técnico). |
| **Formato de código** | Bloques con triple backtick + lenguaje (` ```json`, ` ```bash`, ` ```javascript`). |
| **Ejemplos cURL** | En sección independiente. Incluir `--location`, `--header` y cuerpo JSON indentado. |
| **URLs base** | Usar placeholder `{{BASE_URL}}` y `{{INSTANCE_ID}}`. |
| **Notas / Advertencias** | Usar `> ⚠️` para advertencias y `> ℹ️` para notas informativas. |
| **Endpoints** | Siempre en formato `METHOD /ruta/{param}`. |
| **Diagramas** | Mermaid: arquitectura general, flujo de mensaje entrante/saliente, ciclo de conexión de instancia. |
| **Tablas** | Para endpoints, campos de payload, y comparativas. |
| **Headers de sección** | Nivel 2 (`##`) para secciones principales. Nivel 3 (`###`) para subsecciones. |

---

## 7. Entregable esperado

Un documento Markdown único, autocontenido, de aproximadamente **25–35 páginas impresas equivalentes** (~12,000–18,000 palabras), que incluya:

- **15 secciones** según la estructura definida arriba.
- **Mínimo 4 diagramas Mermaid** (arquitectura general, flujo de envío, flujo de recepción vía webhook, ciclo de vida de instancia).
- **Al menos 25 ejemplos de código** funcionales (cURL + JavaScript/Node.js).
- **3 tablas comparativas** (Baileys vs Cloud API, tipos de mensaje soportados, límites y cuotas).
- **Referencia completa de endpoints** en apéndice.
- Índice de contenidos al inicio con enlaces internos.

---

¿Procedo a la fase de **investigación y redacción** del documento completo?