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]
@@ Línea 1: / Línea 1: @@
-====== Conexión al Web Service Retenciones y Pagos ======
-Para realizar la conexión con el Web Service de iTimbre es necesario proveer los siguientes datos en el llamado:
-  * **Usuario**. El usuario es el correo electrónico utilizado al momento de crear la cuenta en el Portal de iTimbre. El mismo con el que se ingresa al sistema.
-  * **RFC**  del emisor.
-  * **Contraseña del emisor**. La contraseña generada al registrar al emisor en el sistema, como se mostró anteriormente. Nota: no confundir con la contraseña utilizada para acceder al Portal de iTimbre.
-  * **Método**. El método es la función a realizar. Actualmente se cuenta con los siguientes métodos:
-      * **enviarRetencion**  → método que se utiliza para validar y timbrar un CFDI.
-      * **cancelarRetencion**  →método utilizado para cancelar un CFDI.
-      * **verificarEstatusRetencion**→ Para recibir un acuse utilizando el parametro folio_seguimiento.
-  * **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.
-**Direcciones del servicio:**
-Pruebas:[[http://portalws1.itimbre.com/itimbreprueba.php?q=|http://portalws1.itimbre.com/itimbreprueba.php?q=]]
-====== Timbrado de Retenciones y Pagos ======
-Las siguientes validaciones se realizan al XML:
-  * La estructura del XML cumple con las especificaciones del SAT.
-  * El Certificado de Sello Digital (CSD) del emisor haya sido emitido por el SAT.
-  * El CSD esté vigente en la fecha de generación del Comprobante.
-  * El Comprobante no haya sido validado previamente.
-  * Que el RFC y número de certificado se encuentren en las lista de contribuyentes del SAT.
-  * El periodo de tiempo entre la fecha de expedición del documento y la fecha en la que se pretende certificar no exceda de 72 horas.
-  * El CSD con el que se sello el documento corresponda al contribuyente que aparece como emisor del CFDI y que el sello digital corresponda al documento enviado.
-En caso que el XML cumpla con las validaciones mencionadas, el Web Service lo devolverá al contribuyente con la información contenida y el Timbre Fiscal Digital, este incluye:
-  * El número de folio fiscal asignado.
-  * Fecha y hora de Validación.
-  * El número de serie del certificado del SAT con el que se realizó la validación.
-  * El sello digital del Timbre Fiscal Digital.
-===== Llamado =====
-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Á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. **Por defecto se asignará 0**.  |
-|  method  |Este parámetro consiste en el tipo de petición solicitado para generar el CFDI. Los valores posibles se encuentran en el catálogo de métodos. |
-|  params  |Debe contener un arreglo con los parámetros: **user**, **pass**, **RFC**, y **xmldata**.  |
-|  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 asignada al emisor de manera automática. Se puede utilizar la **contraseña máster** del administrador de los emisores para cualquier RFC.  |
-|  RFC  |RFC del emisor del CFDI. Nota: es el único parámetro que debe estar en mayúsculas. |
-|  xmldata  |Contenido del XML con la información del comprobante. |
-==== Ejemplos ====
-**Ejemplo de codificación del llamado en formato JSON para certificación de retenciones**:
-<file JSON llamado-retenciones.json>
-{
-    "id":"101",
-    "method":"enviarRetencion",
-    "params": {
-        "user":"miemail@midominio.com",
-        "pass":"cabb17fb8536180e11af6dff0da42132",
-        "RFC":"EEM010101XYZ",
-        "xmldata":"<cfdi></cfdi>"
-    }
-}
-</file>
-===== Respuesta =====
-En caso de validación del XML o que surja algún error en el proceso, el Web Service de iTimbre le enviará una respuesta.
-==== Parámetros de la Respuesta ====
-^  PARÁMETROS  ^  DESCRIPCIÓN  |
-|  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. |
-|  UUID  |Identificador único del CFDI timbrado. Nota: es el único parámetro que se regresa en mayúsculas. |
-|  data  |XML timbrado. |
-|  acuse  |Acuse que proporciona el SAT como comprobante de que el CFDI fue recibido satisfactoriamente. Nota: este parámetro pudiera no ser regresado si el servicio de recepción del SAT no se encuentre disponible en el momento de la llamada. |
-|  error  |En caso de existir, una descripción del error regresado al intentar validar el XML. |
-|  Otros  |Otros parámetros en caso de que se ocupen como referencia, por ejemplo el usuario que hizo el llamado, o algún **timestamp**.  |
-==== Ejemplos ====
-**Ejemplo de respuesta válida arrojada por el Web Service**:
-<file JSON respuesta.json>
-{
-    "id":"101",
-    "result": {
-        "retcode":1,
-        "UUID":"63C2042F-FAF0-48A0-A9AF-0304813D2528",
-        "data":"<cfdi></cfdi>",
-        "acuse":"<xml></xml>"
-    }
-}
-</file>
-**Ejemplos de errores**:
-<file JSON error1.json>
-{
-    "id":0,
-    "result":
-    {
-        "retcode":-1,
-        "error":"Variable q faltante."
-    }
-}
-</file>
-<file JSON error2.json>
-{
-    "id":0,
-    "result":    {
-        "retcode":-1,
-        "error":"Los datos recibidos no cumplen con el formato JSON correcto."
-    }
-}
-</file>
-==== Códigos de Respuesta ====
-^  Código  ^  Validación  |
-|  1002  |El PAC envía versión del estándar no existente. |
-|  1004  |La estructura del comprobante recibido no es válida. |
-|  1006  |El Timbre proporcionado ya existe. UUID: <UUID>. |
-|  1009  |El documento de retenciones no cuenta con los datos mínimos. |
-|  1010  |Sello de certificación inválido. |
-|  1011  |Sello del documento de retenciones inválido. |
-|  1012  |TFD no válido. |
-|  1013  |Versión del estándar no vigente. |
-|  1014  |Comprobante con envío extemporáneo por vigencia de versión. |
-|  1015  |Uso del complemento no vigente. |
-|  1016  |Uso de complemento no permitido. |
-|  1017  |Uso del certificado de FIEL no válido. |
-===== Cancelación de CFDI =====
-Para cancelar algún CFDI no se necesita que éste haya sido certificado por iTimbre. No obstante, se requiere que el mensaje enviado al SAT incluya cierta información firmada por el emisor del CFDI, por lo que es necesario que se proporcione el sello digital (CSD) con el que fue firmado el CFDI en un archivo PFX. Para más detalle consulte el documento “Manual de Generación del PFX”.
-===== Llamado =====
-Los parámetros a ser enviados para realizar la Cancelación del XML están estructurados de la siguiente manera:
-==== Parámetros enviados para la cancelación ====
-^  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**.  |
-|  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ó). |
-|  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. |
-|  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**:
-<file JSON llamada-001cancelacion.json>
-{
-    "id":1001,
-    "method":"cancelarRetencion",
-    "params": {
-        "user":"miemail@midominio.com",
-        "pass":"cabb17fb8536180e11af6dff0da42132",
-        "RFC":"EEM010101XYZ",
-        "pfx_pass":"Clave de mi archivo PFX",
-        "pfx_pem":"<<Archivo PFX de mi CSD>>",
-        "folios": [
-            "25916C58-672A-43CD-96EE-F14E0FDD4378",
-        ]
-    }
-}
-</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>
-==== Respuesta ====
-^  PARÁMETROS  ^  DESCRIPCIÓN  |
-|  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. |
-|  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)**:
-<file JSON respuesta-01cancelacion.json>
-{
-    {
-        "id":1001,
-        "result": {
-            "acuse_cancelacion":"<s:Envelope>Acuse del SAT<\/s:Envelope>",
-            "id":1001,
-            "fecha":"2013-04-15T20:48:39.7200698",
-            "retcode":1,
-            "signature":"AuPN3mjhCjI2NYiif2Mdtdib9nxhTOw5jf7TPIloqqv2RHnsJ5XnHAdkf5A9ccfXJ4fpJNY0k3kNHkwFRQmhXw==",
-            "folios": [
-                {
-                "UUID":"48D57A35-48BB-4C4B-AB44-678FCBF74D93",
-                "status":"201"
-                }
-            ]
-        }
-    }
-}
-</file>
-=== Códigos de Respuesta  de Estatus UUID ( Para retenciones y pagos)===
-^  Código  ^  Validación  |
-|  1201  |UUID Cancelado. |
-|  1202  |UUID Previamente cancelado. |
-|  1203  |UUID no corresponde con el emisor. |
-|  1205  |UUID no existe. |
-\\
-=== Códigos de Respuesta  a nivel petición   (Para retenciones y pagos)===
-^  Código  ^  Validación  |
-|  1300  |Autenticación no valida. |
-|  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 correspondiente al emisor. |
-|  1306  |Certificado no vigente. |
-|  1307  |Uso de la FIEL no permitido. |
-|  1308  |Certificado revocado o caduco. |
-|  1309  |Firma mal formada o invalida. |
-\\

iTimbre Wiki

Herramientas de usuario

Herramientas del sitio

Diferencias

Herramientas de la página