Search by

sat-suite / cfdi-status

xaamin

Consulta del estatus de un CFDI ante el SAT y generación de la expresión impresa

Package info

gitlab.com/sat-suite/cfdi-status

Issues

pkg:composer/sat-suite/cfdi-status

Statistics

Installs: 2 867

Dependents: 0

Suggesters: 0

Stars: 0

1.0.0 2026-11-14 19:34 UTC

This package is auto-updated.

Last update: 2026-11-20 17:17:30 UTC


README

Consulta el estatus de un CFDI ante el SAT con el servicio SOAP público ConsultaCFDIService: si está vigente o cancelado, si es cancelable (con o sin aceptación) y en qué estado va su cancelación. También genera la expresión impresa (la URL de verificación que va en el código QR de la representación impresa) a partir del XML timbrado o de sus datos, e incluye simuladores de respuestas para entornos sin acceso al SAT.

Es una pieza posterior al timbrado: sirve para verificar comprobantes emitidos o recibidos y para decidir y dar seguimiento a una cancelación (el XML de cancelación lo genera sat-suite/cfdi-cancel-xml). sat-suite/cfdi-validations lo usa para comprobar en vivo que un CFDI siga vigente.

Requisitos

  • PHP ^8.3
  • Extensiones: dom, libxml y simplexml
  • xaamin/xml-to-array ^1.0, xaamin/enum ^1.0 y sat-suite/support ^0.1.6 (se instalan como dependencias)
  • Sugeridos:
    • ext-openssl (y allow_url_fopen activo), que necesita el cliente HTTP por defecto (SimpleHttpClient) para conectarse al SAT por HTTPS.
    • guzzlehttp/guzzle, para usar GuzzleHttpClient.

Instalación

composer require sat-suite/cfdi-status

# Opcional, para usar GuzzleHttpClient
composer require guzzlehttp/guzzle

Uso

Consultar el estatus de un CFDI timbrado

use SatSuite\CfdiStatus\CfdiStatusQuery;
use SatSuite\CfdiStatus\Expressions\Comprobantes;

// Ruta o contenido del XML timbrado (también acepta DOMDocument o SimpleXMLElement).
// Detecta la versión (3.2, 3.3 o 4.0) y extrae RFCs, UUID del TFD, total y sello.
$expression = (new Comprobantes())->load('/ruta/al/cfdi.xml')->make();

$status = (new CfdiStatusQuery())->make($expression); // producción por defecto

if ($status->isValid() && $status->isCancellableWithNoApproval()) {
    // Vigente y se puede cancelar sin aceptación del receptor
}

Respuesta (SatSuite\CfdiStatus\Status\CfdiStatus)

Propiedades públicas con los textos del SAT (recortados; '' si no vienen):

PropiedadCampo del SATEjemplo
$status->consultaCodigoEstatusS - Comprobante obtenido satisfactoriamente.
$status->estadoEstadoVigente, Cancelado
$status->cancelableEsCancelableCancelable sin aceptación, Cancelable con aceptación, No cancelable
$status->cancelacionEstatusCancelacion'', En proceso, Cancelado sin aceptación, Cancelado con aceptación, Plazo vencido, Solicitud rechazada

Métodos:

MétodoDevuelve true cuando
found()CodigoEstatus empieza con S (el SAT encontró el comprobante).
isValid()Se encontró y Estado es Vigente.
isCancelled()Estado es Cancelado.
isCancellable() / isNotCancellable()EsCancelable es (o no es) "Cancelable con aceptación" o "Cancelable sin aceptación".
isCancellableWithApproval()EsCancelable es "Cancelable con aceptación".
isCancellableWithNoApproval()EsCancelable es "Cancelable sin aceptación".
isProcessing()EstatusCancelacion es "En proceso".
$status->toArray();   // respuesta normalizada del SAT: CodigoEstatus, EsCancelable, Estado y
                      // EstatusCancelacion siempre presentes, más los campos extra que envíe (p. ej. ValidacionEFOS)
(string) $status;     // la misma respuesta en JSON

// Enums (xaamin/enum) con los valores reconocidos; si el texto no coincide, quedan en "undefined"
$status->query();        // CfdiQueryStatus: isFound(), isNotFound()
$status->status();       // CfdiSatStatus: isValid(), isCancelled()
$status->cancellable();  // CfdiCancellable: isCancellableWithApproval(), isCancellableWithNoApproval()
$status->cancellation(); // CfdiCancellationStatus: isAuto(), isExpiration(), isApproved(), isProcessing(), isRejected()

Opciones de la consulta

use SatSuite\CfdiStatus\CfdiStatusQuery;
use SatSuite\CfdiStatus\Http\SimpleHttpClient;

$query = new CfdiStatusQuery(new SimpleHttpClient(['timeout' => 30, 'verify' => true, 'cafile' => null]));

$query->production(false); // usa el servicio de pruebas del SAT
$query->debugging(true);   // agrega la petición y la respuesta HTTP a getResult()

$status = $query->make($expression);

$query->getResult(); // ['success' => true, 'data' => [...], 'debug' => ['request' => [...], 'response' => [...]]]
EntornoEndpoint
Producción (production(true), por defecto)https://consultaqr.facturaelectronica.sat.gob.mx/ConsultaCFDIService.svc
Pruebas (production(false))https://pruebacfdiconsultaqr.cloudapp.net/ConsultaCFDIService.svc

Clientes HTTP (SatSuite\CfdiStatus\Http\), ambos con las opciones timeout (segundos, 30 por defecto), verify (verificación TLS, true por defecto) y cafile (ruta a un bundle de CA):

  • SimpleHttpClient (por defecto): file_get_contents con stream context.
  • GuzzleHttpClient: new GuzzleHttpClient($options, $client); el segundo argumento opcional es un GuzzleHttp\Client propio.

Para usar otro cliente, implementa SatSuite\CfdiStatus\Contracts\HttpClientInterface::call($url, $body, array $headers = []), que debe devolver ['status' => int, 'body' => string], y pásalo al constructor de CfdiStatusQuery.

Errores

Excepción (SatSuite\CfdiStatus\Exceptions\)Cuándo
SatServiceUnavailableExceptionEl SAT respondió con un código HTTP distinto de 200 (el código queda en getCode()). Si la conexión falla (DNS, TLS, timeout), los clientes lo reportan como HTTP 503.
InvalidSatResponseException (subclase de la anterior)HTTP 200 con cuerpo vacío, que no es XML o sin ConsultaResult.
UnexpectedValueExceptionAl generar la expresión: XML vacío o inválido, versión no soportada, o faltan Emisor, Receptor (CFDI), Totales (retenciones) o el TimbreFiscalDigital.

Expresión impresa / URL de verificación

use SatSuite\CfdiStatus\Expressions\Comprobantes;
use SatSuite\CfdiStatus\Expressions\Retenciones;

$expression = (new Comprobantes())->load($xmlTimbrado); // Comprobantes32, Comprobantes33 o Comprobantes40

$expression->values(); // ['rfc_emisor', 'rfc_receptor', 'uuid', 'total', 'sello']
$expression->make();   // expresión impresa que se envía a CfdiStatusQuery::make()
$expression->url();    // URL de verificación (la del código QR)

// Sin XML, a partir de los datos
$url = (new Comprobantes())->using('4.0')->make([
    'rfc_emisor' => 'EKU9003173C9',
    'rfc_receptor' => 'XAXX010101000',
    'uuid' => 'E7A2D1B0-1C3F-4A5B-9C8D-0123456789AB',
    'total' => 116,
    'sello' => '...', // se usan sus últimos 8 caracteres
]);
// https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=E7A2D1B0-...&re=EKU9003173C9&rr=XAXX010101000&tt=116.0&fe=<últimos 8 del sello>

// CFDI de Retenciones 1.0 y 2.0
$retencion = (new Retenciones())->load($xmlRetencion); // Retenciones10 o Retenciones20
$retencion->values(); // ['rfc_emisor', 'rfc_receptor_nacional', 'rfc_receptor_extranjero', 'uuid', 'total', 'sello']
$retencion->url();

Formato por versión:

Versiónmake()url()
CFDI 3.3 y 4.0La URL completa: https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=..&re=..&rr=..&tt=..&fe=..Igual que make()
CFDI 3.2?re=..&rr=..&tt=..&id=..https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?re=..&rr=..&tt=..&id=..&fe=..
Retenciones 1.0?re=..&rr=..&tt=..&id=.. (nr en lugar de rr si el receptor es extranjero)https://prodretencionverificacion.clouda.sat.gob.mx?re=..
Retenciones 2.0?id=..&re=..&rr=..&tt=..&fe=.. (nr si el receptor es extranjero)https://prodretencionverificacion.clouda.sat.gob.mx/?id=..
  • tt en 3.3, 4.0 y Retenciones 2.0: total con hasta 6 decimales, sin ceros finales y al menos un decimal (1160.5, 116.0). En 3.2: 17 caracteres rellenos con ceros a la izquierda (0000001160.500000). En Retenciones 1.0: 6 decimales (100.000000).
  • Los RFC se escapan para XML (& → &amp;).
  • El TFD sólo se busca dentro de Complemento; un XML sin timbrar lanza UnexpectedValueException.
  • Cada versión es una instancia compartida dentro de Comprobantes/Retenciones: para reutilizarla con otro XML llama de nuevo a load() o with().

Simulación (sin SAT)

CfdiStatusSimulation y CfdiCancellationSimulation devuelven arreglos con la misma forma que ConsultaResult, para construir un CfdiStatus en desarrollo o pruebas:

use SatSuite\CfdiStatus\Status\CfdiStatus;
use SatSuite\CfdiStatus\Simulation\CfdiStatusSimulation;
use SatSuite\CfdiStatus\Simulation\CfdiCancellationSimulation;

$meta = [
    'total' => 1000,
    'tipo' => 'I',                              // TipoDeComprobante
    'receptor_rfc' => 'XAXX010101000',
    'fecha_comprobante' => '2024-05-10 13:14:15',
    'fecha_cancelacion' => '2024-05-11 09:00:00',
];

// Estatus de un CFDI vigente: cancelable sin o con aceptación, o 'no_cancelable'
$status = new CfdiStatus((new CfdiStatusSimulation())->threshold(15)->simulate($meta));

// Resultado de solicitar la cancelación, a partir del estatus anterior.
// $type: null, 'no_cancelable', 'cancelado', 'autorizado', 'rechazado' u otro valor (pendiente de aceptación)
$result = (new CfdiCancellationSimulation())->simulate($status->toArray(), $meta, 'autorizado');
  • Se considera "cancelable sin aceptación" cuando el total es de hasta 5,000 en tipo I, el tipo es N, E o T, el receptor es un RFC genérico (XAXX010101000, XEXX010101000) o el comprobante se emitió dentro del umbral. Son aproximaciones de las reglas del SAT.
  • threshold($minutes) (15 por defecto) reemplaza en minutos tanto la ventana de 3 días posteriores a la emisión como el plazo de aceptación del receptor.
  • En CfdiCancellationSimulation::simulate(), si el CFDI es cancelable sin aceptación el resultado es "Cancelado sin aceptación" (salvo con 'no_cancelable'); sin $type, sigue vigente y cancelable con aceptación; con 'cancelado', 'autorizado' o 'rechazado' devuelve ese desenlace, y con cualquier otro valor la solicitud queda "En proceso" hasta que vence el umbral contado desde fecha_cancelacion, y después pasa a "Plazo vencido".

Notas de comportamiento

  • La petición SOAP usa SOAPAction: http://tempuri.org/IConsultaCFDIService/Consulta y envía la expresión en expresionImpresa dentro de un CDATA; es lo que espera el SAT.
  • La verificación TLS está activa por defecto. El host de pruebas del SAT puede requerir 'verify' => false o un cafile.
  • Los campos de ConsultaResult que llegan vacíos o con i:nil="true" se normalizan a ''.
  • En una respuesta exitosa getResult()['success'] siempre es true; los errores se reportan con excepciones.
  • La URL de verificación de Retenciones 2.0 sigue el mismo formato que la de CFDI 4.0; no se ha confirmado contra el SAT.

Desarrollo

composer install && npm install   # npm instala los hooks de husky (commitlint)
npm test                          # Pest
npm run lint:check                # phpcs PSR12 sobre src/ (npm run lint:fix para corregir)
npm run code:scan                 # phpstan nivel 5 con phpstan-baseline.neon

Las pruebas no salen a internet: usan respuestas SOAP de tests/Fixtures/soap/, un servidor local (php -S) que imita al SAT y otro HTTPS con certificado autofirmado para probar verify/cafile.

Los mensajes de commit siguen Conventional Commits. Para publicar una versión: npm run release (o release:patch|minor|major), que actualiza package.json, composer.json, CHANGELOG.md, hace el commit y crea la etiqueta vX.Y.Z; después, git push --follow-tags.

Licencia

MIT. Consulta LICENSE.