# Ejemplos de Uso - API SAT Descarga Masiva

## Requisitos Previos

1. Asegúrate de que el servidor esté corriendo:
```bash
php artisan serve
```

2. La API estará disponible en: `http://localhost:8000`

---

## Ejemplo Completo con cURL

### 1. Crear Solicitud de Descarga

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

**Respuesta esperada:**
```json
{
    "success": true,
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status_code": 5000,
    "status_message": "Solicitud Aceptada",
    "fecha_inicio": "2024-01-01 00:00:00",
    "fecha_fin": "2024-01-31 23:59:59"
}
```

**Guarda el `request_id` para los siguientes pasos.**

---

### 2. Verificar Estado de la Solicitud

Reemplaza `{REQUEST_ID}` con el ID obtenido en el paso anterior:

```bash
curl -X GET http://localhost:8000/api/v1/sat/solicitud/{REQUEST_ID}/verificar \
  -H "Accept: application/json"
```

**Ejemplo:**
```bash
curl -X GET http://localhost:8000/api/v1/sat/solicitud/a1b2c3d4-e5f6-7890-abcd-ef1234567890/verificar \
  -H "Accept: application/json"
```

**Respuestas posibles:**

**Solicitud en proceso:**
```json
{
    "success": true,
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status_code": 5003,
    "status_message": "Solicitud en Proceso",
    "code_request": 5003,
    "number_cfdi": 0,
    "packages": [],
    "package_count": 0
}
```

**Solicitud lista para descargar:**
```json
{
    "success": true,
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status_code": 5004,
    "status_message": "Solicitud Procesada",
    "code_request": 5004,
    "number_cfdi": 250,
    "packages": [
        "pkg-001",
        "pkg-002"
    ],
    "package_count": 2
}
```

**Nota:** Repite este paso cada 30-60 segundos hasta que `status_code` sea `5004`.

---

### 3. Descargar los Paquetes

Cuando el `status_code` sea `5004`, descarga los paquetes:

```bash
curl -X GET http://localhost:8000/api/v1/sat/solicitud/{REQUEST_ID}/descargar \
  -H "Accept: application/json"
```

**Ejemplo:**
```bash
curl -X GET http://localhost:8000/api/v1/sat/solicitud/a1b2c3d4-e5f6-7890-abcd-ef1234567890/descargar \
  -H "Accept: application/json"
```

**Respuesta esperada:**
```json
{
    "success": true,
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "total_packages": 2,
    "downloaded": 2,
    "failed": 0,
    "packages": [
        {
            "package_id": "pkg-001",
            "filename": "package_pkg-001.zip",
            "filepath": "/path/to/storage/app/sat_downloads/package_pkg-001.zip",
            "size": 2048576,
            "status": "downloaded"
        },
        {
            "package_id": "pkg-002",
            "filename": "package_pkg-002.zip",
            "filepath": "/path/to/storage/app/sat_downloads/package_pkg-002.zip",
            "size": 1536789,
            "status": "downloaded"
        }
    ],
    "errors": []
}
```

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

---

### 4. Extraer XMLs de un Paquete

Una vez descargados los paquetes, puedes extraer los archivos XML:

```bash
curl -X GET http://localhost:8000/api/v1/sat/paquete/{PACKAGE_ID}/extraer \
  -H "Accept: application/json"
```

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

**Respuesta esperada:**
```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
        }
    ]
}
```

Los archivos XML extraídos se guardan en: `storage/app/sat_downloads/extracted/{package_id}/`

---

### 5. Leer Metadata de un Paquete

Para obtener solo la información de los CFDIs sin extraer los archivos:

```bash
curl -X GET http://localhost:8000/api/v1/sat/paquete/{PACKAGE_ID}/metadata \
  -H "Accept: application/json"
```

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

**Respuesta esperada:**
```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
        }
    ]
}
```

---

## Ejemplo con Postman

### Colección de Postman

Puedes importar esta colección en Postman:

```json
{
    "info": {
        "name": "SAT Descarga Masiva API",
        "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
    },
    "item": [
        {
            "name": "1. Crear Solicitud",
            "request": {
                "method": "POST",
                "header": [
                    {
                        "key": "Content-Type",
                        "value": "application/json"
                    },
                    {
                        "key": "Accept",
                        "value": "application/json"
                    }
                ],
                "body": {
                    "mode": "raw",
                    "raw": "{\n    \"fecha_inicio\": \"2024-01-01 00:00:00\",\n    \"fecha_fin\": \"2024-01-31 23:59:59\"\n}"
                },
                "url": {
                    "raw": "http://localhost:8000/api/v1/sat/solicitud",
                    "protocol": "http",
                    "host": ["localhost"],
                    "port": "8000",
                    "path": ["api", "v1", "sat", "solicitud"]
                }
            }
        },
        {
            "name": "2. Verificar Solicitud",
            "request": {
                "method": "GET",
                "header": [
                    {
                        "key": "Accept",
                        "value": "application/json"
                    }
                ],
                "url": {
                    "raw": "http://localhost:8000/api/v1/sat/solicitud/{{request_id}}/verificar",
                    "protocol": "http",
                    "host": ["localhost"],
                    "port": "8000",
                    "path": ["api", "v1", "sat", "solicitud", "{{request_id}}", "verificar"]
                }
            }
        },
        {
            "name": "3. Descargar Paquetes",
            "request": {
                "method": "GET",
                "header": [
                    {
                        "key": "Accept",
                        "value": "application/json"
                    }
                ],
                "url": {
                    "raw": "http://localhost:8000/api/v1/sat/solicitud/{{request_id}}/descargar",
                    "protocol": "http",
                    "host": ["localhost"],
                    "port": "8000",
                    "path": ["api", "v1", "sat", "solicitud", "{{request_id}}", "descargar"]
                }
            }
        }
    ],
    "variable": [
        {
            "key": "request_id",
            "value": "",
            "type": "string"
        }
    ]
}
```

**Pasos en Postman:**

1. Importa la colección JSON
2. Ejecuta "1. Crear Solicitud"
3. Copia el `request_id` de la respuesta
4. Pega el `request_id` en la variable de colección
5. Ejecuta "2. Verificar Solicitud" hasta que el status sea 5004
6. Ejecuta "3. Descargar Paquetes"

---

## Script de Automatización (Bash)

Aquí hay un script que automatiza todo el proceso:

```bash
#!/bin/bash

# Configuración
API_URL="http://localhost:8000/api/v1/sat"
FECHA_INICIO="2024-01-01 00:00:00"
FECHA_FIN="2024-01-31 23:59:59"

echo "=== SAT Descarga Masiva - Script Automatizado ==="
echo ""

# Paso 1: Crear solicitud
echo "Paso 1: Creando solicitud..."
RESPONSE=$(curl -s -X POST "${API_URL}/solicitud" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d "{\"fecha_inicio\": \"${FECHA_INICIO}\", \"fecha_fin\": \"${FECHA_FIN}\"}")

echo "Respuesta: $RESPONSE"
echo ""

# Extraer request_id
REQUEST_ID=$(echo $RESPONSE | grep -o '"request_id":"[^"]*' | cut -d'"' -f4)

if [ -z "$REQUEST_ID" ]; then
    echo "Error: No se pudo obtener el request_id"
    exit 1
fi

echo "Request ID: $REQUEST_ID"
echo ""

# Paso 2: Verificar estado (polling)
echo "Paso 2: Verificando estado de la solicitud..."
STATUS_CODE=0
MAX_ATTEMPTS=60
ATTEMPT=0

while [ $STATUS_CODE -ne 5004 ] && [ $ATTEMPT -lt $MAX_ATTEMPTS ]; do
    ATTEMPT=$((ATTEMPT + 1))
    echo "Intento $ATTEMPT de $MAX_ATTEMPTS..."
    
    VERIFY_RESPONSE=$(curl -s -X GET "${API_URL}/solicitud/${REQUEST_ID}/verificar" \
      -H "Accept: application/json")
    
    STATUS_CODE=$(echo $VERIFY_RESPONSE | grep -o '"status_code":[0-9]*' | cut -d':' -f2)
    STATUS_MESSAGE=$(echo $VERIFY_RESPONSE | grep -o '"status_message":"[^"]*' | cut -d'"' -f4)
    
    echo "Estado: $STATUS_CODE - $STATUS_MESSAGE"
    
    if [ $STATUS_CODE -eq 5004 ]; then
        echo "¡Solicitud procesada y lista para descargar!"
        break
    elif [ $STATUS_CODE -eq 5005 ]; then
        echo "Error: Solicitud rechazada"
        exit 1
    fi
    
    echo "Esperando 30 segundos antes del siguiente intento..."
    sleep 30
done

if [ $STATUS_CODE -ne 5004 ]; then
    echo "Error: Tiempo de espera agotado"
    exit 1
fi

echo ""

# Paso 3: Descargar paquetes
echo "Paso 3: Descargando paquetes..."
DOWNLOAD_RESPONSE=$(curl -s -X GET "${API_URL}/solicitud/${REQUEST_ID}/descargar" \
  -H "Accept: application/json")

echo "Respuesta: $DOWNLOAD_RESPONSE"
echo ""

echo "=== Proceso completado ==="
```

**Uso del script:**

1. Guarda el script como `sat_descarga.sh`
2. Dale permisos de ejecución: `chmod +x sat_descarga.sh`
3. Edita las fechas si es necesario
4. Ejecuta: `./sat_descarga.sh`

---

## Manejo de Errores Comunes

### Error: Fecha inválida
```json
{
    "success": false,
    "message": "Error de validación",
    "errors": {
        "fecha_inicio": ["La fecha de inicio debe tener el formato: Y-m-d H:i:s"]
    }
}
```
**Solución:** Usa el formato correcto: `YYYY-MM-DD HH:MM:SS`

### Error: Certificados no encontrados
```json
{
    "success": false,
    "message": "Error al crear la solicitud",
    "error": "Archivo CER no encontrado: /path/to/cert"
}
```
**Solución:** Verifica que los archivos de certificados existan en `storage/certs/`

### Error: Contraseña incorrecta
```json
{
    "success": false,
    "message": "Error al crear la solicitud",
    "error": "Invalid password"
}
```
**Solución:** Verifica que la contraseña en `SATDescargaMasivaService.php` sea correcta

---

## Códigos de Estado del SAT

| Código | Descripción |
|--------|-------------|
| 5000 | Solicitud Aceptada |
| 5002 | Solicitud en Cola |
| 5003 | Solicitud en Proceso |
| 5004 | Solicitud Procesada (lista para descargar) |
| 5005 | Solicitud Rechazada |

---

## Notas Importantes

1. **Tiempo de Procesamiento**: El SAT puede tardar de 5 minutos a varias horas en procesar una solicitud, dependiendo del rango de fechas y la cantidad de CFDIs.

2. **Límite de Fechas**: El SAT tiene límites en el rango de fechas que puedes consultar. Generalmente no más de 1 mes por solicitud.

3. **Archivos ZIP**: Los archivos descargados son ZIPs que contienen XMLs de CFDIs. Necesitarás descomprimirlos para acceder a los archivos individuales.

4. **Almacenamiento**: Los archivos se guardan en `storage/app/sat_downloads/`. Asegúrate de tener suficiente espacio en disco.
