README

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.

Requerimientos

Esta herramienta usa PHP versión 8.2 o superior con las extensiones xml, openssl, zip, curl, intl y bcmath.

Instalación

Ejecutable

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 --version

Phive

Pendiente.

Docker

docker pull phpcfdi/descarga-masiva
docker run --rm -it phpcfdi/descarga-masiva --version

Composer

Puedes 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 --version

Suponiendo 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/vendor/bin/descarga-masiva.php "${@}"

Instalación desde el repositorio Git

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 --version

Ejemplos de uso

Para 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.

Comando ws:consulta

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: Vigentes vigentes o canceladas canceladas.
• --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 comando info: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.

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-39a79f02f5cc

En 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.

Comando ws:descarga

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_01

En 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.

Parámetros de autenticación

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 entorno EFIRMA_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.

Archivos de eFirma

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).

Comando info:complementos

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.

Comando zip:metadata

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.xlsx

Comando zip:xml

El 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/

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.

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.

Copyright and License

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.