API DE INTEGRACIÓN DE SERVICIOS CFDI 3.3

API de Integración de Servicios CFDI 3.3

12 abril, 2020

En esta API se encuentra la documentación para realizar la integración de la versión 3.3 mediante un archivo de intercambio basado en un formato CSV.

Para visualizar PDF de la API de Integración: API de Integración – Servicios CFDi 3.3

Para visualizar PDF de la API de integración para el servicio de Addendas: API de integración – Servicio de Addendas

Para descargar archivo que contiene el formato CSV: Formato CSV – CFDI 3.3

A continuación se describen los siguientes métodos:

Tabla de contenido

  • Método acuseCancelacion
    • Descripción
    • URL
    • Parámetros
    • Atributos
    • Ejemplo de petición REST
  • Método cancelarCfdiConOpciones
    • Descripción
    • URL
    • Parámetros
    • Atributos
    • Ejemplo de petición REST
    • Códigos de respuesta para los diferentes servicios
    • Códigos para los nuevos estatus de cancelación.
    • Códigos para el nodo estatusCfdi en el método de consulta estatus de comprobantes.
  • Método consultacfdPorUUID:
    • Descripción
    • URL
    • Parámetros
    • Atributos
    • Ejemplo de petición REST
  • Método procesarArchivo
    • Descripción
    • URL
    • Parámetros
    • Atributos
    • Ejemplo de petición REST
    • Tabla de opciones
    • Tabla de códigos del servicio

Método acuseCancelacion:

El método permite recuperar el acuse de cancelación de un comprobante en formato base64

Se encuentra disponible en la siguiente URL:
https://timbrado.pade.mx/servicio/rest/integracion/acuseCancelacion

Y cuyos parámetros (URL Query Parameters) se describen a continuación:

  • contrato: Clave del contrato de servicios.
  • uuid: UUID del comprobante que se desea recuperar.

Las credenciales (usuario y contraseña) deberán ir en el HEAD de la petición mediante el atributo “Authorization Basic” con el formato usuario:password codificados en base64.

El tipo de contenido (atributo Content-Type) deberá especificar el valor “application/xml“.

No todos los atributos están presentes en la respuesta, y esto dependerá del resultado de la operación. La descripción de los atributos se describe a continuación:

  • contrato: Clave del contrato de servicios.
  • consultaOk. Los valores posibles son “true” o “false”, y determina si la invocación al webservice fue exitosa.
  • codigo. Código global de la invocación. Un valor de 0 (cero) indica que la invocación se dio exitosamente, o de otra forma se indica la razón del problema.
  • xmlBase64. String en formato base64 del xml correspondiente al uuid consultado.

Ejemplo de petición REST con el cliente Advanced Rest Client:


Método cancelarCfdiConOpciones:

Este método crea la solicitud de cancelación de uno o varios CFDI.

Se encuentra disponible en la siguiente URL:
https://timbrado.pade.mx/servicio/rest/integracion/cancelarCfdiConOpciones

Y cuyos parámetros (URL Query Parameters) se describen a continuación:

  • contrato. Identificador único del contrato de servicios.
  • rfcEmisor. RFC del emisor al que pertenecen los CFDI que se desea cancelar.
  • uuids: Lista de Strings con el UUID, RFC Receptor, RFC Emisor y Total del Comprobante de los CFDI que se desea cancelar. A partir del 03 de junio del 2019, para comprobantes timbrados por Prodigia o algún otro PAC se requieren enviar la siguiente información separada por el carácter pipe (|):
    • UUID para cancelar.
    • RFC Receptor del comprobante.
    • RFC Emisor del comprobante.
    • Total del comprobante.
      • Ejemplo: <uuids>UUID|RFC_Receptor|RFC_Emisor|Total</uuids>
  • certBase64: String en base64 con el archivo del certificado de sello digital con que fueron generados los CFDI que se cancelarán.
  • keyBase64: String en base64 con la Llave privada correspondiente al certificado.
  • keyPass: Contraseña de la llave privada que se está enviando.
  • opciones: Lista de String con las opciones que seran proporcionadas a la petición en el servicio, las opciones reconocidas son:
    – PLUGIN_PROCESO:GENERICO_CFDI33:1.0
    – PKCS12
    – XML_CANCELACION
    – CERT_DEFAULT
    – CONSULTAR_SALDO

Las credenciales (usuario y contraseña) deberán ir en el HEAD de la petición mediante el atributo “Authorization Basic” con el formato usuario:password codificados en base64.

El tipo de contenido (atributo Content-Type) deberá especificar el valor “application/xml“.

Ejemplo de petición REST con el cliente Advanced Rest Client


No todos los atributos están presentes en la respuesta, y esto dependerá del resultado de la operación y de las cancelaciones. La descripción de los atributos se describe a continuación:

  • statusOk. Los valores posibles son “true” o “false”, y determina si la invocación al webservice fue exitosa. Es importante observar que el valor de este atributo no refleja el valor de cada cancelación individual. Por ejemplo podemos obtener “true” aquí pero error en cada cancelación individual. Obtendremos un valor de false en este atributo en caso de un error mayor, por ejemplo que el contrato de servicios esté expirado, o el usuario tenga una contraseña incorrecta.
    rfc. RFC del emisor de los CFDI. Se proporciona para fines informativos.
  • código. Código global de la invocación. Un valor de 0 (cero) indica que la invocación se dio exitosamente, o de otra forma se indica la razón del problema.
  • mensaje. Mensaje descriptivo del error en caso que el valor de código sea diferente de cero.
  • cancelaciones. Nodo que contiene la lista con los resultados de las operaciones individuales sobre cada UUID.
  • cancelación. Nodo que contiene el resultado de una cancelación individual.
  • uuid. UUID que fue procesado.
  • código. Código generado por el SAT con el resultado de la cancelación. La lista de códigos individuales se muestra al final del documento en la tabla “Códigos de respuesta para los diferentes servicios”.
  • mensaje. Mensaje opcional adicional con la descripción del problema (en caso de haberlo).
  • acuseCancelBase64. Acuse de cancelación proporcionado por el SAT, codificado en base 64.


Códigos de respuesta par
a los diferentes servicios

Código
Descripción
0 Timbrado exitoso.
1 El usuario del webservice no existe o proporcionó una contraseña incorrecta.
2 Contrato inválido. El contrato está expirado, o no cuenta con servicio de timbrado.
3 Parámetro inválido. Uno de los parámetros de la operación del webservice es incorrecto o hace falta.
5 Off-line por mantenimiento.
7 El servicio de CancelaciónSAT no está disponible, intente más tarde.
20 El usuario no cuenta con un certificado default.
21 CFDI sin cancelar. Aplica a la consulta de acuse de cancelación.
201 Comprobante cancelado exitosamente. (sin autorización).
202 El comprobante ya ha sido previamente cancelado.
203 El RFC del emisor no corresponde.
205 El UUID no existe.
301 XML mal formado.
302 Sello mal formado o inválido.
303 Sello no corresponde al emisor.
304 Certificado revocado o caduco.
305 La fecha de emisión no está dentro de la vigencia del CSD del emisor.
306
El certificado no es de tipo CSD.
307 El CFDI contiene un timbre previo.
308 Certificado no expedido por el SAT.
401
Fecha y hora de generación fuera de rango.
402 El RFC del emisor no se encuentra en el régimen de contribuyentes.
403 La fecha de emisión no es posterior al 1 de enero de 2012.
602 CFDI no existe.


Códigos para los nuevos estatus de cancelación.

Código
Descripción
90 N – 602: Comprobante no encontrado. Este código tiene lugar cuando un comprobante no ha sido encontrado en la base de datos del SAT.
91 S – Comprobante obtenido satisfactoriamente. Este código tiene lugar cuando el comprobante consultado se encuentra en la base de datos del SAT.
92 N – 601: La expresión impresa proporcionada no es válida. Este código tiene lugar cuando alguno de los parámetros enviados para la consulta del estatus del comprobante es erróneo.
93 Indeterminado. Este código tiene lugar cuando el SAT actualizó algún elemento en la respuesta del servicio de consulta de comprobantes y dicho elemento no es reconocido por Prodigia.
94 No Cancelable. Este código comúnmente aparecerá cuando el comprobante que se desea cancelar contenga al menos un cfdi relacionado vigente.
95 Cancelado con aceptación. Este código aparecerá una vez que el cfdi está cancelado y requirió de autorización por parte del receptor para ser cancelado.
96 En proceso. Este código aparecerá cuando se intenta enviar una nueva solicitud de cancelación de un comprobante que previamente intentó ser cancelado y dicha solicitud requiere de aceptación por parte del receptor.
97 Solicitud rechazada. Este código aparecerá cuando el receptor rechaza la cancelación de algún comprobante, para este caso el cfdi queda con estado vigente.
98 Plazo vencido. Este código aparecerá cuando exista una solicitud de cancelación que requiera de aceptación por parte del receptor, y tras pasar las 72 horas, no se obtuvo respuesta alguna. En este caso el cfdi se cancela dando por hecho que la cancelación fue aceptada.
99 Límite máximo alcanzado. Pendiente por definir
201 Cancelado sin aceptación. Este código aparecerá cuando el cfdi se canceló sin necesidad de que el receptor autorice, básicamente funciona de manera unilateral.


Códigos para el nodo estatusCfdi en el método de consulta estatus de comprobantes.

Código
Descripción
0 Desconocido. Se obtiene cuando la respuesta del SAT no pudo ser interpretada de acuerdo a un estatus válido del CFDI.
1 CFDi no existe. Se obtiene cuando la respuesta del SAT indica que el comprobante no pudo ser encontrado.
2 Vigente. Se obtiene cuando la respuesta del SAT indica que el comprobante se encuentra Vigente y no se puede especificar si se requiere aceptación o no para cancelarlo.
3 Vigente con aceptación. Se obtiene cuando la respuesta del SAT indica que el comprobante se encuentra Vigente y se requiere aceptación para cancelarlo.
4 Vigente sin aceptación. Se obtiene cuando la respuesta del SAT indica que el comprobante se encuentra Vigente y no se requiere aceptación para cancelarlo.
5 Vigente no cancelable. Se obtiene cuando la respuesta del SAT indica que el comprobante se encuentra Vigente y no es posible cancelarlo.
6 Cancelado. Se obtiene cuando la respuesta del SAT indica que el comprobante se encuentra Cancelado y no se puede especificar el medio como fue cancelado(con/sin aceptación o por plazo vencido).
7 Cancelación en proceso. Se obtiene cuando la respuesta del SAT indica que el comprobante se encuentra Vigente y está en espera de la respuesta del receptor para su cancelación.
8 Cancelado con aceptación. Se obtiene cuando la respuesta del SAT indica que el comprobante se encuentra Cancelado y se requirió aceptación del receptor para cancelarlo.
9 Cancelado sin aceptación. Se obtiene cuando la respuesta del SAT indica que el comprobante se encuentra Cancelado y no se requirió aceptación del receptor para cancelarlo.
10 Cancelado por plazo vencido. Se obtiene cuando la respuesta del SAT indica que el comprobante se encuentra Cancelado y no hubo una respuesta del receptor en las 72 horas hábiles posteriores a la solicitud de cancelación.
99 Indeterminado. Se obtiene cuando hay un error en la interpretación de la respuesta del SAT o cuando no hay una respuesta(que el servicio no se encuentre disponible).


Método consultacfdPorUUID:

El metodo permite recuperar el xml en formato base64 de un cfdi.

Se encuentra disponible en la siguiente URL:
https://timbrado.pade.mx/servicio/rest/integracion/consultaCfdiPorUUID

Y cuyos parámetros (URL Query Parameters) se describen a continuación:

  • contrato: Clave del contrato de servicios.
  • uuid: UUID del comprobante que se desea recuperar.

Las credenciales (usuario y contraseña) deberán ir en el HEAD de la petición mediante el atributo “Authorization Basic” con el formato usuario:password codificados en base64.

El tipo de contenido (atributo Content-Type) deberá especificar el valor “application/xml“.

No todos los atributos están presentes en la respuesta, y esto dependerá del resultado de la operación. La descripción de los atributos se describe a continuación:

  • contrato: Clave del contrato de servicios.
  • consultaOk. Los valores posibles son “true” o “false”, y determina si la invocación al webservice fue exitosa.
  • codigo. Código global de la invocación. Un valor de 0 (cero) indica que la invocación se dio exitosamente, o de otra forma se indica la razón del problema.
  • xmlBase64. String en formato base64 del xml correspondiente al uuid consultado.

Ejemplo de petición REST con el cliente Advanced Rest Client


Método procesarArchivo (REST):

El método permite generar el timbrado de un comprobante a partir del archivo de intercambio en formato csv

Se encuentra disponible en la siguiente URL:
https://timbrado.pade.mx/servicio/rest/integracion/procesarArchivo

Y cuyos parámetros (URL Query Parameters) se describen a continuación:

  • contrato: Clave del contrato de servicios.
  • prueba: Los valores posibles son “true” o “false”, e indican el modo de operación de la peticion para el servicio, siendo true para un timbrado de prueba y false para uno real.
  • datos: Formato csv del archivo que se requiere timbrar, el formato para el atributo datos debe estar codificado en Base64.
  • opciones: Lista de Strings que le indican al servicio las opciones que se utilizaran en la petición, como lo son: CALCULAR_SELLO, PLUGIN_PROCESO:GENERICO_CFDI33:1.0, básicamente las opciones que se utilizan de igual forma en el servicio de timbrado.
    Como opcional se puede optar por enviar todas las opciones codificadas en base64 en el primer elemento de la lista de "opciones", formadas en un string donde cada opción va separada por el caracter "pipe" ( | ) y codificada en base 64.

    Ejemplo: CALCULAR_SELLO|CONSULTAR_SALDO|GENERAR_PDF codificado en base64.

Las credenciales (usuario y contraseña) deberán ir en el HEAD de la petición mediante el atributo “Authorization Basic” con el formato usuario:password codificados en base64.

El tipo de contenido (atributo Content-Type) deberá especificar el valor “application/xml“ y para el método procesarArchivoConCSD (vía REST) será “application/json“.

Ejemplo de petición REST con el cliente Advanced Rest Client


procesarArchivoConCSD

En caso de requerir enviar los archivos del certificado del sello digital (CSD) en la petición y no calcularlos previamente ni solicitar que se calculen por parte de prodigia al enviar la petición, puede utilizarse el método procesarArchivoConCSD  (REST) donde se pueden enviar los archivos del CSD codificados en base64 para la construcción del sello del comprobante, como se aprecia en la siguiente petición:

vía REST:

 {<br /><br />    "contrato" :"[CONTRATO]",<br /><br />    "certBase64":"MIIF3DCCA8SgAwIBAgIUMzAwMDEwMDAwMDA0MDAwMDI0NDQ...",<br /><br />    "keyBase64" : "MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDg...",<br /><br />    "keyPass" : "12345678a",<br /><br />    "datos":"Q0ZESXwzLjN8Y2xvdWR3YXRjaHwxfDIwMjAtMTItMTRUMTA6NTQ6....",<br /><br />    "prueba" : "true",<br /><br />    "opciones":[ "PLUGIN_PROCESO:GENERICO_CFDI33:1.0"]<br /><br />}<br /><br /><br /><br /><br />Ejemplo de petición vía SOAP:<br /><br />&lt;int:procesarArchivoConCSD&gt;<br /><br />         &lt;!--Optional:--&gt;<br /><br />         &lt;contrato&gt;[CONTRATO]&lt;/contrato&gt;<br /><br />         &lt;usuario&gt;[USUARIO]&lt;/usuario&gt;<br /><br />         &lt;passwd&gt;[PASSWORD]&lt;/passwd&gt;<br /><br />         &lt;prueba&gt;false&lt;/prueba&gt;<br /><br />         &lt;!--Optional:--&gt;<br /><br />         &lt;datos&gt;&lt;![CDATA[ArchivoCSV]]&gt;&lt;/datos&gt;<br /><br />         &lt;!--Optional:--&gt;<br /><br />         &lt;cert&gt;MIIF+TCCA+GgAwIBAgIUMzAwMDEwMDAwMDAzMDAwMjM3M...&lt;/cert&gt;<br /><br />         &lt;!--Optional:--&gt;<br /><br />         &lt;key&gt;MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDg.../key&gt;<br /><br />         &lt;!--Optional:--&gt;<br /><br />         &lt;keyPass&gt;12345678a&lt;/keyPass&gt;<br /><br />         &lt;!--Zero or more repetitions:--&gt;<br /><br />         &lt;opciones&gt;PLUGIN_PROCESO:GENERICO_CFDI33:1.0&lt;/opciones&gt;<br /><br />      &lt;/int:procesarArchivoConCSD&gt;
          

No todos los atributos están presentes en la respuesta, y esto dependerá del resultado de la operación. La descripción de los atributos se describe a continuación, básicamente la respuesta es similar a la del servicio de timbrado:

  • id. Identificador de la transacción interna, en formato UUID. Este valor es de uso interno, no está relacionado con ninguna propiedad del XML o del Timbre Fiscal Digital.
  • timbradoOk. Indica si la operación de timbrado fue conducida exitosamente. Los valores posibles son “true”, que indica éxito; y “false”, que indica que el CFDI no pudo ser timbrado y en consecuencia no fue aceptado por el servicio.
    contrato. Identificador único del contrato del cliente. Se regresa para fines informativos.
  • codigo. El código es un valor cuya función principal es indicar el error que fue detectado, en caso de haberlo. Cuando la transacción de timbrado fue exitosa (timbradoOk vale “true”) el código se regresa con un valor de 0 (cero) y de otra forma se regresa con el código de error específico definido por el SAT. Por otro lado, es posible que se acepte el certificado pero con incidencias, lo que causará que se regrese un código aún cuando el atributo timbradoOk tenga valor de “true”. El código siempre pertenecerá al último error registrado por el servicio(en caso de que se hayan registrado más de uno).
  • mensaje. Este valor es un texto informativo. Es especialmente útil cuando ocurren errores en el procesamiento del CFDI. Cuando la transacción de timbrado fue exitosa, éste valor viene vacío. Es probable que la respuesta del servicio incluya más de un mensaje de error, éstos serán separados por un carácter pipe (|).
  • versión. Versión del Timbre Fiscal generado. A la fecha, el valor es 1.1. Este valor forma parte del elemento <tfd:TimbreFiscalDigital> dentro del CFDI. Este valor se incluye solamente cuando la transacción de timbrado es exitosa.
  • uuid. Folio fiscal asignado al CFDI. Este valor forma parte del elemento <tfd:TimbreFiscalDigital> dentro del CFDI. Este valor se incluye solamente cuando la transacción de timbrado es exitosa.
  • FechaTimbrado. Fecha de generación del Timbre Fiscal Digital. Este valor forma parte del elemento <tfd:TimbreFiscalDigital> dentro del CFDI. Este valor se incluye solamente cuando la transacción de timbrado es exitosa.
  • selloCFD. Sello del CFDI. Este valor forma parte del elemento <tfd:TimbreFiscalDigital> dentro del CFDI. Este valor se incluye solamente cuando la transacción de timbrado es exitosa.
  • noCertificadoSAT. Número de certificado del SAT. Este valor forma parte del elemento <tfd:TimbreFiscalDigital> dentro del CFDI. Este valor se incluye solamente cuando la transacción de timbrado es exitosa.
  • selloSAT. Sello del timbre fiscal digital. Este valor forma parte del elemento <tfd:TimbreFiscalDigital> dentro del CFDI. Este valor se incluye solamente cuando la transacción de timbrado es exitosa.
  • xmlBase64. String codificado en Base 64 que contiene el documento XML timbrado. Este valor se incluye solamente cuando la transacción de timbrado es exitosa.
  • pdfBase64. String codificado en Base 64 que contiene el arreglo de bytes del PDF del documento XML timbrado. Este valor se incluye solamente cuando la transacción de timbrado es exitosa y se utiliza la opción GENERAR_PDF.
  • saldo. El valor de este nodo es el número de transacciones disponibles para el contrato con el que se realizó la petición de timbrado. Este valor se incluye solamente cuando la transacción es exitosa y se utiliza la opción CONSULTAR_SALDO.


Tabla de opciones
PLUGIN_PROCESO:GENERICO_CFDI33:1.0
CALCULAR_SELLO
RESPUESTA_XML_CFDI
CONSULTAR_SALDO
ENVIAR_AMBOS:
ADDENDA:LIBRE:
REGRESAR_CON_ERROR_307_XML
OBSERVACIONES:
REGRESAR_CADENA_ORIGINAL
GENERAR_PDF


Tabla de códigos del servicio

Código Descripción
0 Timbrado exitoso.
1 El usuario del webservice no existe o proporcionó una contraseña incorrecta.
2 Contrato inválido. El contrato está expirado, o no cuenta con servicio de timbrado.
3 Parámetro inválido. Uno de los parámetros de la operación del webservice es incorrecto o hace falta.
5 Off-line por mantenimiento.
7 El servicio de CancelaciónSAT no está disponible, intente más tarde.
20 El usuario no cuenta con un certificado default.
21 CFDI sin cancelar. Aplica a la consulta de acuse de cancelación.
201 Comprobante cancelado exitosamente. (sin autorización).
202 El comprobante ya ha sido previamente cancelado.
203 El RFC del emisor no corresponde.
205 El UUID no existe.
301 XML mal formado.
302 Sello mal formado o inválido.
303 Sello no corresponde al emisor.
304 Certificado revocado o caduco.
305 La fecha de emisión no está dentro de la vigencia del CSD del emisor.
306
El certificado no es de tipo CSD.
307 El CFDI contiene un timbre previo.
308 Certificado no expedido por el SAT.
401
Fecha y hora de generación fuera de rango.
402 El RFC del emisor no se encuentra en el régimen de contribuyentes.
403 La fecha de emisión no es posterior al 1 de enero de 2012.
602 CFDI no existe.