Diferencias

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

--- web-service-retenciones [2015/01/24 20:21]
+++ web-service-retenciones [2016/01/05 23:15] (actual)
@@ Línea 1: / Línea 1: @@
+====== Web Service Timbrado Retenciones y Pagos ======
+====== 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.
+====== 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.
+====== Registro ======
+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]]
+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.
+Al realizar el registro recibirá un correo electrónico de confirmación con la liga hacia el Portal de iTimbre y una contraseña temporal. En caso de no recibir el correo electrónico busque en su carpeta de “Spam” o “Correo no deseado”.
+Cuando ingrese al sistema por primera vez, éste le pedirá que cambie su contraseña temporal por una personalizada que cumpla con los requisitos de seguridad establecidos. La contraseña debe contener al menos 8 caracteres e incluir al menos una mayúscula, una minúscula, un número y un carácter especial (@#$).
+Posteriormente, el sistema lo llevará a la página de inicio, donde podrá ver sus datos personales, editarlos, cambiar su contraseña, y descargar las políticas de uso, el acuerdo de confidencialidad y el presente manual de integración.
+En el sub-módulo de “Emisores” aparece la lista de los emisores registrados. El sistema actualmente no cuenta con un límite de emisores, así que puede registrar todos los que desee siempre y cuando no hayan sido registrados en la aplicación gratuita. Para dar de alta un nuevo emisor dar clic en “Agregar Emisor”.
+Agregue los datos de la empresa y al terminar haga clic en “Aceptar”. Si los datos fueron llenados correctamente se registrará el emisor en el sistema y se generará una contraseña aleatoria, la cual necesitará al momento de hacer el llamado al Web Service de iTimbre. La contraseña aparecerá en el campo correspondiente.
+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 ======
@@ Línea 12: / 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.
 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.
@@ Línea 19: / Línea 47: @@
 Pruebas:[[http://portalws1.itimbre.com/itimbreprueba.php?q=|http://portalws1.itimbre.com/itimbreprueba.php?q=]]
 ====== Timbrado de Retenciones y Pagos ======
@@ Línea 43: / 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:
 ==== Parámetros de la llamada ====
@@ Línea 156: / Línea 182: @@
 ^  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 es: **cancelarCFDI**. \\ El nombre del método para cancelar retenciones y pagos: **cancelarRetencion**.  |
+|  method  |El nombre del método para cancelar : **cancelarRetencion**.  |
 |  params  |Debe contener un arreglo con los parámetros: user, pass, RFC, y folios. |
 |  user  |Usuario del Portal de iTimbre con el que se ingresa al sistema (correo electrónico con el que se registró). |
@@ Línea 163: / Línea 189: @@
 |  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. |
-|  folios  |Arreglo que contiene la lista de folios (UUID) a cancelar. El número máximo es de 500 y todos los folios deben pertenecer al mismo emisor y haber sido generados con el mismo CSD que se proporciona en el archivo PFX. |
-|  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 ====
 **Ejemplo de codificación de llamado en formato JSON (Un solo folio) para retenciones y pagos**:
@@ Línea 186: / Línea 212: @@
 </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 208: / Línea 219: @@
 |  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. |
-|  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. |
 |  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. |
 |  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. |
-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)**:
@@ Línea 251: / Línea 251: @@
 </file>
+=== Códigos de Respuesta de Estatus UUID  ===
-=== Códigos de Respuesta  de Estatus UUID ( Para retenciones y pagos)===
 ^  Código  ^  Validación  |
@@ Línea 260: / Línea 259: @@
 |  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  |
@@ Línea 278: / 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>

iTimbre Wiki

Herramientas de usuario

Herramientas del sitio

Diferencias

Herramientas de la página