====== Conector iTimbre ====== {{:conector:conector.jpg?nolink&234x168}} **Acceda a la siguiente liga para descargar el conector:** [[https://www.itimbre.com/downloads/Conector-iTimbre.zip|Descargar conector última versión 3.3]]. [[https://www.itimbre.com/Descargas/Conector 4.0.zip|Descargar conector última versión 4.0.]] ===== Información General ===== Es una herramienta de integración que ofrece iTimbre para integrar a nuestros clientes sin la necesidad de realizar grandes modificaciones a los sistemas de facturación que utilicen y, en la mayoría de casos, sin realizar modificaciones en lo absoluto. ===== Funcionamiento ===== El Conector iTimbre funciona procesando archivos de intercambio en diversos formatos, los cuales contienen toda la información de los comprobantes (facturas, recibos de nómina, etc.) que se desean timbrar o cancelar. El Conector abstrae todo el proceso de comunicación con los servicios de iTimbre, brinda diversas opciones de configuración y gestiona el tratamiento de errores, respaldo de la información y logs. El Conector soporta 2 formatos nativos, uno CSV //(Comma Separated Values)// y otro JSON //(JavaScript Object Notation)//. Estos formatos son ideales para integraciones donde los datos puedan ser exportados desde el sistema del cliente con un mínimo esfuerzo por parte del cliente. El Conector también soporta una serie de formatos de intercambio propios de diversos sistemas cuya integración ha sido realizada con anterioridad en respuesta a las necesidades de algunos clientes. Este tipo de integración se realiza cuando el cliente cuenta con un sistema que de manera nativa es capaz de exportar los datos de los comprobantes a un archivo de texto, luego, para completar la integración se desarrolla en el conector el soporte necesario para interpretarlo adecuadamente. ===== Configuración ===== El Conector iTimbre soporta 2 tipos de configuraciones: la standard y la personalizada. ==== Configuración Standard ==== Esta configuración es la que está accesible desde la ventana de configuración del Conector y sirve a los propósitos generales de la mayoría de usuarios. === General === {{:conector:conector-configuracion-general.png?nolink&473x506}} En esta pestaña se establecen los principales directorios de trabajo del Conector y algunas opciones de filtrado. == Carpeta de entrada == Esta carpeta es constantemente monitoreada por el conector en busca de nuevos archivos para ser procesados. Dicho de otra manera, los archivos que sean copiados en esta carpeta serán automáticamente procesados por el Conector cuando este se encuentre iniciado. Mientras el Conector esté trabajando siempre intentará dejar esta carpeta vacía ya que cada vez que se procese un archivo este es movido a una carpeta de respaldo. == Monitorear subcarpetas == Cuando esta opción se encuentra activada, el conector procesará archivos que se encuentren en la carpeta de entrada y en todas sus subcarpetas, de lo contrario ignorará cualquier archivo que se encuentre dentro de una subcarpeta de la carpeta de entrada. == Ignorar archivo si ya fue timbrado == Esta opción es útil en escenarios donde por alguna razón se tiene el riesgo de que se genere un mismo archivo varias veces aunque este ya haya sido procesado con anterioridad. En tales escenarios, lo recomendable es tratar de controlar el proceso de creación de los archivos en la carpeta de entrada para tener un mayor control sobre el proceso. Aún así, esta opción, cuando está activa, el Conector realiza un chequeo adicional para garantizar que el archivo no haya sido procesado con anterioridad. Dicho chequeo consiste en verificar en la carpeta de timbrados la presencia de un archivo cuyo nombre haya sido generado a partir del archivo que esta siendo procesado. Si este archivo no existe, entonces se busca en la carpeta de errores algun archivo con nombre derivado del archivo original y cuyos contenidos coincidan. Debe tenerse en cuenta que para que este filtro funcione, en la pestaña de configuración avanzada, el formato del archivo de la factura debe establecerse a "". == Filtro de nombre == Esta opción pertime filtrar archivos en base a su nombre y admite un patrón de expresión regular de manera que todo archivo cuyo nombre coincida con dicho patrón será ignorado. == Filtro de contenido == De manera similar al filtro de nombre, esta opción pertime filtrar archivos en base a su contenido y admite un patrón de expresión regular de manera que todo archivo cuyo contenido coincida con dicho patrón será ignorado. == Carpeta de facturas timbradas == En esta carpeta se depositarán todos los comprobantes timbrados por el Conector. == Carpeta de archivos procesados == En esta carpeta se respaldan cada uno de los archivos procesados correctamente. == Almacén de archivos erroneos == En esta carpeta se depositan los archivos que no pudieron ser procesados correctamente. == Trazas del sistema == En esta carpeta se crean archivos de logs. Los archivos de logs se generan uno por día y en ellos se guarda un registro de cada una de las transacciones realizadas por el conector y el resultado de la misma. === Cancelaciones === {{:conector:conector-configuracion-cancelaciones.png?nolink&473x506}} En esta pestaña se establecen las configuraciones relativas a las cancelaciones realizadas por el conector. == Carpeta de entrada == Esta carpeta es constantemente monitoreada por el conector en busca de nuevos archivos de cancelación para ser procesados, de manera similar a como se hace con la carpeta de entrada general para comprobantes. === Autenticación === {{:conector:conector-configuracion-autenticacion.png?nolink&473x506}} En esta pestaña de configuración se recopilan los datos de acceso necesarios para poder utilizar los servicios de iTimbre. == Sistema CDF Factura == En esta sección se establecen el nombre de cuenta, usuario y contraseña para autenticarse con el servicio de facturación cuando se cuente con una cuenta de software de iTimbre, lo cual es el caso más común de uso del Conector. == Timbrado directo == En esta sección se establecen el RFC, usuario y contraseña para autenticarse con el servicio de timbrado directo. Esta opción es util en los casos en el que el cliente pueda exportar un CFD versión 3.2 listo para ser timbrado y no requiera las bondades del sistema de facturación de iTimbre. === Servidor de correo === {{:conector:conector-configuracion-servidor-de-correo.png?nolink&473x506}} En esta pestaña se configuran las opciones relativas a correo electrónico, requeridas por el conector para su correcto funcionamiento. == Enviar notificaciones de error a == El Conector iTimbre, como parte de su mecanismo de tratamiento de errores, permite enviar notificaciones de correo al cliente cuando ocurra un error durante el procesamiento de algún archivo, de esta manera el cliente podrá tomar la acción ante el problema. == Nombre del remitente == En ocaciones es conveniente poder identificar rápidamente quién es el remitente del mismo. Esto es especialmente cierto en entornos dende se ejecutan y administran varias instancias simultáneas del conector. Esta opción permite indicar el nombre del remitente de kas notificaciones enviadas por el conector. == Servidor principal y Servidor alternativo == Para enviar los correos, el Conector requiere de una cuenta en un servidor SMTP. Los datos solicitados son los requeridos para hacer la conexión y son proporcionados por los administradores del servidor de correo. Para mayor seguridad, el Conector soporta una segunda cuenta de correo alternativa la cual será utiilizada en caso de que la cuenta principal no esté disponible en algún momento. Esto resulta muy útil cuando se utilizan servidores con límite de correos que se pueden enviar por hora o presentan algún otro tipo de restricciones. === Opciones === {{:conector:conector-configuracion-opciones.png?nolink&473x506}} En esta pestaña se configuran la mayoría de opciones de propósito general del Conector iTimbre == Notificaciones de error y Notificaciones de timbrado exitoso == Cuando se timbra correctamente un comprobante u ocurre un error durante el procesamiento de un archivo, el Conector brinda opciones para notificar al usuario de una o varias maneras. La opción seleccionada para notificar el timbrado exitoso se aplica también a las cancelaciones exitosas. Estas opciones son: * Ninguna / Sin notificaciones en la pantalla: Se omite completamente la notificación en la pantalla de la computadora. Esta opción es generalmente no recomendada ya que no proporciona indicio ninguno del estado del procesamiento que lleva a cabo el Conector. * Área de notificaciones: Se muestra un popup no obstrusivo en el área de notificaciones de la barra de tareas con el mensaje de éxito o error. Esta opción es recomendable cuando por lo general el Conector estará procesando grandes volúmenes de archivos simultáneos. * Diálogo: Se muestra un cuadro de mensaje en la pantalla que requerirá la atención del usuario. * Ventana: Esta opción, disponible solamente para el timbrado exitoso, muestra detalles de la operación en una ventana especial la cual muestra el PDF (si se obtiene) y el XML del comprobante timbrado y, para el caso de las cancelaciones, muestra un resumen detallado del resultado de la operación. Adicionalmente, los errores pueden ser notificados via correo electrónico seleccionando la opción correspondiente. == Obtener Formato imprimible (PDF) == Haciendo uso de esta opción se solicita la obtención del PDF del comprobante el cual será guardado en la carpeta de facturas timbradas junto con su correspondiente archivo .XML. Solo el servicio de timbrado mediante una cuenta del software de facturación de iTimbre soporta esta opción. Si se utiliza el timbrado directo esta opción es ignorada. == Enviar facturas al receptor automáticamente == El Conector permite enviar los comprobantes timbrados al cliente. Si se utiliza el timbrado directo, el único método soportado es enviarlos desde el conector. Si se utiliza una cuenta de software de facturación de iTimbre se puede utilizar la opción "Respetar la configuración de la cuenta en el servidor". * **Respetar la configuración de la cuenta en el servidor:** Las cuentas de software de facturación cuentan con una opción para enviar automáticamente al receptor los comprobantes que se timbren desde el sistema. Esta opción delega la desición de enviar la factura al receptor respetando la configuración de la cuenta. Cuando se decide enviar los comprobantes al cliente o respetar la configuración de la cuenta para enviar o no las facturas al cliente se habilitan otras opciones relacionadas: * Desde dónde enviar las facturas * Sólo desde el conector: los comprobantes siempre se envian desde el Conector. * Intentar desde el servidor y luego desde el conector: se intenta enviar los comprobantes timbrados desde el servidor de iTimbre y en caso de no poderse por alguna razón, se intenta el envío desde el Conector. * Mostrar ventana de envío si el receptor no tiene dirección de correo: Si esta opción se activa, cuando se timbre un comprobante y se desconozca la dirección de correo del receptor, se abrirá una ventana para enviar el correo electrónico. Esta operación requiere la intervención del usuario y el procesamiento de los archivos restantes es detenido hasta que dicha ventana se cierre y se concluya el procesamiento del archivo actual. * Enviar copia al correo de notificaciones: Esta opción permite enviar al correo de notificaciones una copia de todos los correos enviados a los receptores de los comprobantes. == Opciones de inicio == * **Vigilar carpeta de entrada automáticamente al inicio del programa:** Esta opción define si al ejecutarse el programa del Conector este debe comenzar a vigilar y procesar automáticamente los archivos de las carpetas de entrada. * **Iniciar minimizado hacia el área de notificaciones del sistema:** Por defecto, al ejecutar el programa del Conector se muestra la ventana principal dle programa. Esta opción permite que la ventana principal no se muestre y solo se cargue el icono del Conector en el área de notificaciones. === Avanzado === {{:conector:conector-configuracion-avanzado.png?nolink&473x506}} Algunas de las opciones que se configuran en esta pestaña pueden presentar cierto grado de complejidad para su comprención, aunque han sido presentadas de la manera más sencilla posible. == Codificación de archivos == Los archivos de texto tiene una codificación específica entre muchas disponibles. A la hora de leer el contenido de los archivos de texto es pereciso interpretarlos con la codificación correcta, de lo contrario algunos caracteres como la ñ y las vocales con tílde podrían perderse en el proceso. La codificación de un archivo depende el programa que los generó. Esta opción permite seleccionar la codificación utilizada para leer los archivos de las carpetas de entrada. Las codificaciones más comunes son: * 1252 : Windows-1252 (es la codificación por defecto de Windows y también del Conector) * 437 : IBM437 * 65001 : utf-8 == Servicios == En esta sección se definen las URLs de los servicios de timbrado que utilizará el conector. Solo bajo situaciones excepcionales se utilizará un valor direfente al "Servicio predeterminado". No modifique esta opción a menos que esté seguro de lo que está haciendo. == Formato del nombre de archivos de la factura == El formato del nombre de los archivos de las facturas puede ser especificado haciendo uso de las siguientes etiquetas representativas: * **** : RFC del emisor * **** : RFC del Receptor * **** : Serie de la factura * **** : Folio de la factura * **** : Fecha y formato de fecha (Ej.: , ) * **** : Nombre original del archivo procesado: Cualquier otro caracter adicional será incluido literalmente en el nombre de los archivos de la factura. == Título de la instancia == Nombre de la instancia actual del conector el cual se muestra en la ventana principal y al mover el puntero del mouse por encima del ícono del Conector en el área de notificaciones. Esta opción es especialmente útil en entornos donde se ejecuten varios conectores simultáneamente ya que permite asgnarles nombre diferentes e identificarlos rápidamente moviendo el puntero del mouse por encima del ícono del área de notificaciones. ==== Configuración personalizada (avanzado) ==== La configuración personalizada del Conector está diseñada para adaptarse a los requerimientos especiales de los clientes, de ahí su nombre de personalizada. Esta configuración no está disponible desde una ventada de configuración, por lo que su uso solo es propicio para personal técnico y generalmente es establecido por el personal de iTimbre. La configuración personalizada se guarda en un archivo en formato XML ubicado en **\personalizados\cgf.xml**. Es importante tener respaldo de este archivo y asegurarse de que sea restablecido con todas sus modificaciones cuando se realicen actualizaciones al Conector iTimbre, pues si se reemplaza por el archivo por defecto el Conector puede dejar de funcionar como se espera. Las siguientes secciones explican detalles técnicos de sobre el archivo de configuración personalizada que puede ser no relevante para el usuario comun del Conector iTimbre. === Ejemplo de archivo de configuración personalizado === === Estructura del archivo de configuracion personalizado === El archivo de configuración por defecto incluye los procesadores de propósito general más comunmente utilizados por los clientes. Un procesador es un componente de software que se encarga de procesar los archivos de alguna manera específica acorde al formato de su contenido. El archivo de configuración personalizada define el conjunto de procesadores que se podran utilizar y como se identifican los archivos que debe procesar cada uno de ellos. Esta identificación se realiza en base al nombre del archivo a procesar. === El nodo Procesador === ===== Servicio ===== ===== Archivos Soportados ===== ===== Registro de Cambios =====