erp-core/docs/00-vision-general/INTEGRACIONES-EXTERNAS.md

id	title	type	status	version	created_date	updated_date
INTEGRACIONES-EXTERNAS-ERP-CORE	Integraciones Externas - ERP Core	Technical	Published	1.0.0	2026-01-10	2026-01-10

Integraciones Externas - ERP Core

Catalogo completo de integraciones con servicios externos

Resumen

ERP Core integra multiples servicios externos para proveer funcionalidades de billing, comunicaciones, almacenamiento e inteligencia artificial.

---

1. Catalogo de Integraciones

ID	Servicio	Proveedor	Modulo	Estado
INT-001	Billing	Stripe	MGN-016	Planificado
INT-002	Email	SendGrid/SES	MGN-008	Planificado
INT-003	Push	Web Push API	MGN-008	Planificado
INT-004	WhatsApp	Meta Cloud API	MGN-021	Planificado
INT-005	Storage	S3/R2/MinIO	N/A	Planificado
INT-006	Cache/Queue	Redis/BullMQ	N/A	Planificado
INT-007	LLM Gateway	OpenRouter	MGN-020	Planificado
INT-008	Transcripcion	OpenAI Whisper	MGN-021	Planificado
INT-009	Vision/OCR	Google Vision	MGN-021	Planificado

---

2. INT-001: Stripe (Billing)

2.1 Descripcion

Stripe provee la infraestructura de pagos para suscripciones, facturacion y gestion de metodos de pago.

2.2 Caracteristicas

• Suscripciones recurrentes (mensual/anual)
• Trial periods configurables
• Upgrade/downgrade con prorateo
• Webhooks para sincronizacion
• Portal de cliente integrado
• Multiples monedas (USD, MXN)

2.3 Configuracion

# Variables de entorno requeridas
STRIPE_SECRET_KEY=sk_live_...
STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

2.4 Webhooks Requeridos

Evento	Accion
customer.subscription.created	Activar suscripcion
customer.subscription.updated	Actualizar plan
customer.subscription.deleted	Cancelar suscripcion
invoice.paid	Registrar pago
invoice.payment_failed	Notificar fallo

2.5 Documentacion

• Stripe Docs
• Stripe API Reference

---

3. INT-002: SendGrid/SES (Email)

3.1 Descripcion

Servicios de email transaccional para notificaciones, verificaciones y comunicaciones con usuarios.

3.2 Proveedores Soportados

Proveedor	Caso de uso
SendGrid	Principal - alto volumen
AWS SES	Alternativo - bajo costo
SMTP generico	Desarrollo/self-hosted

3.3 Configuracion SendGrid

SENDGRID_API_KEY=SG...
SENDGRID_FROM_EMAIL=noreply@example.com
SENDGRID_FROM_NAME=ERP Core

3.4 Configuracion AWS SES

AWS_SES_ACCESS_KEY_ID=AKIA...
AWS_SES_SECRET_ACCESS_KEY=...
AWS_SES_REGION=us-east-1
AWS_SES_FROM_EMAIL=noreply@example.com

3.5 Templates de Email

Template	Uso
welcome	Bienvenida a nuevo usuario
verify_email	Verificacion de email
password_reset	Reset de password
invoice_paid	Factura pagada
trial_ending	Trial por terminar

3.6 Documentacion

• SendGrid Docs
• AWS SES Docs

---

4. INT-003: Web Push API (Notificaciones Push)

4.1 Descripcion

Notificaciones push para navegadores web usando el estandar Web Push con VAPID.

4.2 Configuracion

VAPID_PUBLIC_KEY=BJ...
VAPID_PRIVATE_KEY=...
VAPID_SUBJECT=mailto:admin@example.com

4.3 Generacion de Claves VAPID

npx web-push generate-vapid-keys

4.4 Documentacion

• Web Push Protocol
• web-push npm

---

5. INT-004: Meta WhatsApp Business (Mensajeria)

5.1 Descripcion

WhatsApp Business Cloud API para comunicacion con clientes via WhatsApp, integrado con IA conversacional.

5.2 Configuracion

WHATSAPP_ACCESS_TOKEN=EAA...
WHATSAPP_PHONE_NUMBER_ID=123456789
WHATSAPP_WABA_ID=987654321
WHATSAPP_WEBHOOK_VERIFY_TOKEN=my-verify-token

5.3 Webhooks

Evento	Accion
messages	Procesar mensaje entrante
message_status	Actualizar estado (sent/delivered/read)

5.4 Templates Pre-aprobados

Los templates de WhatsApp deben ser aprobados por Meta antes de usarse:

Template	Uso
order_confirmation	Confirmacion de pedido
payment_reminder	Recordatorio de pago
shipping_update	Actualizacion de envio

5.5 Documentacion

• WhatsApp Business API

---

6. INT-005: S3/R2/MinIO (Storage)

6.1 Descripcion

Almacenamiento de archivos compatible con S3 API para documentos, imagenes y assets.

6.2 Proveedores Soportados

Proveedor	Caso de uso
AWS S3	Produccion - alta disponibilidad
Cloudflare R2	Alternativo - sin egress fees
MinIO	Self-hosted / desarrollo

6.3 Configuracion AWS S3

AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1
AWS_S3_BUCKET=erp-core-files

6.4 Configuracion Cloudflare R2

R2_ACCESS_KEY_ID=...
R2_SECRET_ACCESS_KEY=...
R2_ENDPOINT=https://xxx.r2.cloudflarestorage.com
R2_BUCKET=erp-core-files

6.5 Configuracion MinIO

MINIO_ENDPOINT=http://localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=erp-core-files

6.6 Documentacion

• AWS S3 Docs
• Cloudflare R2 Docs
• MinIO Docs

---

7. INT-006: Redis/BullMQ (Cache y Colas)

7.1 Descripcion

Redis para cache de datos y BullMQ para colas de trabajos asincronos.

7.2 Casos de Uso

Uso	Proposito
Session store	Almacenar sesiones de usuario
Cache	Cache de queries frecuentes
Rate limiting	Control de limite de requests
Job queue	Colas para webhooks, emails, etc.

7.3 Configuracion

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_TLS=false

7.4 Colas Definidas

Cola	Procesador	Uso
email	EmailProcessor	Envio de emails
webhook	WebhookProcessor	Envio de webhooks
notification	NotificationProcessor	Notificaciones push
llm	LLMProcessor	Requests a LLM

7.5 Documentacion

• Redis Docs
• BullMQ Docs

---

8. INT-007: OpenRouter (LLM Gateway)

8.1 Descripcion

Gateway unificado para acceder a multiples modelos de lenguaje (LLM) con una sola API key.

8.2 Modelos Disponibles

Modelo	ID	Costo/1M tokens	Uso
Claude 3 Haiku	anthropic/claude-3-haiku	$0.25	Default
Claude 3 Sonnet	anthropic/claude-3-sonnet	$3.00	Premium
GPT-4o-mini	openai/gpt-4o-mini	$0.15	Fallback
GPT-3.5 Turbo	openai/gpt-3.5-turbo	$0.50	Fallback
Mistral 7B	mistralai/mistral-7b	$0.06	Economico
Llama 3	meta-llama/llama-3-8b	$0.20	Open source

8.3 Configuracion

OPENROUTER_API_KEY=sk-or-v1-...
LLM_MODEL_DEFAULT=anthropic/claude-3-haiku
LLM_MODEL_FALLBACK=openai/gpt-3.5-turbo
LLM_MAX_TOKENS=1000
LLM_TEMPERATURE=0.7
LLM_BASE_URL=https://openrouter.ai/api/v1

8.4 Rate Limits

Los rate limits dependen del modelo y plan de OpenRouter.

8.5 Documentacion

• OpenRouter Docs

---

9. INT-008: OpenAI Whisper (Transcripcion)

9.1 Descripcion

Transcripcion de audio a texto para procesamiento de notas de voz en WhatsApp.

9.2 Configuracion

OPENAI_API_KEY=sk-...
WHISPER_MODEL=whisper-1

9.3 Formatos Soportados

• MP3, MP4, MPEG, MPGA, M4A, WAV, WEBM
• Maximo 25 MB por archivo

9.4 Documentacion

• Whisper API

---

10. INT-009: Google Vision (OCR)

10.1 Descripcion

Vision por computadora para reconocimiento de texto en imagenes (OCR) y deteccion de productos.

10.2 Casos de Uso

Caso	Descripcion
OCR de productos	Extraer nombre/precio de fotos
Codigo de barras	Detectar y decodificar barcodes
Etiquetas	Extraer texto de etiquetas

10.3 Configuracion

GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
GOOGLE_VISION_PROJECT_ID=my-project

10.4 Documentacion

• Cloud Vision API

---

11. Variables de Entorno Consolidadas

# ==========================================
# STRIPE (Billing)
# ==========================================
STRIPE_SECRET_KEY=sk_live_...
STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

# ==========================================
# EMAIL (SendGrid)
# ==========================================
SENDGRID_API_KEY=SG...
SENDGRID_FROM_EMAIL=noreply@example.com
SENDGRID_FROM_NAME=ERP Core

# ==========================================
# PUSH NOTIFICATIONS (VAPID)
# ==========================================
VAPID_PUBLIC_KEY=BJ...
VAPID_PRIVATE_KEY=...
VAPID_SUBJECT=mailto:admin@example.com

# ==========================================
# WHATSAPP
# ==========================================
WHATSAPP_ACCESS_TOKEN=EAA...
WHATSAPP_PHONE_NUMBER_ID=123456789
WHATSAPP_WABA_ID=987654321
WHATSAPP_WEBHOOK_VERIFY_TOKEN=my-verify-token

# ==========================================
# STORAGE (S3)
# ==========================================
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1
AWS_S3_BUCKET=erp-core-files

# ==========================================
# REDIS
# ==========================================
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# ==========================================
# LLM (OpenRouter)
# ==========================================
OPENROUTER_API_KEY=sk-or-v1-...
LLM_MODEL_DEFAULT=anthropic/claude-3-haiku
LLM_MODEL_FALLBACK=openai/gpt-3.5-turbo
LLM_MAX_TOKENS=1000
LLM_TEMPERATURE=0.7

# ==========================================
# WHISPER (Transcripcion)
# ==========================================
OPENAI_API_KEY=sk-...

# ==========================================
# GOOGLE VISION (OCR)
# ==========================================
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
GOOGLE_VISION_PROJECT_ID=my-project

---

Referencias

• VISION-ERP-CORE.md - Vision general
• STACK-TECNOLOGICO.md - Stack completo
• ARQUITECTURA-SAAS.md - Arquitectura SaaS
• ARQUITECTURA-IA.md - Arquitectura IA

---

Actualizado: 2026-01-10