Servicio Web de Timbrado Este documento describe la información relacionada para la implementación del Servicio Web de Timbrado Versión documento 3.1 dotnet Desarrollo de Sistemas 01/01/2014
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... 4 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 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. Prerrequisitos Estar familiarizado con 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. LINK: http://www.sat.gob.mx/informacion_fiscal/factura_electronica/paginas/complemento_nomin a.aspx Lea con detenimiento el siguiente documento, para una exitosa implementación del servicio de timbrado. 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 ó que le parezca incompleta, por favor contactarnos: 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 conforme las especificaciones del Anexo 20(No se confunda, en una parte de la documentación se encuentra descrito CFD y en otra CFDI): http://www.sat.gob.mx/sitio_internet/e_sat/comprobantes_fiscales/15_17416.html Si esta 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 xmls contra esquemas. 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 Ya que abrir un xml con algún browser o con notepad no le va ser de mucha ayuda Puede que la estructura de su xml sea valida y haya obtenido el nodo del timbre, pero a nivel fiscal no necesariamente este colocando los datos ó nodos correctos. Dudas a nivel fiscal deberá 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 XML CFDI 3.2, con alguno de 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 timbrado son los siguientes: URL Web Service: https://stagecfdi.facturadorelectronico.com/wstimbrado/timbrado.asmx Usuario: test Contraseña: TEST Si desconoce como implementar la conexión entre su desarrollo y un web servicie, deberá consultar la documentación de su lenguaje de programación. Este kit provee ejemplos en.net y PHP. Palabras clave: -SOAP -HTTP POST Web Service dotnet Desarrollo de Sistemas Manual de referencia para el desarrollador 4
Podemos acceder a la descripción de los métodos directamente desde la url de timbrado: El Web Service de Timbrado contiene dos métodos: 1. obtenertimbrado 2. cancelarcomprobante Podemos ver los parámetros de cada método dando clic directamente en el nombre del método ó 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: dotnet Desarrollo de Sistemas Manual de referencia para el desarrollador 5
Código miinstancia.obtenertimbrado(string CFDIcliente, string Usuario, string password) El método obtener timbrado únicamente regresa el nodo del timbre del timbre Usted debe incrustar 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 6
Ensobretado SOAP Para un ensobretado SOAP el xml deberá enviarse con los caracteres <, >, " con sus caracteres de escape correspondientes
Respuesta del proceso de Timbrado: Se obtiene un XML de respuesta con la siguiente estructura: Dato Tipo de Longitud Descripción dato 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 XMLs.
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 llevo acabo 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 aun 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
<solicitud esvalido="false" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"> <errores> <Error codigo="025" mensaje="error al solicitar la cancelación al SAT: Sintaxis no válida en línea 4 - 'Se esperaba el carácter >'." /> </errores> </solicitud> dotnet Desarrollo de Sistemas Manual de referencia para el desarrollador 3
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 conexiónes 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. Aun no he realizado pruebas pero ya quiero contratar, es recomendable? Para evitar errores a futuro en producción, el desperdicio de timbres y la perdida de tiempo, se requiere que primero se lleven acabo todas las pruebas necesarias con este Kit. 3. Cuanto 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, que puedo hacer? Pueden consultar nuestra alternativa de Interfaz ERP. 5. Ustedes además del timbrado regresan el código bidimensional? El web service únicamente (en caso de que todo el proceso se lleve acabo correctamente), responderá con otro Xml que contiene el nodo de timbrado. 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 GOYA. 7. Que datos deben ir en el XML? Deben consultar el documento del SAT, anexo 20 correspondiente a CFDI 3.2. 8. Tienen modo de generar el xml desde mi base de datos? Pueden consultar nuestra alternativa de Interfaz ERP. 9. Cuando envío una cancelación se me descuentan timbres (Producción)? Únicamente con el método obtenertimbrado se descuentan timbres. dotnet Desarrollo de Sistemas Manual de referencia para el desarrollador 4
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? 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 5