jaja

MANUAL DE INTEGRACIÓN

FISCOCLIC WINDOWS CONNECTOR

Versión 1.0

DESARROLLO DE SOFTWARE PROMOCIÓN TURÍSTICA RURAL ON-LINE

SOLUCIONES DE INTEGRACIÓN

Y MOVILIDAD

C ONTENIDO

FISCOCLIC WINDOWS CONNECTOR (FWC) ..................................................................................................... 3 REQUISITOS ADMINISTRATIVOS PARA UTILIZAR FWC ................................................................................... 3 REQUISITOS TÉCNICOS PARA UTILIZAR FWC .................................................................................................. 3 SERVICIOS WINDOWS ..................................................................................................................................... 4 COMUNICACIÓN CON FISCOCLIC WEB SERVICE (WSDL) ................................................................................ 4 AMBIENTE DE PRUEBAS ................................................................................................................................. 5 Consideraciones y sugerencias sobre el ambiente de pruebas ....................................................... 5 INSTALACIÓN DE FWC .................................................................................................................................... 6 CONFIGURACION DE FWC .............................................................................................................................. 7 ARRANCAR Y DETENER A FWC........................................................................................................................ 8 LOGS Y MONITOREO DE FWC ....................................................................................................................... 10 OBSERVACIONES GENERALES FISCOCLIC WEB SERVICES y FWC .................................................................. 11 ERRORES DEL SAT ......................................................................................................................................... 13 DATOS DE CONTACTO .................................................................................................................................. 13

CONTACTO: (55) 44342246

www.3sit.com.mx

Insurgentes sur 686 int. 402 Col. Del valle C.P. 03100

2| P a g e Soluciones especializadas de TI

DESARROLLO DE SOFTWARE PROMOCIÓN TURÍSTICA RURAL ON-LINE

SOLUCIONES DE INTEGRACIÓN

Y MOVILIDAD FISCOCLIC WINDOWS CONNECTOR (FWC) Es una solución orientada a todos aquellos Contribuyentes/Corporativos que deseen conectar sus ERP, CRM, POS, o cualquier otro sistema que ya utilicen CFD para su facturación. El conector permite Integrarse a FiscoClic Web Services sin tener que modificar sus sistemas. Dicho esquema proporciona un ambiente de “nube”, lo que significa que los servicios de generación, certificación, creación de pdf estarán disponibles vía internet para ser invocados por éste conector desde sistemas operativos Windows.

REQUISITOS ADMINISTRATIVOS PARA UTILIZAR FWC 1. 2. 3. 4. 5. 6. 7.

Debe realizar pruebas con un usuario de pruebas de FWC Debe existir un registro en el portal Web del contribuyente que va a emitir facturas Debe solicitar un usuario funcional de Web service que es el usuario maestro para FWC Debe solicitar al personal de FiscoClic, ligar el usuario funcional al usuario del portal Web Se debe configurarse el sello digital del contribuyente en la máquina que tiene instalado FWC Se debe configurar el sello digital en el portal web Se debe configurar logotipo y color de su formato de factura en el portal web.

REQUISITOS TÉCNICOS PARA UTILIZAR FWC 1.

Sistemas operativos Windows.

2. 3. 4. 5. 6.

.NET Framework 4.0 (full) Tener un certificado de sello digital (CSD) en una ruta local de servidor donde está FWC Conexión a internet y habilitar los puertos 80 y 443 para comunicación HTTP y HTTPS Permisos de administrador para instalar/desinstalar FWC Acceso al Event viewer (Visor de eventos) y a los servicios Windows como administrador

a.

CONTACTO: (55) 44342246

Revisar versiones soportadas: http://msdn.microsoft.com/en-us/library/vstudio/8z6watww(v=vs.100).aspx

www.3sit.com.mx

Insurgentes sur 686 int. 402 Col. Del valle C.P. 03100

3| P a g e Soluciones especializadas de TI

DESARROLLO DE SOFTWARE PROMOCIÓN TURÍSTICA RURAL ON-LINE

SOLUCIONES DE INTEGRACIÓN

Y MOVILIDAD

SERVICIOS WINDOWS FWC se instala en sistemas operativos Windows y funciona como un servicio Windows. Lo que significa que no tiene interfaz de usuario y funciona en “background”. Es decir, FWC no se puede visualizar. Solamente es un script que funciona sin requerir la intervención del usuario. Los servicios no son nada más ni nada menos que programas o aplicaciones cargadas por el propio sistema operativo. Estas aplicaciones tienen la particularidad que se encuentran corriendo en segundo plano (Background). 1.

Para abrir la consola de servicios presione las teclas

2.

Escriba services.msc y presione la tecla enter.

COMUNICACIÓN CON FISCOCLIC WEB SERVICE (WSDL) Para que FWC funcione, necesita tener conexión en tiempo real con FiscoClic Web Services. FiscoClic Web services exponen mediante el WSDL (Web Services Description Language) una estructura que FWC entiende y por éste canal mandará los XML para timbrar y obtener su PDF. Los Web services están disponible en un link público que define la forma de comunicación, los requisitos del protocolo, la lista de servicios ofrecidos, los tipos de datos y los formatos de mensajes necesarios para que CUALQUIER sistema “cliente” pueda interactuar con los Web Service. De ésta manera, FWC puede leer el WSDL para determinar qué funciones están disponibles en el servidor y pueda utilizarlas. Para mayor referencia visite http://es.wikipedia.org/wiki/WSDL El WSDL de FiscoClic Web services se encuentra en https://www.fiscoclic.mx/factura/WSEntityServices/timbre/TimbraWS?wsdl FWC se conecta en específico a una operación que recibe una factura XML versión 3.2 y regresa al sistema “cliente” un “zip” que contiene 2 archivos: el XML con el nodo TimbreFiscalDigital y la representación impresa en formato PDF. El XML que reciba FiscoClic Web Services, debe ser generado previamente con el sello digital del contribuyente, mismo que será validado por FiscoClic. La representación impresa saldrá con el logotipo y color configurado previamente en el portal web www.fiscoclic.mx . Ésta última tarea de generar el XML CFDI 3.2 antes de enviarlo a FiscoClic Web Services lo realiza FWC y él mismo manda esta factura a FiscoClic Web services para obtener tanto el XML timbrado como el PDF.

CONTACTO: (55) 44342246

www.3sit.com.mx

Insurgentes sur 686 int. 402 Col. Del valle C.P. 03100

4| P a g e Soluciones especializadas de TI

DESARROLLO DE SOFTWARE PROMOCIÓN TURÍSTICA RURAL ON-LINE

SOLUCIONES DE INTEGRACIÓN

Y MOVILIDAD

AMBIENTE DE PRUEBAS Las definiciones de los servicios de pruebas se encuentran en el mismo link del WSDL. FWC únicamente necesita configurar los siguientes parámetros cuando se esté probando el servicio. Posteriormente se entregarán el usuario funcional para reemplazar en la configuración de FWC y poder entrar en producción.

user=AAA111111ZZZ pass=TeStInGfIsCoClIc2012Ws IMPORTANTE: Solicite a su asesor tecnológico FiscoClic las claves de producción de FWC para acceder a FiscoClic Web Services y también tu usuario de portal para que puedas configurar tu certificado de sello digital y tu logotipo para el PDF.

CONSIDERACIONES Y SUGERENCIAS SOBRE EL AMBIENTE DE PRUEBAS 1. Tanto para el ambiente de pruebas como los servicios de producción, se utiliza el protocolo HTTPS (SSL). Inicialmente dependiendo de su lenguaje de programación debe configurar su sistema para que el certificado de FiscoClic sea de “confianza”. Para ello, debe importar el certificado en su almacén de certificados de confianza y pueda hacer una conexión con nuestro servidor. 2. El Certificado de Sello digital del Timbre de prueba no se encuentra en las LCO (listas de contribuyentes obligados) de producción del SAT. 3. Los UUID generados para las facturas son de prueba y no se podrán validar en los servicios productivos del SAT 4. El resultado de los servicios que reciban un UUID, será siempre el mismo (validación, cancelación, recuperación y envío por correo) 5. El tiempo de respuesta del ambiente de pruebas es mucho mas corto ya que se simula la conexión con el SAT. Considere un factor de 2X para el tiempo de respuesta de los servicios. Por ejemplo, si tarda 0.5 segundos al timbrar en pruebas, considere que el servicio de timbrar en producción tardará 1 segundo en promedio (hay casos que el SAT tarda mas de 40 segundos en timbrar)

CONTACTO: (55) 44342246

www.3sit.com.mx

Insurgentes sur 686 int. 402 Col. Del valle C.P. 03100

5| P a g e Soluciones especializadas de TI

DESARROLLO DE SOFTWARE PROMOCIÓN TURÍSTICA RURAL ON-LINE

SOLUCIONES DE INTEGRACIÓN

Y MOVILIDAD INSTALACIÓN DE FWC Ejecuta el programa de instalación como usuario administrador. Posteriormente elige “siguiente” en todo y fíjate muy bien la ruta donde vas a instalar FWC por que tendrás que ir ahí para configurar el servicio antes de arrancarlo.

CONTACTO: (55) 44342246

www.3sit.com.mx

Insurgentes sur 686 int. 402 Col. Del valle C.P. 03100

6| P a g e Soluciones especializadas de TI

DESARROLLO DE SOFTWARE PROMOCIÓN TURÍSTICA RURAL ON-LINE

SOLUCIONES DE INTEGRACIÓN

Y MOVILIDAD

CONFIGURACION DE FWC FWC requiere de un archivo de configuración que es creado al realizar la instalación. Dicho archivo se encuentra en la ruta de instalación la cual tiene la siguiente estructura:

Elige un editor de texto y abre el archivo FiscoClicAgent.exe.config. Dicho archivo tiene la siguiente estructura:

CONTACTO: (55) 44342246

www.3sit.com.mx

Insurgentes sur 686 int. 402 Col. Del valle C.P. 03100

7| P a g e Soluciones especializadas de TI

DESARROLLO DE SOFTWARE PROMOCIÓN TURÍSTICA RURAL ON-LINE

SOLUCIONES DE INTEGRACIÓN

Y MOVILIDAD

…………

NOTAS IMPORTANTES 1. 2. 3. 4.

Únicamente debes modificar lo que se encuentra entre las etiquetas de appSettings los valores en AZUL Todas las rutas que coloques de directorios deben separarse con doble diagonal invertida \\ Las modificaciones deben realizarse cuando FWC (servicio Windows) esté detenido Los cambios en el archivo de configuración se tomarán cuando FWC se vuelva a inicie/reinicie

• filePathGenerados: es la carpeta donde se van a estar colocando los XML del CFD en versión 2.2 •

filePathProcesados: es la carpeta donde FWC coloca los archivos que ya fueron procesados

•

filePathErrores: es la carpeta donde se colocan los archivos que tuvieron algún error en conversión o en timbrado.

•

filePathResultados: es la carpeta donde se colocan los archivos .zip de las facturas. Cada.zip contiene el XML timbrado en versión 3.2 y el PDF estándar de FiscoClic.

•

Usuario: es el usuario funcional para poder autenticarse a FiscoClic Web Services.

•

Password: es el password del usuario funcional para poder autenticarse con FiscoClic Web Services.

•

filePathsellocer: Es la ruta del archivo con terminación .cer de su certificado de sello digital

•

filePathsellokey: Es la ruta del archivo con terminación .key de su certificado de sello digital

•

clavellaveprivada: Es la clave de llave privada con la que generó su certificado de sello digital

ARRANCAR Y DETENER A FWC 1. Entrar a Windows como administrador 2. Entrar a la consola de servicios en Windows presionando las teclas 3. Escriba services.msc y presione la tecla enter

CONTACTO: (55) 44342246

www.3sit.com.mx

Insurgentes sur 686 int. 402 Col. Del valle C.P. 03100

8| P a g e Soluciones especializadas de TI

DESARROLLO DE SOFTWARE PROMOCIÓN TURÍSTICA RURAL ON-LINE

SOLUCIONES DE INTEGRACIÓN

Y MOVILIDAD

4. Ubique el servicio “FiscoClic Windows Connector” y de doble click. Vaya a la pestaña de “Iniciar Sesion”

5. Elegir la opción de “Cuenta del sistema local”. Posteriormente vaya a la pestaña de General y de click en “Iniciar”. Recuerde que FWC toma al iniciarse en automático los parámetros del archivo de configuración

CONTACTO: (55) 44342246

www.3sit.com.mx

Insurgentes sur 686 int. 402 Col. Del valle C.P. 03100

9| P a g e Soluciones especializadas de TI

DESARROLLO DE SOFTWARE PROMOCIÓN TURÍSTICA RURAL ON-LINE

SOLUCIONES DE INTEGRACIÓN

Y MOVILIDAD

6. Para detener el servicio igualmente en la pestaña de General de click en el botón “Detener”

LOGS Y MONITOREO DE FWC FWC tiene dos formas de monitorear. 1. Logger.txt ubicado en la ruta de instalación de FWC. Errores generales de timbrado o parseo 2. El event viewer de Windows bajo la llave LogFiscoClic. Errores de Windows de arranque

CONTACTO: (55) 44342246

www.3sit.com.mx

Insurgentes sur 686 int. 402 Col. Del valle C.P. 03100

10| P a g e Soluciones especializadas de TI

DESARROLLO DE SOFTWARE PROMOCIÓN TURÍSTICA RURAL ON-LINE

SOLUCIONES DE INTEGRACIÓN

Y MOVILIDAD NOTAS IMPORTANTES Si la llave LogFiscoClic del visor de eventos se llena FWC se va a detener. Para evitar este aspecto, entra al visor de eventos (como administrador), ve a las propiedades de la llave (click derecho /opción propiedades) y aumenta el tamaño máximo del registro y elige la opción “sobreescribir eventos si es necesario”.

OBSERVACIONES GENERALES FISCOCLIC WEB SERVICES

Y

FWC

1. Los servicios Web son “Stateless” por lo que no guardan ningún estado ni crean una sesión autenticada. Esto representa que por cada petición debe existir una identificación y autorización del usuario. Posterior a la firma del contrato, cada contribuyente que desee utilizar FiscoClic Web Services, recibe un usuario y un password que va a utilizar en sus sistemas o en FWC para poder invocar los servicios web. 2. Al ser servicios dependientes de otros sistemas (proveedores de certificación y el SAT), los servicios de timbrado pueden llegar a saturarse en horas pico o tardar más de lo normal, normalmente el tiempo de timbrado es entre 0.8 y 2.5 segundos. Recomendamos tener un “Timeout” en las petición entre 100 y 120 segundos ya que hemos registrado casos que el SAT ha tardado hasta 2 minutos en timbrar un comprobante y hasta 180 segundos para una cancelación en horas de alta demanda 3. Recurrentemente en las cancelaciones ocurren errores por que la factura “NO EXISTE” en el SAT. El servicio Web de cancelación se conecta directamente a SAT. Esto pasa la mayoría de las veces por que las facturas tardan en verse reflejadas en el portal del SAT para poderse cancelar. Han existido casos que una factura tarda hasta 3 horas en aparecer en los portales del SAT aunque ya se haya timbrado y generado un folio fiscal en tiempo real.

CONTACTO: (55) 44342246

www.3sit.com.mx

Insurgentes sur 686 int. 402 Col. Del valle C.P. 03100

11| P a g e Soluciones especializadas de TI

DESARROLLO DE SOFTWARE PROMOCIÓN TURÍSTICA RURAL ON-LINE

SOLUCIONES DE INTEGRACIÓN

Y MOVILIDAD

4. El error que más ocurre y es motivo de no poder facturar en un 60% de nuestros clientes, es que suben su FIEL a FiscoClic en lugar de su sello digital, lo que ocasiona que el SAT regrese un error de “No se puede timbrar” o el “El sello es de tipo fiel y no de CSD”. Recomendamos ampliamente revisar qué tipo de certificado se configura en el portal web de FiscoClic y en FWC. Las facturas deben sellarse con el Certificado de Sello Digital y NO con el Certificado de FIEL. 5. Es indispensable que toda la obtención y manejo de cadenas (incluida la cadena original) esté codificada en UTF-8, las secuencias de escape no son necesarias al expresar el documento XML bajo el estándar de codificación UTF-8 si fue creado correctamente. De igual manera es importante recordar que el sello del XML, deberá ser expresado cómo una cadena de texto en formato Base 64. FWC ya realiza todo esto por usted. 6. El estándar del SAT para los decimales permite tener hasta 6 dígitos y así es como el comprobante se timbra y se almacena en su formato XML. Sin embargo, para los servicios en los que se cuenta con la generación del PDF, el estándar de FiscoClic es redondear dichos elementos únicamente a dos decimales. El formato es estándar y es idéntico al formato generado desde el portal www.fiscoclic.mx; únicamente se podrá configurar el logotipo y el color de la factura por el mismo portal para cada contribuyente. 7. Cualquier RFC va en mayúsculas, sin guiones, ni espacios y únicamente pueden ser de longitud 12 para personas morales o 13 para personas físicas. 8. Es necesario contar en su sistema con manejo de excepciones en todas las peticiones que se realizan a los web services de FiscoClic. FWC ya realiza esto por usted. 9. Se recomienda ampliamente para evitar problemas de validación de fechas con el certificador, que la fecha de generación de factura sea 5 o 10 minutos menor a la fecha actual, ya que muy probablemente su sistema (o servidor) pueda tener una fecha que sea posterior a la fecha del certificador y éste le lance un error.

CONTACTO: (55) 44342246

www.3sit.com.mx

Insurgentes sur 686 int. 402 Col. Del valle C.P. 03100

12| P a g e Soluciones especializadas de TI

DESARROLLO DE SOFTWARE PROMOCIÓN TURÍSTICA RURAL ON-LINE

SOLUCIONES DE INTEGRACIÓN

Y MOVILIDAD ERRORES DEL SAT FiscoClic tiene sus propios errores manejados por medio del SOAP Fault, así como sus propias validaciones. Sin embargo, cada proveedor de certificación regresa a FiscoClic los errores y las validaciones de acuerdo a los estándares del SAT y básicamente se valida lo siguiente: Mensaje Original de SAT Que cumpla con el estándar de XML y con el esquema XSD Que el sello del Emisor sea válido Que el CSD del Emisor corresponda al RFC que viene como Emisor en el Comprobante. Que el CSD del Emisor no haya sido revocado, utilizando la lista de LCO. Que la fecha de emisión esté dentro de la vigencia del CSD del Emisor. Que la llave utilizada para sellar corresponda a un CSD (no de FIEL). Que no contenga un timbre previo. Que el CSD del Emisor haya sido firmado por uno de los Certificados de Autoridad de SAT. Que el rango de la fecha de generación no sea mayor a 72 horas para la emisión del timbre. Que exista el RFC del emisor conforme al régimen autorizado (Lista de validación de régimen) LCO. Que la fecha de emisión sea posterior al 01 de Enero 2011.

DATOS DE CONTACTO Soluciones a la medida: www.3sit.com.mx Factura electrónica www.fiscoclic.mx

Tel: 44342246

Tel: 50032142

Responsable del área técnica: Carlos Santillán

CONTACTO: (55) 44342246

www.3sit.com.mx

Insurgentes sur 686 int. 402 Col. Del valle C.P. 03100

email: [email protected]

email informació[email protected]

13| P a g e Soluciones especializadas de TI