1. Concepto de integración con APIs

Una API (Application Programming Interface) es un contrato que expone funcionalidades de un servicio a través de HTTP. La integración consiste en:

• Obtener credenciales y tokens de autorización (OAuth 2.0).
• Construir peticiones GET/POST/PUT/DELETE según la documentación.
• Parsear respuestas JSON o XML y mapearlas a objetos de negocio.
• Gestionar límites de velocidad (rate limits) y errores.

En el caso de agentes, la API permite:

• Recibir mensajes entrantes.
• Publicar respuestas o contenidos.
• Obtener métricas de interacción.

2. Arquitectura típica de integración

Una arquitectura robusta suele incluir:

1. Gateway de autenticación: gestiona refresco de tokens y almacena secretos en un vault (HashiCorp Vault, AWS Secrets Manager).
2. Micro‑servicio de orquestación: expone endpoints internos (REST/GraphQL) que los agentes consumen.
3. Workers asíncronos: procesan colas (RabbitMQ, Kafka) para evitar bloqueos por rate limits.
4. Contenedores Docker/Podman: facilitan despliegue y escalado horizontal.

En los ejemplos siguientes, simplificaremos la arquitectura a un único script Python, pero la lógica es fácilmente trasladable a un micro‑servicio.

3. Preparación de credenciales y permisos

Antes de escribir código, crea las apps en los portales oficiales:

• Facebook: Developers Portal → My Apps → Add Product → Facebook Graph API. Necesitarás PAGE_ACCESS_TOKEN y, opcionalmente, APP_SECRET para validar webhooks.
• Twitter: Twitter Developer Portal → Projects & Apps. Genera Bearer Token (OAuth 2.0) y API Key / Secret si usarás OAuth 1.0a.

Guarda estos valores en variables de entorno y nunca los committees al repositorio.

export FB_PAGE_TOKEN='EAAB...'
export TWITTER_BEARER='AAAAAAAA...'
export TWITTER_API_KEY='xxxx'
export TWITTER_API_SECRET='yyyy'

4. Ejemplo práctico: Publicar en una página de Facebook

Usaremos la librería requests para enviar una publicación simple.

import os
import requests

PAGE_TOKEN = os.getenv('FB_PAGE_TOKEN')
GRAPH_URL = 'https://graph.facebook.com/v17.0/me/feed'

def publicar_facebook(mensaje: str, enlace: str = None):
    payload = {
        'message': mensaje,
        'access_token': PAGE_TOKEN
    }
    if enlace:
        payload['link'] = enlace
    response = requests.post(GRAPH_URL, data=payload)
    if response.status_code == 200:
        print('✅ Publicación exitosa:', response.json()['id'])
    else:
        print('❌ Error:', response.status_code, response.text)

if __name__ == '__main__':
    publicar_facebook('Hola desde mi bot Python! 🚀', 'https://example.com')

Notas de seguridad:

• El PAGE_ACCESS_TOKEN tiene permisos de publicación; revócalo inmediatamente si sospechas una fuga.
• Usa HTTPS siempre y valida el certificado del endpoint.

Gestión de rate limits: Facebook permite 200 llamadas por hora por token. Implementa una cola (Redis + RQ) si tu agente envía >10 mensajes por minuto.

5. Ejemplo práctico: Twittear con la API v2

Utilizaremos tweepy (versión 4.x) que soporta OAuth 2.0 Bearer Token y OAuth 1.0a.

import os
import tweepy

BEARER_TOKEN = os.getenv('TWITTER_BEARER')
API_KEY = os.getenv('TWITTER_API_KEY')
API_SECRET = os.getenv('TWITTER_API_SECRET')

# Cliente para operaciones de solo lectura (search, trends)
client = tweepy.Client(bearer_token=BEARER_TOKEN)

# Cliente con OAuth 1.0a para publicar tweets
auth = tweepy.OAuth1UserHandler(API_KEY, API_SECRET)
api = tweepy.API(auth)

def twittear(mensaje: str):
    try:
        tweet = api.update_status(status=mensaje)
        print('✅ Tweet publicado ID:', tweet.id)
    except tweepy.TweepError as e:
        print('❌ Error al twittear:', e)

if __name__ == '__main__':
    twittear('Hola Twitter desde Python 🐍 #APIintegration')

Consideraciones de límite: Twitter permite 300 tweets por 3 horas para cuentas estándar. Si superas el límite, la API devolverá 429 Too Many Requests con un encabezado x-rate-limit-reset que indica cuándo puedes reintentar.

6. Comparativa rápida: Facebook vs Twitter

7. Buenas prácticas de seguridad

• Almacena tokens en secretos gestionados (Vault, AWS Secrets Manager, Azure Key Vault).
• Renueva tokens automáticamente usando el endpoint de refresco de Facebook o el flujo de OAuth 2.0 Refresh Token de Twitter.
• Limita scopes: solicita solo los permisos estrictamente necesarios (pages_manage_posts, tweet.write).
• Validación de firmas de webhook: compara X-Hub-Signature-256 (Facebook) o crc_token (Twitter) con tu APP_SECRET.
• Escaneo de vulnerabilidades: ejecuta bandit o pylint en tu código Python antes de desplegar.

8. Manejo de errores y troubleshooting

Los errores más comunes y sus soluciones:

Para depuración, habilita logs estructurados:

import logging
logging.basicConfig(level=logging.INFO, format='%(asctime)s %(levelname)s %(message)s')

9. Optimización y escalabilidad

Si tu agente maneja cientos de interacciones por segundo, considera:

• Uso de asyncio + httpx para enviar peticiones concurrentes sin bloquear.
• Pool de conexiones (keep‑alive) para reducir latencia.
• Contenedores Docker con gunicorn --workers 4 --threads 2 o uvicorn en modo async.
• Escalado horizontal mediante Kubernetes Horizontal Pod Autoscaler (HPA) basado en CPU o en métricas personalizadas de queue length.

Ejemplo de cliente async para Facebook:

import os, asyncio, httpx
PAGE_TOKEN = os.getenv('FB_PAGE_TOKEN')
GRAPH_URL = 'https://graph.facebook.com/v17.0/me/feed'

async def publicar_async(mensaje: str):
    async with httpx.AsyncClient(timeout=10) as client:
        payload = {'message': mensaje, 'access_token': PAGE_TOKEN}
        r = await client.post(GRAPH_URL, data=payload)
        r.raise_for_status()
        print('✅ Publicado async:', r.json()['id'])

asyncio.run(publicar_async('Mensaje async desde Python'))

10. Conclusión

Integrar agentes con Facebook y Twitter mediante sus APIs permite una atención al cliente moderna y omnicanal. Siguiendo las buenas prácticas de seguridad, manejo de límites y escalado, podrás construir soluciones robustas que escalen junto a tu negocio.

Recuerda siempre revisar la documentación oficial, mantener tus dependencias actualizadas (pip list --outdated) y monitorizar los logs de producción para detectar anomalías antes de que afecten a tus usuarios.