Herramientas de usuario

Herramientas del sitio


web-service-retenciones

Diferencias

Muestra las diferencias entre dos versiones de la página.

Enlace a la vista de comparación

Ambos lados, revisión anterior Revisión previa
Próxima revisión
Revisión previa
web-service-retenciones [2015/01/24 20:51]
web-service-retenciones [2016/01/05 23:15] (actual)
Línea 1: Línea 1:
 ====== Web Service Timbrado Retenciones y Pagos ====== ====== Web Service Timbrado Retenciones y Pagos ======
- 
  
 ====== Introducción ====== ====== Introducción ======
  
 Como proveedor autorizado de certificación con el número 68934, **iTimbre** realiza la validación y certificación (**timbrado**) 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. Como proveedor autorizado de certificación con el número 68934, **iTimbre** realiza la validación y certificación (**timbrado**) 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.
- 
- 
- 
 ====== Servicio ====== ====== Servicio ======
  
 La característica principal de la arquitectura del Web Service de iTimbre es que utiliza JSON+REST en lugar del tradicional XML+SOAP. Por lo tanto es importante tener conocimientos del formato JSON para poder crear los mensajes que serán enviados al Web Service. Afortunadamente JSON es mucho más fácil de entender e implementar. La característica principal de la arquitectura del Web Service de iTimbre es que utiliza JSON+REST en lugar del tradicional XML+SOAP. Por lo tanto es importante tener conocimientos del formato JSON para poder crear los mensajes que serán enviados al Web Service. Afortunadamente JSON es mucho más fácil de entender e implementar.
- 
- 
  
 ====== Registro ====== ====== Registro ======
  
 Antes de comenzar a realizar pruebas con el Web Service de iTimbre es necesario registrarse a través de las siguientes ligas: Antes de comenzar a realizar pruebas con el Web Service de iTimbre es necesario registrarse a través de las siguientes ligas:
- 
  
 **Pruebas:​** [[https://​pruebas.itimbre.com/​registro/​index.php?​servicio=timbrado|https://​pruebas.itimbre.com/​registro/​index.php?​servicio=timbrado]] **Pruebas:​** [[https://​pruebas.itimbre.com/​registro/​index.php?​servicio=timbrado|https://​pruebas.itimbre.com/​registro/​index.php?​servicio=timbrado]]
- 
- 
  
 Es necesario que en el campo de “Servicio deseado” se mantenga seleccionada la opción de “Solo timbrado”,​ para que se habiliten en el Web Service las conexiones externas. También es importante distinguir entre la versión de pruebas y la de producción,​ ya que **son sistemas totalmente independientes aunque sean idénticos**. La única diferencia es la validez de los comprobantes certificados. La versión de pruebas utiliza un CSD de pruebas para validar los comprobantes,​ pero al igual que la versión de producción,​ también verifica el RFC y el certificado del CFDI en la lista de contribuyentes del SAT. Por esta razón no es posible utilizar certificados de pruebas para enviar comprobantes a la versión de pruebas del Web Service, ya que generarán el código de error correspondiente. Es necesario que en el campo de “Servicio deseado” se mantenga seleccionada la opción de “Solo timbrado”,​ para que se habiliten en el Web Service las conexiones externas. También es importante distinguir entre la versión de pruebas y la de producción,​ ya que **son sistemas totalmente independientes aunque sean idénticos**. La única diferencia es la validez de los comprobantes certificados. La versión de pruebas utiliza un CSD de pruebas para validar los comprobantes,​ pero al igual que la versión de producción,​ también verifica el RFC y el certificado del CFDI en la lista de contribuyentes del SAT. Por esta razón no es posible utilizar certificados de pruebas para enviar comprobantes a la versión de pruebas del Web Service, ya que generarán el código de error correspondiente.
Línea 36: Línea 27:
  
 En caso de necesitar ayuda vaya al módulo de “Soporte” y llene el formulario. En breve nos comunicaremos con usted. En caso de necesitar ayuda vaya al módulo de “Soporte” y llene el formulario. En breve nos comunicaremos con usted.
- 
  
 ====== Conexión al Web Service Retenciones y Pagos ====== ====== Conexión al Web Service Retenciones y Pagos ======
Línea 51: Línea 41:
   * **Parámetros**. Los parámetros son datos adicionales que deben enviarse y dependen del método utilizado, los cuales se describen más adelante.   * **Parámetros**. Los parámetros son datos adicionales que deben enviarse y dependen del método utilizado, los cuales se describen más adelante.
 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. 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 ligas del Web Service se enlistan a continuación. Las ligas del Web Service se enlistan a continuación.
Línea 58: Línea 47:
  
 Pruebas:​[[http://​portalws1.itimbre.com/​itimbreprueba.php?​q=|http://​portalws1.itimbre.com/​itimbreprueba.php?​q=]] Pruebas:​[[http://​portalws1.itimbre.com/​itimbreprueba.php?​q=|http://​portalws1.itimbre.com/​itimbreprueba.php?​q=]]
- 
  
 ====== Timbrado de Retenciones y Pagos ====== ====== Timbrado de Retenciones y Pagos ======
Línea 82: Línea 70:
  
 Para realizar la validación y certificación de un CFDI se deben utilizar los métodos “**enviarRetencion**”. Los parámetros a ser enviados por el Web Service para realizar la función de validación de los comprobantes fiscales están estructurados de la siguiente manera: Para realizar la validación y certificación de un CFDI se deben utilizar los métodos “**enviarRetencion**”. Los parámetros a ser enviados por el Web Service para realizar la función de validación de los comprobantes fiscales están estructurados de la siguiente manera:
- 
  
 ==== Parámetros de la llamada ==== ==== Parámetros de la llamada ====
Línea 202: Línea 189:
 |  pfx_pass ​ |Llave publica usada para abrir el PFX. | |  pfx_pass ​ |Llave publica usada para abrir el PFX. |
 |  pfx_pem ​ |Archivo resultante de convertir el certificado (.cer) y la llave (.key) a PEM. Para generar este archivo puede consultar el documento “Manual de Generación del PFX” ofrecido por iTimbre. | |  pfx_pem ​ |Archivo resultante de convertir el certificado (.cer) y la llave (.key) a PEM. Para generar este archivo puede consultar el documento “Manual de Generación del PFX” ofrecido por iTimbre. |
-|  folio_seguimiento ​ |Parámetro de retenciones y pagos, este parámetro se envia cuando se desea recuperar un acuse de cancelación ​ brindando un folio de seguimiento.. |+
  
 ==== Ejemplos Cancelación ==== ==== Ejemplos Cancelación ====
 +
 **Ejemplo de codificación de llamado en formato JSON (Un solo folio) para retenciones y pagos**: **Ejemplo de codificación de llamado en formato JSON (Un solo folio) para retenciones y pagos**:
  
Línea 224: Línea 212:
 </​file>​ </​file>​
  
-**Ejemplo de codificación de llamado en formato JSON  para recuperar acuse de cancelación de retenciones y pagos**: 
- 
-<file JSON llamada-0001cancelacion.json>​ 
-{ 
-    "​id":​1001,​ 
-    "​method":"​verificarEstatusRetencion",​ 
-    "​params":​ { 
-        "​user":"​miemail@midominio.com",​ 
-        "​pass":"​cabb17fb8536180e11af6dff0da42132",​ 
-        "​RFC":"​EEM010101XYZ",​ 
-        "​folio_seguimiento":"​005",​ 
-        ​ 
-    } 
-} 
-</​file>​ 
  
  
Línea 246: Línea 219:
 |  id  |El mismo id que fue enviado en el llamado. | |  id  |El mismo id que fue enviado en el llamado. |
 |  result ​ |Un arreglo dentro del cual se encuentran el resto de los parámetros que se describen abajo. | |  result ​ |Un arreglo dentro del cual se encuentran el resto de los parámetros que se describen abajo. |
-|  retcode ​ |Código de retorno, ​si es 1, la repuesta es exitosa. Si es diferente de 1, el número es el código de error. Nota: aunque el valor de retcode sea 1, la solicitud de cancelación no se debe considerar como satisfactoria. Debido a que en el llamado se puede solicitar cancelar más de un CFDI, algunos podrían cancelarse exitosamente mientras que otros no. Es por eso que se debe revisar el parámetro folios, el cual contiene la lista de folios que se solicitaron cancelar con su respectivo código de respuesta. \\   \\ El parametro redcode para **retenciones y pagos** tiene un significado distinto: \\ Si es 1 –> La cancelación ha sido exitosa y el acuse se regresa en el parámetro **acuse_cancelacion** \\ ​Si la respuesta es 2 –> Significa que se activo la cancelación asincrona,​entonces se regresa un folio de seguimiento en la variable **folio_seguimiento**. \\ Si es -1 –>​Entonces hubo un error genérico y la descripción se reflejara en la variable error. Cualquier otro valor en el retcode será uno de los códigos del catalogo. | +|  retcode ​ |Código de retorno, : \\ Si es 1 –> La cancelación ha sido exitosa y el acuse se regresa en el parámetro **acuse_cancelacion** \\ ​Si la respuesta es 2 –> Significa que se activo la cancelación asincrona,​entonces se regresa un folio de seguimiento en la variable **folio_seguimiento**. \\ Si es -1 –>​Entonces hubo un error genérico y la descripción se reflejara en la variable error. Cualquier otro valor en el retcode será uno de los códigos del catalogo. |
-|  acuse  |Acuse del SAT en caso de que retcode sea 1 y que dentro del arreglo folios haya al menos un UUID cancelado. |+
 |  acuse_cancelacion ​ |Parámetro de retenciones y pagos , donde regresa el acuse del SAT cuando es exitosa. | |  acuse_cancelacion ​ |Parámetro de retenciones y pagos , donde regresa el acuse del SAT cuando es exitosa. |
 |  fecha  |Fecha en que el SAT cancela el CFDI, en caso de existir acuse. | |  fecha  |Fecha en que el SAT cancela el CFDI, en caso de existir acuse. |
 |  signature ​ |Firma del acuse del SAT, en caso de existir. Esta firma es parte del acuse, pero aquí se proporciona por separado por simplificación. | |  signature ​ |Firma del acuse del SAT, en caso de existir. Esta firma es parte del acuse, pero aquí se proporciona por separado por simplificación. |
 |  error  |En caso de existir, descripción del error. NOTA: es importante que no exista ningún error para considerar que la cancelación fue exitosa. | |  error  |En caso de existir, descripción del error. NOTA: es importante que no exista ningún error para considerar que la cancelación fue exitosa. |
-|  folios ​ |Arreglo que contiene la lista de folios que se enviaron a cancelar y su correspondiente estatus. | 
 |  folio_seguimiento ​ |Parámetro de retenciones y pagos, este parametro se regresa cuando se activa la cancelación asincrona brindando un folio de seguimiento. | |  folio_seguimiento ​ |Parámetro de retenciones y pagos, este parametro se regresa cuando se activa la cancelación asincrona brindando un folio de seguimiento. |
  
-Ejemplo del manejo de los folios: 
  
-<code PHP> 
-$primer_folio = $folios[0] -> UUID; 
-$estatus_primer_folio = $folios[0] -> status; 
-$segundo_folio = $folios[1] -> UUID; 
-$estatus_segundo_folio = $folios[1] -> status; 
-</​code>​ 
- 
-\\ 
  
 **Ejemplo de respuesta válida arrojada por el Web Service para retenciones y pagos (un folio)**: **Ejemplo de respuesta válida arrojada por el Web Service para retenciones y pagos (un folio)**:
Línea 289: Línea 251:
 </​file>​ </​file>​
  
- +=== Códigos de Respuesta de Estatus UUID  ===
-=== Códigos de Respuesta ​ de Estatus UUID ( Para retenciones y pagos)===+
  
 ^  Código ​ ^  Validación ​ | ^  Código ​ ^  Validación ​ |
Línea 298: Línea 259:
 |  1205  |UUID no existe. | |  1205  |UUID no existe. |
  
-\\ +=== Códigos de Respuesta a nivel petición ​ ===
- +
-=== Códigos de Respuesta ​ a nivel petición ​  (Para retenciones y pagos)===+
  
 ^  Código ​ ^  Validación ​ | ^  Código ​ ^  Validación ​ |
Línea 316: Línea 275:
 \\ \\
  
 +====Método para Consulta de estatus de cancelación====
 +
 +Al intentar efectuar una cancelación entre 2 y 10,000 folios como respuesta se recibirá un folio de seguimiento,​ como se explico anteriormente. Para finalmente recibir un acuse es necesario conectarse nuevamente pero ahora llamando al método **verificarEstatusRetencion**.El único parámetro que deben mandar es '​folio_seguimiento'​. La respuesta es idéntica a la de la cancelación solo que aquí nunca recibirían el retcode 2.
 +
 +^  PARÁMETRO ​ ^  DESCRIPCIÓN ​ |
 +|  id  |Identificador de referencia asignado por el cliente. Este parámetro no es requerido por el Web Service de iTimbre, sino que tiene como propósito ser utilizado por el cliente como método de control para asegurarse de recibir la respuesta solicitada. Se recomienda utilizar el número de folio interno del XML. |
 +|  method ​ |El nombre del método para cancelar : **verificarEstatusRetencion**. ​ |
 +|  params ​ |Debe contener un arreglo con los parámetros:​ user, pass, RFC, y folio de seguimiento. |
 +|  user  |Usuario del Portal de iTimbre con el que se ingresa al sistema (correo electrónico con el que se registró). |
 +|  pass  |Contraseña generada por iTimbre al momento de registrar al emisor. |
 +|  RFC  |RFC del emisor del CFDI. Nota: es el único parámetro que debe estar en mayúsculas. |
 +|  folio_seguimiento ​ |Parámetro de retenciones y pagos, este parámetro se envia cuando se desea recuperar un acuse de cancelación brindando un folio de seguimiento.. |
 +
 +
 +**Ejemplo de codificación de llamado en formato JSON para recuperar acuse de cancelación de retenciones y pagos**:
 +
 +<file JSON llamada-0001cancelacion.json>​
 +{
 +    "​id":​1001,​
 +    "​method":"​verificarEstatusRetencion",​
 +    "​params":​ {
 +        "​user":"​miemail@midominio.com",​
 +        "​pass":"​cabb17fb8536180e11af6dff0da42132",​
 +        "​RFC":"​EEM010101XYZ",​
 +        "​folio_seguimiento":"​005",​
 +
 +    }
 +}
 +</​file>​
web-service-retenciones.1422132664.txt.gz · Última modificación: 2016/01/05 23:15 (editor externo)