# CRM Pro GECOERP — Documentación Técnica y Arquitectura Completa para LLMs

## 1. Visión General del Sistema

CRM Pro GECOERP es una solución de software empresarial basada en la nube desarrollada específicamente para el mercado mexicano e hispanohablante. La plataforma combina la gestión de relaciones con clientes (CRM), automatización de marketing y prospección por redes sociales, omnicanalidad con inteligencia artificial (WhatsApp, Facebook, Instagram, LinkedIn), facturación electrónica CFDI 4.0 con timbrado SAT, administración de inventarios y almacenes, punto de venta (TPV/POS), mesa de ayuda con acuerdos de nivel de servicio (SLA), gestión integral de proyectos, recursos humanos (HRMS) y un estudio avanzado de inteligencia de negocios (BI Studio) con análisis predictivo.

- **Dominio Principal**: https://geco-crm.gecoerp.com
- **Plataforma**: Web / Cloud SaaS
- **Región Principal**: México (MX) / Latinoamérica
- **Moneda Base**: MXN (Pesos Mexicanos) con soporte multimoneda y facturación API en USD.
- **Cumplimiento Normativo**: SAT Anexo 20 (CFDI 4.0), Ley Federal de Protección de Datos Personales, NOM-035-STPS (Línea Ética y Clima Laboral).

---

## 2. Especificaciones de la API Externa (/api/ext/*)

La API externa de GECOERP permite a desarrolladores y empresas sincronizar sistemas ERP locales, plataformas de comercio electrónico (Shopify, WooCommerce, Magento), aplicaciones móviles y herramientas de BI con el CRM.

### Protocolo de Autenticación y Seguridad
Las solicitudes a `/api/ext/*` se protegen mediante autenticación criptográfica HMAC-SHA256 con firmas por petición:

1. **Encabezados requeridos**:
   - `x-api-key`: Clave pública de 64 caracteres alfanuméricos identificadora de la empresa.
   - `x-timestamp`: Timestamp Unix en milisegundos (`Date.now()`). La ventana de validez máxima es de 300 segundos (5 minutos).
   - `x-nonce`: Cadena alfanumérica única por petición para evitar ataques de repetición (replay attacks).
   - `x-signature`: Firma HMAC-SHA256 codificada en hexadecimal.
2. **Cálculo de la firma**:
   ```
   string_to_sign = timestamp + "\n" + nonce + "\n" + method + "\n" + path + "\n" + payload_hash
   signature = HMAC_SHA256(string_to_sign, api_secret)
   ```
   Donde `payload_hash` es el hash SHA-256 del cuerpo JSON de la petición (o cadena vacía en peticiones GET/DELETE sin cuerpo).

### Catálogo de Endpoints de Integración Versionados (`/api/v1/` y `/api/ext/`)

#### Clientes (`/api/v1/clients` / `/api/ext/clients`)
- `GET /api/v1/clients`: Lista paginada de clientes activos. Soporta parámetros `search`, `page`, `limit`.
- `GET /api/v1/clients/:id`: Obtiene el detalle de un cliente específico, saldo acumulado y límite de crédito.
- `POST /api/v1/clients`: Crea un nuevo cliente con datos fiscales (RFC, Razón Social, Régimen Fiscal, Uso CFDI).
- `PATCH /api/v1/clients/:id`: Actualiza datos comerciales o de contacto de un cliente existente.

#### Productos e Inventario (`/api/v1/products`, `/api/ext/warehouses`)
- `GET /api/v1/products`: Consulta catálogo de productos con precios, stock consolidado, código de barras y categoría SAT.
- `GET /api/v1/products/:id`: Información detallada y disponibilidad por almacén.
- `POST /api/v1/products`: Da de alta un nuevo producto o servicio.
- `PATCH /api/v1/products/:id`: Modifica precios o datos del producto.
- `GET /api/ext/warehouses`: Listado de almacenes y sucursales físicas.

#### Cotizaciones y Pedidos (`/api/ext/quotations`, `/api/ext/orders`)
- `GET /api/ext/quotations`: Consulta cotizaciones emitidas, estado (borrador, enviada, aprobada, rechazada).
- `POST /api/ext/quotations`: Crea una cotización con partidas de productos, descuentos e impuestos desglosados.
- `PATCH /api/ext/quotations/:id/status`: Cambia el estado de la cotización.
- `GET /api/ext/orders`: Consulta pedidos de venta y estado de surtido/entrega.
- `POST /api/ext/orders`: Genera un pedido de venta desde sistemas de e-commerce.

#### Facturación CFDI 4.0 (`/api/ext/invoices`)
- `GET /api/ext/invoices`: Consulta facturas timbradas y su estado ante el SAT.
- `GET /api/ext/invoices/:id`: Obtiene los datos de la factura, UUID fiscal, enlace a XML y PDF.
- `POST /api/ext/invoices`: Emite y timbra una factura electrónica CFDI 4.0 directamente con el PAC.

#### Pipeline de Ventas (`/api/ext/pipeline`)
- `GET /api/ext/pipeline/stages`: Obtiene las etapas del embudo comercial y sus probabilidades.
- `GET /api/ext/pipeline`: Lista las oportunidades comerciales activas y su valor proyectado.
- `POST /api/ext/pipeline`: Crea una nueva oportunidad en el embudo comercial.
- `PATCH /api/ext/pipeline/:id`: Actualiza la etapa o estado (ganada/perdida) de la oportunidad.

---

## 3. Modelo de Módulos del Sistema

### BI Studio y Modelado Predictivo
- **Tablas de Trabajo (Work Tables)**: Tablas materializadas en base de datos con scheduler periódico.
- **Data Warehouse**: Repositorio centralizado con motor ETL para análisis OLAP.
- **Motor de Enriquecimiento y Deduplicación**: Algoritmos de similitud fonética y Levenshtein para unificar registros de clientes duplicados.
- **Redes Neuronales MLP**: Pronóstico de ingresos a 30, 60 y 90 días evaluando estacionalidad y velocidad del pipeline.

### Facturación Electrónica SAT (CFDI 4.0)
- Catálogos SAT 2026 precargados: `c_ClaveProdServ`, `c_ClaveUnidad`, `c_UsoCFDI`, `c_FormaPago`, `c_MetodoPago`, `c_RegimenFiscal`.
- Generación automática de cadena original y sellado digital con certificados CSD de la empresa emisora.
- Cancelación con motivo SAT y sustitución de UUIDs relacionados.

### Mesa de Ayuda y Escalamiento de Tickets
- Niveles de soporte jerárquico (Nivel 1: Primera línea, Nivel 2: Especialistas, Nivel 3: Ingeniería).
- Escalamiento automático basado en cron que calcula el tiempo transcurrido únicamente dentro de la jornada laboral configurada (`support_business_hours`).
- Integración bidireccional con WhatsApp para que el cliente final responda directamente desde su teléfono.

---

## 4. Recursos Disponibles para Agentes de IA

- **OpenAPI 3.0.3**: https://geco-crm.gecoerp.com/openapi.json
- **OpenAPI YAML**: https://geco-crm.gecoerp.com/openapi.yaml
- **Sitemap Dinámico**: https://geco-crm.gecoerp.com/sitemap.xml
- **Autodescubrimiento RSS del Marketplace**: https://geco-crm.gecoerp.com/api/marketplace/rss
- **Portal de Autoridad Certificadora**: https://geco-crm.gecoerp.com/certificados
- **Documentación Interactiva**: https://geco-crm.gecoerp.com/docs/