API DE INTEGRACIÓN DESCARGA MASIVA

API de Integración Descarga Masiva

18 septiembre, 2019

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:

Generar Solicitud:

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

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:

  • rfcEmisor: RFC del emisor al que pertenecen los CFDI’s que desea descargar. 
  • rfcReceptor: RFC del receptor al que pertenecen los CFDI’s que desea descargar.
  • rfcSolicitante*: RFC correspondiente al PFX enviado. Este debe corresponder con al menos un parámetro rfcEmisor o rfcReceptor.
  • fechaInicio*: Rango inicial de fechas que requiere en su consulta ante el SAT con formato (Año-Mes-Día’T’hora:minutos:segundos) ej. 2019-10-19T11:15:45.
  • fechaFinal*: Rango final de fechas que requiere en su consulta ante el SAT con formato (Año-Mes-Día’T’hora:minutos:segundos) ej. 2019-10-19T11:15:45.
  • tipoSolicitud*: Establece el valor “CFDI” para descargar los comprobantes. Establece el valor”Metadata” para descargar un archivo de texto con los siguientes datos: Uuid, RfcEmisor, NombreEmisor, RfcReceptor, NombreReceptor, RfcPac, FechaEmision, FechaCertificacionSat, Monto, EfectoComprobante(Tipo de comprobante), Estatus, FechaCancelacion
  • pfx*: Archivo generado con la Fiel del contribuyente y envíado en base64.
  • password*: Indica la contraseña de la clave privada de su archivo Fiel.
  • 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.

Los parámetros marcados con * son obligatorios.

Sin embargo los parámetros rfcEmisor 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:

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.