miércoles, diciembre 03, 2014

Descarga tus facturas desde el portal del SAT con VGestorCFDI. Parte 2.


Como comentaba en el artículo anterior, creamos 2 versiones de VGestorCFDI, una para usuarios finales y otra para los programadores.

Ahora toca el turno para explicar el funcionamiento de VGestorCFDI (o ConsultaSAT, como quieras llamarle) para desarrollador y como incluirlo en tus programas.

La versión para desarrollador de VGestorCFDI es una línea de comandos que puedes ejecutar desde tus programas Windows ya sea con una llamada las funciones WinExec() o WaitRun(), disponbiles en la mayoría de los lenguajes para Windows.

A diferencia de algunos otros de nuestros productos, donde hay LIBs, DLLs y otros componentes para llamarlos nativamente desde desde la mayoría de los lenguajes de programación, esta versión decidimos hacerla como un EXE externo que ha demostrado ser una manera eficaz de implementar en los distintos lenguajes de programación y garantizando que funcione perfectamente en todos ellos.

Antes de descargar la versión de desarrollador, asegurate que el equipo donde vayas a instalar la herramienta cuente con estos requisitos previos:

Estos requisitos también son necesarios para el equipo donde vayas a instalar tu aplicación que utilice ConsultaSAT.

Una vez que nos hemos asegurado de tener los requisitos previos,  estamos listos para descargar la versión de desarrollador de:


Descarga el EXE, ejecutalo en tu computadora y listo, el programa de instalación copiará los archivos necesarios para usar el producto y registrará un control ActiveX que es necesario para que la aplicación funcione.


La versión para desarrollador esta integrada por los siguientes componentes, mismos que deberás distribuir junto con tu aplicación para que ConsultaSAT funcione adecuadamente:

  • ConsultaSAT.EXE
  • CommandLine.DLL
  • csExWB.DLL
  • Interop.CSEXWBDLMANLib.DLL
  • csExWBDLMAN.DLL
Para que la aplicación funcione correctamente con tu software, deberás incluir los archivos anteriores en tu distribución, copiarlos en la carpeta del disco duro donde instales tu programa y al momento de instalar deberás "registrar" en el sistema de Windows un control ActiveX, el cual está contenido en la DLL csExWBDLMAN.DLL

La mayoría de los instaladores gratuitos y comerciales, pueden realizar los procesos de "registro" de los ActiveX en el momento de instalar la aplicación, nosotros recomendamos el instalador gratuito InnoSetup, que aparte de sus muchas características,  tiene la capacidad de registrar ActiveX al momento de instalar un programa.

Los controles ActiveX se pueden instalar también manualmente desde la línea de comandos, es muy importante que cuando ejecutes una línea de comandos para instalar un control ActiveX, lo hagas ejecutando la línea de comandos como ADMINISTRADOR, de lo contrario, el control ActiveX no quedará registrado.

Para ejecutar la línea de comandos como Administrador, da click con el botón derecho del raton, y selecciona del menú: Ejecutar como administrador:

 

Con esto se abrirá la ventana de comandos de Windows y podrás registrar el ActiveX tecleando:

REGSVR32  csExWBDLMAN.DLL



Nota que debes teclear este comando DESDE LA CARPETA DONDE TIENES LA DLL que quieres registrar, y repito: si quieres automatizar este paso, utiliza un instalador que registre ActiveX.

El archivo instalación que descargaste registra el ActiveX al momento de instalar, por lo que no es necesario que hagas el paso anterior manualmente.


Usando VGestorCFDI para desarrollador:

Como comenté al principio, ConsultaSAT para desarrollador es una línea de comando a la cual le envias los parámetros de consulta por medio de "switches", estos switches no son mas que letras o palabras que le indican al programa lo que tiene que hacer, seguido del parametro de configuración.

Los switches se pueden indicar con una sola letra antecedida por un signo de "-" (-o, -r, etc.) o bien mediante una palabra antecedida por 2 signos de "-" (--rango, --inicial, etc).


VGestorCFDI utiliza los siguientes switches:

Switches obligatorios y de información del contribuyente:

-e, --emisor: Se utiliza para indicar el RFC del  contribuyente del cual se desean descargar los archivos XML del portal del SAT. Es un parametro OBLIGATORIO

-c, --ciec: Se utiliza para indicar la clave CIEC (Clave de Identificación Electrónica Confidencial) del contribuyente, esta clave se tramita en el SAT y es la que se utiliza para acceder a los servicios del portal del SAT. Es un parámetro OBLIGATORIO

-l, --licencia: Es la licencia de uso del producto, esta licencia es gratuita para descargar archivos del año 2014 y se obtiene del portal de licencias de ConsultaSAT, para mas información para obtener la licencia gratuita de uso del producto, consulta la Parte 1, de esta serie de artículos. Es un parámetro OBLIGATORIO

Swtiches para controlar los archivos de salida:

-p, --path: Indica la ruta del disco duro donde se guardarán los XMLs descargados de la página del SAT, si la carpeta no existe, el programa la crea, la carpeta predeterminada es C:\ConsultaSAT. Cabe mencionar que el programa creará OTRAS carpetas debajo de la anterior, ya sea la de default o la que tu indiques, creará una carpeta con el nombre del RFC del cual estas obteniendo los archivos, debajo de esta carpeta creará otra carpeta con el nombre del AÑO que estes descargando, debajo de esta carpeta creará otra carpeta con el numero del mes que estas descargando y finalmente, debajo de esta carpeta creará una carpeta mas con el nombre "R", donde se almacenarán los documentos RECIBIDOS y otra con el nombre "E", donde se almacenarán los documentos EMITIDOS.


-o, --outFile: Sirve para indicar el nombre del archivo de salida donde se guardarán los resultados de la operación de descarga. Este es un archivo con formato XML donde se guardará el resultado y donde se indicará la cantidad de archivos encontrados, existentes, la fecha de la ultima descarga, etc, y además se incluye un listado de todos los documentos descargados indicando entre otros datos UUID: RFC, nombre del emisor y del receptor, fecha de certifiación, PAC que certificó, tipo de comprobante, estado, etc., si no se indica nombre, el programa creará ConsultaSAT.LOG en la misma carpeta indicada en el parametro -p. En caso de proporcionar un nombre específico al archivo este se creará en la ruta indicada en el nombre.


Switches para configurar tipos de documento y períodos de descarga:

-t, --type: Se utiliza para indicar el tipo de documento que deseamos recuperar de la pagina del SAT, se debe utilizar la letra "E" mayuscula para indicar que se quieren descargar los documentos EMITIDOS, o bien la letra "R" mayúscula para indicar que se quieren descargar los documentos RECIBIDOS.

Los siguientes 3 parámetros deben siempre de usarse juntos, y NO SE DEBEN UTILIZAR CUANDO SE UTILICEN LOS PARAMETROS -m, --mes, -a y --anio.

-r, --rango: Le indica VGestorCFDI que se desea realizar una búsqueda por rango de fechas, no se debe usar cuando se utilizan los parámetros -m, --mes, -a y --anio.

-i, --inicial: Indica la fecha inical de búsqueda, la fecha debe expresarse COMPLETA en el formato AAAA-MM-DDTHH:MM:SS, este parametro no se debe usar cuando se utilicen los parámetros -m, --mes, -a y --anio.

-f, -- final: Indica la fecha final de búsqueda, la fecha debe expresarse COMPLETA en el formato AAAA-MM-DDTHH:MM:SS, este parametro no se debe usar cuando se utilicen los parámetros -m, --mes, -a y --anio.

Los siguientes 2 parámetros deben de usarse siempre juntos y NO DEBEN DE USARSE CUANDO SE UTILICEN LOS PARAMETROS -r, --rango, -i, --inicial, -f y --final.

-m, --mes: Indica el número de mes que se desea descargar, este número hay que indicarlo siempre CON DOS DIGITOS (01 = Enero, 02 = febrero ......11 = Noviembre, 12 = Diciembre), este parámetro no se debe usar cuando se utilicen los parámetros  -r, --rango, -i, --inicial, -f y --final.

-a, --anio: Indica el numero de año que se desea descargar, este número hay que indicarlo siempre CON CUATRO DIGITOS (2013, 2014, 2015, etc), este parámetro no se debe usar cuando se utilicen los parámetros  -r, --rango, -i, --inicial, -f y --final.

En este punto tenemos que hacer un paréntesis para analizar las reglas que impone el SAT para descargar documentos del portal:

En primer lugar, el portal del SAT no permite descargar mas de 500 documentos por conexión.

En el caso de los documentos EMITIDOS, el rango de fechas solo puede estar DENTRO DEL MISMO AÑO, es decir no puedes descargar documentos de Octubre del 2013 a Marzo del 2014 por ejemplo, tienes que especificar fechas dentro del mismo año calendario es decir, de Octubre a Diciembre del 2013 y luego puedes hacer otra descarga de Enero a Marzo del 2014.

En el caso de los documentos RECIBIDOS, la fecha solo puede ser DENTRO DEL MISMO DIA, y existe una buena razón para esto, algunos de nuestros usuarios reciben mas 100 mil XMLs al mes, obviamente con la limitación de 500 documentos por descarga no es posible descargar todos los documentos recibidos, así que cuando uses la descarga por rango de fechas para documentos recibidos, puedes hacerlo por intervalos de tiempo dentro del mismo día:

Pensemos que el día 25 de Noviembre de 2014 recibiste mas de 500 documentos durante el día ¿ cómo descargarlos todos ?, bueno, si crees que entre las 00:00:00 y las 09:00:00 no hay mas 500 documentos, entonces puedes hacer una descarga:

desde: 2014-11-25T00:00:00
hasta:  2014-11-25T09:00:00

Luego, si crees que hay menos de 500 documentos por hora, puedes hacer una descarga:

desde: 2014-11-25T09:00:00
hasta: 2014-11-25T11:00:00

O bien, puedes reducir aun mas los intervalos de descarga incluso a minutos o segundos, por ejemplo:

desde: 2014-11-25T13:30:00
hasta:  2014-11-25T13:35:00

Y podrás recuperar los documentos generados dentro de los 5 minutos del rango de la hora especificada, usando esta característica puedes darle la vuelta a la limitación de los 500 documentos por conexión.

Parámetros para controlar la ventana de interfaz:

La línea de comandos tiene una pequeña interfaz que te mostrará en pantalla el progreso de la descarga de los docuementos, dicha interfaz siempre aparecerá en la parte inferior derecha de tu pantalla cuando ejecutes ConsultaSAT:


Por default esta interfaz está programada para aparecer, ejecutar de manera automatica la descarga de archivos de acuerdo a los parámetros que le proprocionaste en la línea de comandos y después de realizar las operaciones, cerrarse de manera automática, sin embargo, para propósitos de depuración de tu programa cuando lo integres a tu sistema, es posible manipular algunos comportamientos usando switches:

-s, --showForm: Muestra la interfaz, pero no ejecuta el proceso de descarga automáticamente, para hacerlo, deberás pulsar manualmente el botón Consultar, esto te permite revisar que los parámetros hayan sido pasados correctamente y en un momento dado modificarlos antes de realizar la descarga. Después de realizar la consulta, la interfaz se cerrará automáticamente.

-x, --noclose: Si se especifica este parámetro, la ventana de interfaz no se cierra al terminar de descargar los archivos y permanece abierta NO HAY MANERA DE CERRARLA, evita el uso de este parámetro.

-v, --maxvueltas: En algunas ocasiones el portal del SAT demora en entregar los archivos XMLs, con este parámetro se estable el número máximo de intentos que debe hacer ConsultaSAT para descargar un XML, el valor por default es 20, recomendamos un valor máximo de 50 intentos de descarga.

--opacity: Este parámetro nos sirve para indicar la transparencia de la ventana de interfaz, sus valores van de 0 a 1 en intervalos decimales, por ejemplo si no se quiere que la ventana de interfaz aparezca, habrá que indicar un valor 0 en este parámetro, si quieremos la ventana transparente un valor 0.5 podría ser aceptable, mientras que si queremos que aparezca la ventana usaremos el valor por default que es 1. EVITA USAR ESTE PARAMETRO CUANDO UTILICES LOS SWITCHES -s ó -x, ya que si la ventana está invisble no es posible interactuar con ella.

Veamos algunos ejemplos básicos del uso de la linea de comandos:

Ejemplo para descargar XMLs RECIBIDOS del mes de ENERO de 2014:

consultasat -e CTE940531F58 -c 1234abc -p C:\XMLSRECIBIDOS -t R -m 06 -a 2014 -o C:\XMLRECIBIDOS\junio.XML -l 2cuYXf/XeUdep13U4aO5NCmepd374YnrHtENyyutO0i2dpbVSVCUqGereg1

Ejemplo para descargar XMLs EMITIDOS del mes de NOVIEMBRE de 2014:

consultasat -e AAA010101AAA --ciec 1234ABC --path C:\XMLSEMITIDOS -t E -m 11 -a 2014 -o C:\XMLSEMITIDOS\NOVIEMBRE2014.XML --licencia 1cuYXf/XeUdep13U4aO5NGBlbdpbVSVCUqGereg1


Ejemplo para descargar XMLs RECIBIDOS del día 26 de Noviembre del 2014 de las 9 de la mañana a las 6 de la tarde (recuerda: documentos recibidos solo se pueden descargar del mismo dia):

consultasat -e AAA010101AAA -c 1234abc -p C:\XMLSRECIBIDOS -t R --rango -i 2014-11-26T09:00:00 --final 2014-11-26T17:59:59 -o C:\XMLSRECIBIDOS\NOVIEMBRE2014.XML -l 2cuYXf/XeUdep13U4aO5NCmepd374YnrHtENyyutO0i2QGBlbdpbVSVCUqGereg1

Ejemplo para descargar XMLs EMITIDOS de los meses de OCTUBRE y NOVIEMBRE del año 2014:

consultasat -e AAA010101AAA -c 1234abc -p C:\XMLSEMITIDOS -t E -r -i 2014-10-01T00:00:00 -f 2014-11-29T23:59:59 -o C:\XMLSEMITIDOS\RangoOctNov2014.XML -l 2cuYXf/XeUdep13U4aO5NCmepd374YnrHtENyyutO0i2QGBlbdpbVSVCUqGereg1


Próximamente liberaremos nuevas opciones en la línea de comandos, te recuerdo que para cualquier duda o aclaración nos contactes al tel (55) 55600168 o al correo soporte@ciber-tec.com

1 comentario:

Anónimo dijo...

Hola René:

Esta herramienta me parece fabulosa, como recordaras ando en busca de una herramienta para validar CFDIs en el portal del SAT. me explico, leer el CFDI que te llegue y validarlo en el portal del SAT.

Tienes algo para este dolor?

Saludos, Armando Estrada