sat-suite / cfdi-status
Consulta del estatus de un CFDI ante el SAT y generación de la expresión impresa
Requires
- php: ^8.3
- ext-dom: *
- ext-libxml: *
- ext-simplexml: *
- sat-suite/support: ^1.0
- xaamin/enum: ^1.0
- xaamin/xml-to-array: ^1.0
Requires (Dev)
- guzzlehttp/guzzle: ^7.9
- pestphp/pest: ^3.0
- phpstan/phpstan: ^2.1
- squizlabs/php_codesniffer: ^3.8
Suggests
- ext-openssl: Required by SimpleHttpClient to reach the SAT over HTTPS
- guzzlehttp/guzzle: To perform http requests using the GuzzleHttpClient class
Provides
None
Conflicts
None
Replaces
None
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,libxmlysimplexml xaamin/xml-to-array ^1.0,xaamin/enum ^1.0ysat-suite/support ^0.1.6(se instalan como dependencias)- Sugeridos:
ext-openssl(yallow_url_fopenactivo), que necesita el cliente HTTP por defecto (SimpleHttpClient) para conectarse al SAT por HTTPS.guzzlehttp/guzzle, para usarGuzzleHttpClient.
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):
| Propiedad | Campo del SAT | Ejemplo |
|---|---|---|
$status->consulta | CodigoEstatus | S - Comprobante obtenido satisfactoriamente. |
$status->estado | Estado | Vigente, Cancelado |
$status->cancelable | EsCancelable | Cancelable sin aceptación, Cancelable con aceptación, No cancelable |
$status->cancelacion | EstatusCancelacion | '', En proceso, Cancelado sin aceptación, Cancelado con aceptación, Plazo vencido, Solicitud rechazada |
Métodos:
| Método | Devuelve 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' => [...]]]
| Entorno | Endpoint |
|---|---|
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_contentscon stream context.GuzzleHttpClient:new GuzzleHttpClient($options, $client); el segundo argumento opcional es unGuzzleHttp\Clientpropio.
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 |
|---|---|
SatServiceUnavailableException | El 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. |
UnexpectedValueException | Al 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ón | make() | url() |
|---|---|---|
| CFDI 3.3 y 4.0 | La 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=.. |
tten 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 (
&→&). - El TFD sólo se busca dentro de
Complemento; un XML sin timbrar lanzaUnexpectedValueException. - Cada versión es una instancia compartida dentro de
Comprobantes/Retenciones: para reutilizarla con otro XML llama de nuevo aload()owith().
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 esN,EoT, 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 desdefecha_cancelacion, y después pasa a "Plazo vencido".
Notas de comportamiento
- La petición SOAP usa
SOAPAction: http://tempuri.org/IConsultaCFDIService/Consultay envía la expresión enexpresionImpresadentro de unCDATA; es lo que espera el SAT. - La verificación TLS está activa por defecto. El host de pruebas del SAT puede requerir
'verify' => falseo uncafile. - Los campos de
ConsultaResultque llegan vacíos o coni:nil="true"se normalizan a''. - En una respuesta exitosa
getResult()['success']siempre estrue; 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.