API DE INTEGRACIÓN CFDI RETENCIONES 

API  DE INTEGRACIÓN CFDI RETENCIONES

 

Documentación de la API de Integración para Retenciones de Pade


Revisión
 		Fecha
 		Comentarios
1 2016-02-10
 Se agrega método de timbrado para CFDi de retenciones.
2 2016-12-15
 Se agrega método de cancelación para CFDi de retenciones.
3 2017-01-16
Se agrega método de consulta de acuse de cancelación para CFDi de retenciones.
3.1 2017-01-31
Se cambió el nombre del método de consulta de acuse para retenciones.

Introducción

La API de Integración para Retenciones es un servicio ofrecido al cliente que requiere emitir comprobantes fiscales digitales de retenciones directamente desde sus sistemas de producción y operación. El servicio se ofrece mediante la invocación de métodos remotos de un Web Service.

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

 https://timbrado.pade.mx/PadeApp/TimbradoRet2.0 

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 timbrado de CFDI Retenciones.

Operación de Timbrado

String timbradoRet ( String contrato , String usuario , String password , String xml , String [ ] opciones , boolean modoPrueba )

El método acepta un string con un documento XML y genera el respectivo timbre fiscal digital. 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 integración.
  • password. Contraseña del usuario del servicio.
  • xml. Documento XML con el CFDI. El documento debe incluir el certificado de sello digital del cliente embebido.
  • opciones: es un arreglo de strings que le indica al servicio opciones o acciones alternativas. Las opciones actualmente reconocidas por el servicio de timbrado de retenciones son:
    • CALCULAR_SELLO
    • REGRESAR_CON_ERROR_307_XML

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

<servicioTimbrado>
    <id/>
    <timbradoOk/>
    <contrato/>
    <codigo/>
    <mensaje/>
    <version/>
    <UUID/>
    <FechaTimbrado/>
    <selloCFD/>
    <noCertificadoSAT/>
    <selloSAT/>
    <xmlBase64/>
</servicioTimbrado>

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

id.
Identificador de la transacción interna, en formato UUID. Este valor es de uso interno, no está relacionado con niguna 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 defindo 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”.
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 nodo se omite.
version.
Versión del Timbre Fiscal generado. A la fecha, el valor es 1.0. 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 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.

Métodos para cancelación de CFDI

Operación de Cancelación

String cancelarRet ( String contrato , String usuario , String passwd , String rfcEmisor , String [ ] arregloUUID , byte [ ] cert , byte [ ] key , String keyPass , String [ ] opciones )

Este método permite la cancelación de uno o varios CFDI. 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 integración.
passwd.
Contraseña del usuario del servicio.
rfcEmisor. RFC del e...
arregloUUID.
Arreglo de Strings con los UUID de los CFDI que se desea cancelar.  Se debe enviar el siguiente arreglo:  <arregloUUID>uuid o folio fiscal|motivo cancelacion|folio sustitución o uuid</arregloUUID>
cert.
Arreglo de bytes con el archivo del certificado de sello digital con que fueron generados los CFDI que se cancelarán. Se debe enviar el archivo binario tal como se obtuvo del SAT (formato DER).
key.
Arreglo de bytes Llave privada correspondiente al certificado.
keyPass.
Contraseña de la llave privada que se está enviando.
opciones.
Es un arreglo de Strings con indicaciones adicionales para el servicio de cancelación. Las opciones reconocidas son:

  • CERT_DEFAULT
  • PKCS12

El significado de las opciones se puede consultar en la tabla “Opciones para los diferentes servicios” al final del documento.

El servicio de cancelación regresa un archivo XML sin esquemas, estructurado de la siguiente manera:

<servicioCancel>
        <statusOk/>
        <rfc/>
        <codigo/>
        <procesados/>
        <cancelados/>
        <mensaje/>
        <cancelaciones>
            <cancelacion>
            <uuid/>
            <codigo/>
            <mensaje/>
        </cancelacion>
    </cancelaciones>
    <acuseCancelBase64/>
</servicioCancel>

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.
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.
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.

cancelacion.
Nodo que contiene el resultado de una cancelación individual.

uuid.
UUID que fue procesado.
codigo.
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 Resultado de Cancelación”.
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.

Operación para consulta del acuse de cancelación de un CFDI

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

Obtiene el acuse de cancelación proporcionado por el SAT. 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 integración.
passwd.
Contraseña del usuario del servicio.
uuid.
UID del CFDI que se desea obtener el acuse de cancelación.

El UUID proporcionado debe estar asociado a un CFDI de retenciones que esté previamente cancelado, en cuyo caso se regresará un código de error 602 (No se encontró el acuse de cancelación).

La respuesta es un string XML sin esquemas con la siguiente estructura:

<servicioConsulta>
    <consultaOk/>
    <contrato/>
    <codigo/>
    <mensaje/>
    <xmlBase64/>
</servicioConsulta>

No todos los atributos están presentes en la respuesta, dependerá del resultado de la operación. Esta respuesta se utiliza en todos los métodos de consulta. Los atributos se describen a continuación:

consultaOk.
Toma valores de “true” o “false”, dependiendo del resultado de éxito o error en la consulta del acuse.
contrato.
ID del contrato del cliente. Se proporciona para fines informativos.
codigo.
Código del error, en caso de haberlo.
mensaje.
Mensaje descriptivo del error, en caso de haberlo.
xmlBase64.
String con el acuse de cancelación, codificado en base64.

Tabla1: 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
CALCULAR_SELLO
 Timbrado
 Le indica al servicio que antes de generar el timbre fiscal digital se debe calcular el sello del CFDI. Para que el servicio pueda calcular el sello del CFDI el cliente deberá contar con su certificado de sello digital guardados en la plataforma de Pade. Esta opción tiene las siguientes implicaciones:

  • Puede ser que esta opción no esté disponible para su contrato, dependerá de los servicios que haya solicitado (puede consultarlo con el personal de ventas) y en su caso se generará un mensaje de error.
  • El atributo “sello” del archivo XML que se envía debe venir vacío.
REGRESAR_CON_ERROR_307_XML
 Timbrado
 Le indica al servicio que si el XML que se envía ya fue timbrado anteriormente deberá regresar la información completa del comprobante previamente timbrado(código, UUID, fechaTimbrado, selloSAT,etc).
PKCS12:
 Cancelación
 Se utiliza en la cancelación y sirve para especificar el certificado de sello digital del emisor y su llave privada empaquetados en un archivo con formato PKCS12.

El formato para especificar el archivo PKCS12 es:

PKCS12:archivo_base64

PKCS12:archivo_base64 En donde la cadena “archivo_base64” corresponde al archivo codificado en base 64. Esta opción tiene las siguientes implicaciones:

  • Se ignora el valor de los parámetros cert y pkey que contienen el CSD y la llave privada (individuales), respectivamente.
  • Se debe especificar el parámero keyPass. Esta contraseña es la que se emplea para leer el archivo PKCS12 y debe corresponder a la contraseña de la llave privada del emisor.

El CSD y la llave privada deben estar alojados en el archivo con un alias, que corresponde al RFC del emisor en letras mayúsculas.
CERT_DEFAULT
 Cancelación
 Le indica a la plataforma que obtenga el certificado por default del usuario para realizar las cancelaciones. Al utilizar esta opción, los parámetros: certificado, llave privada y password de la llave privada deben enviarse vacíos.


Tabla 2: Códigos de Resultado Comunes.

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 Off-line por mantenimiento.
20 El usuario no cuenta con un certificado default.


Tabla 3: Códigos de Resultado de Timbrado

Código
 		Descripción
0 Timbrado exitoso.
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.


Tabla 4: Códigos de Resultado de Cancelación.

Código
 		Descripción
1201 Comprobante cancelado exitosamente.
1202 El comprobante ya ha sido previamente cancelado.
1203 El RFC del emisor no corresponde.
1205 El UUID no existe.
1300 Autenticación no válida.
1301 XML mal formado.
1302 Estructura de folios no válida.
1303 Estructura de RFC no válida.
1304 Estructura de fecha no válida.
1305 Certificado no corresponde al emisor.
1306 Certificado no vigente.
1307 Uso de FIEL no permitido.
1308 Certificado revocado o caduco.
1309 Firma mal formada o inválida.
602
 No se encontró el acuse de cancelación