Laravel Factura MX — Facturación electrónica CFDI 4.0 para México

Paquete de Laravel para la facturación electrónica en México (CFDI 4.0): construcción del comprobante, sellado con el CSD del emisor, timbrado ante un PAC (Finkok), cancelación, consulta de estatus ante el SAT, recuperación de XML timbrados y generación del PDF legible con el QR oficial de verificación del SAT.

La documentación está en español porque es el idioma natural de los tecnicismos del SAT (Anexo 20).

📖 Mapa funcional de la librería — todo lo que hace y con qué método: ciclo de vida del CFDI, las 8 áreas de funcionalidad, matriz de cobertura por tipo de comprobante, excepciones y configuración.

Características

• Construcción fluida del CFDI 4.0 (ingreso, egreso/nota de crédito y complemento de pago) sobre eclipxe/cfdiutils.
• Validación local (XSD + reglas SAT) antes de enviar al PAC — los CFDI malformados no queman intentos de timbrado.
• Timbrado con Finkok resistente a sus estados no documentados: Comprobante timbrado previamente (307), timbrado asíncrono en cola, recuperación del resultado original vía stamped — todo normalizado en una sola respuesta (getCheckProcess()).
• Guard anti-doble-timbrado y guard de la ventana de 72 horas del SAT.
• Errores como excepciones tipadas (FacturaMxException y subclases) — seguras para colas y comandos, nunca abort().
• Logs SOAP por operación en storage/logs/cfdi_finkok_*.log (con la contraseña del PAC redactada), también cuando la llamada falla.
• Persistencia post-timbrado opcional (estatus, UUID, XML, PDF, limpieza de borradores) o control total desde tu aplicación.
• Catálogos oficiales del SAT 4.0 servidos desde una base SQLite de solo lectura.

Requisitos

• PHP ^8.2 con ext-soap y ext-intl
• Laravel (el paquete se desarrolla con Orchestra Testbench)
• Una cuenta con el PAC (Finkok) — demo o producción
• El CSD del emisor (.cer, .key y contraseña) emitido por el SAT

Instalación

composer require jiagbrody/laravel-factura-mx

Publica el archivo de configuración:

php artisan vendor:publish --tag="jiagbrody-laravel-factura-mx-config"

Las migraciones se cargan directamente desde el paquete (no necesitas publicarlas):

php artisan migrate

Los nombres de las tablas (prefijo jiagbrody_lfmx_*) son configurables en table_names, solo antes de correr las migraciones.

Configuración esencial

FACTURA_MX_FINKOK_USER=tu_usuario_finkok
FACTURA_MX_FINKOK_PASSWORD=tu_password_finkok

Uso

Crear un CFDI de ingreso (borrador sellado)

use JiagBrody\LaravelFacturaMx\Facades\LaravelFacturaMx;
use JiagBrody\LaravelFacturaMx\Models\InvoiceCompany;
use JiagBrody\LaravelFacturaMx\Sat\InvoiceSatData\{ComprobanteAtributos, ReceptorAtributos, ConceptoAtributos, ImpuestoTrasladoAtributos};

$company = InvoiceCompany::find(1); // el emisor (con su CSD registrado)

$voucher = LaravelFacturaMx::create()->ingreso()->custom($company);

$atributos = new ComprobanteAtributos;   // Fecha default: ahora, en default_timezone
$atributos->setSerie('A');
$atributos->setFolio('1');
$atributos->setFormaPago('01');
$atributos->setMetodoPago('PUE');
$atributos->setMoneda('MXN');
$atributos->setTipoDeComprobante('I');
$atributos->setExportacion('01');
$atributos->setLugarExpedicion('63732');
$voucher->addAtributos($atributos);

$receptor = new ReceptorAtributos;
$receptor->setRfc('XAXX010101000');
$receptor->setNombre('PUBLICO EN GENERAL');
$voucher->addReceptor($receptor);

// ... addConceptos(), addRelacionados(), addComplementoImpuestosLocales() ...

$invoice = $voucher->build()->createNewInvoice(); // valida, sella y persiste el borrador

Timbrar

$response = LaravelFacturaMx::invoiceStamper($invoice)->build();

if ($response->getCheckProcess()) {
    $uuid = $response->getUuid();   // UUID fiscal
    $xml = $response->getXml();     // XML timbrado
} else {
    $motivo = $response->getIncidenciaMensaje(); // incidencia del PAC (también se guarda en invoice_incidents)
}

Con persist_stamp_result = true (default), el timbrado exitoso deja la factura vigente con su CFDI, XML, PDF y sin borradores — en la misma llamada.

Cancelar, estatus y recuperación

use JiagBrody\LaravelFacturaMx\Enums\InvoiceCfdiCancelTypeEnum;

// Cancelación ante el SAT (persiste el acuse cuando procede)
$cancel = LaravelFacturaMx::invoiceCanceller($invoice)
    ->setCancelTypeEnum(InvoiceCfdiCancelTypeEnum::NEW_NOT_EXECUTED)
    ->build();

// Estatus del CFDI ante el SAT (total = string EXACTO impreso en el CFDI)
$status = LaravelFacturaMx::status()
    ->setInvoice($invoice)
    ->setReceptorRfc('XAXX010101000')
    ->setTotal('612.90')
    ->build();
// $status->estado, $status->esCancelable, $status->invoiceStatusEnum (null si el SAT no lo reconoce)

// Recuperar el XML timbrado (get_xml y, si el PAC no lo indexa, fallback vía "stamped")
$xml = LaravelFacturaMx::RecoveryCfdiXmlFile()->setInvoice($invoice)->build();

Manejo de errores

Todo fallo del paquete lanza JiagBrody\LaravelFacturaMx\Exceptions\FacturaMxException o una subclase:

Testing

composer test      # Pest
composer analyse   # PHPStan (larastan)
composer format    # Pint

Los tests que sellan un CFDI real se saltan si no encuentras el CSD de pruebas oficial del SAT (EKU9003173C9) en sat_files_path — ver tests/Pest.php. Los tests de contrato del PAC corren siempre: usan respuestas SOAP reales grabadas del demo de Finkok.

Checklist para producción

1. pac_environment_production => true y credenciales productivas del PAC en .env.
2. CSD reales de los emisores en sat_files_path (carpeta fuera del acceso público).
3. filesystem_disk privado (los CFDI llevan datos personales).
4. Verifica en los primeros timbrados los logs storage/logs/cfdi_finkok_*.log.

Changelog / Contributing / Security

Ver CHANGELOG, CONTRIBUTING y la política de seguridad.

Créditos y licencia

• J. Israel Alvarez G. (Brody)
• Construido sobre eclipxe/cfdiutils y phpcfdi/credentials.

The MIT License (MIT). Ver License File.