# Módulo de Empresa — API Reference

Base URL: `/api`  
Todos los endpoints requieren `Authorization: Bearer <token>`.  
Prefijo real: `/api/base/empresa/`

---

## Endpoints

| Método | URL | Permiso | Descripción |
|---|---|---|---|
| `POST` | `/api/base/empresa/listar` | `base.empresa.listar` | Lista paginada |
| `GET` | `/api/base/empresa/detalle/{id}` | `base.empresa.detalle` | Detalle de una empresa |
| `GET` | `/api/base/empresa/cargar-datos-edicion/{id}` | `base.empresa.cargarDatosEdicion` | Datos para el form de edición |
| `POST` | `/api/base/empresa/guardar` | `base.empresa.guardar` | Crear o actualizar |
| `POST` | `/api/base/empresa/cambiar-estado` | `base.empresa.cambiarEstado` | Activar / Eliminar |
| `GET` | `/api/base/empresa/descargar-plantilla` | `base.empresa.descargarPlantilla` | Descarga plantilla Excel |
| `POST` | `/api/base/empresa/guardar-archivo-temporal` | `base.empresa.guardarArchivoTemporal` | Subir Excel al servidor |
| `POST` | `/api/base/empresa/obtener-datos-archivo` | `base.empresa.obtenerDatosArchivo` | Obtener total de filas del archivo |
| `POST` | `/api/base/empresa/validar-chunk` | `base.empresa.validarChunk` | Validar un chunk antes de importar |
| `POST` | `/api/base/empresa/importar-chunk` | `base.empresa.importarChunk` | Importar un chunk |
| `POST` | `/api/base/empresa/eliminar-archivo-temporal` | `base.empresa.eliminarArchivoTemporal` | Limpiar archivo temporal |
| `POST` | `/api/base/empresa/exportar-excel` | `base.empresa.exportarExcel` | Descarga Excel |
| `POST` | `/api/base/empresa/exportar-pdf` | `base.empresa.exportarPdf` | Descarga PDF |

> Este módulo administra las empresas del sistema. **No filtra por empresa activa** — muestra todas las empresas según permisos.

---

## IDs en base64

Los IDs viajan en base64 en los parámetros URL y en el body.

```js
btoa(String(id))          // 1 → "MQ=="
parseInt(atob("MQ=="), 10) // → 1
```

---

## `POST /listar`

```json
{
  "perPage":        10,
  "searchQuery":    "FSG",
  "empresaEstado":  "Activo",
  "sort_field":     "empresaNombre",
  "sort_direction": "asc"
}
```

Usa `"typeData": "all"` para obtener todas sin paginar.

---

## `POST /guardar` — Crear

```json
{
  "empresaNombre":            "FSG Consultores",
  "empresaRazonSocial":       "FSG Consultores S.A. de C.V.",
  "empresaRFC":               "FSG201001ABC",
  "empresaDireccion":         "Av. Insurgentes Sur 1234, CDMX",
  "empresaEmail":             "contacto@fsg.com.mx",
  "empresaCoordenadas":       "19.4326,-99.1332",
  "empresaTipoContribuyente": "Moral",
  "empresaTipo":              "Interna"
}
```

## `POST /guardar` — Actualizar

Agrega `idEmpresa` en base64:

```json
{
  "idEmpresa":                "MQ==",
  "empresaNombre":            "FSG Consultores Actualizado",
  "empresaRazonSocial":       "FSG Consultores S.A. de C.V.",
  "empresaRFC":               "FSG201001ABC",
  "empresaDireccion":         "Av. Insurgentes Sur 1234, CDMX",
  "empresaEmail":             "contacto@fsg.com.mx",
  "empresaCoordenadas":       "19.4326,-99.1332",
  "empresaTipoContribuyente": "Física",
  "empresaTipo":              "Externa"
}
```

| Campo | Regla |
|---|---|
| `empresaNombre` | Requerido |
| `empresaRazonSocial` | Opcional |
| `empresaRFC` | Opcional |
| `empresaDireccion` | Opcional |
| `empresaEmail` | Opcional, formato email |
| `empresaCoordenadas` | Opcional, ej: `"19.4326,-99.1332"` |
| `empresaTipoContribuyente` | `"Física"` \| `"Moral"` |
| `empresaTipo` | `"Interna"` \| `"Externa"` |

---

## `POST /cambiar-estado`

```json
{
  "idEmpresa": "MQ==",
  "estado":    "Activo"
}
```

`estado`: `"Activo"` | `"Eliminado"`

---

## Importación masiva desde Excel

El flujo de importación tiene 4 pasos:

### Paso 1 — Subir archivo

`POST /guardar-archivo-temporal` — `multipart/form-data`

| Campo | Tipo | Descripción |
|---|---|---|
| `archivoExcel` | `file` (`.xlsx`) | Archivo Excel con la plantilla correcta |

#### Respuesta

```json
{
  "success":   true,
  "archivoId": "import_6789abc.123",
  "total":     150,
  "message":   "Archivo guardado temporalmente"
}
```

### Paso 2 — Obtener total de filas

`POST /obtener-datos-archivo`

```json
{ "archivoId": "import_6789abc.123" }
```

#### Respuesta

```json
{ "success": true, "total": 150 }
```

### Paso 3 — Importar en chunks

Repite `POST /importar-chunk` para cada fragmento hasta cubrir `total`:

```json
{
  "archivoId":    "import_6789abc.123",
  "inicioChunk":  0,
  "finChunk":     50,
  "esUltimoChunk": false
}
```

En el último chunk, `"esUltimoChunk": true` para eliminar el temporal automáticamente.

#### Respuesta

```json
{
  "success":  true,
  "exitosos": 48,
  "errores": [
    { "fila": 12, "mensaje": "Error al procesar el registro: ..." }
  ]
}
```

### Paso 4 (opcional) — Limpiar si se cancela

`POST /eliminar-archivo-temporal`

```json
{ "archivoId": "import_6789abc.123" }
```

### Plantilla Excel

`GET /descargar-plantilla` — No requiere body. Devuelve un `.xlsx` con las columnas:

| Columna | Campo BD | Requerido |
|---|---|---|
| `nombre` | `empresaNombre` | Sí |
| `razonsocial` | `empresaRazonSocial` | No |
| `RFC` | `empresaRFC` | No |
| `direccion` | `empresaDireccion` | No |
| `email` | `empresaEmail` | No |
| `coordenadas` | `empresaCoordenadas` | No |
| `TipoContribuyente` | `empresaTipoContribuyente` | No |
| `Tipo` | `empresaTipo` | No |

---

## Exportación

```
POST /api/base/empresa/exportar-excel
POST /api/base/empresa/exportar-pdf
```

Acepta los mismos filtros que `/listar`. Para PDF, agrega `"output_mode": "inline"` para preview en navegador en lugar de descarga.

---

## Respuesta paginada (`/listar`)

```json
{
  "success":          true,
  "code":             200,
  "data":             [...],
  "lastPage":         5,
  "totalData":        48,
  "totalPage":        10,
  "currentPage":      1,
  "recordsTotal":     48,
  "recordsFiltered":  48,
  "draw":             1
}
```