# Módulo Cliente — Grupo Empresarial · API Reference

Base URL: `/api`  
Todos los endpoints requieren `Authorization: Bearer <token>` y el permiso correspondiente.  
Prefijo real: `/api/cliente/grupoempresarial/`

---

## Empresa activa

Los registros se filtran por la columna `idEmpresa` directa en la tabla `cli_grupoempresarial`.
Al crear, el `idEmpresa` se toma automáticamente de `empresa_activa_id()` — el cliente **no lo envía**.

Para pruebas en Postman incluye la empresa activa:

```
X-Empresa-Id: 2
```

o en el body:
```json
{ "idEmpresaId": 2 }
```

---

## IDs en base64

El endpoint `POST /listar` devuelve el `idGrupoEmpresarial` **ya codificado en base64** (Resource).  
El endpoint `GET /cargar-datos-edicion/{id}` devuelve el entero crudo — si reutilizas el ID en un form, codifícalo:

```js
$('#form-idGrupoEmpresarial').val(btoa(String(d.idGrupoEmpresarial)));
```

---

## Código auto-generado

El campo `grupoEmpresarialCodigo` sigue el formato:

```
GE{YY}-{NNN}     →     GE26-001, GE26-002, GE27-001 …
```

- `YY` = últimos 2 dígitos del año en curso (`date('y')`)
- `NNN` = correlativo de 3 dígitos, reinicia con el nuevo año
- El backend lo genera al crear. **No se envía en el body** ni se puede modificar después.

---

## Endpoints

| Método | URL | Permiso | Descripción |
|---|---|---|---|
| `POST` | `/api/cliente/grupoempresarial/listar` | `cliente.grupoempresarial.listar` | Lista paginada (DataTable) |
| `GET` | `/api/cliente/grupoempresarial/cargar-datos-edicion/{id}` | `cliente.grupoempresarial.cargarDatosEdicion` | Datos para edición |
| `POST` | `/api/cliente/grupoempresarial/guardar` | `cliente.grupoempresarial.guardar` | Crear o actualizar |
| `POST` | `/api/cliente/grupoempresarial/cambiar-estado` | `cliente.grupoempresarial.cambiarEstado` | Activar / Inactivar |
| `GET` | `/api/cliente/grupoempresarial/detalle/{id}` | `cliente.grupoempresarial.detalle` | Detalle |
| `POST` | `/api/cliente/grupoempresarial/exportar-excel` | `cliente.grupoempresarial.exportarExcel` | Excel |
| `POST` | `/api/cliente/grupoempresarial/exportar-pdf` | `cliente.grupoempresarial.exportarPdf` | PDF |

---

## `POST /listar`

**Postman:**
```json
{
  "idEmpresaId":                   2,
  "perPage":                       10,
  "searchQuery":                   "GE26",
  "grupoEmpresarialCodigo":        "GE26-001",
  "grupoEmpresarialAlias":         "Grupo Norte",
  "grupoEmpresarialRepresentante": "Juan",
  "grupoEmpresarialEstado":        "Activo",
  "sort_field":                    "grupoEmpresarialAlias",
  "sort_direction":                "asc"
}
```

**Respuesta:**
```json
{
  "success": true,
  "code":    200,
  "data": [
    {
      "idGrupoEmpresarial":            "MQ==",
      "grupoEmpresarialCodigo":         "GE26-001",
      "grupoEmpresarialAlias":          "Grupo Norte",
      "grupoEmpresarialRepresentante":  "Juan García",
      "grupoEmpresarialTelefono":       "5512345678",
      "grupoEmpresarialCorreo":         "grupo@norte.com",
      "grupoEmpresarialEstado":         "Activo"
    }
  ],
  "lastPage":    1,
  "totalData":   1,
  "currentPage": 1
}
```

> `idGrupoEmpresarial` viene en **base64** — úsalo directamente sin `btoa()`.

---

## `POST /guardar` — Crear

```json
{
  "grupoEmpresarialAlias":         "Grupo Norte",
  "grupoEmpresarialRepresentante": "Juan García",
  "grupoEmpresarialTelefono":      "5512345678",
  "grupoEmpresarialCorreo":        "grupo@norte.com"
}
```

El backend asigna automáticamente:
- `grupoEmpresarialCodigo` → `GE26-001` (correlativo)
- `grupoEmpresarialEstado` → `Activo`
- `idEmpresa` → empresa activa en sesión

**Respuesta:**
```json
{
  "success": true,
  "code":    200,
  "message": "Grupo empresarial registrado correctamente",
  "data": {
    "idGrupoEmpresarial":    1,
    "grupoEmpresarialCodigo": "GE26-001",
    "grupoEmpresarialEstado": "Activo"
  }
}
```

---

## `POST /guardar` — Actualizar

Agrega `idGrupoEmpresarial` en base64. El código **no se puede modificar**.

```json
{
  "idGrupoEmpresarial":            "MQ==",
  "grupoEmpresarialAlias":         "Grupo Norte Actualizado",
  "grupoEmpresarialRepresentante": "Carlos López",
  "grupoEmpresarialTelefono":      "5598765432",
  "grupoEmpresarialCorreo":        "carlos@norte.com"
}
```

| Campo | Regla |
|---|---|
| `grupoEmpresarialAlias` | Requerido, máx. 150 chars |
| `grupoEmpresarialRepresentante` | Opcional, máx. 150 chars |
| `grupoEmpresarialTelefono` | Opcional, máx. 25 chars |
| `grupoEmpresarialCorreo` | Opcional, formato email, máx. 100 chars |

---

## `POST /cambiar-estado`

```json
{
  "idGrupoEmpresarial": "MQ==",
  "estado":             "Inactivo"
}
```

`estado`: `"Activo"` | `"Inactivo"`

**Respuesta:**
```json
{
  "success": true,
  "code":    200,
  "message": "Se inactivó el grupo empresarial correctamente",
  "data":    { "idGrupoEmpresarial": 1, "grupoEmpresarialEstado": "Inactivo" }
}
```

---

## `GET /cargar-datos-edicion/{id}`

`{id}` = base64 del ID (viene del `listar`).

**Respuesta:**
```json
{
  "success": true,
  "code":    200,
  "data": {
    "idGrupoEmpresarial":            1,
    "grupoEmpresarialCodigo":         "GE26-001",
    "grupoEmpresarialAlias":          "Grupo Norte",
    "grupoEmpresarialRepresentante":  "Juan García",
    "grupoEmpresarialTelefono":       "5512345678",
    "grupoEmpresarialCorreo":         "grupo@norte.com",
    "grupoEmpresarialEstado":         "Activo"
  }
}
```

> El `idGrupoEmpresarial` aquí es **entero** (modelo crudo). Codifícalo con `btoa(String(id))` si lo reutilizas en el form.

---

## `GET /detalle/{id}`

`{id}` = base64 del ID.

**Respuesta:**
```json
{
  "success": true,
  "code":    200,
  "message": "Grupo empresarial encontrado con éxito",
  "data":    { ... }
}
```

---

## Exportar

### `POST /exportar-excel`
### `POST /exportar-pdf`

```json
{
  "idEmpresaId":  2,
  "estado":       "Activo",
  "tituloEstado": "Activos",
  "output_mode":  "download"
}
```

Aplica los mismos filtros que el `listar`. El PDF acepta `output_mode`: `"download"` | `"inline"`.

**Columnas exportadas:**

| Campo | Encabezado |
|---|---|
| `grupoEmpresarialCodigo` | Código |
| `grupoEmpresarialAlias` | Alias |
| `grupoEmpresarialRepresentante` | Representante |
| `grupoEmpresarialTelefono` | Teléfono |
| `grupoEmpresarialCorreo` | Correo |
| `grupoEmpresarialEstado` | Estado |

---

## Bitácora

| ID acción | Descripción |
|---|---|
| 54 | Crear grupo empresarial |
| 55 | Editar grupo empresarial |
| 56 | Inactivar grupo empresarial |
| 57 | Activar grupo empresarial |

---

## Permisos necesarios (`seg_ruta`)

```sql
INSERT INTO seg_ruta (rutaUrl, rutaPermiso, rutaModulo) VALUES
('/api/cliente/grupoempresarial/listar',               'cliente.grupoempresarial.listar',               'cliente'),
('/api/cliente/grupoempresarial/cargar-datos-edicion', 'cliente.grupoempresarial.cargarDatosEdicion',    'cliente'),
('/api/cliente/grupoempresarial/guardar',              'cliente.grupoempresarial.guardar',               'cliente'),
('/api/cliente/grupoempresarial/cambiar-estado',       'cliente.grupoempresarial.cambiarEstado',         'cliente'),
('/api/cliente/grupoempresarial/detalle',              'cliente.grupoempresarial.detalle',               'cliente'),
('/api/cliente/grupoempresarial/exportar-excel',       'cliente.grupoempresarial.exportarExcel',         'cliente'),
('/api/cliente/grupoempresarial/exportar-pdf',         'cliente.grupoempresarial.exportarPdf',           'cliente');
```