====== Web Service Validaciones ======

====== Introducción ======

Como proveedor autorizado de certificación con el número 68934, **iTimbre** realiza la validación de Comprobantes Fiscales Digitales generados por Internet (//**CFDI**//) conforme a las especificaciones requeridas por el SAT a través de su Web Service (Software como Servicio) de una manera rápida y segura. Adicionalmente el servicio se encarga de buscar el CFDI consultado en las bases de datos del [[sat|SAT]] e indicar si ya ha sido procesado por este último, así como su estado en él (vigente o cancelado).

====== Servicio ======

La característica principal de la arquitectura delos **Web Services** de iTimbre es que utiliza //JSON//+//REST// en lugar del tradicional //XML//+//SOAP//. Por lo tanto es importante tener conocimientos del formato JSON para crear los mensajes que serán enviados al Web Service. Afortunadamente JSON es mucho más fácil de entender e implementar.

====== Registro ======

El servicio de validaciones **no requiere ningún registro**. La autorización para las certificaciones se da de manera interna, autorizando a cada RFC del envío de CFDIs a validar. 

====== Conexión al Web Service ======

Para realizar la conexión con el Web Service de validaciones es necesario proveerlos siguientes datos en el llamado:

  * **method**: Indica el método a utilizar. Se enviará "**validaEgreso**". **Parámetro requerido**.
  * **xmldata**: Contenido completo del XML que se desea validar. **Parámetro requerido**.
  * **pdfBase64**: Dato opcional para enviar el contenido del PDF correspondiente al CFDI. Se adjuntará en el correo de respuesta.
  * **attachmentBaseName**: Nombre que se le asignará a los archivos adjuntos del XML y PDF en el correo de respuesta de la validación.
  * **notEmail**: Dirección de correo a la cual se enviará la respuesta de la validación. **Parámetro requerido**.
  * **supplierEmail**: Dirección  de correo a la cual se envía una segunda respuesta, esta le corresponde al proveedor de la factura.

Nota: **En caso de no utilizar algún parámetro se enviará una cadena de texto vacía**.

Al realizar el llamado, las variables se deben serializar en formato JSON y almacenarse en una variable llamada “q”, la cual se debe enviar por HTTP. Las dirección del servicio es la siguiente: 

Producción: [[https://validador.itimbre.com/service.php|https://validador.itimbre.com/service.php]]

====== Llamado ======
Consistente en los siguientes datos: 


El llamado corresponderá a un objeto JSON con la siguiente estructura: 

<file JSON llamado-validacion.json>
{
	"method":"validaEgreso",
	"xmldata":"<XML>CFDI</XML>",
	"pdfBase64":"",
	"attachmentBaseName":"cfdi_123",
	"notEmail":"micorreo@mi-empresa.com"
	"supplierEmail":"correo@proveedor.com"
}
</file>

====== Respuesta ======

===== Válido =====

El procesamiento correcto de un CFDI resulta en un objeto como el siguiente:

<file JSON respuesta-validacion.json>
{
	"retcode":1,
	"schema":"CFDI Validado",
	"verificacionSAT": {
		"mensajeSAT":"S - Comprobante obtenido satisfactoriamente.",
		"estadoSAT":"Vigente"
	}
}
</file>
Consistente en los siguientes datos: 

  * **retcode**: Código de respuesta recibido de acuerdo al catalogo de códigos de respuesta.
  * **schema**: Mensaje que indica si el CFDI fue validado correctamente. 
  * **verificacionSAT**: Arreglo que incluye los datos con la respuesta obtenida por el SAT.
    * **mensajeSAT**: Redacción que indica si el CFDI fue obtenido de la base de datos del SAT.
    * **estadoSAT**: Estado en las bases de datos del SAT, es decir si se encuentra //Vigenete// o //Cancelado//.

===== Inválido =====

El procesamiento de un CFDI inválido resulta en un objeto como el siguiente: 

<file JSON error-validacion.json>
{
	"retcode":101,
	"error":"El XML no se puede parsear."
}
</file>

Consistente en los siguientes datos: 

  * **retcode**: Código de respuesta recibido de acuerdo al catalogo de códigos de respuesta.
  * **error**: Redacción sobre el detalle del procesamiento y el motivo de error.

====== Catálogo de Códigos de Respuesta ======

^	Retcode		^	Descripción											^
|	400			|Violación del contrato. Los datos enviados no corresponden con el formato y/o contenido esperados.	|
|	401			|El receptor no se encuentra autorizado para consumir el servicio de validaciones o con servicio bloqueado.|
|	500			|Error en la comunicación con el servicio.|
|	101			|El CFDI no es válido.|
|	100			|El receptor no se encuentra autorizado para consumir el servicio de validaciones.|