Servicio de Firma XML
Contenido
- Características generales
-
Método [
SignXml
]: Firma de XML.- Solicitud SignXml
- Respuesta SignXml
- Transferencia de archivos
- Descarga de XML y PDF
Características generales
El servicio de firma proporcionado por Sovos tiene por objetivo:
- Recibir un XML, para verificar que se cumplan las reglas y condiciones establecidas en dicho esquema (XSD).
- 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. - 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 Error tenga 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&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&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