# 🆕 Nuevas APIs - Extracción de XMLs y Lectura de Metadata

## 📋 Resumen

Se han agregado **2 nuevas APIs** para trabajar con los paquetes ZIP descargados del SAT:

1. **API 4:** Extraer XMLs de un paquete
2. **API 5:** Leer metadata de un paquete

---

## 🎯 API 4: Extraer XMLs de un Paquete

### Descripción
Extrae todos los archivos XML de un paquete ZIP descargado y los guarda en el sistema de archivos.

### Endpoint
```
GET /api/v1/sat/paquete/{packageId}/extraer
```

### Parámetros
- **packageId** (string, requerido): ID del paquete obtenido al descargar

### Ejemplo de Uso
```bash
curl -X GET http://localhost:8000/api/v1/sat/paquete/pkg-001/extraer \
  -H "Accept: application/json"
```

### Respuesta Exitosa
```json
{
    "success": true,
    "package_id": "pkg-001",
    "zip_file": "/path/to/storage/app/sat_downloads/package_pkg-001.zip",
    "extract_directory": "/path/to/storage/app/sat_downloads/extracted/pkg-001",
    "total_files": 150,
    "total_size": 5242880,
    "files": [
        {
            "uuid": "12345678-1234-1234-1234-123456789012",
            "filename": "12345678-1234-1234-1234-123456789012.xml",
            "filepath": "/path/to/storage/app/sat_downloads/extracted/pkg-001/12345678-1234-1234-1234-123456789012.xml",
            "size": 34952
        }
    ]
}
```

### Ubicación de Archivos
Los XMLs extraídos se guardan en:
```
storage/app/sat_downloads/extracted/{packageId}/
```

Cada archivo XML se nombra con su UUID: `{uuid}.xml`

---

## 🎯 API 5: Leer Metadata de un Paquete

### Descripción
Lee la información de metadata de los CFDIs contenidos en un paquete ZIP **sin extraer los archivos**. Útil para obtener información rápida sin ocupar espacio en disco.

### Endpoint
```
GET /api/v1/sat/paquete/{packageId}/metadata
```

### Parámetros
- **packageId** (string, requerido): ID del paquete obtenido al descargar

### Ejemplo de Uso
```bash
curl -X GET http://localhost:8000/api/v1/sat/paquete/pkg-001/metadata \
  -H "Accept: application/json"
```

### Respuesta Exitosa
```json
{
    "success": true,
    "package_id": "pkg-001",
    "zip_file": "/path/to/storage/app/sat_downloads/package_pkg-001.zip",
    "total_records": 150,
    "metadata": [
        {
            "uuid": "12345678-1234-1234-1234-123456789012",
            "fecha_emision": "2024-01-15T10:30:00",
            "rfc_emisor": "ABC123456789",
            "nombre_emisor": "EMPRESA EJEMPLO SA DE CV",
            "rfc_receptor": "XYZ987654321",
            "nombre_receptor": "CLIENTE EJEMPLO SA DE CV",
            "rfc_pac": "PAC123456789",
            "total": "1500.00",
            "efecto_comprobante": "I",
            "estatus": "Vigente",
            "fecha_cancelacion": null
        }
    ]
}
```

### Campos de Metadata
- **uuid**: Folio fiscal del CFDI
- **fecha_emision**: Fecha y hora de emisión
- **rfc_emisor**: RFC del emisor
- **nombre_emisor**: Nombre o razón social del emisor
- **rfc_receptor**: RFC del receptor
- **nombre_receptor**: Nombre o razón social del receptor
- **rfc_pac**: RFC del PAC (Proveedor Autorizado de Certificación)
- **total**: Monto total del comprobante
- **efecto_comprobante**: Efecto del comprobante (I=Ingreso, E=Egreso, etc.)
- **estatus**: Estado del CFDI (Vigente, Cancelado)
- **fecha_cancelacion**: Fecha de cancelación (null si está vigente)

---

## 🔄 Flujo de Trabajo Completo

### Opción 1: Extraer XMLs (para procesamiento posterior)

```bash
# 1. Crear solicitud
curl -X POST http://localhost:8000/api/v1/sat/solicitud \
  -H "Content-Type: application/json" \
  -d '{"fecha_inicio": "2024-01-01 00:00:00", "fecha_fin": "2024-01-31 23:59:59"}'

# 2. Verificar estado (repetir hasta status_code = 5004)
curl http://localhost:8000/api/v1/sat/solicitud/{request_id}/verificar

# 3. Descargar paquetes
curl http://localhost:8000/api/v1/sat/solicitud/{request_id}/descargar

# 4. Extraer XMLs de cada paquete
curl http://localhost:8000/api/v1/sat/paquete/{package_id}/extraer
```

### Opción 2: Solo Leer Metadata (para consulta rápida)

```bash
# 1-3. Mismo proceso anterior...

# 4. Leer metadata sin extraer
curl http://localhost:8000/api/v1/sat/paquete/{package_id}/metadata
```

---

## 📁 Estructura de Archivos

```
storage/app/sat_downloads/
├── package_pkg-001.zip                    ← Paquete descargado
├── package_pkg-002.zip
└── extracted/                             ← XMLs extraídos
    ├── pkg-001/
    │   ├── 12345678-1234-1234-1234-123456789012.xml
    │   ├── 87654321-4321-4321-4321-210987654321.xml
    │   └── ...
    └── pkg-002/
        ├── abcdef12-3456-7890-abcd-ef1234567890.xml
        └── ...
```

---

## 🔧 Archivos Modificados

### 1. Servicio
**Archivo:** `app/Services/SATDescargaMasivaService.php`
- ✅ Agregado método `extraerXMLs()`
- ✅ Agregado método `leerMetadata()`
- ✅ Importadas clases `CfdiPackageReader` y `MetadataPackageReader`

### 2. Controlador
**Archivo:** `app/Http/Controllers/Api/SATController.php`
- ✅ Agregado método `extraerXMLs()`
- ✅ Agregado método `leerMetadata()`

### 3. Rutas
**Archivo:** `routes/api.php`
- ✅ Agregada ruta `GET /api/v1/sat/paquete/{packageId}/extraer`
- ✅ Agregada ruta `GET /api/v1/sat/paquete/{packageId}/metadata`

### 4. Documentación
- ✅ Actualizado `SAT_API_DOCS.md`
- ✅ Actualizado `SAT_EJEMPLOS.md`
- ✅ Actualizado `README.md`
- ✅ Actualizado `API_README.md`

---

## 💡 Casos de Uso

### Caso 1: Procesamiento Masivo de CFDIs
```bash
# Extraer todos los XMLs para procesarlos con otra herramienta
curl http://localhost:8000/api/v1/sat/paquete/pkg-001/extraer

# Los archivos quedan disponibles en:
# storage/app/sat_downloads/extracted/pkg-001/*.xml
```

### Caso 2: Búsqueda Rápida
```bash
# Leer metadata para buscar un CFDI específico sin extraer todo
curl http://localhost:8000/api/v1/sat/paquete/pkg-001/metadata | \
  jq '.metadata[] | select(.rfc_emisor == "ABC123456789")'
```

### Caso 3: Validación de Datos
```bash
# Verificar cuántos CFDIs hay y sus totales
curl http://localhost:8000/api/v1/sat/paquete/pkg-001/metadata | \
  jq '.metadata | length'
```

---

## ⚠️ Consideraciones

### Espacio en Disco
- **Extraer XMLs**: Requiere espacio adicional (los XMLs se guardan descomprimidos)
- **Leer Metadata**: No requiere espacio adicional (lee directamente del ZIP)

### Rendimiento
- **Extraer XMLs**: Más lento, pero los archivos quedan disponibles para uso posterior
- **Leer Metadata**: Más rápido, ideal para consultas

### Recomendaciones
1. Usa **Leer Metadata** para consultas rápidas y búsquedas
2. Usa **Extraer XMLs** cuando necesites procesar los archivos completos
3. Limpia periódicamente el directorio `extracted/` para liberar espacio

---

## 🧪 Pruebas

### Probar Extracción de XMLs
```bash
# Asumiendo que ya tienes un paquete descargado
PACKAGE_ID="pkg-001"

# Extraer XMLs
curl http://localhost:8000/api/v1/sat/paquete/${PACKAGE_ID}/extraer

# Verificar archivos extraídos
ls -lh storage/app/sat_downloads/extracted/${PACKAGE_ID}/
```

### Probar Lectura de Metadata
```bash
# Leer metadata
curl http://localhost:8000/api/v1/sat/paquete/${PACKAGE_ID}/metadata | jq .

# Contar registros
curl http://localhost:8000/api/v1/sat/paquete/${PACKAGE_ID}/metadata | \
  jq '.total_records'
```

---

## 📊 Resumen de APIs Completas

| # | Endpoint | Método | Descripción |
|---|----------|--------|-------------|
| 1 | `/api/v1/sat/solicitud` | POST | Crear solicitud de descarga |
| 2 | `/api/v1/sat/solicitud/{requestId}/verificar` | GET | Verificar estado de solicitud |
| 3 | `/api/v1/sat/solicitud/{requestId}/descargar` | GET | Descargar paquetes ZIP |
| 4 | `/api/v1/sat/paquete/{packageId}/extraer` | GET | **Extraer XMLs de un paquete** |
| 5 | `/api/v1/sat/paquete/{packageId}/metadata` | GET | **Leer metadata de un paquete** |

---

## ✅ Estado

**Implementación completada y lista para usar.**

Todas las APIs están funcionando y documentadas.

---

**Fecha de implementación:** 2025-10-09  
**Versión:** 1.1.0
