Documentación de la API de Integración Descarga Masiva

Revisión	Fecha	Comentarios
1	2019-­09-18	Documento inicial
2	2020-­06-18	Como crear un archivo pfx

Tabla de Contenido

• Pre-requisitos
• Limitantes
• Conexión al servicio de Descarga Masiva
  • Generar Solicitud
  • Consulta estatus de la Solicitud
• Que es un pfx
• Como crear un archivo pfx
• Tabla de códigos

Pre-requisitos

• Contar con la FIEL de cada RFC a usar en las consultas.
• Estar registrado en la plataforma PADE, lo que garantizará que cuente con usuario, contraseña y contrato para autenticarse en el servicio.
• Contar con un software cliente que le permita realizar las peticiones a nuestro servicio.

Limitantes

• Únicamente se puede repetir la misma solicitud con los mismos datos (rfcEmisor, rfcReceptor, fechaInicio y fechaFinal) un máximo de dos veces. Al superar este límite ya no se podrá generar una solicitud con los mismos datos.
• Los xmls no traen el estatus (cancelado, activo).
• Sólo él Emisor o Receptor podrán realizar la consulta y recuperación.
• 200000 xml por solicitud pero esta se puede fragmentar en varias solicitudes (lapso de meses, lapso de semanas).
• Al exceder los 3 intentos de acceso erróneamente, el usuario y contraseña se bloquearán,
  • Por lo que deberá realizar un cambio de contraseña en la plataforma PADE por haber excedido el numero de intentos posibles.
• Se podrán recuperar hasta 1 millón de registros de los metadatos por consulta

Conexión al servicio de Descarga Masiva:

El servicio se encuentra disponible en una dirección URL pública:

https://descargamasiva.pade.mx/api/

Generar Solicitud:

URL de generación de una solicitud de Descarga de comprobantes:

https://descargamasiva.pade.mx/api/solicitud/generar

Descripción

Este método se utiliza para generar la solicitud según los parámetros especificados en la petición. El método realiza la autenticación al servicio, valida los parámetros y regresa un Json como respuesta al servicio. La estructura del Json de respuesta se explica más adelante.

Características de la petición

• Petición REST
• Tipo POST
• Headers: Content-Type = application/json
• Body:

Parámetros del servicio:

Los parámetros marcados con * son obligatorios.

Sin embargo los parámetros rfcEmisor o rfcReceptor debe de ir al menos uno, ya que uno de los dos (emisor o receptor) debe coincidir con el rfc del solicitante. 

Ejemplo de generación de solicitud:

Ejemplo de respuesta exitoso:

Ejemplo de respuesta con error:

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

• numeroSolicitud: Número correspondiente a la solicitud generada.
• estadoSolicitud: Código correspondiente al estado de la solicitud procesada.
• mensaje: Mensaje referente al estado de la solicitud.
• codigo: Código específico definido por el SAT.
• mensaje: Este valor es un texto descriptivo del código definido por el SAT.

Solicitud estatus:

Consulta de estatus de una solicitud:

URL para consultar el estatus de una solicitud generada de Descarga de comprobantes:

https://descargamasiva.pade.mx/api/solicitud/estatus

Descripción

Se utiliza para consultar el estatus de una solicitud anteriormente generada para la descarga de comprobantes de un RFC Solicitante según los parámetros especificados. Este método realiza la autenticación al servicio, validación y descarga de los paquetes ante el SAT.

Características de la petición

• Petición REST
• Tipo POST
• Headers: Content-Type = application/json
• Body:

Parámetros del servicio:

• numeroSolicitud: Número de solicitud a consultar.
• usuario: Indica el usuario con el cual se autenticará al servicio.
• passPade: Indica la contraseña del usuario con el cual se autenticará al servicio.
• contrato: Indica el código de contrato del usuario con el que se realizará la solicitud.

Ejemplo de respuesta exitoso:

En proceso para descarga

Lista para descarga

Ejemplo de respuesta con error:

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

• numeroSolicitud: Número correspondiente a la solicitud proporcionada.
• estadoSolicitud: Código correspondiente al estado de la solicitud procesada.
• mensaje: Mensaje resultante a la consulta del estado de la solicitud.
• paquetes: URL(s) para la descarga de los paquetes correspondientes al número de solicitud. Solo está presente en la respuesta cuando los paquetes se encuentran listos para su descarga. La URL proporcionada estará disponible durante 5 minutos para descargar el paquete, una vez expirado ese tiempo se tiene que volver a generar la URL consultando de nuevo el estatus de la solicitud. No es necesario generar la solicitud por segunda ocasión.

¿Qué es un PFX?

Un archivo PFX no es más que el Certificado y Llave privada en un solo archivo. Podríamos decir que una fusión de ambos archivos.

¿Como se crea este archivo PFX?

Para la generación de este archivo, necesitaremos un certificado (*.cer) y su llave privada correspondiente (*.key), teniendo esto, además necesitaremos la utilería para OpenSSL. Para Windows lo descargaremos de  https://www.openssl.org/source/

Una vez teniendo descomprimido, abriremos la consola en windows. Para ello iremos a “inicio” y buscaremos “cmd” y ejecutaremos la consola o “Command Prompt”, después nos posicionaremos en el mismo directorio donde descomprimiste el .zip. Para este ejemplo utilizaré la ruta “c:\out\openssl”

Y estando utilizaremos los siguientes comandos.

1 openssl pkcs8 -inform der –in CSD_Pruebas_CFDI_LAN7008173R5.key -passin pass:12345678a -out key.pem

Donde tenemos “CSD_Pruebas_CFDI_LAN7008173R5.key” como la llave privada, “12345678a” como el password de la llave privada y “key.pem” como el archivo de salida.

1 openssl x509 -inform der –in CSD_Pruebas_CFDI_LAN7008173R5.cer -out cer.pem

En este caso tenemos “CSD_Pruebas_CFDI_LAN7008173R5.cer” como el certificado y “cer.pem” como el archivo de salida.

1 openssl pkcs12 -export –in cer.pem -inkey key.pem -out LAN7008173R5.pfx

Al ejecutar esté último comando, nos solicitara un password, dicho password es el que tendrá el PFX. En este caso yo proporcione el mismo que tiene la llave privada (12345678a). De igual manera nos solicitara confirmar el password. (En la consola no se mostrará lo que escribamos como password, pero si lo tiene en cuenta para la generación del mismo).

Como paso final, en los WebService que ofrecemos normalmente solicitamos este archivo en el request como base64. Esto lo podemos hacer en nuestro lenguaje de programación directamente o a través de OpenSSL.

1 openssl enc -base64 –in LAN7008173R5.pfx -out LAN7008173R5.txt

Y esto nos generará un archivo .txt con la encriptación de los binarios del PFX en base64.

Códigos Estados Paquete

Código del estado de la solicitud	Mensaje
1	Solicitud aceptada
2	Solicitud en progreso.
3	Lista para descarga.
4	Descargando paquetes.
5	Solicitud rechazada.
6	Solicitud vencida.
7	Paquetes listos.

Códigos   Generar Solicitud

Código del estado de la solicitud	Mensaje
5000	Solicitud creada exitosamente
8000	Error al generar la solicitud

Códigos Respuesta SAT

Código Respuesta SAT	Mensaje	Observaciones
5000	Solicitud recibida con éxito	Indica que la solicitud de descarga que se está verificando fue aceptad
5001	Tercero no Autorizado
5002	Se agotó las solicitudes de por vida	Para el caso de descarga de tipo CFDI, se tiene un límite máximo para solicitudes con los mismos parámetros (Fecha Inicial, Fecha Final, RfcEmisor, RfcReceptor).
5003	Tope máximo	Indica que en base a los parámetros de consulta se está superando el tope máximo de CFDI o Metadata, por solicitud de descarga masiva.
5004	No se encontró la información	Indica que la solicitud de descarga que se está verificando no generó paquetes por falta de información.
5005	Solicitud duplicada
5007	No existe el paquete solicitado	Indica que la solicitud de descarga que se está verificando no generó paquetes por falta de información.
5010	Error de empaquetado	Indica que la solicitud tuvo un problema en su empaquetado, se reencolará para ser consultado más tarde.
404	Error no Controlado	Error genérico, en caso de presentarse realizar nuevamente la petición y si persiste el error levantar un RMA.