API DE INTEGRACIÓN - FIRMADO V0.5.3

                      API de Integración - FIRMADO V0.5.3

                      13 OCTUBRE, 2021

                      Documentación de la API de Integración FIRMADO V0.5.3

                      Revisión
                      Fecha
                      Comentarios
                      12021-­10-13
                      Documento inicial

                      Tabla de Contenido

                      • Introducción
                      • Métodos de firmado

                        • Descripción del método.

                        • Parámetros 

                        • Especificación del xml

                        • Especificación de los nodos del xml

                        • Respuesta del método de firmado.

                          • Atributos

                      • Métodos de firmado para el contrato de adhesión 

                        • Descripción del método.

                        • Parámetros 

                        • Especificación del xml

                        • Especificación de los nodos del xml

                        • Respuesta del método de firmado.

                          • Atributos

                      • Códigos de resultado

                      • Anexo


                        Introducción

                      Esta API permite la integración de los usuarios que deseen realizar el firmado de la carta de adhesión, el cual sirve para firmar una carta manifiesto o contrato de adhesión entre el cliente y el PAC .

                      La ubicación del WSDL del WebService es:

                      Método de firmado 

                      String firmar(String contrato, String usuario, String passwd, String xml, boolean modoPrueba)

                      Descripción del método:

                      Permite firmar el contrato entre contribuyente y Proveedor de Certificación de CFDi (PCCFDI).

                      Parámetros: 

                      • contrato: Es el código de contrato asignado al asociado integrador. Mediante éste se realizan las transacciones de timbrado con el PCCFDI. No tiene ninguna relación con el contrato que se firmará.

                      • usuario: Es el usuario asignado al asociado integrador.
                      • passwd: Es la contraseña establecida por el asociado integrador.

                      • xml: Es el XML en base64 que contiene el contrato y las firmas de contribuyente, integrador y PCCFDI. Se detalla a continuación.
                      • modoPrueba: Especifica si la solicitud se realizará en modo prueba o si se refiere a una solicitud real.

                      Especificación del XML


                      La estructura base del XML es:

                      <?xml version="1.0" encoding="utf-8"?>

                              <Contrato>

                              <Fecha></Fecha>

                              <Hash></Hash>

                              <Texto></Texto>

                              <Firmas>

                                  <Firma Quien="" RFC="" Nombre="" RepLegalRFC="" RepLegal="" CertificadoSerie="" Certificado=”” Sello="" />

                              </Firmas>

                      </Contrato>

                      Especificación de los nodos del XML

                      • id. Identificador de la transacción interna, en formato UUID. Este valor es de uso interno, no está relacionado con ninguna propiedad del XML
                      • Fecha: especifica la fecha y hora de petición de firmado. El formato es: yyyy-MM-dd'T'HH:mm:ss.

                      • Hash: es el hash calculado del texto de contrato. Se utiliza para validar que el texto del contrato sea el original. El hash se calcula con el algoritmo sha1, especificado más adelante.

                      • Texto: es el texto del contrato entre contribuyente, integrador y PCCFDI. Se genera mediante un XSLT y los datos de las tres partes que firman.

                      • Firmas: contiene las firmas de cada una de las partes involucradas en el contrato.

                        • Firma: la solicitud debe contener 2 firmas(contribuyente e integrador). Este nodo contiene en sus atributos los datos de la entidad que firma.

                          • En el atributo ‘Quien’ se especifica: “Cliente” o las siglas del integrador.

                          • El atributo Nombre contiene la razón social del contribuyente.

                          • El atributo RepLegalRFC contiene el RFC del representante legal del contribuyente.

                          • El atributo RepLegal contiene el nombre del representante legal del contribuyente.

                          • El atributo CertificadoSerie contiene el valor de la serie del certificado.

                          • El atributo Certificado contiene el certificado en base64 de la entidad que firma.

                          • El atributo Sello se genera con el certificado, llave privada y password de la entidad en conjunto con el texto del contrato.

                          • En caso de una firma exitosa, la plataforma devolverá un nodo adicional de Firma con el sello del PCCFDI.

                      Adicional a los atributos previamente mencionados, el nodo Firma del integrador deberá contener los siguientes atribut

                      • Siglas: Las siglas con las cuales se identifica el integrador.

                      • CalleNumero:  Calle y número del domicilio fiscal del integrador.

                      • Colonia:  Colonia del domicilio fiscal del integrador.

                      • Ciudad:  Ciudad del domicilio fiscal del Integrador.

                      • Estado:  Estado del domicilio fiscal del Integrador.

                      • CodigoPostal: Código postal del domicilio fiscal del Integrador.

                      • NombreSoftware:  Nombre de la solución tecnológica del integrador usada por el contribuyente.

                      • URLInformacion:  URL donde el contribuyente puede obtener información y los costos del servicio que está contratando.


                      Respuesta del método de firmado      

                      El servicio devuelve un XML sin esquemas. La estructura se describe a continuación: 

                      <?xml version="1.0" encoding="UTF-8"?>

                              <padeFirmado>

                                  <firmaOk></firmaOk>

                                  <codigoResultado></codigoResultado>

                                  <mensajeResultado></mensajeResultado>

                                  <fechaFirma></fechaFirma>

                                  <xmlBase64></xmlBase64>

                              </padeFirmado>

                      • firmaOk: indica si la operación de firmado fue realizada con éxito. Los valores posible son ‘true’, que indica éxito, y ‘false’, que indica algún error en la operación que impidió firmar el contrato.

                      • codigoResultado: indica el código del error detectado, si hubo alguno. Cuando la transacción es exitosa, el código devuelto es 0 (cero), en caso contrario devuelve el código de error correspondiente(Ver tabla de códigos de resultado).

                      • mensajeResultado: describe el código devuelto por el servicio.

                      • fechaFirma: Especifica la fecha y hora en la que el servicio devuelve la respuesta. Solo se incluye cuando la respuesta es exitosa. El formato es:

                        yyyy-MM-dd'T'HH:mm:ss.

                      • xmlBase64: contiene el XML firmado en formato base64. Sólo se incluye cuando la transacción es exitosa.

                      Método de firmado para el contrato de adhesión 


                      String firmarContratoAdhesion(String xml, boolean modoPrueba)

                      Descripción del método:

                      Permite firmar el contrato de adhesión entre contribuyente y Proveedor de Certificación de CFDi       (PCCFDI).

                      Parámetros: 

                      • xml : Es el XML en base64 que contiene el contrato y las firmas de contribuyente y PCCFDI. Se detalla a continuación.

                      • modoPrueba : Especifica si la solicitud se realizará en modo prueba o si se refiere a 

                        una solicitud real.

                      Estructura base del XML es: 

                      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>

                      <Contrato>

                          <Fecha></Fecha>

                          <Hash><Hash>

                          <Texto></Texto>

                          <Firmas>

                              <Firma Quien="" Sello="" CertificadoSerie="" Certificado="" Nombre="" RepLegal="" Facultad="" CalleNumero="" Colonia="" Ciudad="" Estado="" CodigoPostal=""/>

                          </Firmas>

                      </Contrato>

                      Especificación de los nodos del XML


                      • Fecha: especifica la fecha y hora de petición de firmado. El formato es: yyyy-MM-dd'T'HH:mm:ss.

                      • Hash: es el hash calculado del texto de contrato. Se utiliza para validar que el texto del contrato sea el original. El hash se calcula con el algoritmo sha1, especificado más adelante.

                      • Texto: es el texto del contrato entre contribuyente, integrador y PCCFDI. Se genera mediante un XSLT y los datos de las dos partes que firman.

                      • Firmas: contiene las firmas de cada una de las partes involucradas en el contrato    .

                        • Firma: la solicitud debe contener la firma del contribuyente. Este nodo

                           contiene en sus atributos los datos de la entidad que firma.

                          • En el atributo 'Quien' se especifica: “Cliente”.

                          • El atributo 'Sello' se genera con el certificado, llave privada y password de la 

                            entidad en conjunto con el texto del contrato.

                          • El atributo 'CertificadoSerie' contiene el valor de la serie del certificado.

                          • El atributo 'Certificado' contiene el certificado en base64 de la entidad que 

                            firma.

                          • El atributo 'Nombre' contiene la razón social del contribuyente.

                          • El atributo 'RepLegal' contiene el nombre del representante legal del 

                            contribuyente.

                          • El atributo 'Facultad' contiene la descripción de la facultad del representante legal

                          • El atributo 'CalleNumero' contiene como parte del domicilio fiscal la calle y numero del cliente

                          • El atributo 'Colonia' contiene como parte del domicilio fiscal la colonia del cliente

                          • El atributo 'Ciudad' contiene como parte del domicilio fiscal la ciudad del cliente

                          • El atributo 'Estado' contiene como parte del domicilio fiscal el estado del cliente

                          • El atributo 'CodigoPostal' contiene como parte del domicilio fiscal el código postal del cliente 

                          • En caso de una firma exitosa, la plataforma devolverá un nodo adicional de

                            firma con el sello del PCCFDI.

                      Respuesta del método de firmado         

                      El servicio devuelve un XML sin esquemas. La estructura se describe a continuación: 

                      <?xml version="1.0" encoding="UTF-8"?>

                      <padeFirmado>

                          <firmaOk></firmaOk>

                          <codigoResultado></codigoResultado>

                          <mensajeResultado></mensajeResultado>

                          <fechaFirma></fechaFirma>

                          <xmlBase64></xmlBase64>

                      </padeFirmado>

                      • firmaOk: indica si la operación de firmado fue realizada con éxito. Los valores posible son ‘true’, que indica éxito, y ‘false’, que indica algún error en la operación que impidió firmar el contrato.

                      • codigoResultado: indica el código del error detectado, si hubo alguno. Cuando la transacción es exitosa, el código devuelto es 0 (cero), en caso contrario devuelve el código de error correspondiente (Ver tabla de códigos de resultado).

                      • mensajeResultado: describe el código devuelto por el servicio.

                      • fechaFirma: Especifica la fecha y hora en la que el servicio devuelve la respuesta. Solo se incluye cuando la respuesta es exitosa. El formato es:

                        yyyy-MM-dd'T'HH:mm:ss.

                      • xmlBase64: contiene el XML firmado en formato base64. Sólo se incluye cuando la transacción es exitosa.


                      Códigos de resultado 

                      Código
                      Descripción
                      0 Firma exitos
                      1 Usuario, contraseña o código de contrato del asociado inválido
                      2 Contrato firmado previamente
                      301 Xml mal formado 
                      302 Contrato mal formado
                      303 El sello del emisor mal formado o inválido
                      304 El sello del asociado integrador mal formado o inválido. 
                      305 El certificado del emisor mal formado o inválido. 
                      306 El certificado del asociado mal formado o inválido. 
                      307 El certificado del emisor no es válido 
                      308 El certificado del asociado no es válido 
                      309 El contrato no es válido. 
                      310 El certificado del integrador no fue emitido por el SAT. 
                      311 El certificado del emisor no fue emitido por el SAT. 
                      400 La petición no es válida, faltan parametros
                      99 Ocurrió un error interno

                      Anexo

                      Algoritmo para calcular el Hash (C#):


                      /// <summary>

                      /// Genera el hash del texto especificado

                      /// </summary>

                      /// <param name=" texto">Texto cuyo hash se desea generar</param> protected string ContratoGenerarHash(string texto)

                      {

                      string hash = "Error: sin calcular"; try

                      {

                      Byte [] stream = null;

                      using (System.Security.Cryptography.SHA1CryptoServiceProvider shaProvider = new System.Security.Cryptography.SHA1CryptoServiceProvider())

                      {

                      stream = shaProvider.ComputeHash(System.Text.Encoding.UTF8.GetBytes(texto)); if (stream == null)

                      {

                      hash = "Error al Calcular Hash del Texto";

                      }

                      else

                      {

                      hash = System.BitConverter.ToString(stream);

                      }

                      }

                      }

                      catch (Exception error)

                      {

                      hash = string.Format("Error SHA-1: {0}", error);

                      }

                      return hash;

                      }