daniel-monroy/sat-estado-cfdi

Paquete interno Laravel para consultar estado CFDI (SAT)

v0.0.5 2025-09-04 20:35 UTC

Requires

• php: ^8.3
• ext-dom: *
• guzzlehttp/guzzle: ^7.9
• laravel/framework: ^11.0|^12.0
• nyholm/psr7: ^1.8
• php-http/guzzle7-adapter: ^1.0
• phpcfdi/cfdi-expresiones: ^v3.3.0
• phpcfdi/sat-estado-cfdi: ^2.0

MIT

README

Este paquete integra la librería phpcfdi/sat-estado-cfdi a Laravel 11 / 12 para consultar el estado de un CFDI directamente en el servicio web del SAT.

El protocolo que utiliza el SAT para esta consulta es SOAP sobre HTTP/HTTPS, expuesto como servicio web.
Este paquete se conecta mediante el cliente HTTP (PSR-18), con compatibilidad para middlewares (reintentos, timeouts, logging, etc.).

📦 Instalación

Instálalo vía Composer:

composer require daniel-monroy/sat-estado-cfdi

⚙️ Configuración

Publica el archivo de configuración:

php artisan vendor:publish --tag="sat-estado-cfdi-config"

Ejemplo de configuración en config/sat-estado-cfdi.php:

return [
    'expose_routes' => env('SAT_ESTADO_EXPOSE_ROUTES', false),
    'route_prefix'  => env('SAT_ESTADO_ROUTE_PREFIX', 'api'),
    'middleware'    => ['api', 'auth:sanctum'],
    'cache_ttl'     => env('SAT_ESTADO_CACHE_TTL', 900), // segundos
];

En el archivo .env puedes definir:

SAT_ESTADO_EXPOSE_ROUTES=true
SAT_ESTADO_ROUTE_PREFIX=api
SAT_ESTADO_CACHE_TTL=900

📡 Endpoints expuestos (opcional)

Si SAT_ESTADO_EXPOSE_ROUTES está en true, se habilitan los siguientes endpoints:

Método	Endpoint	Descripción
POST	/api/cfdi/consulta	Consulta el estado de un CFDI
GET	/api/cfdi/estatus	Verifica que el servicio esté activo

El prefijo (/api) y el middleware (ej. auth, sanctum, etc.) pueden modificarse con la variable SAT_ESTADO_ROUTE_PREFIX y SAT_ESTADO_ROUTE_MIDDLEWARE.

Ejemplo de consulta

curl -X POST http://tu-dominio.test/api/sat-estado-cfdi/consulta \
-H "Content-Type: application/json" \
-d '{
  "expression": "id=12345678-1234-1234-1234-123456789012&re=AAA010101AAA&rr=BBB010101BBB&tt=1234.56"
}'

o con multipart/form-data enviando directamente el archivo XML:

curl -X POST http://tu-dominio.test/api/sat-estado-cfdi/
consulta \
-H "Content-Type: multipart/form-data" \
-F "xml=@/ruta/al/archivo.xml"

La respuesta será similar a:

{
  "ok": true,
  "estatus": "activo",
  "message": "El CFDI es válido y está activo.",
  "cancelabilidad": "sin_aceptacion",
  "cancelacion": "no_cancelado",
  "flags": {
    "isActive": true,
    "isCancelled": false,
    "isPendingCancel": false
  },
  "raw": {
    "query": {
      "isFound": true
    },
    "document": {
      "isActive": true,
      "isCancelled": false
    },
    "cancellable": {
      "isCancellableByDirect": true,
      "isCancellableByApproval": false
    },
    "cancellation": {
      "isCancelledByDirect": false,
      "isCancelledByApproval": false,
      "isCancelledByExpiration": false,
      "isPending": false,
      "isDisapproved": false,
      "isUndefined": false
    },
    "efos": "Excluded"
  }
}

🧪 Ejemplo de uso en código

use DanielMonroy\SatEstadoCfdi\Facades\SatEstado;

$expresion = '?re=AAA010101AAA&rr=BBB010101BBB&tt=123.450000&id=UUID...';
$status = SatEstado::consultByExpression($expresion);
if ($status->document->isActive()) {
    echo "El CFDI está activo";
}

📌 Notas

• El paquete se apoya en y utiliza la librería phpcfdi/sat-estado-cfdi
• El servicio del SAT puede ser intermitente, se recomienda configurar caché y reintentos.
• Los estados dependen de la respuesta oficial del SAT.

📄 Licencia Este paquete es software libre bajo la licencia MIT.