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:
No todos los atributos estarán presentes siempre en la respuesta. La descripción de los mismos se define a continuación.
- 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.
- 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.
- Identificador único del contrato del cliente. Se regresa para fines informativos.
- 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”.
- 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.
- Versión del Timbre Fiscal generado. A la fecha, el valor es 1.0. Este valor forma parte del elemento
- <tfd:TimbreFiscalDigital>
- <tfd:TimbreFiscalDigital>
- dentro del CFDI. Este valor se incluye solamente cuando la transacción de timbrado es exitosa.
- 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
Este método permite la cancelación de uno o varios CFDI. Los argumentos que acepta el método son:
- Identificador único del contrato de servicios.
- Nombre del usuario del servicio. Éste usuario debe estar autorizado para utilizar la API de integración.
- Contraseña del usuario del servicio.
- 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>
- 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).
- Arreglo de bytes Llave privada correspondiente al certificado.
- Contraseña de la llave privada que se está enviando.
- 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:
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:
- 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 del emisor de los CFDI. Se proporciona para fines informativos.
- 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 descriptivo del error en caso que el valor de código sea diferente de cero.
- Nodo que contiene la lista con los resultados de las operaciones individuales sobre cada UUID.
- Nodo que contiene el resultado de una cancelación individual.
- UUID que fue procesado.
- 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 opcional adicional con la descripción del problema (en caso de haberlo).
- Nodo que contiene el resultado de una cancelación individual.
- Acuse de cancelación proporcionado por el SAT, codificado en base 64.
Operación para consulta del acuse de cancelación de un CFDI
Obtiene el acuse de cancelación proporcionado por el SAT. Los argumentos que acepta el método son:
- Identificador único del contrato de servicios.
- Nombre del usuario del servicio. Éste usuario debe estar autorizado para utilizar la API de integración.
- Contraseña del usuario del servicio.
- 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:
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:
- Toma valores de “true” o “false”, dependiendo del resultado de éxito o error en la consulta del acuse.
- ID del contrato del cliente. Se proporciona para fines informativos.
- Código del error, en caso de haberlo.
- Mensaje descriptivo del error, en caso de haberlo.
- 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:
|
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:
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 |