laravel-sat-catalogs/README.md

📦 Laravel SAT Catalogs

---

📌 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:

composer require koneko/laravel-sat-catalogs

Publicar archivos de configuración y migraciones:

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

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

// 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

$estados = SatCatalogService::searchCatalog('estado', '', ['select2Mode' => true]);

Salida esperada:

[
    ['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

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

---

🛠 Comandos Artisan disponibles

🔹 Generar CSV desde XLS

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

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:

$.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.

---

Hecho con ❤️ por Koneko Soluciones Tecnológicas