Documentación de la API de Integración PADE

Revisión	Fecha	Comentarios
1	2017-08-25	Documento inicial
2	2020-08-06	Se agrega al servicio la opción MODO_PRUEBA
3	2022-04-15	Se agrega método para consultar EFOS mediante RFC: consultarEfoByRfc (SOAP)
4	2022-09-30	Se agrega método para consulta de listas del artículo 69.

Introducción

El servicio de recepción automatiza el proceso de validación de los comprobantes fiscales digitales que un cliente recibe de sus proveedores. El servicio se ofrece mediante la invocación de los métodos remotos de un Web Service.

La ubicación del WSDL del servicio de Recepción es la siguiente:

https://timbrado.pade.mx/PadeServ/RecepcionCfdiService?WSDL

Estructura de la respuesta de los métodos remotos

Los métodos del Web Service regresan una respuesta que, dependiendo de la operación, puede ser compleja. Esta respuesta es un String, y está estructurada en formato XML simple (sin esquemas). Los atributos y nodos del archivo XML varía dependiendo de la operación invocada, y se describen a detalle en cada operación.

Métodos para recepción de CFDI

A continuación, se describirán cada uno de los métodos utilizados para la validación y verificación de los comprobantes fiscales.

Operación de Recepción básica

String recepcionCfdi(String contrato, String usuario, String passwd, String cfdiXml, String etiqueta, String[] opciones)

El método acepta un string con un documento XML, el cual es analizado de forma estructural y semántica. Los resultados de la validación son reportados en la respuesta. El comprobante se guarda en la base de datos, aunque esto dependerá de lo crítico de sus errores de validación (en caso de haberlos). Los argumentos que acepta el método son:

• Contrato: Identificador único del contrato de servicios.
• Usuario: Nombre del usuario del servicio. Éste usuario debe estar autorizado para utilizar la API de recepción.
• Passwd: Contraseña del usuario del servicio.
• cfdiXml: Documento XML con el CFDI.
• Etiqueta: String único que sirve para identificar el cfdi. Este valor es generado por el usuario y no debe ser mayor a 40 caracteres.
• Opciones: Arreglo de strings que indica al servicio las opciones que se utilizarán en el servicio.
  • MODO_PRUEBA: n. Donde “n” es el caso de modo prueba que se quiere simular. Con esta opción no se hará una validación del comprobante recibido, solo se regresará una respuesta con estructura real e información de prueba para simular el caso que aplique. 

La respuesta del método es un archivo XML sin esquemas. La estructura básica del mismo se describe a continuación:

<servicioRecepcion>
<id/>
<recepcionOk/>
<contrato/>
<codigo/>
<recibidos/>
<validados/>
<validos/>
<resultados>
<resultado etiqueta=”” mensaje=”” uuid=”” valido=”true|false”/> </resultados>
</servicioRecepcion>

No todos los atributos estarán presentes siempre en la respuesta. La descripción de los mismos se define de la siguiente manera:

• 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.
• recepcionOk: Indica si la operación de recepción fue conducida exitosamente. Los valores posibles son “true”, que indica éxito; y “false” que indica una condición de error. Es necesario aclarar que un valor de “true” en este elemento no determina que uno o varios comprobantes se hayan recibido satisfactoriamente. Por ejemplo, puede ser posible que el status del proceso de recepción regrese “true” (procesamiento terminado) y que el XML no haya sido recibido. Un valor de “false” nos indicará que ocurrió un error de nivel general, no relacionado con los resultados de validación de los comprobantes.
• 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 recepción fue exitosa (recepcionOk 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. Este código de error informará acerca del error general ocurrido durante el procesamiento de los comprobantes.
• recibidos: Indica el total de comprobantes recibidos para recepción/validación. Este valor será 1 para el caso de este método de recepción, y tomará valores iguales o mayores a 1 en el caso de los métodos que acepten varios comprobantes para recepción.
• validados: Indica el total de comprobantes que pudieron ser validados. Este valor no necesariamente debe ser el mismo que el número de comprobantes recibidos, pero nunca deberá ser mayor.
• validos: Indica el total de comprobantes cuya validación fue correcta.
• mensaje: Este valor es un texto informativo. Es especialmente útil cuando ocurren errores en el procesamiento durante la recepción.
• resultados: Elemento que agrupa los resultados individuales de la validación. En el caso del método de recepción que solamente acepta un comprobante, se tendrá solamente un nodo hijo.
  • resultado: Descripción individual del resultado de la validación de un comprobante. Los posibles atributos son:
    • etiqueta: Etiqueta proporcionada por el usuario para éste comprobante. Es útil para identificar el XML en casos donde ni siquiera es posible analizar estructuralmente el documento.
    • mensaje: Texto descriptivo con los problemas encontrados. En caso de obtner múltiples problemas de validación, los mensajes será concatenados con un carácter “|” (pipe).
    • valido: Determina si el comprobante puede ser aceptado. Los valores posibles son “true” (válido) o “false” (inválido).

Las opciones se proporcionan al método como un arreglo de Strings. Las Opciones reconocidas por este método son:

• ENVIAR_ERRORES:
• MODO_PRUEBA:

La descripción de cada una de las opciones se indica en la tabla 1 “Opciones para los diferentes servicios” y 1.1 “Códigos de resultados para la opción MODO_PRUEBA:”.

Operación de Recepción múltiple

String recepcionCfdiMultiple(String contrato, String usuario, String passwd, String[] arregloCfdiXml, String etiquets[], String[] opciones)

Este método es similar al de recepción básica, con dos diferencias:

1. Es posible enviar múltiples archivos XML en un arreglo de
2. Se deben especificar las respectivas etiquetas de los XML en un arreglo (parámetro “etiquetas”).

El número de etiquetas debe ser igual al número de comprobantes enviados. Las etiquetas se asignarán en el orden encontrado.

La respuesta del método de recepción múltiple es similar a la respuesta del método de recepción básica. Las Opciones reconocidas por este método son:

• ENVIAR_ERRORES:
• MODO_PRUEBA:

La descripción de cada una de las opciones se indica en la tabla 1 “Opciones para los diferentes servicios” y 1.1 “Códigos de resultados para la opción MODO_PRUEBA:”.

Operación de Recepción múltiple en archivo zip

String recepcionCfdiZip(String contrato, String usuario, String passwd, byte[] archivo, String[] opciones)

Este método se ofrece como alternativa a la recepción múltiple. Aquí se debe proporcionar un archivo comprimido con formato ZIP, el cual debe contener los documentos XML que se desea procesar para recepción. Los archivos XML deberán estar en la raíz del archivo zip, los subdirectorios serán ignorados. Así mismo, el nombre del documento XML incluido en el archivo será tomado para el valor de su respectiva etiqueta en el sistema.

El número máximo de archivos proporcionados para procesar es 100.

La respuesta del método de recepción múltiple en archivo zip es similar a la respuesta de recepción básica. Las Opciones reconocidas por este método son:

• ENVIAR_ERRORES:
• MODO_PRUEBA:

La descripción de cada una de las opciones se indica en la tabla 1 “Opciones para los diferentes servicios” y 1.1 “Códigos de resultados para la opción MODO_PRUEBA:”.

Operación de Consulta

String cfdiPorUUIDv33(String contrato, String usuario, String passwd, String uuid)

Este método sirve para recuperar un XML guardado en la base datos en función del UUID. El método regresa un String en formato XML sin esquemas. La estructura del archivo de respuesta se describe a continuación:

<consultaRecepcion>
<consultaOk/>
<codigo/>
<contrato/>
<mensaje/>
<comprobantes>
<comprobante etiqueta=”” mensaje=”” statusValidacion=”VALIDO|INVALIDO” uuid=””>
</xmlBase64>
</comprobante>
</consultaRecepcion>

La descripción de los atributos es la siguiente:

• consultaOk: Indica el resultado del procesamiento de la consulta, con los posibles valores “false” o “true”. Estos valores indican el resultado del procesamiento de la consulta y no reflejan ningún estado o propiedad del (los) XML que fueron solicitados.
• 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 consulta es exitosa el código se regresa con un valor de 0 (cero) y de otra forma se regresa con el código de error.
• contrato: Identificador único del contrato del cliente. Se regresa para fines informativos.
• mensaje: Este valor es un texto informativo.
• comprobantes: Elemento que agrupa los resultados individuales de la consulta.
  • comprobante. Definición específica de un CFDI recuperado de la base de Los atributos del valor son:
    • etiqueta: Etiqueta asociada al XML (que fue proporcionada por el usuario durante la recepción).
    • mensaje: Mensaje informativo específico al comprobante recuperado.
    • statusValidacion: Estatus del comprobante. Posibles valores: VALIDO / INVALIDO.
    • uuid; UUID (folio fiscal digital) del comprobante recuperado.
    • XML base 64. Contiene el XML codificado en base

String  cfdiPorEtiquetav33(String  contrato,  String        usuario, String passwd, String etiqueta)

El método recupera un XML recibido desde la base de datos en función de la etiqueta. Es un método alternativo a cfdiPorUUIDv33(), pero este método especialmente útil en un caso en donde no es posible obtener el UUID del XML (por ejemplo que el documento esté estructuralmente mal formado).

La respuesta del método es similar a la respuesta de cfdiPorUUIDv33().

String   verificacionPorQrCodev33(String   contrato, String usuario, String passwd, String qrCode)

Este método determina si un comprobante existe en las bases de datos del SAT, y en caso de ser encontrado, determina su estado. La consulta se hace dinámicamente en los servidores del SAT.

El argumento indicado como qrCode corresponde al texto representado por el código de barras bidimensional que se muestra en la representación impresa del CFDI. Se solicita como texto plano.

Ejemplo del parametro qrCode

https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=5756A690-FAA4-40F5-A873-0F0AD4D8C440&rr=OICJ871226M79&re=DDA960425Q43&tt=0000000180.000000&fe=VU1nKw== 

La respuesta del método es un archivo XML sin esquemas, que se ilustra a continuación.

<servicioVerificacion>
<consultaOk/>
<codigo/>
<mensaje/>
<estado/>
<codigoEstatus/>
</servicioVerificacion>

Ejemplo:

<?xml version=”1.0″ encoding=”UTF-8″?>
<servicioVerificacion>
<consultaOk>true</consultaOk>
<codigo>91</codigo>
<estado>Cancelado</estado>
<codigoEstatus>S – Comprobante obtenido satisfactoriamente.</codigoEstatus>
</servicioVerificacion>

La descripción de los atributos se define a continuación.

• consultaOk: Determina si la operación de consulta transcurrió sin problemas. Los valores posibles con true o false.
• codigo: Determina de forma mas detallada el resultado del procesamiento de la consulta. El listado de códigos se ilustra en la tabla “Códigos de Resultado para Verificacion”. Es necesario respetar el formato de este código, y en caso de que no pueda ser interpretado por el SAT se obtendrá un código 93 y en el mensaje se indicará el texto: “Ocurrió un error en la consulta en el SAT. qrCode: <codigo qr proporcionado>, mensaje: Client received SOAP Fault from server: Object reference not set to an instance of an object. Please see the server log to find more detail regarding exact cuase of the failure.” Este mensaje se muestra tal y como lo proporciona el servicio del SAT.
• mensaje: Texto opcional que se utiliza para dar más información acerca de alguna situación de error.
• estado: Estado del CFDI. Este atributo solo debe considerarse cuando el comprobante sea encontrado en la base de datos del SAT (código 91), y los posibles valores con “Vigente” y “Cancelado”.
• codigoEstatus: Descripción extendida. Este texto se muestra exactamente como se obtiene desde el servicio del SAT.

Validación de EFOS
(Lista de  Empresa que Factura Operaciones Simuladas)

Método para consultar EFOS mediante RFC: consultarEfoByRfc (SOAP) 

Esta operación se encarga de realizar la búsqueda del RFC especificado dentro del listado que contempla el SAT como empresas que facturan operaciones simuladas(EFOS)

Los parámetros que acepta el método son:

• contrato:  Indica el código de contrato del usuario con el que se realizará el timbrado.

• usuario:  Indica el usuario con el que se autenticará el servicio de timbrado.

• passwd:  Indica la contraseña del usuario con el que se autenticará al servicio de timbrado.

• rfc:  Índica el rfc que será consultado en el listado de EFOS proporcionado por el SAT.

Request

Debajo se muestra un ejemplo de una petición, en él se pueden observar los parámetros anteriormente mencionados.

Request_efos

<?xml version="1.0"?>

-<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:rfc="http://rfc.ws.pade.prodigia.mx/">

           <soapenv:Header/>
       - <soapenv:Body>

        - <rfc:consultarEfoByRfc>

               <contrato>CONTRATO</contrato>

               <usuario>USUARIO</usuario>

               <passwd>PASSWORD</passwd>

               <rfc>AAA080808HL8</rfc>

           </rfc:consultarEfoByRfc>

       </soapenv:Body>

</soapenv:Envelope>

Response

No todos los atributos estarán presentes siempre en la respuesta, esto dependerá del flujo del proceso, a continuación se definen:

• consultaOk:  Valores permitidos, true | false, indican el resultado de la operación. En concreto si todo resultó exitosamente y el proceso no presentó errores, el valor esperado será true, por el contrario false.

• fechaLista:Cadena:  de texto con información sobre la fecha de actualización de la lista por parte del SAT

• codigo:  Indica el estatus de la operación, si el proceso se realizó correctamente el valor esperado es 0, de lo contrario se especifica el codigo de error.

• detalles:  Nodo que contiene la lista con el resultado de la consulta

• detalle:  Nodo que contiene los atributos de un registro de manera individual

• rfc

• razonSocial

• situacionContrib

• numFechaPresuncion

• pubFechaSatPresuntos

• numGlobalPresuncion

• pubFechaDofPresuntos

• pubSatDesvirtuados

• numContribDesvirtuados

• pubDofDesvirtuados

• numFechaDefinitivos

• pubSatDefinitivos

• pubDofDefinitivos

• numFechaSentFav

• pubSatSentFav

• numFechaGlobalSentFav

• pubDofSentFav

Debajo se muestra un ejemplo de una respuesta, en él se pueden observar los parámetros anteriormente mencionados.

<?xml version="1.0"?>

-<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">

       -<S:Body>

           -<ns2:consultarEfoByRfcResponse xmlns:ns2="http://rfc.ws.pade.prodigia.mx/">

               -<return>

                   -<![CDATA[

                       <ResultConsultaEFO>

                           <consultaOk>true</consultaOk>

                           <fechaLista>Información actualizada al 03 de diciembre de 2019</fechaLista>

                           <codigo>0</codigo>

                           <detalles>

                               <detalle>

                                   <rfc>AAA010101AAA</rfc>

                                   <razonSocial>EMPRESA DE PRUEBA, S.A. DE C.V.</razonSocial>

                                   <situacionContribuyente>Sentencia Favorable</situacionContribuyente>

                                   <numFechaPresuncion>500-05-2018-16596 de fecha 01 de junio de 2018</numFechaPresuncion>

                                   <pubFechaSatPresuntos>01/06/2018</pubFechaSatPresuntos>

                                   <numGlobalPresuncion>500-05-2018-16596 de fecha 01 de junio de 2018</numGlobalPresuncion>

                                   <pubFechaDofPresuntos>25/06/2018</pubFechaDofPresuntos>

                                   <numFechaDefinitivos>500-05-2018-27248 de fecha 27 de septiembre de 2018</numFechaDefinitivos>

                                   <pubSatDefinitivos>28/09/18</pubSatDefinitivos>

                                   <pubDofDefinitivos>23/10/18</pubDofDefinitivos>

                                   <numFechaSentFav>500-05-2019-7305 de fecha 5 de marzo de 2019</numFechaSentFav>

                                   <pubSatSentFav>5/03/19</pubSatSentFav>

                                   <numFechaGlobalSentFav>500-05-2019-7987 de fecha 5 de marzo de 2019</numFechaGlobalSentFav>

                                   <pubDofSentFav>16/04/19</pubDofSentFav>

                               </detalle>

                           </detalles>

                       </ResultConsultaEFO>]]>

                   </return>

               </ns2:consultarEfoByRfcResponse>

       </S:Body>
</S:Envelope>

 

Método para consulta de listas del Artículo 69

Códigos de respuesta en consulta de RFC

Código	Descripción
0	Request aceptado.
101	El RFC no existe en la lista de RFC inscritos no cancelados del SAT.
102	El RFC no cumple con el patrón requerido.
103	El RFC está vacío.
200	OK. Sin mensaje.
301	Error en los parámetros de request – usuario, password, contrato o algún otro error en la sintaxis.

Tabla 1: Opciones para los diferentes servicios.

La siguiente tabla describe las opciones que pueden ser proporcionadas. Los nombres de las opciones son sensibles a mayúsculas y minúsculas, y se deben proporcionar como se indican.

Opción	Aplica en	Descripción
ENVIAR_ERRORES	Recepción	Si esta opción está presente, le indica al sistema que deberá reportar los errores encontrados durante la recepción. La opción se debe acompañar de una dirección de correo electrónico a donde se enviará el reporte del procesamiento. El formato para especificar la opción es: ENVIAR_ERRORES:correo_electrónico   Ejemplo: ENVIAR_ERRORES:usuario@gmail.com
MODO_PRUEBA	Recepción	Esta opción se encarga de realizar una simulación en modo prueba con la intención que ya no regrese una respuesta real y no se estén consumiendo las transacciones del actual contrato.

Tabla 1.1: Códigos de resultados para la opción MODO_PRUEBA:

Tabla 2: Códigos de Resultado para Recepción

Código	Descripción
0	La operación tuvo un resultado 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	Offline por mantenimiento.
100	Comprobante no encontrado. Se utiliza en el método de consulta.

Tabla 3. Listado de códigos para verificación.  

Código	Descripción
0	El procesamiento de la verificación sucedió sin problemas. Este método no está relacionado al hecho de que exista o no un CFDI en el SAT, solo indica el estado de la transacción en la plataforma.
1	Error de autentificación. El usuario proporcionó una contraseña incorrecta, un usuario inexistente o un usuario no autorizado.
2	Contrato inválido. El contrato está expirado o no cuenta con un plan de recepción.
3	Parámetro inválido. Uno de los parámetros o argumentos de los métodos no está presente o es incorrecto.
4	Error interno. Se indica cuando ocurrió un error interno y no pudo ser manejado durante el procesamiento.
5	Offline por mantenimiento. El servicio está inactivo por mantenimiento.
6	Uno de los modulos que hizo Armando y que puede migrar a v13 Marco es journal_entry_prodigia
90	No encontrado. El comprobante no fue localizado en la base de datos del SAT.
91	Encontrado. El comprobante se localizó en la base de datos del SAT. Este código tiene dos variantes que deben ser verificadas en el elemento en el XML de respuesta.
92	Expresión no válida
93	Indeterminado. Ocurrió un error durante la consulta con el SAT.