Consumo del web service de descarga masiva del SAT por línea de comandos
🇺🇸 The documentation of this project is in spanish as this is the natural language for intented audience.
🇲🇽 La documentación del proyecto está en español porque ese es el lenguaje principal de los usuarios. También te esperamos en el canal #phpcfdi de discord
Esta librería contiene un cliente (consumidor) del servicio del SAT de Servicio Web de Descarga Masiva de CFDI y Retenciones.
Esta herramienta usa PHP versión 8.2 o superior con las extensiones xml, openssl, zip, curl, intl y bcmath.
Puedes descargar el archivo PHAR desde la dirección https://github.com/phpcfdi/sat-ws-descarga-masiva-cli/releases/latest/download/descarga-masiva.phar.
wget https://github.com/phpcfdi/sat-ws-descarga-masiva-cli/releases/latest/download/descarga-masiva.phar -O descarga-masiva.phar
php descarga-masiva.phar --versionPendiente.
docker pull phpcfdi/descarga-masiva
docker run --rm -it phpcfdi/descarga-masiva --versionPuedes instalar el proyecto en una carpeta especial y usar la herramienta o como dependencia de tu proyecto. Personalmente, no recomiendo instalarla como una dependencia de algún proyecto, dado que se trata de una herramienta y no de un componente o libería.
# instalar la herramienta
composer require phpcfdi/sat-ws-descarga-masiva-cli
# ejecutar el script
php vendor/bin/descarga-masiva.php --versionSuponiendo que la herramienta se instaló en ~/projects/sat-ws-descarga-masiva-cli, entonces podrías poner después
un script de ejecución como el siguiente en /usr/local/bin/descarga-masiva o en ~/.local/bin/descarga-masiva:
!#/usr/bin/env bash -e
php ~/projects/sat-ws-descarga-masiva-cli/bin/descarga-masiva.php "${@}"Puedes decargar el proyecto de github y ejecutar el archivo bin/descarga-masiva.php.
Esta opción la recomiendo aún menos, dado que no es fácil mantener la herramienta desde Git.
# descargar el proyecto
git clone https://github.com/phpcfdi/sat-ws-descarga-masiva-cli /opt/descarga-masiva
# instalar dependencias
composer --working-dir=/opt/descarga-masiva update --no-dev
# ejecución del proyecto
php /opt/descarga-masiva/bin/descarga-masiva.php --versionPara entender plenamente el uso del servicio web y los códigos de respuesta consulta la documentación de la librería
phpcfdi/sat-ws-descarga-masiva.
La aplicación cuenta con dos tipos de comandos: ws para trabajar con el servicio y zip para trabajar con los paquetes.
Para obtener la lista de comandos disponibles usa el comando list.
Para obtener ayuda de la aplicación o cualquier comando agrega el parámetro --help.
El comando ws:consulta presenta una consulta con los parámetros establecidos.
El siguiente comando presenta una consulta de CFDI de metadata de comprobantes emitidos en el periodo
2023-01-01 00:00:00 al 2023-12-31 23:59:59 con los datos de la FIEL del RFC EKU9003173C9.
php bin/descarga-masiva ws:consulta \
--certificado fiel/EKU9003173C9.cer --llave fiel/EKU9003173C9.key --password=12345679a \
--desde "2023-01-01 00:00:00" --hasta "2023-12-31 23:59:59"Con lo que puede entregar el siguiente resultado:
Consulta:
Servicio: cfdi
Paquete: Metadata
RFC: EKU9003173C9
Desde: 2024-01-01T00:00:00.000UTC
Hasta: 2024-12-31T23:59:59.000UTC
Tipo: Emitidos
RFC de/para: (cualquiera)
Documentos: (cualquiera)
Complemento: (cualquiera)
Estado: (cualquiera)
Tercero: (cualquiera)
Resultado:
Consulta: 5000 - Solicitud Aceptada
Identificador de solicitud: ba31f7fa-3713-4395-8e1f-39a79f02f5cc
Los parámetros --efirma, --certificado, --llave, --password, --token son de autenticación
y se documentan más adelante.
Adicionalmente, se pueden especificar los siguientes parámetros:
--servicio: Si se consultarán los CFDI regulares (cfdi) o CFDI de Retención e información de pagos (retenciones). Por omisión:cfdi.--tipo: Si se consultarán los comprobantes emitidos (emitidos) o recibidos (recibidos). Por omisión:emitidos.--paquete: Si se solicita un paquete de Metadatos (metadata) o de XML (xml). Por omisión:metadata.
Y los siguientes filtros, que son opcionales:
--estado: Filtra por el estado se encuentra el comprobante: Vigentesvigenteso canceladascanceladas.--rfc: Filtra la información por RFC, si se solicitan emitidos entonces es el RFC receptor, si se solicitan recibidos entonces es el RFC emisor.--documento: Filtra por el tipo de documento: Ingreso (ingreso), egreso (egreso), traslado (traslado), pago (pago) o nómina (nomina).--complemento: Filtra por el tipo de complemento, ver el comandoinfo:complementos.--tercero: Filtra por el RFC a cuenta de terceros.
También se pueden hacer consultas por UUID con el paámetro --uuid. En caso de usar el filtro de UUID entonces
no se toman en cuenta los parámetros --desde, --hasta o cualquiera de los filtros antes mencionados.
En la respuesta, entrega el resultado de la operación y el identificador de la solicitud,
que puede ser usado después en el comando ws:verifica.
El comando ws:verifica verifica una consulta previamente presentada con los parámetros establecidos.
El siguiente comando verifica una consulta de CFDI con el identificador ba31f7fa-3713-4395-8e1f-39a79f02f5cc.
php bin/descarga-masiva ws:verifica \
--certificado fiel/EKU9003173C9.cer --llave fiel/EKU9003173C9.key --password=12345679a \
ba31f7fa-3713-4395-8e1f-39a79f02f5ccEn la respuesta, entrega el resultado de la operación y el identificador de uno o más paquetes para descarga,
que pueden ser usados después en el comando ws:descarga.
Verificación:
RFC: EKU9003173C9
Identificador de la solicitud: ba31f7fa-3713-4395-8e1f-39a79f02f5cc
Resultado:
Verificación: 5000 - Solicitud Aceptada
Estado de la solicitud: 3 - Terminada
Estado de la descarga: 5000 - Solicitud recibida con éxito
Número de CFDI: 572
Paquetes: BA31F7FA-3713-4395-8E1F-39A79F02F5CC_01
Los parámetros --efirma, --certificado, --llave, --password, --token son de autenticación
y se documentan más adelante.
Adicionalmente, se pueden especificar los siguientes parámetros:
--servicio: Si se verificará la consulta en el servicio web de CFDI regulares (cfdi) o de CFDI de Retención e información de pagos (retenciones). Por omisión:cfdi.
El comando ws:descarga descarga un paquete de una consulta previamente verificada.
El siguiente comando descarga un paquete de CFDI con el identificador BA31F7FA-3713-4395-8E1F-39A79F02F5CC_01
en el directorio de destino storage/paquetes.
php bin/descarga-masiva ws:descarga \
--certificado fiel/EKU9003173C9.cer --llave fiel/EKU9003173C9.key --password=12345679a \
--destino storage/paquetes BA31F7FA-3713-4395-8E1F-39A79F02F5CC_01En la respuesta, entrega el resultado de la operación y el identificador de uno o más paquetes para descarga,
que pueden ser usados después en el comando ws:descarga.
Descarga:
RFC: DIM8701081LA
Identificador del paquete: BA31F7FA-3713-4395-8E1F-39A79F02F5CC_01
Destino: storage/paquetes/ba31f7fa-3713-4395-8e1f-39a79f02f5cc_01.zip
Resultado:
Descarga: 5000 - Solicitud Aceptada
Tamaño: 216126
Los parámetros --efirma, --certificado, --llave, --password, --token son de autenticación
y se documentan más adelante.
Adicionalmente, se pueden especificar los siguientes parámetros:
--servicio: Si se descargará el paquete en el servicio web de CFDI regulares (cfdi) o de CFDI de Retención e información de pagos (retenciones). Por omisión:cfdi.--destino: Si se establece, determina en qué carpeta se descargará el paquete, en caso de no usarse se utiliza el directorio actual.
Los parámetros --efirma, --certificado, --llave, --password y --token son de autenticación
y se utilizan en los comandos ws:consulta, ws:descarga y ws:verifica.
--efirma: Ruta absoluta o relativa al archivo de especificación de eFirma.--certificado: Ruta absoluta o relativa al archivo de certificado.--llave: Ruta absoluta o relativa al archivo de llave privada.--password: Contraseña de la llave privada, si no se especifica entonces usa el valor de la variable de entornoEFIRMA_PASSPHRASE.--token: Ruta absoluta o relativa a un archivo Token (que genera esta aplicación).
Es recomendado establecer la ruta del token, es en donde se almacena la autenticación con el servicio web del SAT y se intenta reutilizar para no realizar más peticiones de autenticación de las necesarias.
Para no tener que especificar los parámetros --certificado, --llave, --password y --token, se puede
especificar el parámetro --efirma que espera la ubicación a un archivo JSON con la siguiente estructura:
certificateFile: Ruta absoluta o relativa al archivo de certificado CER.privateKeyFile: Ruta absoluta o relativa al archivo de llave privada KEY.passPhrase: Contraseña de la llave privada.tokenFile: Ruta absoluta o relativa a un archivo Token (que genera esta aplicación).
El comando info:complementos muestra la información de los complementos registrados para usarse en una consulta.
Adicionalmente, se pueden especificar los siguientes parámetros:
--servicio: Si se mostrarán los complementos del servicio web de CFDI regulares (cfdi) o de CFDI de Retención e información de pagos (retenciones). Por omisión:cfdi.
El comando zip:metadata lee un paquete de metadatos desde paquetes/ba31f7fa-3713-4395-8e1f-39a79f02f5cc_01.zip
y exporta su información a un archivo de Excel en archivos/listado.xlsx.
php bin/descarga-masiva zip:metadata paquetes/ba31f7fa-3713-4395-8e1f-39a79f02f5cc_01.zip archivos/listado.xlsxEl comando zip:xml lee un paquete de XML y exporta los comprobantes a un directorio, el nombre de cada
comprobante es el UUID con la extensión .xml.
El siguiente comando lee un paquete de XML desde paquetes/ba31f7fa-3713-4395-8e1f-39a79f02f5cc_01.zip
y exporta todos los archivos de comprobantes en el directorio archivos/xml/.
php bin/descarga-masiva zip:metadata paquetes/ba31f7fa-3713-4395-8e1f-39a79f02f5cc_01.zip archivos/xml/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.
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.
The phpcfdi/sat-ws-descarga-masiva-cli project is copyright © PhpCfdi
and licensed for use under the MIT License (MIT). Please see LICENSE for more information.