# Documentación API SAT Descarga Masiva

Esta API permite interactuar con el servicio de Descarga Masiva del SAT usando la librería `phpcfdi/sat-ws-descarga-masiva`.

## Configuración

Los certificados FIEL se encuentran en:
- **CER**: `storage/certs/foos851205ph8.cer`
- **KEY**: `storage/certs/Claveprivada_FIEL_FOOS851205PH8_20250509_115905.key`
- **Password**: `Flores01`

## Endpoints

### 1. Crear Solicitud de Descarga

Crea una nueva solicitud de descarga masiva de CFDIs.

**Endpoint**: `POST /api/v1/sat/solicitud`

**Headers**:
```
Content-Type: application/json
Accept: application/json
```

**Body**:
```json
{
    "fecha_inicio": "2019-01-13 00:00:00",
    "fecha_fin": "2019-01-13 23:59:59"
}
```

**Respuesta Exitosa** (200):
```json
{
    "success": true,
    "request_id": "b35ac93e-b5d7-4e63-9b49-0f5fbd86c2e8",
    "status_code": 5000,
    "status_message": "Solicitud Aceptada",
    "fecha_inicio": "2019-01-13 00:00:00",
    "fecha_fin": "2019-01-13 23:59:59"
}
```

**Respuesta de Error** (422):
```json
{
    "success": false,
    "message": "Error de validación",
    "errors": {
        "fecha_inicio": ["La fecha de inicio es requerida"],
        "fecha_fin": ["La fecha de fin debe ser posterior a la fecha de inicio"]
    }
}
```

---

### 2. Verificar Estado de Solicitud

Verifica el estado de una solicitud previamente creada.

**Endpoint**: `GET /api/v1/sat/solicitud/{requestId}/verificar`

**Parámetros de URL**:
- `requestId`: UUID de la solicitud (obtenido en el paso 1)

**Headers**:
```
Accept: application/json
```

**Respuesta Exitosa** (200):
```json
{
    "success": true,
    "request_id": "b35ac93e-b5d7-4e63-9b49-0f5fbd86c2e8",
    "status_code": 5000,
    "status_message": "Solicitud Aceptada",
    "code_request": 5000,
    "number_cfdi": 150,
    "packages": [
        "4e80345d-917f-40bb-a98f-4a73939343c5_01",
        "4e80345d-917f-40bb-a98f-4a73939343c5_02"
    ],
    "package_count": 2
}
```

**Códigos de Estado Comunes**:
- `5000`: Solicitud Aceptada
- `5003`: Solicitud en Proceso
- `5004`: Solicitud Procesada (lista para descargar)
- `5005`: Solicitud Rechazada

---

### 3. Descargar Paquetes

Descarga los paquetes ZIP de una solicitud procesada.

**Endpoint**: `GET /api/v1/sat/solicitud/{requestId}/descargar`

**Parámetros de URL**:
- `requestId`: UUID de la solicitud (obtenido en el paso 1)

**Headers**:
```
Accept: application/json
```

**Respuesta Exitosa** (200):
```json
{
    "success": true,
    "request_id": "b35ac93e-b5d7-4e63-9b49-0f5fbd86c2e8",
    "total_packages": 2,
    "downloaded": 2,
    "failed": 0,
    "packages": [
        {
            "package_id": "4e80345d-917f-40bb-a98f-4a73939343c5_01",
            "filename": "package_4e80345d-917f-40bb-a98f-4a73939343c5_01.zip",
            "filepath": "/path/to/storage/app/sat_downloads/package_4e80345d-917f-40bb-a98f-4a73939343c5_01.zip",
            "size": 1024567,
            "status": "downloaded"
        },
        {
            "package_id": "4e80345d-917f-40bb-a98f-4a73939343c5_02",
            "filename": "package_4e80345d-917f-40bb-a98f-4a73939343c5_02.zip",
            "filepath": "/path/to/storage/app/sat_downloads/package_4e80345d-917f-40bb-a98f-4a73939343c5_02.zip",
            "size": 987654,
            "status": "downloaded"
        }
    ],
    "errors": []
}
```

**Nota**: Los archivos ZIP se guardan en `storage/app/sat_downloads/`

---

### 4. Extraer XMLs de un Paquete

Extrae los archivos XML de un paquete ZIP descargado.

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

**Parámetros de URL**:
- `packageId`: ID del paquete (obtenido en el paso 3)

**Headers**:
```
Accept: application/json
```

**Respuesta Exitosa** (200):
```json
{
    "success": true,
    "package_id": "4e80345d-917f-40bb-a98f-4a73939343c5_01",
    "zip_file": "/path/to/storage/app/sat_downloads/package_4e80345d-917f-40bb-a98f-4a73939343c5_01.zip",
    "extract_directory": "/path/to/storage/app/sat_downloads/extracted/4e80345d-917f-40bb-a98f-4a73939343c5_01",
    "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/4e80345d-917f-40bb-a98f-4a73939343c5_01/12345678-1234-1234-1234-123456789012.xml",
            "size": 34952
        },
        {
            "uuid": "87654321-4321-4321-4321-210987654321",
            "filename": "87654321-4321-4321-4321-210987654321.xml",
            "filepath": "/path/to/storage/app/sat_downloads/extracted/4e80345d-917f-40bb-a98f-4a73939343c5_01/87654321-4321-4321-4321-210987654321.xml",
            "size": 28764
        }
    ]
}
```

**Nota**: Los archivos XML se guardan en `storage/app/sat_downloads/extracted/{packageId}/`

---

### 5. Leer Metadata de un Paquete

Lee la metadata de un paquete ZIP sin extraer los archivos.

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

**Parámetros de URL**:
- `packageId`: ID del paquete (obtenido en el paso 3)

**Headers**:
```
Accept: application/json
```

**Respuesta Exitosa** (200):
```json
{
    "success": true,
    "package_id": "4e80345d-917f-40bb-a98f-4a73939343c5_01",
    "zip_file": "/path/to/storage/app/sat_downloads/package_4e80345d-917f-40bb-a98f-4a73939343c5_01.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
        }
    ]
}
```

**Nota**: Esta API es útil para revisar la información de los CFDIs sin necesidad de extraer todos los archivos XML.

---

## Flujo de Trabajo Completo

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

Guarda el `request_id` de la respuesta.

### Paso 2: Verificar el Estado (repetir hasta que status_code sea 5004)
```bash
curl -X GET http://localhost:8000/api/v1/sat/solicitud/{request_id}/verificar \
  -H "Accept: application/json"
```

### Paso 3: Descargar los Paquetes (cuando status_code = 5004)
```bash
curl -X GET http://localhost:8000/api/v1/sat/solicitud/{request_id}/descargar \
  -H "Accept: application/json"
```

### Paso 4: Extraer XMLs de un Paquete (opcional)
```bash
curl -X GET http://localhost:8000/api/v1/sat/paquete/{package_id}/extraer \
  -H "Accept: application/json"
```

### Paso 5: Leer Metadata de un Paquete (opcional)
```bash
curl -X GET http://localhost:8000/api/v1/sat/paquete/{package_id}/metadata \
  -H "Accept: application/json"
```

---

## Manejo de Errores

Todas las APIs pueden retornar errores en el siguiente formato:

```json
{
    "success": false,
    "message": "Descripción del error",
    "error": "Detalle técnico del error"
}
```

**Códigos HTTP**:
- `200`: Éxito
- `422`: Error de validación
- `500`: Error del servidor

---

## Notas Importantes

1. **Tiempo de Procesamiento**: El SAT puede tardar varios minutos en procesar una solicitud. Debes verificar periódicamente el estado.

2. **Límites del SAT**: El SAT tiene límites en cuanto a:
   - Rango de fechas por solicitud
   - Número de solicitudes simultáneas
   - Tamaño de los paquetes

3. **Archivos Descargados**: Los archivos ZIP contienen XMLs de CFDIs. Debes descomprimirlos para acceder a los archivos individuales.

4. **Seguridad**: Los certificados FIEL son sensibles. Asegúrate de que el directorio `storage/certs/` tenga los permisos adecuados y no esté expuesto públicamente.

---

## Instalación de Dependencias

Si aún no has instalado las dependencias, ejecuta:

```bash
composer install
```

La librería `phpcfdi/sat-ws-descarga-masiva` ya está incluida en el `composer.json`.
