Servicio de Firma XML

Contenido

Características generales

El servicio de firma proporcionado por Sovos tiene por objetivo:

  1. Recibir un XML, para verificar que se cumplan las reglas y condiciones establecidas en dicho esquema (XSD).
  2. Realizará la firma del XML con el estándar XAdES-BES, con el número de certificado definido en la solicitud; el certificado debe estar registrado en la plataforma de Sovos para poder realizar la firma electrónica.
  3. Opción para generar un PDF, para mostrar la información contenida en el archivo XML.

Estándar de firma XAdES-BES

El servicio de firma de XML de Sovos proporciona la funcionalidad para realizar firma de un XML, basado en el estándar XML Advanced Electronic Signatures - Basic Electronic Signature XAdES-BES (Firma electrónica avanzada XML - firma electrónica básica)publicado por ETSI (European Telecommunications Standards Institute).

En la siguiente liga encontrará información relacionada con el estándar de firma electrónica de XML XAdES-BES.

¿Qué necesito?

Autenticación

Para poder utilizar el servicio de firma por web service, es necesario contar con un API Key con el cual se realiza la autenticación al servicio. El API Key lo generas desde el portal de Sovos. En este artículo se indica como se genera un API Key en tu cuenta: Generar API Key

Esquemas XSD para validación

Como parte del proceso del servicio de firma, es necesario tener definido las reglas que serán necesarias validar en el XML antes de realizar el firmado, para conservar la integridad de los datos. El esquema se define conforme a las necesidades de los XML a firmar; por ejemplo definir que en el elemento fecha, tenga como tal una fecha válida: 2014-01-01 y no como un texto 01/01/2014. Esto se define por medio del esquema del XML.

Interfaces de Integración

Existen dos maneras para poder enviar los XML al servicio de firma de Sovos:

  • Web Service
  • Transferencia de archivos

Cargar certificado de firma

Para poder realizar la firma electrónica, los certificados deben ser custodiados y guardados en la plataforma Sovos, para lo cual es necesario registrar el certificado, ya sea con extensión .PFX o .CER y .KEY, así como la contraseña correspondiente.

Ubicación del Servicio

La ubicación del web service del servicio de firma de XML son:

Ambiente Ubicación de WSDL
Pruebas https://oat.reachcore.com/api/ws/signature/XmlSignature.svc?wsdl
Producción https://go.reachcore.com/api/ws/signature/XmlSignature.svc?wsdl

Método [SignXml]: Firma de XML

En este método, se realiza la solicitud para firmar el XML, definiendo un certificado en especifico a utilizar.

Solicitud SignXml

Los datos que se requieren enviar en la solicitud de firma de un XML al Web Service, son los siguientes:

Elemento Uso Descripción
ApiKey Requerido Identificador de autenticación, que se genera en el portal de Sovos.
CertificateSerialNumber Requerido Los 40 dígitos hexadecimales del número serial del certificado de firma digital. El certificado debe haber sido instalado en la plataforma Sovos previamente.
TrackingId Opcional Información de contenido libre de hasta 200 caracteres unicode que puede ser usada como dato de referencia del cliente. Por ejemplo un número o folio de documento en un sistema externo.
Xml Requerido El documento XML a firmar. Se deben declarar los namespaces en el XML asociado al esquemas (XSD) contra el cual se hará la validación del XML; los esquemas deben haber sido instalados previamente en la plataforma Sovos. El XML se envía dentro de <![CDATA[...]]>

Para los siguientes ejemplos, se tiene el siguiente esquema registrado, con el cual se realizará las validaciones correspondientes.

<xs:schema xmlns:miEsquema="http://www.miesquema.com" xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.miesquema.com" elementFormDefault="qualified" attributeFormDefault="unqualified">
    <xs:element name="misDatos">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="Fecha" type="xs:dateTime"/>
                <xs:element name="Nombre"/>
                <xs:element name="documentoBase64" type="xs:base64Binary"/>
                <xs:element name="Edad">
                    <xs:simpleType>
                        <xs:restriction base="xs:int">
                            <xs:minInclusive value="18"/>
                            <xs:maxInclusive value="80"/>
                        </xs:restriction>
                    </xs:simpleType>
                </xs:element>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
</xs:schema>

Ejemplo de solicitud de firma, utilizando el certificado con número de serie 3230303031303030303030323030303031343130 y especificando como folio de referencia ABC123, la solicitud correspondiente sería la siguiente.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cus="http://www.reachcore.com/CFDI/customHeaders" xmlns:tem="http://tempuri.org/" xmlns:rc="http://schemas.datacontract.org/2004/07/RC.Signature.Service.Entities">
   <soapenv:Header>
      <cus:ApiKey>0c7e0c034d41471d9a.....f84ad7a386f95540c5e</cus:ApiKey>
   </soapenv:Header>
   <soapenv:Body>
      <tem:Body>
         <rc:CertificateSerialNumber>3230303031303030303030323030303031343130</rc:CertificateSerialNumber>
         <rc:TrackingId>ABC123</rc:TrackingId>
         <rc:Xml><![CDATA[
           <?xml version="1.0" encoding="UTF-8"?>
                <miEsquema:misDatos xmlns:miEsquema="http://www.miesquema.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                    <miEsquema:Fecha>2012-12-17T09:30:47</miEsquema:Fecha>
                    <miEsquema:Nombre>Mi Nombre</miEsquema:Nombre>
                    <miEsquema:documentoBase64>UjBsR09EbGhjZ0dTQUxNQUFBUUNBRU1tQ1p0dU1GUXhEUzhi</miEsquema:documentoBase64>
                    <miEsquema:Edad>18</miEsquema:Edad>
                </miEsquema:misDatos>
              ]]></rc:Xml>
      </tem:Body>
   </soapenv:Body>
</soapenv:Envelope>

Respuesta SignXml

Elemento Descripción
Error
  • false: Transacción exitosa.
  • true: Error al procesarse la transacción.
  • ErrorMessage En caso que el elemento Errortenga el valor true, se mostrara la descripción del error.
    SignedXml El documento XML firmado. Es el principal resultado de la operación.
    TransactionId Número único de transacción asignado por Sovos. Puede ser utilizado en el futuro para referirse a una transacción en particular, con motivos de soporte técnico y para descarga de documentos XML y PDF.

    Ejemplo de respuesta con error, donde se indica que no existe el número de certificado registrado en Sovos:

    <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
       <s:Body>
          <Item xmlns="http://tempuri.org/" xmlns:a="http://schemas.datacontract.org/2004/07/RC.Signature.Service.Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
             <a:Error>true</a:Error>
             <a:ErrorMessage>No existe un certificado con número '3230303031303030303030323030303031343130' para firmar este documento.</a:ErrorMessage>
             <a:SignedXml i:nil="true"/>
             <a:TransactionId>284bf029-61e5-4242-ae56-cdecb5b49e60</a:TransactionId>
          </Item>
       </s:Body>
    </s:Envelope>
    • Ejemplo de un XML firmado con el estándar XaDES-BES
    <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
       <s:Body>
          <Item xmlns="http://tempuri.org/" xmlns:a="http://schemas.datacontract.org/2004/07/RC.Signature.Service.Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
             <a:Error>false</a:Error>
             <a:ErrorMessage/>
             <a:SignedXml><![CDATA[<miEsquema:misDatos xmlns:miEsquema="http://www.miesquema.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Id="id-2168867719" xsi:schemaLocation="http://www.miesquema.com esquemaFirmaDemo.xsd">
      <miEsquema:Fecha>2012-12-17T09:30:47</miEsquema:Fecha>
      <miEsquema:Nombre>Mi Nombre</miEsquema:Nombre>
      <miEsquema:documentoBase64>UjBsR09EbGhjZ0dTQUxNQUFBUUNBRU1tQ1p0dU1GUXhEUzhi</miEsquema:documentoBase64>
      <miEsquema:Edad>18</miEsquema:Edad><ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#" Id="Signature-1627563566">
        <ds:SignedInfo>
            <ds:CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"></ds:CanonicalizationMethod>
            <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"></ds:SignatureMethod>
            <ds:Reference Id="Reference-ID-922611839" URI="#id-2168867719">
                <ds:Transforms>
                    <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"></ds:Transform>
                </ds:Transforms>
                <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod>
                <ds:DigestValue>3gwDpf7wSc2dE7UARmpnVp4f25c=</ds:DigestValue>
            </ds:Reference>
            <ds:Reference Type="http://uri.etsi.org/01903#SignedProperties" URI="#SignedProperties-1399104085">
                <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod>
                <ds:DigestValue>QY6CnrEPJ4lID5MSrWQx/jWPhXo=</ds:DigestValue>
            </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>
    oPfCRJiS81WvZx4ErvqKvp0SX4CbPgu+UmHCqJYE3Vtv/YAE3fsWUV24mmo15Kj5
    5G+H5RiP/SJsjLmASGscA0YADkevAj1twEhuDKflttV+z/DQd/Vi6a7xsFLv0U1a
    renh9TyTcsJ88ph3IEvdIDfyjIl8M/uhV12OOUbSNQGR6Kum6TsZuKUTj65bDFhU
    FPZrfypqoPNY4ElPSxls19hgZmVD41IVuvCIsmhyEUg3rmZ1nwZzZZrrLyM+Oj8J
    V9II9ydTbciI797DTHo/h2hdwnLN5pAF6BZhW19wVOQVmgEnNqRNs3uwTOX8Ikgy
    +HRa/9TGXy4rUAJIUDa0eQ==
        </ds:SignatureValue>
        <ds:KeyInfo>
            <ds:KeyValue>
                <ds:RSAKeyValue>
                    <ds:Modulus>
    xzAmG5Z9ZN1eGHmA1QSLKUE3eUrNzFCrAPZbOJVtyUQJY00kj3usiVvydNyxDI8r
    iACKDhKIPrRbruA2biFoLYbgWTIQKm0TKyZ2ZX2Fefm8OFhqzCDLrqQDLFwnexuI
    9AG7MEHXPb/R/eemzivvth1UWhKF+/6xxNApixnm4rRbkuoVyEIpyFm9BClTi6SH
    LFvfibbzqp01fQZ++JruqTzVRdWF06DQy7HebMujvZxPZ0ldwu9EHBfaTQCQsTaw
    PN6NkLskpzVcM5TahALja1HIYQiEWF04Jt23OgagpX4Fju4HuKO0ZYfjVTbnNRob
    jhr6u8RgGL/clpupfSF97Q==
                    </ds:Modulus>
                    <ds:Exponent>AQAB</ds:Exponent>
                </ds:RSAKeyValue>
            </ds:KeyValue>
            <ds:X509Data>
                <ds:X509IssuerSerial>
                    <ds:X509IssuerName>CN=Reachcore R&amp;D CA4 Root, O=Reachcore, L=Mexico, ST=DF, C=MX</ds:X509IssuerName>
                    <ds:X509SerialNumber>2</ds:X509SerialNumber>
                </ds:X509IssuerSerial>
                <ds:X509SubjectName>CN=AC4Firma01, O=Reachcore, L=Mexico, ST=DF, C=MX</ds:X509SubjectName>
                <ds:X509Certificate>
    MIID5jCCAs6gAwIBAgIBAjANBgkqhkiG9w0BAQsFADBgMQswCQYDVQQGEwJNWDEL
    MAkGA1UECAwCREYxDzANBgNVBAcMBk1leGljbzESMBAGA1UECgwJUmVhY2hjb3Jl
    MR8wHQYDVQQDDBZSZWFjaGNvcmUgUiZEIENBNCBSb290MB4XDTE0MTAwNzIzMzYz
    NloXDTE1MTAwNzIzMzYzNlowVDELMAkGA1UEBhMCTVgxCzAJBgNVBAgMAkRGMQ8w
    DQYDVQQHDAZNZXhpY28xEjAQBgNVBAoMCVJlYWNoY29yZTETMBEGA1UEAwwKQUM0
    RmlybWEwMTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMcwJhuWfWTd
    Xhh5gNUEiylBN3lKzcxQqwD2WziVbclECWNNJI97rIlb8nTcsQyPK4gAig4SiD60
    W67gNm4haC2G4FkyECptEysmdmV9hXn5vDhYaswgy66kAyxcJ3sbiPQBuzBB1z2/
    0f3nps4r77YdVFoShfv+scTQKYsZ5uK0W5LqFchCKchZvQQpU4ukhyxb34m286qd
    NX0Gfvia7qk81UXVhdOg0Mux3mzLo72cT2dJXcLvRBwX2k0AkLE2sDzejZC7JKc1
    XDOU2oQC42tRyGEIhFhdOCbdtzoGoKV+BY7uB7ijtGWH41U25zUaG44a+rvEYBi/
    3JabqX0hfe0CAwEAAaOBtjCBszAJBgNVHRMEAjAAMCwGCWCGSAGG+EIBDQQfFh1P
    cGVuU1NMIEdlbmVyYXRlZCBDZXJ0aWZpY2F0ZTAdBgNVHQ4EFgQUtiTcearAi/gV
    P1pttegjOYxls9YwHwYDVR0jBBgwFoAUfIBl308JUIuSmOSnkldL97vA6HIwOAYI
    KwYBBQUHAQEELDAqMCgGCCsGAQUFBzABhhxodHRwOi8vY2EucmVhY2hjb3JlLm5l
    dDoxMzIzMA0GCSqGSIb3DQEBCwUAA4IBAQCFPmly/c6oWVEJ6QCm4QpjYvrwDOtt
    PIV2SIhZ2tNV8t5cgtGFiS6zeGq+bufdpqk2L8OLPB0SleV8V0mJ0fs5iPK0S2bl
    k8PycF+/Q9TS1WqvViSACISMZ7/v3j/TfufX7VGhqLLMJAk2mDMyA+N9eHvEjDxw
    upjEsfOiWsNSc0qd0mZeyt5MXFQCPZ+AMU674E1s1XlWnF0bkjwQY8l0/d3R1l5q
    rt6d6kWL2fiWr+SxNURCdrf3xF0HUBesFAW+4AJIogIa9uYojGHbSJYAIFaOXsmw
    EKvuLElruY3ggbvoDI7uf65L8T2HGeTbRCdWl0xZ2D+KYttiDd2Fz9qu
                </ds:X509Certificate>
            </ds:X509Data>
        </ds:KeyInfo>
        <ds:Object>
            <etsi:QualifyingProperties xmlns:etsi="http://uri.etsi.org/01903/v1.3.2#" Target="#Signature-1627563566">
                <etsi:SignedProperties Id="SignedProperties-1399104085">
                    <etsi:SignedSignatureProperties>
                        <etsi:SigningTime>2014-12-09T20:26:23.973Z</etsi:SigningTime>
                        <etsi:SigningCertificate>
                            <etsi:Cert>
                                <etsi:CertDigest>
                                    <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod>
                                    <ds:DigestValue>A2SNRcwxTRDjkJ8Z2hWN31FyDmk=</ds:DigestValue>
                                </etsi:CertDigest>
                                <etsi:IssuerSerial>
                                    <ds:X509IssuerName>CN=Reachcore R&amp;D CA4 Root, O=Reachcore, L=Mexico, ST=DF, C=MX</ds:X509IssuerName>
                                    <ds:X509SerialNumber>2</ds:X509SerialNumber>
                                </etsi:IssuerSerial>
                            </etsi:Cert>
                        </etsi:SigningCertificate>
                    </etsi:SignedSignatureProperties>
                    <etsi:SignedDataObjectProperties>
                        <etsi:DataObjectFormat ObjectReference="#Reference-ID-922611839">
                            <etsi:Description>contenido documento</etsi:Description>
                            <etsi:MimeType>text/xml</etsi:MimeType>
                        </etsi:DataObjectFormat>
                    </etsi:SignedDataObjectProperties>
                </etsi:SignedProperties>
            </etsi:QualifyingProperties>
        </ds:Object>
    </ds:Signature>
    </miEsquema:misDatos>]]></a:SignedXml>
             <a:TransactionId>452f4834-af8c-4b9c-96e8-081d035458a2</a:TransactionId>
          </Item>
       </s:Body>
    </s:Envelope>

    Ejemplos de validación de esquema

    Ejemplo de error cuando el valor del elemento Edad esta fuera de los limites establecidos en el esquema.

    Solicitud

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cus="http://www.reachcore.com/CFDI/customHeaders" xmlns:tem="http://tempuri.org/" xmlns:rc="http://schemas.datacontract.org/2004/07/RC.Signature.Service.Entities">
       <soapenv:Header>
          <cus:ApiKey>0c7e0c034d41471d9a.....f84ad7a386f95540c5e</cus:ApiKey>
       </soapenv:Header>
       <soapenv:Body>
          <tem:Body>
             <rc:CertificateSerialNumber>3230303031303030303030323030303031343130</rc:CertificateSerialNumber>
             <rc:TrackingId>ABC123</rc:TrackingId>
             <rc:Xml><![CDATA[
               <?xml version="1.0" encoding="UTF-8"?>
                    <miEsquema:misDatos xmlns:miEsquema="http://www.miesquema.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                        <miEsquema:Fecha>2012-12-17T09:30:47</miEsquema:Fecha>
                        <miEsquema:Nombre>Mi Nombre</miEsquema:Nombre>
                        <miEsquema:documentoBase64>jBsR09EbGhjZ0dTQUxNQUFBUUNBRU1tQ1p0dU1GUXhEUzhi</miEsquema:documentoBase64>
                        <miEsquema:Edad>15</miEsquema:Edad>
                    </miEsquema:misDatos>
                  ]]></rc:Xml>
          </tem:Body>
       </soapenv:Body>
    </soapenv:Envelope>

    Respuesta

    <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
      <s:Body>
          <Item xmlns="http://tempuri.org/" xmlns:a="http://schemas.datacontract.org/2004/07/RC.Signature.Service.Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <a:Error>true</a:Error>
            <a:ErrorMessage>The 'http://www.miesquema.com:Edad' element is invalid - The value '15' is invalid according to its datatype 'Int' - The MinInclusive constraint failed.</a:ErrorMessage>
            <a:SignedXml i:nil="true"/>
            <a:TransactionId>e0191bba-6cb5-4c09-8b0f-b52f03ae38cd</a:TransactionId>
          </Item>
      </s:Body>
    </s:Envelope>

    Ejemplo de error cuando el valor del elemento documentoBase64 no es válido.

    Solicitud

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cus="http://www.reachcore.com/CFDI/customHeaders" xmlns:tem="http://tempuri.org/" xmlns:rc="http://schemas.datacontract.org/2004/07/RC.Signature.Service.Entities">
       <soapenv:Header>
          <cus:ApiKey>0c7e0c034d41471d9a.....f84ad7a386f95540c5e</cus:ApiKey>
       </soapenv:Header>
       <soapenv:Body>
          <tem:Body>
             <rc:CertificateSerialNumber>3230303031303030303030323030303031343130</rc:CertificateSerialNumber>
             <rc:TrackingId>ABC123</rc:TrackingId>
             <rc:Xml><![CDATA[
               <?xml version="1.0" encoding="UTF-8"?>
                    <miEsquema:misDatos xmlns:miEsquema="http://www.miesquema.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                        <miEsquema:Fecha>2012-12-17T09:30:47</miEsquema:Fecha>
                        <miEsquema:Nombre>Mi Nombre</miEsquema:Nombre>
                        <miEsquema:documentoBase64>jBsR09EbGhjZ0dTQUxNQUFBUUNBRU1tQ1p0dU1GUXhEUzhi</miEsquema:documentoBase64>
                        <miEsquema:Edad>18</miEsquema:Edad>
                    </miEsquema:misDatos>
                  ]]></rc:Xml>
          </tem:Body>
       </soapenv:Body>
    </soapenv:Envelope>

    Respuesta

    <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
      <s:Body>
          <Item xmlns="http://tempuri.org/" xmlns:a="http://schemas.datacontract.org/2004/07/RC.Signature.Service.Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <a:Error>true</a:Error>
            <a:ErrorMessage>The 'http://www.miesquema.com:documentoBase64' element is invalid - The value 'jBsR09EbGhjZ0dTQUxNQUFBUUNBRU1tQ1p0dU1GUXhEUzhi' is invalid according to its datatype 'http://www.w3.org/2001/XMLSchema:base64Binary' - Invalid length for a Base-64 char array or string.</a:ErrorMessage>
            <a:SignedXml i:nil="true"/>
            <a:TransactionId>20d6ae19-8b07-476a-a772-43b8bace5c5b</a:TransactionId>
          </Item>
      </s:Body>
    </s:Envelope>

    Transferencia de archivos

    La otra manera de poder enviar a Sovos los archivos XML a firmar, es por medio de la transferencia de archivos. Para esto, es necesario considerar que la transferencia de archivos hacia Sovos se realiza por medio del protocolo de comunicación seguro SFTP. Hay que considerar que los archivos son depositados en una carpeta de entrada para su procesamiento, y el resultado se entrega en otra carpeta con el resultado. La tarea de entrega y recolección de los archivos debe ser considerado por quien hará uso del servicio.

    Formato de archivo

    Los archivos que son transferidos mediante SFTP, deben de cumplir con los siguiente:

    • Archivo con extensión XML
    • Codificación del archivo en UTF-8
    • XML bien formado
    • El XML debe generarse conforme el esquema definido
    • Solo puede haber un documento a firmar por archivo.

    Entrega del resultado

    Después que se ha procesado el archivo XML, el resultado se entregará por el mismo medio (SFTP) y el nombre del archivo indicará el resultado. El nombre del archivo de construye de la siguiente manera (entre corchetes el valor que cambia):

    • Firmado exitosamente: [Nombre archivo original]-[TransactionID]-OK.xml Contendrá el XML firmado
    • Error: [Nombre archivo original]-[TransactionID]-ERR.xml : Indicará el error por la cual no se firmó el XML.

    Descarga de XML y PDF

    Sovos ofrece la opción de generar un PDF a partir del XML que ha sido firmado. Si tiene habilitado este servicio, en el siguiente artículo Consulta y recuperación de documentos, en el apartado "Servicio de firma electrónica", se describe la forma en que pueden obtenerse el XML original, así como el PDF.

    El parámetro al que se hace referencia en la recuperación, ya sea del XML o del PDF, es del transactionId. Este valor se encuentra en cada respuesta del servicio de firma electrónica, así como en el nombre del archivo si se procesó por medio de la transferencia de archivos.

    Para mayor información o aclaración de dudas relacionadas con esta guía, por favor envía un correo a MEX-soporte@sovos.com


    Regresar