# 🚀 API Laravel 12 - Guía de Uso

## 📋 Descripción
Proyecto Laravel 12 configurado para desarrollo de APIs RESTful con autenticación mediante Laravel Sanctum.

**Incluye integración con el servicio de Descarga Masiva del SAT** para la descarga de CFDIs mediante la librería `phpcfdi/sat-ws-descarga-masiva`.

## ⚙️ Tecnologías
- **Laravel**: 12.33.0
- **PHP**: 8.2+
- **Laravel Sanctum**: 4.2.0
- **SAT WS Descarga Masiva**: 1.1+ (phpcfdi)
- **Base de datos**: SQLite (por defecto)

## 🏁 Inicio Rápido

### 1. Levantar el servidor de desarrollo
```bash
cd /Users/sergio.flores/Documents/Soliat/sispac/descargaWS/api-project
php artisan serve
```

El servidor estará disponible en: `http://localhost:8000`

### 2. Ver todas las rutas disponibles
```bash
php artisan route:list
```

## 📡 Endpoints Disponibles

### Rutas Públicas

#### 🔍 Test de Conexión
```http
GET /api/test
```
**Respuesta:**
```json
{
  "message": "¡API funcionando correctamente!",
  "version": "1.0.0",
  "timestamp": "2024-10-09 16:50:15"
}
```

#### 💚 Health Check
```http
GET /api/v1/health
```
**Respuesta:**
```json
{
  "status": "ok",
  "service": "API Laravel 12",
  "timestamp": "2024-10-09T16:50:15-06:00"
}
```

#### ℹ️ Información del Sistema
```http
GET /api/v1/info
```

### Rutas CRUD de Ejemplo (Públicas)

#### Listar Todos
```http
GET /api/v1/ejemplos
```

#### Obtener Uno
```http
GET /api/v1/ejemplos/{id}
```
**Ejemplo:** `GET /api/v1/ejemplos/1`

#### Crear Nuevo
```http
POST /api/v1/ejemplos
Content-Type: application/json

{
  "nombre": "Mi Ejemplo",
  "descripcion": "Descripción del ejemplo"
}
```

#### Actualizar
```http
PUT /api/v1/ejemplos/{id}
Content-Type: application/json

{
  "nombre": "Ejemplo Actualizado",
  "descripcion": "Nueva descripción"
}
```

#### Eliminar
```http
DELETE /api/v1/ejemplos/{id}
```

### Rutas Protegidas (Requieren Autenticación)

#### Obtener Usuario Autenticado
```http
GET /api/user
Authorization: Bearer {token}
```

#### CRUD Protegido
```http
GET /api/recursos-protegidos
Authorization: Bearer {token}
```

### 🏛️ API SAT Descarga Masiva

Para la documentación completa de las APIs del SAT, consulta:
- **[SAT_API_DOCS.md](SAT_API_DOCS.md)** - Documentación detallada de las APIs
- **[SAT_EJEMPLOS.md](SAT_EJEMPLOS.md)** - Ejemplos de uso con cURL, Postman y scripts
- **[SAT_RESUMEN.md](SAT_RESUMEN.md)** - Resumen de la implementación
- **[COMANDOS_UTILES.md](COMANDOS_UTILES.md)** - Comandos útiles para el proyecto

#### Endpoints Disponibles

##### 1. Crear Solicitud de Descarga
```http
POST /api/v1/sat/solicitud
Content-Type: application/json

{
  "fecha_inicio": "2024-01-01 00:00:00",
  "fecha_fin": "2024-01-31 23:59:59"
}
```

##### 2. Verificar Estado de Solicitud
```http
GET /api/v1/sat/solicitud/{requestId}/verificar
```

##### 3. Descargar Paquetes
```http
GET /api/v1/sat/solicitud/{requestId}/descargar
```

##### 4. Extraer XMLs de un Paquete
```http
GET /api/v1/sat/paquete/{packageId}/extraer
```

##### 5. Leer Metadata de un Paquete
```http
GET /api/v1/sat/paquete/{packageId}/metadata
```

**Prueba rápida:**
```bash
./test_sat_api.sh
```

## 🔐 Autenticación con Sanctum

### Configurar un Usuario para API

1. **Crear un usuario (puedes usar tinker):**
```bash
php artisan tinker
```

```php
$user = \App\Models\User::create([
    'name' => 'Usuario API',
    'email' => 'api@example.com',
    'password' => bcrypt('password123')
]);

// Crear un token para el usuario
$token = $user->createToken('api-token')->plainTextToken;
echo $token;
```

2. **Usar el token en tus peticiones:**
```http
Authorization: Bearer {tu-token-generado}
```

## 🛠️ Comandos Útiles

### Crear un Nuevo Controlador
```bash
php artisan make:controller Api/TuControlador --api
```

### Crear un Modelo con Migración
```bash
php artisan make:model TuModelo -m
```

### Ejecutar Migraciones
```bash
php artisan migrate
```

### Refrescar Migraciones (⚠️ Borra datos)
```bash
php artisan migrate:fresh
```

### Crear un Seeder
```bash
php artisan make:seeder TuSeeder
```

### Ejecutar Seeders
```bash
php artisan db:seed
```

### Limpiar Caché
```bash
php artisan cache:clear
php artisan config:clear
php artisan route:clear
```

## 📝 Estructura de Respuestas API

### Respuesta Exitosa
```json
{
  "success": true,
  "data": { ... },
  "message": "Operación exitosa"
}
```

### Respuesta con Error de Validación
```json
{
  "message": "The given data was invalid.",
  "errors": {
    "nombre": ["El campo nombre es obligatorio."]
  }
}
```

## 🧪 Testing

### Ejecutar Tests
```bash
php artisan test
```

### Crear un Test
```bash
php artisan make:test Api/TuTest
```

## 📦 Instalación de Paquetes Adicionales

### Instalar un paquete con Composer
```bash
composer require nombre/paquete
```

### Paquetes Recomendados para APIs
```bash
# Documentación API con Swagger
composer require darkaonline/l5-swagger

# Rate Limiting avanzado
composer require spatie/laravel-rate-limiting

# Recursos API
composer require spatie/laravel-fractal

# CORS (ya incluido en Laravel)
# Configuración en config/cors.php
```

## 🔒 Configuración de CORS

El archivo `config/cors.php` ya está configurado para permitir peticiones desde cualquier origen. En producción, modifica:

```php
'allowed_origins' => ['https://tudominio.com'],
```

## 🌍 Variables de Entorno

Edita el archivo `.env` para configurar tu aplicación:

```env
APP_NAME=MiAPI
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8000

DB_CONNECTION=sqlite
# O usa MySQL/PostgreSQL según necesites

SANCTUM_STATEFUL_DOMAINS=localhost:3000,localhost:8080
```

## 📚 Recursos Adicionales

- [Documentación Laravel 12](https://laravel.com/docs/12.x)
- [Laravel Sanctum](https://laravel.com/docs/12.x/sanctum)
- [API Resources](https://laravel.com/docs/12.x/eloquent-resources)
- [Validación](https://laravel.com/docs/12.x/validation)

## 🚀 Despliegue a Producción

1. Configurar variables de entorno en `.env`
2. Establecer `APP_ENV=production` y `APP_DEBUG=false`
3. Ejecutar optimizaciones:
```bash
php artisan config:cache
php artisan route:cache
php artisan view:cache
composer install --optimize-autoloader --no-dev
```

## 👨‍💻 Desarrollo

### Estructura Recomendada para APIs

```
app/
├── Http/
│   ├── Controllers/
│   │   └── Api/
│   │       ├── V1/          # Versionado de API
│   │       └── ...
│   ├── Requests/            # Form Requests para validación
│   ├── Resources/           # API Resources
│   └── Middleware/
├── Models/
└── Services/                # Lógica de negocio
```

## ✅ Checklist para Nuevas APIs

- [ ] Crear Modelo y Migración
- [ ] Crear Controlador en `Api/`
- [ ] Definir rutas en `routes/api.php`
- [ ] Implementar validación (Form Requests)
- [ ] Crear API Resources para respuestas
- [ ] Agregar autenticación si es necesario
- [ ] Documentar endpoints
- [ ] Crear tests

---

**¡Tu API Laravel 12 está lista para desarrollar! 🎉**
