laravel-sat-catalogs/README.md

# 📦 Laravel SAT Catalogs

<p align="center">
    <a href="https://koneko.mx" target="_blank">
        <img src="https://git.koneko.mx/Koneko-ST/koneko-st/raw/branch/main/logo-images/horizontal-05.png" width="400" alt="Koneko Soluciones Tecnológicas Logo">
    </a>
</p>

<p align="center">
    <a href="https://koneko.mx"><img src="https://img.shields.io/badge/Website-koneko.mx-blue" alt="Sitio Web"></a>
    <a href="https://packagist.org/packages/koneko/laravel-sat-catalogs"><img src="https://img.shields.io/packagist/v/koneko/laravel-sat-catalogs" alt="Latest Stable Version"></a>
    <a href="https://packagist.org/packages/koneko/laravel-sat-catalogs"><img src="https://img.shields.io/packagist/l/koneko/laravel-sat-catalogs" alt="License"></a>
    <a href="https://git.koneko.mx/koneko"><img src="https://img.shields.io/badge/Git%20Server-Koneko%20Git-orange" alt="Servidor Git"></a>
    <a href="https://github.com/koneko-mx/laravel-sat-catalogs/actions/workflows/tests.yml"><img src="https://github.com/koneko-mx/laravel-sat-catalogs/actions/workflows/tests.yml/badge.svg" alt="Build Status"></a>
    <a href="https://github.com/koneko-mx/laravel-sat-catalogs/issues"><img src="https://img.shields.io/github/issues/koneko/laravel-sat-catalogs" alt="Issues"></a>
</p>

---

## 📌 Descripción

**Laravel SAT Catalogs** es un paquete diseñado para gestionar catálogos oficiales del **SAT** en Laravel, facilitando su extracción, conversión y consulta.

### ✨ Características:
- 🔹 Migraciones para la estructura de catálogos del SAT.
- 🔹 Conversión de archivos **XLS** del SAT a **CSV** mediante `CsvGeneratorService`.
- 🔹 Carga de datos en la base de datos desde CSV con `CsvDatabaseService`.
- 🔹 Consultas optimizadas mediante `SatCatalogService` con búsqueda flexible.
- 🔹 Integración con Select2 para autocompletado.
- 🔹 Kernel mínimo de Laravel mediante `bootstrap.php`.

---

## 📦 Instalación

Instalar vía **Composer**:

```bash
composer require koneko/laravel-sat-catalogs
```

Publicar archivos de configuración y migraciones:

```bash
php artisan vendor:publish --tag=sat-catalogs-seeders
```

---

## 📂 Estructura de archivos

```
laravel-sat-catalogs/
│── Console/Commands/                # Comandos Artisan para importar/exportar catálogos
│── database/migrations/              # Migraciones para catálogos del SAT
│── database/seeders/sat_cache/       # Archivos CSV generados
│── Models/                           # Modelos de catálogos SAT
│── Providers/SatCatalogsServiceProvider.php  # Proveedor de servicio
│── routes/admin.php                   # Rutas administrativas
│── Services/                          # Servicios de conversión y consulta de datos
└── README.md
```

---

## 🔍 Uso de `SatCatalogService`

### 📌 **Búsqueda de datos**
```php
use Koneko\SatCatalogs\Services\SatCatalogService;

// Buscar bancos que coincidan con "Banamex"
$bancos = SatCatalogService::searchCatalog('banco', 'Banamex');

// Obtener una clave de producto/servicio específica
$producto = SatCatalogService::searchCatalog('clave_prod_serv', '10101500');
```

### 📌 **Filtrar resultados**
```php
// Obtener municipios del estado de Jalisco
$municipios = SatCatalogService::searchCatalog('municipio', '', ['c_estado' => 'JAL']);

// Obtener colonias por código postal
$colonias = SatCatalogService::searchCatalog('colonia', '', ['c_codigo_postal' => '64000']);
```

### 📌 **Integración con Select2**
```php
$estados = SatCatalogService::searchCatalog('estado', '', ['select2Mode' => true]);
```
Salida esperada:
```php
[
    ['id' => 'JAL', 'text' => 'Jalisco'],
    ['id' => 'CDMX', 'text' => 'Ciudad de México'],
    ...
]
```

---

## 📂 Generación de CSV desde el archivo del SAT

El archivo **XLS** del SAT no está incluido en este repositorio por su tamaño y cambios frecuentes. Puedes descargarlo desde el sitio oficial:

🔗 [Descargar archivo XLS del SAT](http://omawww.sat.gob.mx/tramitesyservicios/Paginas/anexo_20.htm)

Una vez descargado, colócalo en:
database/data/catCFDI_V_4_xxxx.xls

---

## 🛠 Comandos Artisan disponibles

### 🔹 **Generar CSV desde XLS**
```bash
php artisan sat:generate-csv catCFDI_V_4_20250213.xls --all
```
Convierte el archivo `XLS` del SAT a `CSV` optimizado.

### 🔹 **Importar catálogos SAT a la base de datos**
```bash
php artisan sat:import-csv --update
```
Carga los archivos `CSV` en la base de datos.


## 🚀 Rutas Disponibles

| Método | Ruta | Controlador | Descripción |
|--------|------|------------|-------------|
| `POST` | `/catalogos/sat/get/{type}` | `SatCatalogController@catalogAjax` | Obtener datos de un catálogo vía AJAX. |

Ejemplo de consumo vía AJAX:
```js
$.post('/catalogos/sat/get/clave_prod_serv', { search: 'software' }, function(response) {
    console.log(response);
});
```

---

## 🛠 Dependencias

Este paquete requiere:
- Laravel 11+
- PHP 8.1+
- PhpSpreadsheet para la manipulación de archivos XLS.

---

## 🏗 Licencia

Este paquete es de código abierto bajo la licencia **MIT**.

---

<p align="center">
    Hecho con ❤️ por <a href="https://koneko.mx">Koneko Soluciones Tecnológicas</a>
</p>