phpcfdi/sat-estado-cfdi

Consulta el estado de un CFDI en el webservice del SAT

🇺🇸 This library contains helpers to consume the Servicio de Consulta de CFDI from SAT. The documentation of this project is in spanish as this is the natural language for intended audience.

🇲🇽 Esta librería se utiliza para consumir el Servicio de Consulta de CFDI del SAT. La documentación del proyecto está en español porque ese es el lenguaje de los usuarios que la utilizarán.

Esta librería solo permite verificar el estado de un CFDI Regular y no de CFDI de Retenciones e información de pagos. Para estos últimos, use la librería phpcfdi/sat-estado-retenciones.

Servicio de Consulta de CFDI del SAT:

Servicio productivo: https://consultaqr.facturaelectronica.sat.gob.mx/ConsultaCFDIService.svc
Servicio de pruebas: https://pruebacfdiconsultaqr.cloudapp.net/ConsultaCFDIService.svc
SAT: https://www.sat.gob.mx/consultas/20585/conoce-los-servicios-especializados-de-validacion
Documentación del Servicio de Consulta de CFDIVersión 1.4 (noviembre 2022): https://www.sat.gob.mx/cs/Satellite?blobcol=urldata&blobkey=id&blobtable=MungoBlobs&blobwhere=1461175223997&ssbinary=true

Cambios recientes en el servicio:

Por motivo del cambio en el proceso de cancelación, en 2018 agregaron nuevos estados.
Por una razón desconocida e inexplicable, el WSDL no estuvo disponible de 2018 a 2020. Esta librería usa una estrategia en donde no depende del WSDL para consumir el servicio.
A finales de 2020 agregaron el campo de respuesta VerificacionEFOS.

Instalación

Usa composer

composer require phpcfdi/sat-estado-cfdi

Ejemplo básico de uso

Los pasos básicos son:

Tener un cliente que implemente ConsumerClientInterface.
Crear un consumidor del servicio Consumer
Realizar la solicitud con una expresión definida.
Usar el resultado

<?php
use PhpCfdi\SatEstadoCfdi\Consumer;
use PhpCfdi\SatEstadoCfdi\Contracts\ConsumerClientInterface;

/** @var ConsumerClientInterface $client */
$consumer = new Consumer($client);

$cfdiStatus = $consumer->execute('...expression');

if ($cfdiStatus->cancellable->isNotCancellable()) {
    echo 'CFDI no es cancelable';
}

Clientes de consumo `ConsumerClientInterface`

Esta librería incluye dos diferentes clientes de consumo: SoapConsumerClient y HttpConsumerClient.

Además, puedes usar tu propio cliente de consumo implementando la interface ConsumerClientInterface.

Cliente SOAP `SoapConsumerClient`

El cliente SoapConsumerClient permite hacer el consumo usando la estrategia SOAP.

Requerimientos:

ext-soap: Extensión SOAP de PHP.

Ejemplo:

<?php
use PhpCfdi\SatEstadoCfdi\Clients\Soap\SoapConsumerClient;
use PhpCfdi\SatEstadoCfdi\Consumer;

function createConsumerUsingSoap(): Consumer
{
    $client = new SoapConsumerClient();
    return new Consumer($client);
}

Cliente HTTP PSR `HttpConsumerClient`

El cliente HttpConsumerClient permite hacer el consumo usando la estrategia HTTP con base en los estándares PSR.

Estándares utilizados:

PSR-18: HTTP Client: Interfaces para clientes HTTP (el que hace la llamada POST). https://www.php-fig.org/psr/psr-18/
PSR-17: HTTP Factories: Interfaces de fábricas de HTTP Request y Response (para PSR-7). https://www.php-fig.org/psr/psr-17/

Las librerías de Guzzle guzzlehttp/guzzle, y guzzlehttp/psr7 proveen los estándares necesarios.

O puedes ver en Packagist los que te agraden:

Requerimientos:

ext-dom: Extensión DOM de PHP.
psr/http-client: ^1.0: Estándar PSR-18 (Cliente HTTP).
psr/http-factory: ^1.0: Estándar PSR-17 (Fábricas de mensajes HTTP).
Algunas librerías que implementen PSR-18 y PSR-17, por ejemplo:
- Guzzle: guzzlehttp/guzzle y guzzlehttp/psr7.
- Symfony: symfony/http-client y nyholm/psr7 o laminas/laminas-diactoros.

Ejemplo:

<?php
use PhpCfdi\SatEstadoCfdi\Clients\Http\HttpConsumerClient;
use PhpCfdi\SatEstadoCfdi\Clients\Http\HttpConsumerFactory;
use PhpCfdi\SatEstadoCfdi\Consumer;

function createConsumerUsingGuzzle(): Consumer
{
    // Implements PSR-18 \Psr\Http\Client\ClientInterface
    $guzzleClient = new \GuzzleHttp\Client();
    // Implements PSR-17 \Psr\Http\Message\RequestFactoryInterface and PSR-17 \Psr\Http\Message\StreamFactoryInterface
    $guzzleFactory = new \GuzzleHttp\Psr7\HttpFactory();

    $factory = new HttpConsumerFactory($guzzleClient, $guzzleFactory, $guzzleFactory);
    $client = new HttpConsumerClient($factory);
    return new Consumer($client);
}

El siguiente es un ejemplo usando symfony/http-client y nyholm/psr7:

use PhpCfdi\SatEstadoCfdi\Consumer;
use PhpCfdi\SatEstadoCfdi\Clients\Http\HttpConsumerClient;
use PhpCfdi\SatEstadoCfdi\Clients\Http\HttpConsumerFactory;

function createConsumerUsingSymfonyNyholm(): Consumer
{
    $httpClient = new \Symfony\Component\HttpClient\Psr18Client();
    $messageFactory = new \Nyholm\Psr7\Factory\Psr17Factory();
    
    $factory = new HttpConsumerFactory($httpClient, $messageFactory, $messageFactory);
    $client = new HttpConsumerClient($factory);
    return new Consumer($client);
}

Para Laravel puedes usar algún paquete adicional como wimski/laravel-psr-http, que gracias al uso del propio framework y php-http/discovery, facilita la creación de los objetos, ya sea que los fabrique directamente usando el contenedor, o bien los inyecte como dependencias.

<?php
use PhpCfdi\SatEstadoCfdi\Consumer;
use PhpCfdi\SatEstadoCfdi\Clients\Http\HttpConsumerClient;
use PhpCfdi\SatEstadoCfdi\Clients\Http\HttpConsumerFactory;

function createConsumerUsingLaravel(): Consumer
{
    $httpClient = app(\Psr\Http\Client\ClientInterface::class);
    $requestFactory = app(Psr\Http\Message\RequestFactoryInterface::class);
    $streamFactory = app(Psr\Http\Message\StreamFactoryInterface::class);
    
    $factory = new HttpConsumerFactory($httpClient, $requestFactory, $streamFactory);
    $client = new HttpConsumerClient($factory);
    return new Consumer($client);
}

También te recomiendo hacer tu propio Service Provider o configurar el Service Container y solo requerir la clase Consumer como cualquier otra dependencia y permitir que sea inyectada.

Expresiones (input)

El consumidor requiere una expresión para poder consultar. La expresión es el texto que viene en el código QR de la representación impresa de un CFDI.

Las expresiones son diferentes para CFDI 3.2, CFDI 3.3, CFDI 4.0, RET 1.0 y RET 2.0. Tienen reglas específicas de formato y de la información que debe contener.

Si no cuentas con la expresión, te recomiendo usar la librería phpcfdi/cfdi-expresiones que puedes instalar usando composer require phpcfdi/cfdi-expresiones.

<?php
use PhpCfdi\CfdiExpresiones\DiscoverExtractor;
use PhpCfdi\SatEstadoCfdi\Consumer;

// lectura del contenido del CFDI
$document = new DOMDocument();
$document->load('archivo-cfdi.xml');

// creación de la expresión
$expressionExtractor = new DiscoverExtractor();
$expression = $expressionExtractor->extract($document);

// realizar la consulta con la expresión obtenida
/** @var Consumer $consumer */
$cfdiStatus = $consumer->execute($expression);

// usar el estado
if ($cfdiStatus->document->isActive()) {
    echo 'El CFDI se encuentra vigente';
}

Estados (salida)

Después de consumir el servicio, se responderá con un objeto CfdiStatus que agrupa de los cuatro estados.

Los estados son enumeradores, puedes compararlos rápidamente usando métodos de ayuda is*, por ejemplo: $response->document->isCancelled().

Posibles estados:

CodigoEstatus: query: QueryStatus.
- Found: Si el estado inicia con S - .
- NotFound: en cualquier otro caso.
Estado: document: DocumentStatus.
- Active: Si el estado reportó Vigente.
- Cancelled: Si el estado reportó Cancelado.
- NotFound: en cualquier otro caso.
EsCancelable: cancellable: CancellableStatus.
- CancellableByDirectCall: Si el estado reportó Cancelable sin aceptación.
- CancellableByApproval: Si el estado reportó Cancelable con aceptación.
- NotCancellable: en cualquier otro caso.
EstatusCancelacion: cancellation: CancellationStatus.
- CancelledByDirectCall: Si el estado reportó Cancelado sin aceptación.
- CancelledByApproval: Si el estado reportó Cancelado con aceptación.
- CancelledByExpiration: Si el estado reportó Plazo vencido.
- Pending: Si el estado reportó En proceso.
- Disapproved: Si el estado reportó Solicitud rechazada.
- Undefined: en cualquier otro caso.
ValidacionEFOS: efos: EfosStatus.
- Included: Si el estado no reportó 200 o 201.
- Excluded: Si el estado reportó 200 o 201.

Estados mutuamente excluyentes

CodigoEstatus	Estado	EsCancelable	EstatusCancelacion	Explicación
N - ...	*	*	*	El SAT no sabe del CFDI con la expresión dada
S - ...	Cancelado	*	Plazo vencido	Cancelado por plazo vencido
S - ...	Cancelado	*	Cancelado con aceptación	Cancelado con aceptación del receptor
S - ...	Cancelado	*	Cancelado sin aceptación	No fue requerido preguntarle al receptor y se canceló
S - ...	Vigente	No cancelable	*	No se puede cancelar
S - ...	Vigente	Cancelable sin aceptación	*	Se puede cancelar, pero no se ha realizado la cancelación
S - ...	Vigente	Cancelable con aceptación	(ninguno)	Se puede cancelar, pero no se ha realizado la solicitud
S - ...	Vigente	Cancelable con aceptación	En proceso	Se hizo la solicitud y está en espera de respuesta
S - ...	Vigente	Cancelable con aceptación	Solicitud rechazada	Se hizo la solicitud y fue rechazada

Cuando tienes un CFDI en estado Cancelable con aceptación y mandas a hacer la cancelación entonces su estado de cancelación cambiaría a En proceso.

El receptor puede aceptar la cancelación (Cancelado con aceptación) o rechazarla (Solicitud rechazada).

Si es la primera vez que se hace la solicitud, el receptor tiene 72 horas para aceptarla o rechazarla, si no lo hace entonces automáticamente será cancelada (Plazo vencido).

Podrías volver a enviar la solicitud de cancelación por segunda vez aun cuando la solicitud fue previamente rechazada.

En ese caso, el receptor puede aceptar o rechazar la cancelación, pero ya no aplicará un lapso de 72 horas. Por lo anterior entonces podrías tener el CFDI en estado de cancelación en proceso indefinidamente. Incluso, que la cancelación suceda meses después de lo esperado.

Compatibilidad

Esta librería se mantendrá compatible con al menos la versión con soporte activo de PHP más reciente.

También utilizamos Versionado Semántico 2.0.0 por lo que puedes usar esta librería sin temor a romper tu aplicación.

`sat-estado-cfdi`	Versiones soportadas de PHP
1.0.3	7.3, 7.4, 8.0, 8.1, 8.2, 8.3
2.0.0	8.2, 8.3

Guía de actualización de la versión 1.x a 2.x.

Contribuciones

Las contribuciones con bienvenidas. Por favor lee CONTRIBUTING para más detalles y recuerda revisar el archivo de tareas pendientes TODO y el archivo CHANGELOG.

phpcfdi/sat-estado-cfdi

phpcfdi/sat-estado-cfdi

Instalación

Ejemplo básico de uso

Clientes de consumo ConsumerClientInterface

Cliente SOAP SoapConsumerClient

Cliente HTTP PSR HttpConsumerClient

Expresiones (input)

Estados (salida)

Estados mutuamente excluyentes

Compatibilidad

Contribuciones

Copyright and License

Clientes de consumo `ConsumerClientInterface`

Cliente SOAP `SoapConsumerClient`

Cliente HTTP PSR `HttpConsumerClient`