# Guía de Configuración de API Keys

Esta guía detalla el proceso para obtener las credenciales necesarias para cada plataforma.

## Tabla de Contenidos

1. [X (Twitter) Developer](#x-twitter-developer)
2. [Meta Developer (Facebook, Instagram, Threads)](#meta-developer)
3. [DeepSeek API](#deepseek-api)
4. [Configuración en el Sistema](#configuración-en-el-sistema)

---

## X (Twitter) Developer

### Paso 1: Crear cuenta de desarrollador

1. Visita [developer.twitter.com](https://developer.twitter.com/)
2. Inicia sesión con tu cuenta de X/Twitter
3. Haz clic en "Sign up for Free Account" o "Apply for access"

### Paso 2: Crear un Proyecto y App

1. En el Dashboard, ve a **Projects & Apps** > **Overview**
2. Crea un nuevo proyecto:
   - Nombre: `Consultoria-AS-Social-Automation`
   - Caso de uso: `Making a bot` o `Building tools for Twitter users`
3. Dentro del proyecto, crea una App:
   - Nombre: `social-media-automation`

### Paso 3: Configurar permisos

1. En la configuración de la App, ve a **User authentication settings**
2. Configura:
   - **App permissions**: Read and Write
   - **Type of App**: Web App, Automated App or Bot
   - **Callback URL**: `https://tu-dominio.com/callback` (o `http://localhost:8000/callback` para desarrollo)
   - **Website URL**: `https://consultoria-as.com`

### Paso 4: Obtener credenciales

En la sección **Keys and Tokens**, genera y guarda:

| Credencial | Variable de Entorno |
|------------|---------------------|
| API Key | `TWITTER_API_KEY` |
| API Key Secret | `TWITTER_API_SECRET` |
| Access Token | `TWITTER_ACCESS_TOKEN` |
| Access Token Secret | `TWITTER_ACCESS_TOKEN_SECRET` |
| Bearer Token | `TWITTER_BEARER_TOKEN` |

> **Importante**: El plan gratuito permite 1,500 tweets/mes. Para más volumen, considera el plan Basic ($100/mes) con 3,000 tweets/mes.

---

## Meta Developer

Meta maneja Facebook, Instagram y Threads desde el mismo portal de desarrolladores.

### Paso 1: Crear cuenta de desarrollador

1. Visita [developers.facebook.com](https://developers.facebook.com/)
2. Inicia sesión con tu cuenta de Facebook
3. Acepta los términos de desarrollador

### Paso 2: Crear una App

1. Ve a **My Apps** > **Create App**
2. Selecciona tipo de app: **Business**
3. Configura:
   - Nombre: `Consultoria-AS-Social-Automation`
   - Contacto: tu email
   - Business Account: selecciona o crea una

### Paso 3: Agregar productos

En el dashboard de tu app, agrega estos productos:

#### Para Facebook Pages:
1. Añade el producto **Facebook Login for Business**
2. Añade **Pages API**
3. Configura los permisos:
   - `pages_manage_posts`
   - `pages_read_engagement`
   - `pages_show_list`

#### Para Instagram:
1. Añade el producto **Instagram Graph API**
2. Permisos necesarios:
   - `instagram_basic`
   - `instagram_content_publish`
   - `instagram_manage_comments`
   - `instagram_manage_insights`

#### Para Threads:
1. Añade el producto **Threads API**
2. Permisos necesarios:
   - `threads_basic`
   - `threads_content_publish`
   - `threads_manage_replies`

### Paso 4: Conectar cuentas

1. Ve a **Settings** > **Basic** para obtener:
   - App ID → `META_APP_ID`
   - App Secret → `META_APP_SECRET`

2. Para Facebook Page:
   - Ve a **Tools** > **Graph API Explorer**
   - Selecciona tu app y página
   - Genera un Page Access Token con los permisos necesarios
   - Convierte a Long-Lived Token (60 días)

3. Para Instagram:
   - La cuenta de Instagram debe estar conectada a una Facebook Page
   - Ve a Graph API Explorer
   - Obtén el Instagram Business Account ID
   - Genera Access Token con permisos de Instagram

### Paso 5: Obtener tokens de larga duración

```bash
# Convertir token de corta a larga duración (60 días)
curl -X GET "https://graph.facebook.com/v18.0/oauth/access_token?grant_type=fb_exchange_token&client_id={APP_ID}&client_secret={APP_SECRET}&fb_exchange_token={SHORT_LIVED_TOKEN}"
```

| Credencial | Variable de Entorno |
|------------|---------------------|
| App ID | `META_APP_ID` |
| App Secret | `META_APP_SECRET` |
| Page Access Token | `FACEBOOK_PAGE_ACCESS_TOKEN` |
| Page ID | `FACEBOOK_PAGE_ID` |
| Instagram User ID | `INSTAGRAM_USER_ID` |
| Threads User ID | `THREADS_USER_ID` |

> **Nota**: Los tokens de Meta expiran. Implementa un sistema de refresh o regenera manualmente cada 60 días.

---

## DeepSeek API

### Paso 1: Crear cuenta

1. Visita [platform.deepseek.com](https://platform.deepseek.com/)
2. Regístrate con email o Google
3. Verifica tu cuenta

### Paso 2: Obtener API Key

1. Ve a **API Keys** en el dashboard
2. Crea una nueva API Key
3. Copia y guarda la key (solo se muestra una vez)

### Paso 3: Agregar créditos

1. Ve a **Billing** > **Top Up**
2. Agrega créditos (mínimo $5 USD recomendado para empezar)
3. Los precios son muy económicos (~$0.14/1M tokens input, ~$0.28/1M tokens output)

| Credencial | Variable de Entorno |
|------------|---------------------|
| API Key | `DEEPSEEK_API_KEY` |
| Base URL | `https://api.deepseek.com` (ya configurado por defecto) |

---

## Configuración en el Sistema

### Archivo `.env`

Crea el archivo `.env` en la raíz del proyecto:

```env
# ==============================================
# BASE DE DATOS
# ==============================================
DATABASE_URL=postgresql://postgres:tu_password@localhost:5432/social_automation
REDIS_URL=redis://localhost:6379/0

# ==============================================
# SEGURIDAD
# ==============================================
SECRET_KEY=genera-una-clave-segura-de-32-caracteres-minimo
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# ==============================================
# X (TWITTER) API
# ==============================================
TWITTER_API_KEY=tu_api_key
TWITTER_API_SECRET=tu_api_secret
TWITTER_ACCESS_TOKEN=tu_access_token
TWITTER_ACCESS_TOKEN_SECRET=tu_access_token_secret
TWITTER_BEARER_TOKEN=tu_bearer_token

# ==============================================
# META APIs (Facebook, Instagram, Threads)
# ==============================================
META_APP_ID=tu_app_id
META_APP_SECRET=tu_app_secret

# Facebook
FACEBOOK_PAGE_ACCESS_TOKEN=tu_page_access_token
FACEBOOK_PAGE_ID=tu_page_id

# Instagram
INSTAGRAM_USER_ID=tu_instagram_user_id
INSTAGRAM_ACCESS_TOKEN=tu_instagram_access_token

# Threads
THREADS_USER_ID=tu_threads_user_id
THREADS_ACCESS_TOKEN=tu_threads_access_token

# ==============================================
# DEEPSEEK API (Generación de contenido)
# ==============================================
DEEPSEEK_API_KEY=tu_deepseek_api_key
DEEPSEEK_BASE_URL=https://api.deepseek.com

# ==============================================
# CONFIGURACIÓN DE NEGOCIO
# ==============================================
BUSINESS_NAME=Consultoría AS
BUSINESS_DESCRIPTION=Consultoría tecnológica y venta de equipos de cómputo e impresión 3D
BUSINESS_WEBSITE=https://consultoria-as.com
BUSINESS_LOCATION=Tijuana, México
```

### Generar SECRET_KEY

```bash
# Usando Python
python -c "import secrets; print(secrets.token_urlsafe(32))"

# Usando OpenSSL
openssl rand -base64 32
```

### Verificar configuración

Después de configurar el `.env`, verifica que todo esté correcto:

```bash
# Activar entorno virtual
source venv/bin/activate

# Verificar que las variables se cargan
python -c "from app.core.config import settings; print('DB:', settings.DATABASE_URL[:20] + '...'); print('DeepSeek:', 'OK' if settings.DEEPSEEK_API_KEY else 'NO CONFIGURADO')"
```

---

## Límites de API y Costos Estimados

### X (Twitter)

| Plan | Tweets/mes | Costo |
|------|-----------|-------|
| Free | 1,500 | $0 |
| Basic | 3,000 | $100/mes |
| Pro | 300,000 | $5,000/mes |

### Meta (Facebook/Instagram/Threads)

- Sin límite de publicaciones para cuentas propias
- Rate limits: ~200 llamadas/hora por usuario
- Costo: Gratuito

### DeepSeek

| Modelo | Input | Output |
|--------|-------|--------|
| deepseek-chat | $0.14/1M tokens | $0.28/1M tokens |
| deepseek-coder | $0.14/1M tokens | $0.28/1M tokens |

**Estimación mensual**: ~$5-10 USD para 300 posts/mes

---

## Solución de Problemas

### Error: "Invalid API Key" en X

1. Verifica que copiaste la key completa
2. Regenera las credenciales si es necesario
3. Asegúrate de que la app tiene permisos de escritura

### Error: "Token expired" en Meta

1. Los tokens de página expiran cada 60 días
2. Usa el Graph API Explorer para generar uno nuevo
3. Considera implementar refresh automático

### Error: "Insufficient balance" en DeepSeek

1. Agrega más créditos en el dashboard
2. Verifica el consumo en la sección de billing

---

## Próximos Pasos

1. Configura las credenciales en `.env`
2. Ejecuta `docker-compose up -d` para iniciar servicios
3. Crea el usuario admin: `python scripts/create_admin.py`
4. Accede al dashboard: `http://localhost:8000/dashboard`
5. Configura el calendario de contenido

Para más información, consulta la [documentación principal](./README.md).