# Integración ERP - CRM Portal Visas

## Objetivo
Permitir que el ERP envíe información comercial y transaccional hacia el CRM para alimentar clientes, contactos, productos, pedidos, facturación, devoluciones, cartera, histórico de compras y asignaciones.

## Base URL sugerida
`https://portalvisas.com/v1/public`

## Autenticación
### Solicitar token
`POST /api/crm/auth/token`

Headers:
`Content-Type: application/json`

Body:
```json
{
  "client_id": "erp_portal_visas",
  "client_secret": "CambiaEstaClaveERP2026!"
}
```

Respuesta:
```json
{
  "ok": true,
  "access_token": "TOKEN",
  "token_type": "Bearer",
  "expires_in": 86400
}
```

> La credencial inicial es solo para pruebas. Debe cambiarse antes de producción desde API ERP o Configuración CRM.

## Envío de datos
Todos los endpoints ERP usan:
`Authorization: Bearer TOKEN`
`Content-Type: application/json`

Formato general:
```json
{
  "request_id": "ERP-20260709-001",
  "data": [
    { "codigo_erp": "CL-001", "nit": "900123456", "razon_social": "Cliente SAS" }
  ]
}
```

## Endpoints
- `POST /api/crm/erp/clientes`
- `POST /api/crm/erp/contactos`
- `POST /api/crm/erp/productos`
- `POST /api/crm/erp/pedidos`
- `POST /api/crm/erp/facturas`
- `POST /api/crm/erp/devoluciones`
- `POST /api/crm/erp/cartera`
- `POST /api/crm/erp/historico-compras`
- `POST /api/crm/erp/asignaciones`
- `GET /api/crm/erp/sync-status`
- `GET /api/crm/erp/health`

## Clientes - campos recomendados
```json
{
  "codigo_erp": "CL-001245",
  "nit": "900123456",
  "razon_social": "Cliente Ejemplo SAS",
  "nombre_comercial": "Cliente Ejemplo",
  "ciudad": "Bogotá",
  "departamento": "Cundinamarca",
  "direccion": "Cra 1 # 2 - 3",
  "telefono": "6010000000",
  "correo": "cliente@ejemplo.com",
  "estado": "Activo",
  "segmento": "Corporativo",
  "fecha_ultima_compra": "2026-07-01",
  "valor_historico_compras": 25000000
}
```

## Contactos - campos recomendados
```json
{
  "codigo_erp": "CL-001245",
  "nit": "900123456",
  "nombre": "Laura Gómez",
  "cargo": "Compras",
  "area": "Administrativa",
  "celular": "3100000000",
  "correo": "laura@cliente.com",
  "es_principal": true
}
```

## Respuesta por lote
```json
{
  "ok": true,
  "data": {
    "batch_id": 10,
    "request_id": "ERP-20260709-001",
    "estado": "Procesado",
    "total": 20,
    "ok": 20,
    "errores": 0
  }
}
```

## Manejo de duplicados
- Clientes se actualizan por `codigo_erp` o `nit`.
- Productos se actualizan por `codigo_producto`.
- Pedidos/facturas/devoluciones/cartera se actualizan por `llave_externa`, `numero_documento` o `numero_pedido`.

## Orden recomendado de sincronización
1. Productos
2. Clientes / terceros
3. Contactos
4. Asignaciones de ejecutivos
5. Histórico de compras
6. Pedidos
7. Facturas
8. Devoluciones
9. Cartera

## Frecuencia sugerida
- Clientes, productos y contactos: diaria.
- Pedidos/facturas/devoluciones/cartera: cada hora o según operación.
- Histórico de compras: diaria o semanal.