Documentación para desarrolladores e integradores



Introducción

La empresa Facturación Moderna S.A de C.V, es un Proveedor Autorizado de Certificación (PAC) con número de autorización: 58077 que ofrece los servicios de validación, emisión, resguardo y certificación de CFDI.

Facturación Moderna cuenta con una API SOAP para el servicio de emisión/timbrado de CFDI.

Métodos de Conexión

  • Opción 1: Timbrado de CFDI a partir de un archivo de texto simple mediante Web service o por nuestro conector Ctifac.
  • Opción 2: Timbrado de CFDI a partir de un archivo XML con estructura propia o que siga el estándar CFDI propuesto por el SAT, mediante Web service o por nuestro conector Ctifac.

Beneficios

Al contratar con nosotros el servicio de timbrado, Facturación Moderna te proporciona los siguientes beneficios:

  • Portal de administración y consulta de consumo de timbres en tiempo real.
  • Soporte técnico por email, teléfono y chat.
  • Certificación de cualquier tipo de comprobantes fiscales con soporte para Complementos de Factura Electrónica.
  • Generación de la representación impresa del CFDI o del CBB en formato PNG por Web services.
  • Envío automático del CFDI al cliente final vía Email.
  • Respaldo automático de tus comprobantes emitidos a un servidor FTP o cuenta de Dropbox.
  • Cancelación de CFDI mediante un portal o Web service.
  • Requerimientos adicionales o manejo de lógica del negocio.





¿Comó funciona?

El servicio de timbrado recibe una petición con el archivo a certificar codificado en Base64 y devuelve un objeto con el XML certificado y la representación impresa.

A continuación se presenta un diagrama del funcionamiento general de la solución:

  • Insumos: Archivo de texto (layout) o XML que se quiere enviar a certificar en Base64.
  • Procesamiento: Proceso de validación del comprobante, certificación, envío y almacenamiento del mismo.
  • Resultado: En caso de éxito el sistema devuelve archivo XML del CFDI, representación impresa del CFDI en formato PDF y nodo TimbreFiscalDigital en formato de texto codificado en Base64.

Diagrama 1: Funcionamiento general.






Kit de implementación

Cliente genérico de pruebas ideal para validar tus archivos a certificar

Nota: El cliente es solamente de referencia, sólo deberá ser utilizado para realizar pruebas de estructura y contenido de los archivos a timbrar. (Layout o XML)

Archivos de ayuda

URL del servicio de timbrado. (Endpoint)

  • https://t2demo.facturacionmoderna.com/timbrado/soap

WSDL

  • https://t2demo.facturacionmoderna.com/timbrado/wsdl

Métodos

Ejemplos de Conexión en diferentes lenguajes

Conexion mediante DLLs

  • DLLs compatibles con microsoft.net framework 3.4, 4.0, 4.5 Descargar DLLs





Método requestTimbrarCFDI

El método requestTimbrarCFDI es capaz de certificar cualquier archivo en formato XML o TXT, el cual espera como parámetro un objeto de la siguiente forma:



Descripción del objeto de petición

Propiedad Tipo Descripción Observaciones
UserPass String Contraseña de la conexión Para el ambiente de pruebas es: b9ec2afa3361a59af4b4d102d3f704eabdf097d4
UserID String Nombre del usuario de la conexión Para el ambiende de pruebas es: UsuarioPruebasWS
emisorRFC String RFC del la empresa que emite el comprobante a certificar. Para el ambiente de pruebas el RFC del emisor deberá ser alguno de los siguientes:
  • ESI920427886
  • TUEM470405V4A
  • TUMG620310R95
Descargar Certificados de Prueba.
text2CFDI String Archivo fuente a certificar (Layout o XML) codificado en Base64 Importante El nodo debe estar codificado en Base64.
Puede realizar pruebas de estructura del archivo aquí.
Si desea visualizar ejemplos de archivos fuente de clic aquí
generarPDF (Opcional) Boolean True si se desea que el servicio retorne la representación impresa del CFDI en formato PDF. Al utilizar está propiedad, el método requestTimbrarCFDI retorna el archivo codificado en Base64 en el nodo pdf.
generarCBB (Opcional) Boolean True si se desea que el servicio regrese un archivo PNG con el código de barras bidimensional (CBB). Al utilizar está propiedad, el método regresa el nodo png en lugar del nodo pdf

Petición SOAP

A continuación se muestra una petición al método en formato XML para consumir el método requestTimbrarCFDI con SOAP 1.2

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" xmlns:ns1="https://t1demo.facturacionmoderna.com/timbrado/soap" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:enc="http://www.w3.org/2003/05/soap-encoding">
  <env:Body>     <ns1:requestTimbrarCFDI env:encodingStyle="http://www.w3.org/2003/05/soap-encoding">       <param0 xsi:type="enc:Struct">         <UserPass xsi:type="xsd:string">b9ec2afa3361a59af4b4d102d3f704eabdf097d4</UserPass>         <UserID xsi:type="xsd:string">UsuarioPruebasWS</UserID>         <emisorRFC xsi:type="xsd:string">RFC del emisor contenido en el archivo</emisorRFC>         <text2CFDI xsi:type="xsd:string">Archivo codificado en Base64</text2CFDI>         <generarTXT xsi:type="xsd:boolean">false</generarTXT>         <generarPDF xsi:type="xsd:string">false</generarPDF>         <generarCBB xsi:type="xsd:boolean">false</generarCBB>       </param0>     </ns1:requestTimbrarCFDI>   </env:Body> </env:Envelope>

Descripción del objeto de respuesta

Una vez realizada la petición en caso de éxito nos devolverá un objeto con las siguientes propiedades

Nodo Tipo Descripción Ejemplos de contenido
xml String (Base64) Contiene el CFDI certificado en formato XML. (Codificado en Base64) Visualizar/Descargar
pdf String (Base64) Contiene la representación impresa del CFDI en formato PDF. (Codificado en Base64) Visualizar/Descargar
txt String (Base64) Contiene el nodo TimbreFiscalDigital en formato de texto. (Codificado en Base64) Visualizar/Descargar
png String (Base64) Contiene CBB en formato PNG, este nodo aparece si la propiedad generarCBB fue establecidad con True. (Codificado en Base64) Visualizar/Descargar

Respuesta SOAP

La respuesta en formato XML es similar al siguiente ejemplo

              <?xml version='1.0' encoding='utf-8'?>
              <SOAP-ENV:Envelope
              xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
              xmlns:xsd="http://www.w3.org/2001/XMLSchema"
              xmlns:ns1="https://t2demo.facturacionmoderna.com/timbrado/soap"
              xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
              <SOAP-ENV:Body>
              <ns1:requestTimbrarCFDIResponse>
              <return xsi:type="SOAP-ENC:Struct">
              <xml xsi:type="xsd:string">Nodo con el archivo XML codificado en Base64</xml>
              <txt xsi:type="xsd:string">Nodo con el archivo TXT codificado en Base64</txt>
              <pdf xsi:type="xsd:string">Nodo con el archivo PDF codificado en Base64</pdf>
              </return></ns1:requestTimbrarCFDIResponse>
              </SOAP-ENV:Body>
              </SOAP-ENV:Envelope>





Método requestCancelarCFDI

El método requestCancelarCFDI realiza la cancelación de un CFDI ante el SAT, el método recibe un UUID (Folio Fiscal) y RFC del emisor.

Nota: Para poder pasar a modo producción y poder cancelar, es necesario que el cliente haya cargado sus certificados en el portal: https://gtifac.facturacionmoderna.com

Descripción del objeto de petición

Propiedad Tipo Descripción Observaciones
UserPass String Contraseña de la conexión Para el ambiente de pruebas es: b9ec2afa3361a59af4b4d102d3f704eabdf097d4
UserID String Nombre del usuario de la conexión Para el ambiende de pruebas es: UsuarioPruebasWS
emisorRFC String RFC con el cuál se desea realizar la conexión, deberá ser el mismo que venga en el archivo a certificar. En ambiente de pruebas puede utilizar cualquiera de los RFC incluidos en los certificados de prueba, en la sección Kit de ayuda.
uuid String UUID del CFDI que se desea cancelar  

Petición SOAP

A continuación se muestra una petición al método en formato XML para consumir el método requestCancelarCFDI con SOAP 1.2

              <?xml version="1.0" encoding="UTF-8"?>
              <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://t1demo.facturacionmoderna.com/timbrado/soap" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
              <SOAP-ENV:Body><ns1:requestCancelarCFDI>
	            <request xsi:type="SOAP-ENC:Struct">
		          <UserPass xsi:type="xsd:string">b9ec2afa3361a59af4b4d102d3f704eabdf097d4</UserPass>
		          <UserID xsi:type="xsd:string">UsuarioPruebasWS</UserID>
		          <emisorRFC xsi:type="xsd:string">ESI920427886</emisorRFC>
		          <uuid xsi:type="xsd:string">ABC1147C-D41E-4596-9C3E-45629B097CDB</uuid>
	            </request>
              </ns1:requestCancelarCFDI>
              </SOAP-ENV:Body>
              </SOAP-ENV:Envelope>
            

Respuesta SOAP

La respuesta en formato XML es similar al siguiente ejemplo

Nuestro servicio de cancelación funciona mediante una cola, la cancelación de un comprobante se realiza de 2 a 3 minutos después de haberlo enviado a cancelar.

              <?xml version="1.0" encoding="UTF-8"?>
              <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://t1demo.facturacionmoderna.com/timbrado/soap" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
              <SOAP-ENV:Body><ns1:requestCancelarCFDIResponse>
              <return xsi:type="SOAP-ENC:Struct">
              <Code xsi:type="xsd:string">GT05</Code>
              <Message xsi:type="xsd:string">UUID enviado a la cola de cancelancion, espere unos minutos.</Message>
              </return>
              </ns1:requestCancelarCFDIResponse>
              </SOAP-ENV:Body>
              </SOAP-ENV:Envelope>
		        





Archivos Soportados

La propiedad text2CFDI enviada en el método requestTimbrarCFDI soporta los siguientes tipos de archivos

Puedes descargar ejemplos de archivos por tipo de documento o giro. (Facturas,Recibos de Nómina, Notas de Crédito, Carta Porte, Recibos de Arrendamiento, Facturas de Hoteles, Restaurantes, Constructoras.) Archivos fuente de prueba


Tipo de archivo Descripción Ventajas Ejemplos
Archivo XML (CFDI 3.2) Archivo XML con las especificaciones requeridas por el SAT según el Anexo 20.
  • Soporta Complementos de Factura Electrónica
  • Soporta datos adicionales en el nodo Addenda.
  • Es necesario agregar el sello digital al comprobante.
  • Menor tiempo de procesamiento y respuesta.
Descargar
Archivo XML (versión 2.2) Archivo XML con las especificaciones requeridas por el SAT según el Anexo 20.
  • Orientado a personas que migrarán de CFD a CFDI.
  • El sello , certificado y No. certificado son opcionales.
  • Menor tiempo de adaptación.
Descargar
Archivo de texto (Layout) delimitado por 'pipes' ( | ) Archivo de texto simple, contiene los datos básicos para generación de un Comprobante Fiscal en formato de texto.
  • El sellado y timbrado del comprobante lo realiza automáticamente nuestro Web service.
  • Asignación de folio y fecha en automático.
  • Menor tiempo de implementación.
Descargar
Archivo de texto (Layout) en formato INI Archivo de texto simple, contiene los datos básicos para generación de un Comprobante Fiscal en formato de texto.
  • El sellado y timbrado del comprobante lo realiza automáticamente nuestro Web service.
  • Menor tiempo de implementación.
  • Asignación de folio y fecha en automático.
  • Soporte para datos adicionales.
Descargar
Formato Propio Si tu sistema genera un archivo TXT o XML con los datos básicos para generar un comprobante fiscal, nos podemos adaptar al mismo.
Sólo envía tu solicitud a nuestra cuenta de: soporte@facturacionmoderna.com





Ejemplos por tipo de documento

Ejemplo de la estructura del archivo fuente para timbrado (XML y TXT) para el timbrado de comprobantes fiscales según el tipo de documento






Ejemplos de Conexión

Ejemplos funcionales para el timbrado y cancelación en el lenguaje correspondiente.

Consulta nuestros ejemplos en GitHub https://github.com/facturacionmoderna

Conexion mediante DLLs

  • DLLs compatibles con microsoft.net framework 3.4, 4.0, 4.5 Descargar DLLs





Códigos de error

Código Descripción Causa
FM501 Detalles de conexión requeridos. No se está indicando las credenciales de acceso al servicio (userPass, userID).
FM507 El RFC de la solicitud no corresponde con el comprobante. El RFC del emisor proporcionado no coincide con el RFC emisor del layout.
FM402 El RFC utilizado no se encuentra en la Lista de Contribuyentes Obligados (LCO). El RFC del emisor proporcionado aun no está registrado en la lista oficial de contribuyentes obligados del SAT (Actualizado diariamente.)
301 El CFDI no cumple con el estándar XML. El archivo contiene algún error en la estructura del CFDI.
302 El sello del emisor es inválido. Generalmente ocurre cuándo realiza un paso incorrecto en el proceso de sellado o alguna modificación al contenido del XML después de haber generado el sello.
303 La serie del certificado utilizado no corresponde al certificado reportado. El atributo noCertificado no corresponde al contenido del atributo certificado del XML.
304 El certificado ha sido revocado. El certificado utilizado para sellar el comprobante, aparece como revocado en LCO.
305 El certificado ha expirado. El certificado empleado ha superado su vigencia.
306 El CFDI fue firmado con una FIEL.
307 El CFDI contiene un timbre previo. Ocurre cuándo se envía un XML con el nodo timbre incluido o cuándo el contenido del archivo XML es exactamente el mismo a uno previamente certificado.
307 El comprobante ya fue timbrado anteriormente.
401 El CFDI tiene más de 72 horas de haber sido expedido. La fecha de emisión del comprobante ha superado las 72 horas.





Herramientas







Generar archivos .pem

Lo primero que se necesita es tener instalada la librería OpenSSL (programa dedicado a la generación y tratado de claves, certificados y keyStore) para poder utilizar los comandos que nos ayudarán a crear las llaves de nuestros sellos digitales.

Linux

Instalar librería:

Debian/Ubuntu: #sudo apt-get install openssl

CentOS, Red Hat: #yum install openssl

Ejecutar las instrucciones:

Archivo key.pem

openssl pkcs8 -inform DER -in nombrearchivo.key -out nombrearchivo.key.pem -passin pass:contraseña
archivo cer.pem
openssl x509 -inform DER -outform PEM -in ruta/nombreArchivo.cer -pubkey -out ruta/nombreArchivo.cer.pem

Windows

Descargar libreria: http://slproweb.com/products/Win32OpenSSL.html

Deberán descargar la versión según su sistema operativo, e instalar.

Ejecutar desde terminal

Archivo key.pem

openssl.exe pkcs8 -inform DER -in ruta/nombreArchivo.key -passin pass:contraseña -out ruta/nombreArchivo.key.pem
archivo cer.pem
openssl.exe x509 -inform DER -outform PEM -in ruta/nombreArchivo.cer -pubkey -out ruta/nombreArchivo.cer.pem






Aplicar a modo producción

Si haz realizado pruebas de conexión exitosas puedes aplicar para pasar a producción.

Sólo tienes que enviar evidencia de 3 comprobantes timbrados exitosamente (XML, PDF) al correo de wsoporte@facturacionmoderna.com y haber realizado la contratación de los servicios.






Términos y condiciones

Descargar los Términos y condiciones de uso del servicio