Servicio Web de Timbrado Este documento describe la información relacionada para la implementación del Servicio Web de Timbrado Versión del documento 2.0 DotNET Desarrollo de Sistemas 01/01/2017
Contenido Introducción... 2 A quién va dirigido... 2 Alcance... 2 Prerrequisitos... 2 Recomendaciones... 3 Web Service de Timbrado... 4 Servicio de obtención del timbrado... 5 Servicio de cancelación del CFDI... 1 Preguntas Frecuentes... 3 DotNET Desarrollo de Sistemas Manual de referencia para el desarrollador 1
Introducción Este documento detalla la especificación del Servicio Web de Timbrado para el esquema CFDI Versión 3.2 y CFDI de Retenciones Versión 1.0 El objetivo del Servicio Web de Timbrado es proveer una serie de operaciones, entre las que se incluyen, generar el timbre fiscal digital (TFD) de los comprobantes fiscales digitales por internet (CFDI); además de poder solicitar la cancelación de los mismos. A quién va dirigido El presente documento va dirigido al área de desarrollo y personal de sistemas con conocimientos en consumo de Servicios Web sin importar la plataforma o sistema operativo. Alcance Se provee la información necesaria para el consumo del Servicio Web de Timbrado. Pre requisitos Estar familiarizado con el consumo de Web Services, el protocolo SOAP, el lenguaje XML y los estándares establecidos por el esquema CFDI 3.2. IMPORTANTE: para la realización de comprobantes de nómina es necesario que verifique los documentos emitidos por el SAT que contienen las especificaciones técnicas de los datos a incorporar en los recibos de nómina. DotNET Desarrollo de Sistemas Manual de referencia para el desarrollador 2
Recomendaciones Es importante que para una respuesta correcta del Web Service de Timbrado, lea detenidamente este documento. En caso de que encuentre información confusa o que le parezca incompleta, nos puede contactar: soporte@facturadorelectronico.com 01 800 272 06 46 No se confié por la sencillez del web service, y desee adquirir primero sus timbres sin haber hecho pruebas, ya que pueden surgir detalles (quizá para usted desconocidos) en sus pruebas, que pueden retrasarlo a usted y a su cliente. Es importante que genere el XML CFDI 3.2 conforme las especificaciones del Anexo 20(En la parte que describe CFDI) Si está migrando de CFD a CFDI debe repasar el Anexo 20 para ver los cambios significativos de la nueva versión. Se le recomienda que tenga a la mano algún editor de XML que le permita validar archivos Xml contra esquemas ya que abrir un XML con algún navegador o bloc de notas no le será de ayuda. Esto le puede facilitar la resolución de los posibles errores que pueda obtener del Web Service ó evitar los mismos. Altova XMLspy Notepad++ con plugin xml tools Free xml editor Puede que la estructura de su xml sea válida y haya obtenido el nodo del timbre, pero a nivel fiscal no necesariamente este colocando los datos ó nodos correctos. Las dudas a nivel fiscal deberán consultarlas con su departamento administrativo ó utilizar la línea de ayuda del SAT. DotNET Desarrollo de Sistemas Manual de referencia para el desarrollador 3
Web Service de Timbrado Uno de los requisitos para el proceso de pruebas, es generar el archivo XML CFDI 3.2, con los certificados de prueba que se encuentran dentro de este Kit (Solo estos certificados están establecidos para pruebas). Emisor GOYA780416GM0 Contraseña llave privada: 12345678a Los datos para acceder al Web Service de Pruebas de timbrado son los siguientes: URL Web Service: https://timbradopruebas.stagefacturador.com/timbrado.asmx Usuario: test Contraseña: TEST Si desconoce cómo implementar la conexión entre su desarrollo y un web servicie, deberá consultar la documentación de su lenguaje de programación. Podemos acceder a la descripción de los métodos directamente desde la URL de timbrado: DotNET Desarrollo de Sistemas Manual de referencia para el desarrollador 4
El Web Service de Timbrado contiene 4 métodos: 1. obtenertimbrado 2. cancelarcomprobante 3. EnviarCancelacionPFX 4. CancelarComprobanteRetenciones Podemos ver los parámetros de cada método dando clic directamente en el nombre del método o para una lectura más amigable podemos cargar el descriptor directamente a una aplicación, por ejemplo soapui. Servicio de obtención del timbrado El método obtenertimbrado requiere del XML CFDI 3.2, un usuario y contraseña como parámetros de entrada: Código de ejemplo: miinstancia.obtenertimbrado(string CFDIcliente, string Usuario, string password) El método obtener timbrado únicamente regresa el nodo del timbre del timbre Usted debe integrar el nodo del timbre en el nodo de complementos de su XML CFDI 3.2 DotNET Desarrollo de Sistemas Manual de referencia para el desarrollador 5
Ensobretado SOAP Para hacer la solicitud de Timbrado por medio de SOAP UI se deben reemplazar los siguientes caracteres del XML: < Se reemplaza por < > Se reemplaza por > " Se reemplaza por " En caso de utilizar Ampersand o Comillas en la definición de algún campo del XML se deberán codificar de la siguiente forma para evitar problema con la codificación de estos símbolos: & Se codifica así: &Amp;amp; " Se codifica así: " También es posible realizar la petición de timbrado utilizando el siguiente TAG <![CDATA[]]> Ingresando la información del XML dentro de los corchetes marcados en color verde, para esto no es necesario reemplazar ningún carácter del XML.
Respuesta del proceso de Timbrado Se obtiene un XML de respuesta con la siguiente estructura: Dato Tipo de dato Longitud Descripción obtenertimbradoresult xml Xml que contiene la respuesta del Web Service de Timbrado. La obtención del timbre es exitosa cuando se obtiene la respuesta del Web Service de Timbrado con la siguiente estructura:
Ejemplo de respuesta correcta Nota: En caso de desconocer como manejar (insertar nodos, eliminar nodos, etc ) XMLs, deberá consultar la documentación de su lenguaje de programación. Estos deberán proveerle opciones como Xpath ó Clases incluidas dentro del propio lenguaje, que faciliten el manejo de XML. Caso contrario, la respuesta es la siguiente
Ejemplo <obtenertimbradoresponse xmlns="http://facturadorelectronico.com/timbrado/"> <obtenertimbradoresult> <timbre esvalido="false" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"> <errores> <Error codigo="306" mensaje="el certificado utilizado no es de Sello Digital" /> </errores> </timbre> </obtenertimbradoresult> </obtenertimbradoresponse> Se muestra el error que surgió durante el proceso de la obtención del timbre fiscal digital, mediante un código de error. Para más información acerca de los errores, consultar el documento Manejo de Errores de Timbrado
Servicio de cancelación del CFDI El método cancelarcomprobante requiere como parámetros un Xml de cancelación, un usuario y contraseña. El XML de cancelación debe contener la siguiente estructura: Nota: Las cancelaciones únicamente aplican para los comprobantes timbrados con nuestro Web Service. miinstancia.cancelarcomprobante(string xmlcancelacion, string usuario, string password) DotNET Desarrollo de Sistemas Manual de referencia para el desarrollador 1
La respuesta de Cancelación contiene la siguiente estructura: Devuelve esvalido= True únicamente para indicar que la petición al Web Service se llevó a cabo correctamente (Esto no indica que su comprobante se canceló). Dentro de esta respuesta se encuentra el UUID con su correspondiente status. Los estatus se describen a continuación: Estatus Descripción 201 El folio UUID del CFDI ha sido exitosamente cancelado. 202 El folio UUID del CFDI ha sido previamente cancelado. 203 El folio UUID del CFDI no fue encontrado 204 El folio UUID no es aplicable para ser cancelado 205 El folio UUID del CFDI aún no ha sido enviado al SAT NOTA: El error 205 en pruebas es tomado como una prueba con éxito. Si existe algún error en la petición de cancelación, se muestra el código de error, con su correspondiente descripción. DotNET Desarrollo de Sistemas Manual de referencia para el desarrollador 2
Preguntas Frecuentes 1. Soy nuev@ en estos temas, pero deseo que mi sistema genere facturación electrónica, por donde puedo empezar? Para el servicio de timbrado, se recomienda consultar información para la generación de conexiones con web services mediante el lenguaje de programación que estén utilizando, también conocer que es XML y lo más importante consultar la página del SAT Anexo 20, en el cual se encuentran el documento con las especificaciones para la generación de CFDI 3.2 2. Aún no he realizado pruebas pero ya quiero contratar, es recomendable? Para evitar errores a futuro en producción, el desperdicio de timbres y la pérdida de tiempo, se requiere que primero se lleven a cabo todas las pruebas necesarias con este Kit. 3. Cuánto tiempo se tardan en implementar el servicio de timbrado, en producción? Mucho depende del proceso de pruebas por parte del cliente, ya que el proceso de contratación no lleva más de 24hrs. 4. No tengo tiempo para generar el CFDI 3.2, requiero que mi cliente ya genere facturación, Qué puedo hacer? Pueden consultar nuestra alternativa de Interfaz ERP. 5. Ustedes además del timbrado regresan el código bidimensional? El web service devuelve el Nodo de Timbre, en caso de requerir el Cód. Bidimensional, su sistema lo deberá generar, puede encontrar Info. De cómo generarlo en el Anexo 20 del SAT. 6. Para hacer uso del Kit de pruebas necesito adquirir algún paquete de timbres? No, la única indicación en pruebas, es evitar las pruebas de stress y crear el XML con los datos del Emisor de pruebas GOYA780416GM0. 7. Qué datos deben ir en el XML? Deben consultar el documento del SAT llamado anexo 20 correspondiente a CFDI 3.2 y en la siguiente página para CFDI de Retenciones. 8. Tienen modo de generar el XML desde mi base de datos? En caso de que así lo requiera deberá implementar esa función en su sistema junto con sus programadores. 9. Cuándo envío una cancelación se me descuentan timbres (Producción)? No, Únicamente al realizar el Timbrado se descuentan timbres. 10. Puedo cancelar mis comprobantes timbrados con otro PAC? En el servicio de cancelación, únicamente se pueden cancelar comprobantes timbrados con nuestro Web Service. 11. Puedo generar el XML de pruebas con los archivos de certificado digital de mi cliente? No, para pruebas los únicos certificados que se pueden usar son los que se encuentran en este Kit. DotNET Desarrollo de Sistemas Manual de referencia para el desarrollador 3