API DE RECEPCIÓN V3 PARA CFDI 3.3

API de Recepción v3 para CFDI 3.3

29 septiembre, 2017

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 opcion MODO_PRUEBA


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


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:

Código
Descripción
0 La recepción ocurrió sin problemas.
1 El usuario proporcionado no está autorizado, no existe, o no se proporcionó la contraseña correcta.
2 El contrato está expirado o no representa un plan de recepción.
3 Uno de los parámetros de invocación remota no está presente o no es correcto.
4 Error interno atrapado antes de regresar el resultado a la capa de presentación.
5 El servicio está off-line por mantenimiento.
6 Error General.
100 Comprobante no encontrado.
101 Emisor no encontrado.
102 Timbre fiscal no válido.
103 El PAC no cuenta con certificado vigente o está revocado.
104 El receptor del XML no se encuentra en la lista de asociados.
105 El XML contiene un valor incorrecto.


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.