phpcfdi/sat-ws-descarga-masiva-cli

Consumo del web service de descarga masiva del SAT por l铆nea de comandos

Maintainers

Details

github.com/phpcfdi/sat-ws-descarga-masiva-cli

Homepage

Source

Issues

Chat

Installs: 5

Dependents: 0

Suggesters: 0

Security: 0

Stars: 5

Watchers: 3

Forks: 2

Open Issues: 0

v0.0.2 2024-10-21 17:05 UTC

Requires

Requires (Dev)

MIT d605c539a005055fd79a0fb0a6702b1d922a46e1

  • Carlos C Soto <eclipxe13.woop@gmail.com>

webservicedownloadsatcfdidescarga

This package is auto-updated.

Last update: 2024-12-21 17:44:45 UTC

README

Source Code Packagist PHP Version Support Discord Latest Version Software License Build Status Reliability Maintainability Code Coverage Violations Total Downloads Docker Downloads

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